WIP add docstrings

chainsyncer/error.py

@@ -4,16 +4,24 @@ class SyncDone(Exception):
     pass
 
 class NoBlockForYou(Exception):
+    """Exception raised when attempt to retrieve a block from network that does not (yet) exist.
+    """
     pass
 
 
 class RequestError(Exception):
+    """Base exception for RPC query related errors.
+    """
     pass
 
 
 class BackendError(Exception):
+    """Base exception for syncer state backend related errors.
+    """
     pass
 
 
-class AbortTx(Exception):
-    pass
+#class AbortTx(Exception):
+#    """
+#    """
+#    pass

chainsyncer/filter.py

@@ -8,6 +8,13 @@ logg = logging.getLogger(__name__)
 
 
 class SyncFilter:
+    """Manages the collection of filters on behalf of a specific backend.
+
+    A filter is a pluggable piece of code to execute for every transaction retrieved by the syncer. Filters are executed in the sequence they were added to the instance.
+
+    :param backend: Syncer backend to apply filter state changes to
+    :type backend: chainsyncer.backend.base.Backend implementation
+    """
 
     def __init__(self, backend):
         self.filters = []
@@ -15,6 +22,12 @@ class SyncFilter:
 
 
     def add(self, fltr):
+        """Add a filter instance.
+
+        :param fltr: Filter instance.
+        :type fltr: Object instance implementing signature as in chainsyncer.filter.NoopFilter.filter
+        :raises ValueError: Object instance is incorrect implementation
+        """
         if getattr(fltr, 'filter') == None:
             raise ValueError('filter object must implement have method filter')
         logg.debug('added filter "{}"'.format(str(fltr)))
@@ -22,12 +35,22 @@ class SyncFilter:
         self.filters.append(fltr)
 
 
-    def apply_one(self, fltr, idx, conn, block, tx, session):
+    def __apply_one(self, fltr, idx, conn, block, tx, session):
         fltr.filter(conn, block, tx, session)
         self.backend.complete_filter(idx)
 
 
     def apply(self, conn, block, tx):
+        """Apply all registered filters on the given transaction.
+
+        :param conn: RPC Connection, will be passed to the filter method
+        :type conn: chainlib.connection.RPCConnection
+        :param block: Block object
+        :type block: chainlib.block.Block
+        :param tx: Transaction object
+        :type tx: chainlib.tx.Tx
+        :raises BackendError: Backend connection failed
+        """
         session = None
         try:
             session = self.backend.connect()
@@ -39,7 +62,7 @@ class SyncFilter:
         for f in self.filters:
             if not self.backend.check_filter(i, flags):
                 logg.debug('applying filter {} {}'.format(str(f), flags))
-                self.apply_one(f, i, conn, block, tx, session)
+                self.__apply_one(f, i, conn, block, tx, session)
             else:
                 logg.debug('skipping previously applied filter {} {}'.format(str(f), flags))
             i += 1
@@ -48,8 +71,23 @@ class SyncFilter:
 
 
 class NoopFilter:
+    """A noop implemenation of a sync filter.
+
+    Logs the filter inputs at debug log level.
+    """
     
     def filter(self, conn, block, tx, db_session=None):
+        """Filter method implementation:
+
+        :param conn: RPC Connection, will be passed to the filter method
+        :type conn: chainlib.connection.RPCConnection
+        :param block: Block object
+        :type block: chainlib.block.Block
+        :param tx: Transaction object
+        :type tx: chainlib.tx.Tx
+        :param db_session: Backend sesssion object
+        :type db_session: varies
+        """
         logg.debug('noop filter :received\n{} {} {}'.format(block, tx, id(db_session)))