1. Christopher Nilsson
  2. dirwatch

Commits

Christopher Nilsson  committed ebede67

Added a few docstrings

  • Participants
  • Parent commits d62a71e
  • Branches default

Comments (0)

Files changed (2)

File dirwatch/base.py

View file
 _LOG_HANDLER_ADDED = False
 
 class DirWatcher(object):
+    """ Abstract base class.
+    Provides core DirWatcher event handling, startup and shutdown interfaces.
+    Actual work, like monitoring for file events, should be done by derivative classes.
+
+    It is expected that the derivative classes will pass file events it sees to 
+    the monitor_events queue. Each of these events is expected to appear in the form of
+    a tuple-like object with at least 3 fields:
+
+    (timestamp, path, event_id)
+
+    Where event_id is one of the supported 'EV_*' event types in the eventtype module.
+
+    These events will be dispatched from the queue in order of arrival to any interested
+    listeners, via the EventManager.
+
+    Interested listeners subscribe by registering a callable, and the event_id(s) they want,
+    with the EventManager, self.events.
+    """
     def __init__(self):
         self.events = EventManager([event_name for event_name in dir(eventtype) 
                                                if event_name.startswith("EV_")])
             _LOG_HANDLER_ADDED = True
         
     def _process_incoming_queue(self):
+        """ Core event dispatcher.
+
+	Receives filesystem events from the monitor(s), and
+	broadcasts them to interested listeners via the EventManager.
+	"""
         while self.monitoring:
             event = self.monitor_events.get()
             
         return False
             
     def start_monitor(self):
+        """  Begin watching the directories, given in self.paths, for events.
+        
+        Subsequent calls, if the montior is already active, will be ignored, and 
+        return False.
+        
+        Returns:
+            True, if the monitor starts successfully.
+
+	NOTE: This base-class routine simply sets some state, and broadcasts
+	    a eventtype.EV_MONITOR_STARTED message. The descendant classes
+	    are expected to then start whatever monitoring mechanism they have
+	    provided.
+	"""
         if not self.monitoring:
             assert self._worker_thread is None
             
                 self.events.notify(eventtype.EV_MONITOR_STARTED)
     
     def stop_monitor(self):
+        """ Stop the event monitor.
+
+	NOTE: This base-class routine simply resets the state (set by start_monitor),
+	    and broadcasts a eventtype.EV_MONITOR_STOPPED message.
+	    Descendant is expected to cleanly shutdown its monitoring mechanism.
+	"""
         if self.monitoring:
             self.monitor_events.put(self._exit_notification)
             self.monitoring = False
         """ Builds a set of filepaths in the given directory.
         
         Intension is to be able to find before/after differences, when
-        there are too many events to process.
+        there are too many events to process for our monitor, and we need
+	to refresh our view to catch up.
         """
         def _iter_paths():
             for path, subdirs, filenames in os.walk(directory):
         
         
                 
-            
+            

File dirwatch/nt_dirwatch.py

View file
     return sysinfo[dwNumberOfProcessors]
 
 class DirWatcherNT(DirWatcher):
+    """ Windows implementation of DirWatcher.
+
+    Relies on ReadDirectoryChangesW(). Each watch request is assigned
+    to a IO completion port (IOCP). 
+
+    A thread pool waits on the IOCP, and when changes occur, the IOCP signals.
+    One of the worker threads will parse the relevant result buffer, enqueuing the 
+    events to the DirWatcher.monitor_events queue.
+
+    This class attempts recovery in the event of ReadDirectoryChangesW() buffer 
+    overflows.
+    """
     
-    READ_BUFFER_SIZE = 8192
+    READ_BUFFER_SIZE = 8192 
     EXIT_NOTIFICATION = -1
     
     DIRINFO_HANDLE_IDX = 0
     """ Public factory for DirWatcherNT instances.
     
     Imported in the dirwatch module."""
-    return DirWatcherNT()
+    return DirWatcherNT()