Commits

Anonymous committed 5e55c97

docstrings

  • Participants
  • Parent commits c03d9c1

Comments (0)

Files changed (1)

File ordf/handler/__init__.py

+__all__ = ["Handler"
+
 from ordf.changeset import ChangeSet
 from ordf.graph import Graph
 from ordf.namespace import CS
 
-class ChangeContext:
+class _ChangeContext:
+    """
+    Not to be instantiated directly. Returned from Handler().context().
+    Takes care of constructing changesets and using the handler to save
+    the information to the various plugins.
+
+    Usage:
+        ctx.add(graph)
+        ctx.add(another)
+        ctx.commit()
+    """
     def __init__(self, handler, *av, **kw):
         self.handler = handler
         self.head = []
         self.__kw__ = kw
 
     def add(self, graph):
+        """
+        ChangeContext.add(graph) - add an RDFLib Graph instance to this context
+        """
         self.head.append(graph)
 
     def commit(self):
+        """
+        ChangeContext.commit() - commit any pending changes in this context
+        """
         cs = ChangeSet(*self.__av__, **self.__kw__)
         for graph in self.head:
             orig = self.handler.get(graph)
                 self.handler.set(graph)
                 for handler in self.handler:
                     handler.set(graph)
+    def rollback(self):
+        """
+        ChangeContext.rollback() - roll back any pending changes in this context
+        """
+        self.head = []
+
 
 class Handler:
+    """
+    Handler - class handling management of changesets and storage plugins or indexes
+
+    Usage:
+
+        Handler(storage) - initialise a handler singleton, with primary storage (usually
+                           an ordf.handler.pt.PairTree instance)
+        Handler.register(plugin) - add a plugin to the list of handlers (usually an
+                                   ordf.handler.rdf.RDFLib instance or similar. Optional)
+        Handler.context(user, reason) - create a change context
+        Handler.changeset(csid) - retrieve a ChangeSet from primary storage
+        Handler.history(ident) - generator that walks the history of the given graph or
+                                 graph identifier, yielding ChangeSet instances
+        Handler.construct(ident) - construct a graph from the ChangeSet history
+
+    Plugins:
+
+        Must implement some of these methods, depending on the purpose of the plugin
+
+        .cset(graph) - take a changeset graph and commit it to storage
+        .set(graph) - take a graph and commit it to storage
+        .get(ident) - return a graph from storage given an identifier
+
+        Implementation of a non-null .cset is required for primary storage, optional
+        for others.
+
+        Plugins used as indices (e.g. RDFLib, FourStore, Xapian) need only implement
+        .set to populate their index. .cset may do nothing unless there is some reason
+        to index changesets. Indexes or secondary storage are not required to implement
+        .get.
+
+        A plugin for passing changes to a distributed message queue for further 
+        dissemination to indices should implement both .cset and .set but again need
+        not bother with .get
+    """
     def __init__(self, storage, **kw):
         self.__storage__ = storage
         self.__handlers__ = []