cc-4105: a whole bunch of docstrings were added

python_apps/media-monitor2/media/monitor/airtime.py

@@ -168,14 +168,13 @@ class AirtimeMessageReceiver(Loggable):
     def change_storage(self, msg):
         new_storage_directory = msg['directory']
         self.manager.change_storage_root(new_storage_directory)
-
         for to_bootstrap in [ self.manager.get_recorded_path(),
                 self.manager.get_imported_path() ]:
             self.__request_now_bootstrap( directory=to_bootstrap )
 
     def file_delete(self, msg):
-        # deletes should be requested only from imported folder but we
-        # don't verify that.
+        # Deletes should be requested only from imported folder but we
+        # don't verify that. Security risk perhaps?
         self.logger.info("Attempting to delete(maybe) '%s'" % msg['filepath'])
         if msg['delete']:
             if os.path.exists(msg['filepath']):

python_apps/media-monitor2/media/monitor/events.py

@@ -33,7 +33,7 @@ class EventRegistry(object):
         return event
     def __init__(self,*args,**kwargs):
         raise Exception("You can instantiate this class. Must only use class \
-                methods")
+                         methods")
 
 class HasMetaData(object):
     """
@@ -70,7 +70,12 @@ class BaseEvent(Loggable):
         return "Event(%s). Path(%s)" % ( self.path, self.__class__.__name__)
     def is_dir_event(self): return self._raw_event.dir
 
-    def add_safe_pack_hook(self,k): self._pack_hook = k
+    def add_safe_pack_hook(self,k):
+        """
+        adds a callable object (function) that will be called after the event
+        has been "safe_packed"
+        """
+        self._pack_hook = k
 
     # As opposed to unsafe_pack...
     def safe_pack(self):

python_apps/media-monitor2/media/monitor/handler.py

@@ -15,6 +15,10 @@ class Handles(object):
 # cause a memory leak
 
 class ReportHandler(Handles):
+    """
+    A handler that can also report problem files when things go wrong
+    through the report_problem_file routine
+    """
     __metaclass__ = abc.ABCMeta
     def __init__(self, signal, weak=False):
         self.signal = signal
@@ -28,6 +32,10 @@ class ReportHandler(Handles):
                 exception=exception)
 
 class ProblemFileHandler(Handles, Loggable):
+    """
+    Responsible for answering to events passed through the 'badfile'
+    signal. Moves the problem file passed to the designated directory.
+    """
     def __init__(self, channel, **kwargs):
         self.channel = channel
         self.signal = self.channel.signal

python_apps/media-monitor2/media/monitor/listeners.py

@@ -36,7 +36,8 @@ from media.monitor.log import Loggable, get_logger
 # OrganizeListener('watch_signal') <= wrong
 # OrganizeListener(signal='watch_signal') <= right
 
-# This could easily be a module
+# TODO : remove this FileMediator stuff it's not used anywhere and it's too
+# complicated
 class FileMediator(object):
     ignored_set = set([]) # for paths only
     # TODO : unify ignored and skipped.

python_apps/media-monitor2/media/monitor/log.py

@@ -15,9 +15,15 @@ class Loggable(object):
     def logger(self): return logging.getLogger(appname)
 
     def unexpected_exception(self,e):
+        """
+        Default message for 'unexpected' exceptions
+        """
         self.fatal_exception("'Unexpected' exception has occured:", e)
 
     def fatal_exception(self, message, e):
+        """
+        Prints an exception 'e' with 'message'. Also outputs the traceback.
+        """
         self.logger.error( message )
         self.logger.error( str(e) )
         self.logger.error( traceback.format_exc() )

python_apps/media-monitor2/media/monitor/metadata.py

@@ -77,7 +77,9 @@ truncate_table = {
 }
 
 def format_length(mutagen_length):
-    """Convert mutagen length to airtime length"""
+    """
+    Convert mutagen length to airtime length
+    """
     t = float(mutagen_length)
     h = int(math.floor(t / 3600))
     t = t % 3600
@@ -105,6 +107,9 @@ class Metadata(Loggable):
 
     @staticmethod
     def write_unsafe(path,md):
+        """
+        Writes 'md' metadata into 'path' through mutagen
+        """
         if not os.path.exists(path):
             raise BadSongFile(path)
         song_file = mutagen.File(path, easy=True)
@@ -162,10 +167,21 @@ class Metadata(Loggable):
         self.__metadata['MDATA_KEY_MD5'] = mmp.file_md5(fpath,max_length=100)
 
     def is_recorded(self):
+        """
+        returns true if the file has been created by airtime through recording
+        """
         return mmp.is_airtime_recorded( self.__metadata )
 
     def extract(self):
+        """
+        returns a copy of the metadata that was loaded when object was
+        constructed
+        """
         return copy.deepcopy(self.__metadata)
 
     def utf8(self):
+        """
+        Returns a unicode aware representation of the data that is compatible
+        with what is spent to airtime
+        """
         return mmp.convert_dict_value_to_utf8(self.extract())

python_apps/media-monitor2/media/monitor/syncdb.py

@@ -42,9 +42,15 @@ class AirtimeDB(Loggable):
             dirs_setup[u'watched_dirs'] ])
 
     def to_id(self, directory):
+        """
+        directory path -> id
+        """
         return self.dir_to_id[ directory ]
 
     def to_directory(self, dir_id):
+        """
+        id -> directory path
+        """
         return self.id_to_dir[ dir_id ]
 
     def storage_path(self): return self.base_storage
@@ -70,6 +76,9 @@ class AirtimeDB(Loggable):
         return l
 
     def dir_id_get_files(self, dir_id):
+        """
+        Get all files in a directory with id dir_id
+        """
         base_dir = self.id_to_dir[ dir_id ]
         return set(( os.path.join(base_dir,p) for p in
             self.apc.list_all_db_files( dir_id ) ))

python_apps/media-monitor2/media/monitor/toucher.py

@@ -5,6 +5,9 @@ from media.monitor.log import Loggable
 from media.monitor.exceptions import CouldNotCreateIndexFile
 
 class Toucher(Loggable):
+    """
+    Class responsible for touching a file at a certain path when called
+    """
     def __init__(self,path):
         self.path = path
     def __call__(self):
@@ -61,6 +64,9 @@ class RepeatTimer(threading.Thread):
 
 
 class ToucherThread(Loggable):
+    """
+    Creates a thread that touches a file 'path' every 'interval' seconds
+    """
     def __init__(self, path, interval=5):
         if not os.path.exists(path):
             try: