docstring fixes

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

@@ -10,10 +10,8 @@ from media.monitor.exceptions import BadSongFile
 from media.saas.thread        import getsig, user
 
 class PathChannel(object):
-    """
+    """ Simple struct to hold a 'signal' string and a related 'path'.
-    Simple struct to hold a 'signal' string and a related 'path'. Basically
+    Basically used as a named tuple """
-    used as a named tuple
-    """
     def __init__(self, signal, path):
         self.signal = getsig(signal)
         self.path   = path
@@ -37,10 +35,8 @@ class EventRegistry(object):
         return event
 
 class EventProxy(Loggable):
-    """
+    """ A container object for instances of BaseEvent (or it's
-    A container object for instances of BaseEvent (or it's subclasses) used for
+    subclasses) used for event contractor """
-    event contractor
-    """
     def __init__(self, orig_evt):
         self.orig_evt   = orig_evt
         self.evt        = orig_evt
@@ -73,12 +69,10 @@ class EventProxy(Loggable):
 
 
 class HasMetaData(object):
-    """
+    """ Any class that inherits from this class gains the metadata
-    Any class that inherits from this class gains the metadata attribute that
+    attribute that loads metadata from the class's 'path' attribute.
-    loads metadata from the class's 'path' attribute. This is done lazily so
+    This is done lazily so there is no performance penalty to inheriting
-    there is no performance penalty to inheriting from this and subsequent
+    from this and subsequent calls to metadata are cached """
-    calls to metadata are cached
-    """
     __metaclass__ = abc.ABCMeta
     @LazyProperty
     def metadata(self): return Metadata(self.path)
@@ -105,11 +99,9 @@ class BaseEvent(Loggable):
 
     # TODO : delete this method later
     def reset_hook(self):
-        """
+        """ Resets the hook that is called after an event is packed.
-        Resets the hook that is called after an event is packed. Before
+        Before resetting the hook we execute it to make sure that
-        resetting the hook we execute it to make sure that whatever cleanup
+        whatever cleanup operations were queued are executed. """
-        operations were queued are executed.
-        """
         self._pack_hook()
         self._pack_hook = lambda: None
 
@@ -123,10 +115,8 @@ class BaseEvent(Loggable):
 
     # TODO : delete this method later
     def add_safe_pack_hook(self,k):
-        """
+        """ adds a callable object (function) that will be called after
-        adds a callable object (function) that will be called after the event
+        the event has been "safe_packed" """
-        has been "safe_packed"
-        """
         self._pack_hook = k
 
     def proxify(self):
@@ -134,11 +124,9 @@ class BaseEvent(Loggable):
 
     # As opposed to unsafe_pack...
     def safe_pack(self):
-        """
+        """ returns exceptions instead of throwing them to be consistent
-        returns exceptions instead of throwing them to be consistent with
+        with events that must catch their own BadSongFile exceptions
-        events that must catch their own BadSongFile exceptions since generate
+        since generate a set of exceptions instead of a single one """
-        a set of exceptions instead of a single one
-        """
         try:
             self._pack_hook()
             ret = self.pack()
@@ -163,42 +151,33 @@ class BaseEvent(Loggable):
         return self
 
     def assign_owner(self,req):
-        """
+        """ Packs self.owner to req if the owner is valid. I.e. it's not
-        Packs self.owner to req if the owner is valid. I.e. it's not -1. This
+        -1. This method is used by various events that would like to
-        method is used by various events that would like to pass owner as a
+        pass owner as a parameter. NewFile for example. """
-        parameter. NewFile for example.
-        """
         if self.owner != -1: req['MDATA_KEY_OWNER_ID'] = self.owner
 
 class FakePyinotify(object):
-    """
+    """ sometimes we must create our own pyinotify like objects to
-    sometimes we must create our own pyinotify like objects to
     instantiate objects from the classes below whenever we want to turn
-    a single event into multiple events
+    a single event into multiple events """
-    """
     def __init__(self, path): self.pathname = path
 
 class OrganizeFile(BaseEvent, HasMetaData):
-    """
+    """ The only kind of event that does support the pack protocol. It's
-    The only kind of event that does support the pack protocol. It's used
+    used internally with mediamonitor to move files in the organize
-    internally with mediamonitor to move files in the organize directory.
+    directory. """
-    """
     def __init__(self, *args, **kwargs):
         super(OrganizeFile, self).__init__(*args, **kwargs)
     def pack(self):
         raise AttributeError("You can't send organize events to airtime!!!")
 
 class NewFile(BaseEvent, HasMetaData):
-    """
+    """ NewFile events are the only events that contain
-    NewFile events are the only events that contain MDATA_KEY_OWNER_ID metadata
+    MDATA_KEY_OWNER_ID metadata in them. """
-    in them.
-    """
     def __init__(self, *args, **kwargs):
         super(NewFile, self).__init__(*args, **kwargs)
     def pack(self):
-        """
+        """ packs turns an event into a media monitor request """
-        packs turns an event into a media monitor request
-        """
         req_dict = self.metadata.extract()
         req_dict['mode'] = u'create'
         req_dict['is_record'] = self.metadata.is_recorded()
@@ -207,11 +186,9 @@ class NewFile(BaseEvent, HasMetaData):
         return [req_dict]
 
 class DeleteFile(BaseEvent):
-    """
+    """ DeleteFile event only contains the path to be deleted. No other
-    DeleteFile event only contains the path to be deleted. No other metadata
+    metadata can be or is included. (This is because this event is fired
-    can be or is included.  (This is because this event is fired after the
+    after the deletion occurs). """
-    deletion occurs).
-    """
     def __init__(self, *args, **kwargs):
         super(DeleteFile, self).__init__(*args, **kwargs)
     def pack(self):
@@ -221,9 +198,7 @@ class DeleteFile(BaseEvent):
         return [req_dict]
 
 class MoveFile(BaseEvent, HasMetaData):
-    """
+    """ Path argument should be the new path of the file that was moved """
-    Path argument should be the new path of the file that was moved
-    """
     def __init__(self, *args, **kwargs):
         super(MoveFile, self).__init__(*args, **kwargs)
     def old_path(self):
@@ -247,10 +222,8 @@ class ModifyFile(BaseEvent, HasMetaData):
         return [req_dict]
 
 def map_events(directory, constructor):
-    """
+    """ Walks 'directory' and creates an event using 'constructor'.
-    Walks 'directory' and creates an event using 'constructor'. Returns a list
+    Returns a list of the constructed events. """
-    of the constructed events.
-    """
     # -unknown-path should not appear in the path here but more testing
     # might be necessary
     for f in mmp.walk_supported(directory, clean_empties=False):
@@ -259,30 +232,25 @@ def map_events(directory, constructor):
         except BadSongFile as e: yield e
 
 class DeleteDir(BaseEvent):
-    """
+    """ A DeleteDir event unfolds itself into a list of DeleteFile
-    A DeleteDir event unfolds itself into a list of DeleteFile events for every
+    events for every file in the directory. """
-    file in the directory.
-    """
     def __init__(self, *args, **kwargs):
         super(DeleteDir, self).__init__(*args, **kwargs)
     def pack(self):
         return map_events( self.path, DeleteFile )
 
 class MoveDir(BaseEvent):
-    """
+    """ A MoveDir event unfolds itself into a list of MoveFile events
-    A MoveDir event unfolds itself into a list of MoveFile events for every
+    for every file in the directory. """
-    file in the directory.
-    """
     def __init__(self, *args, **kwargs):
         super(MoveDir, self).__init__(*args, **kwargs)
     def pack(self):
         return map_events( self.path, MoveFile )
 
 class DeleteDirWatch(BaseEvent):
-    """
+    """ Deleting a watched directory is different from deleting any
-    Deleting a watched directory is different from deleting any other
+    other directory. Hence we must have a separate event to handle this
-    directory.  Hence we must have a separate event to handle this case
+    case """
-    """
     def __init__(self, *args, **kwargs):
         super(DeleteDirWatch, self).__init__(*args, **kwargs)
     def pack(self):