diff --git a/chainsyncer/error.py b/chainsyncer/error.py index 0fd8458..b70ba93 100644 --- a/chainsyncer/error.py +++ b/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 diff --git a/chainsyncer/filter.py b/chainsyncer/filter.py index ea04618..140ef45 100644 --- a/chainsyncer/filter.py +++ b/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)))