Add comments to video and filesystem classes

elodie/filesystem.py

@@ -1,19 +1,43 @@
+"""
+Author: Jaisen Mathai <jaisen@jmathai.com>
+Video package that handles all video operations
+"""
 import os
 import time
 
+"""
+General file system methods
+"""
 class FileSystem:
-    def get_all_files(self, pattern, extensions=None):
+    """
+    Recursively get all files which match a path and extension.
+
+    @param, path, string, Path to start recursive file listing
+    @param, extensions, tuple, File extensions to include (whitelist)
+    """
+    def get_all_files(self, path, extensions=None):
         files = []
-        for dirname, dirnames, filenames in os.walk(pattern):
+        for dirname, dirnames, filenames in os.walk(path):
             # print path to all filenames.
             for filename in filenames:
                 if(extensions == None or filename.lower().endswith(extensions)):
                     files.append('%s/%s' % (dirname, filename))
         return files
 
+    """
+    Get the current working directory
+
+    @returns, string
+    """
     def get_current_directory(self):
         return os.getcwd()
 
+    """
+    Generate file name for a video using its metadata.
+
+    @param, video, Video, A Video instance
+    @returns, string or None for non-videos
+    """
     def get_file_name_for_video(self, video):
         if(not video.is_valid()):
             return None
@@ -25,9 +49,20 @@ class FileSystem:
         file_name = '%s-%s.%s' % (time.strftime('%Y-%m-%d-%H-%M', metadata['date_taken']), metadata['base_name'], metadata['extension'])
         return file_name
 
+    """
+    Get date based folder name.
+
+    @param, time_obj, time, Time object to be used to determine folder name.
+    @returns, string
+    """
     def get_folder_name_by_date(self, time_obj):
         return time.strftime('%Y-%m-%b', time_obj)
 
+    """
+    Create a directory if it does not already exist..
+
+    @param, directory_name, string, A fully qualified path of the directory to create.
+    """
     def create_directory(self, directory_path):
         if not os.path.exists(directory_path):
             os.makedirs(dest_directory)

elodie/media/video.py

@@ -1,5 +1,9 @@
-#!/usr/bin/env python
+"""
+Author: Jaisen Mathai <jaisen@jmathai.com>
+Video package that handles all video operations
+"""
 
+# load modules
 from sys import argv
 import mimetypes
 import os
@@ -7,20 +11,26 @@ import re
 import subprocess
 import time
 
-"""
-Video package that handles all video operations
-"""
 
 """
 Video class for general video operations
 """
 class Video(object):
+    # class / static variable accessible through get_valid_extensions()
     __valid_extensions = ('avi','m4v','mov','mp4')
 
-    # Constructor
+    """
+    @param, source, string, The fully qualified path to the video file
+    """
     def __init__(self, source=None):
         self.source = source
 
+    """
+    Get a dictionary of metadata for a video.
+    All keys will be present and have a value of None if not obtained.
+
+    @returns, dictionary or None for non-video files
+    """
     def get_metadata(self):
         if(not self.is_valid()):
             return None
@@ -36,17 +46,22 @@ class Video(object):
 
         return metadata
 
+    """
+    Check the file extension against valid file extensions as returned by get_valid_extensions()
+    
+    @returns, boolean
+    """
     def is_valid(self):
         source = self.source
         # we can't use self.__get_extension else we'll endlessly recurse
         return os.path.splitext(source)[1][1:].lower() in self.get_valid_extensions()
 
-    #
+    """
-    # Private methods
+    Get the date which the video was taken.
-    #
+    The date value returned is defined by the min() of mtime and ctime.
 
-    # get the min() of mtime and ctime
+    @returns, time object or None for non-video files or 0 timestamp
-    # returns a time object
+    """
     def __get_date_taken(self):
         if(not self.is_valid()):
             return None
@@ -58,20 +73,29 @@ class Video(object):
 
         return time.gmtime(seconds_since_epoch)
         
-    # get the duration of a video in seconds
+    """
-    # uses ffmpeg
+    Get the duration of a video in seconds.
+    Uses ffmpeg/ffprobe
+
+    @returns, string or None for a non-video file
+    """
     def __get_duration(self):
         if(not self.is_valid()):
             return None
 
         source = self.source
-        result = subprocess.Popen(['/usr/local/bin/ffprobe', source],
+        result = subprocess.Popen(['ffprobe', source],
             stdout = subprocess.PIPE, stderr = subprocess.STDOUT)
         for key in result.stdout.readlines():
             if 'Duration' in key:
                 return re.search('(\d{2}:\d{2}.\d{2})', key).group(1).replace('.', ':')
+        return None
 
-    # returns file extension
+    """
+    Get the file extension as a lowercased string.
+
+    @returns, string or None for a non-video
+    """
     def __get_extension(self):
         if(not self.is_valid()):
             return None
@@ -79,7 +103,11 @@ class Video(object):
         source = self.source
         return os.path.splitext(source)[1][1:].lower()
     
-    # returns the mime type
+    """
+    Get the mimetype of the video.
+
+    @returns, string or None for a non-video
+    """
     def __get_mimetype(self):
         if(not self.is_valid()):
             return None
@@ -91,6 +119,11 @@ class Video(object):
 
         return mimetype[0]
 
+    """
+    Static method to access static __valid_extensions variable.
+
+    @returns, tuple
+    """
     @classmethod
     def get_valid_extensions(Video):
         return Video.__valid_extensions