Adding some docs for transactions

Author: mwatts15

README.md

@@ -41,11 +41,9 @@ named graphs you want to include in the bundle, serializing them, and putting
 them in a particular file structure. Here's how you can do that:
 
     >>> from owmeta_core.bundle import Installer, Descriptor
-    >>> from owmeta_core.data import TRANSACTION_MANAGER_KEY
     >>> from rdflib.term import URIRef
-    >>> import transaction
 
-    >>> with connect() as conn, conn.conf[TRANSACTION_MANAGER_KEY]:
+    >>> with connect().transaction() as conn:
     ...     # add some stuff to http://example.org/ctx ...
     ...     g = conn.rdf.graph(URIRef('http://example.org/ctx'))
     ...     _ = g.add((URIRef('http://example.org/s'),

docs/transactions.rst

@@ -0,0 +1,60 @@
+.. _transactions:
+
+Transactions
+============
+Transactions in |owm| are managed through the `transaction`_ library. The
+default RDF store is transactional. You can execute code within a transaction
+using a transaction manager. |owm| connections come with a transaction manager
+which you can access via the `transaction_manager` attribute. It's recommended
+to use a context manager to start and commit transactions like this::
+
+    >>> from rdflib.term import URIRef
+    >>> from owmeta_core import connect
+    >>> with connect() as conn, conn.transaction_manager:
+    ...     conn.rdf.add((
+    ...         URIRef('http://example.org/bob'),
+    ...         URIRef('http://example.org/likes'),
+    ...         URIRef('http://example.org/alice')))
+
+Because this is a common pattern, there's a
+:meth:`~owmeta_core.Connection.transaction` method that does something
+equivalent which is provided for convenience::
+
+    >>> with connect().transaction() as conn:
+    ...     conn.rdf.add((
+    ...         URIRef('http://example.org/bob'),
+    ...         URIRef('http://example.org/likes'),
+    ...         URIRef('http://example.org/alice')))
+
+Similar usage is possible with project connections through the high-level
+`~owmeta_core.command.OWM` interface::
+
+    >>> from owmeta_core.command import OWM
+    >>> owm = OWM(non_interactive=True)
+    >>> owm.init(default_context_id=URIRef("http://example.org/context"))
+    Initialized owmeta-core project at .../.owm
+
+    >>> with owm.connect().transaction() as conn:
+    ...     conn.rdf.add((
+    ...         URIRef('http://example.org/bob'),
+    ...         URIRef('http://example.org/likes'),
+    ...         URIRef('http://example.org/alice')))
+
+However, the methods of `~owmeta_core.command.OWM` and its "sub-commands" will
+typically manage the transactions themselves, so it wouldn't be necessary to
+start a transaction explicitly before calling these methods--in fact, doing so
+would typically cause an exception. For example, in this code::
+
+    >>> owm.say('http://example.org/bob',
+    ...         'http://example.org/likes',
+    ...         'http://example.org/eve')
+
+we don't have to declare a transaction since the `~owmeta_core.command.OWM.say`
+method handles that for us.
+
+For read-only operations, it is not strictly necessary to read from the RDF
+store within the context of a transaction, but it is recommended if you're in a
+multithreaded context to avoid getting an inconsistent picture of the data if
+there's an update part way through your operation.
+
+.. _transaction: https://transaction.readthedocs.io/en/latest/

docs/userdocs.rst

@@ -12,4 +12,4 @@ For Users
    python_release_compatibility
    bittorrent
    query
-
+   transactions

owmeta_core/__init__.py

@@ -17,6 +17,7 @@
 import logging
 import uuid
 from os.path import join as pth_join
+from contextlib import contextmanager
 
 LOGGER = logging.getLogger(__name__)
 LOGGER.addHandler(logging.NullHandler())
@@ -145,6 +146,15 @@ def transaction_manager(self):
         from .data import TRANSACTION_MANAGER_KEY
         return self.conf[TRANSACTION_MANAGER_KEY]
 
+    @contextmanager
+    def transaction(self):
+        '''
+        Context manager that executes the enclosed code in a transaction and then closes
+        the connection. Provides the connection for binding with ``as``.
+        '''
+        with self, self.transaction_manager:
+            yield self
+
     def disconnect(self):
         '''
         Close the database and stop listening to module loaders

owmeta_core/command.py

@@ -2583,10 +2583,10 @@ def __str__(self):
     def transaction(self):
         '''
         Context manager that executes the enclosed code in a transaction and then closes
-        the connection
+        the connection. Provides the connection for binding with ``as``.
         '''
         with self, self.transaction_manager:
-            yield
+            yield self
 
 
 class _ProjectContext(Context):

tests/CommandTest.py

@@ -572,8 +572,9 @@ def test_unsupported_namespace_manager_conf_for_read_only(self):
 
     def test_connect_transaction(self):
         self._init_conf()
-        with self.cut.connect(read_only=True).transaction():
-            pass
+        with self.cut.connect(read_only=True).transaction() as conn:
+            # get a transaction
+            conn.transaction_manager.get()
 
         assert not self.cut.connected
 

tests/DocumentationTest.py

@@ -87,3 +87,6 @@ def execute(self, fname, **kwargs):
 
     def test_making_dataObjects(self):
         self.execute('making_dataObjects')
+
+    def test_transactions(self):
+        self.execute('transactions')