1. Christopher Nilsson
  2. dirwatch


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
 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
     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.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 
     """ Public factory for DirWatcherNT instances.
     Imported in the dirwatch module."""
-    return DirWatcherNT()
+    return DirWatcherNT()