Merge pull request #105 from zopefoundation/transactions-and-threading

Documentation on transactions and threading.

CHANGES.rst

@@ -17,6 +17,8 @@
   ``transaction_manager`` was the (default) thread-local manager. See
   `issue 114 <https://github.com/zopefoundation/ZODB/issues/114>`_.
 
+- Many docstrings have been improved.
+
 5.0.0 (2016-09-06)
 ==================
 

doc/articles/old-guide/prog-zodb.rst

@@ -435,7 +435,7 @@ new schema.  This can be easy if your network of object references is quite
 structured, making it easy to find all the instances of the class being
 modified.  For example, if all :class:`User` objects can be found inside a
 single dictionary or BTree, then it would be a simple matter to loop over every
-:class:`User` instance with a :keyword:`for` statement. This is more difficult
+:class:`User` instance with a ``for`` statement. This is more difficult
 if your object graph is less structured; if :class:`User` objects can be found
 as attributes of any number of different class instances, then there's no longer
 any easy way to find them all, short of writing a generalized object traversal

doc/guide/index.rst

@@ -14,13 +14,11 @@ If you haven't yet, you should read the :ref:`Tutorial <tutorial-label>`.
 
    install-and-run
    writing-persistent-objects.rst
+   transactions-and-threading
 
 .. todo:
 
-   transaction.rst
-   storages.rst
-   configuration.rst
-   threading.rst
-   packing-and-garbage-collection.rst
-   blobs.rst
-   multi-databases.rst
+   blobs
+   packing-and-garbage-collection
+   multi-databases
+   blobs

doc/guide/install-and-run.rst

@@ -128,6 +128,8 @@ much of anything.  Connections take care of loading and saving objects
 and manage object caches. Each connection has it's own cache
 [#caches-are-expensive]_.
 
+.. _getting-connections:
+
 Getting connections
 -------------------
 
@@ -144,7 +146,7 @@ db.open()
    done using the connection.
 
    If changes are made, the application :ref:`commits transactions
-   <commit-transactions>` to make them permanent.
+   <using-transactions-label>` to make them permanent.
 
 db.transaction()
    The database :meth:`~ZODB.DB.transaction` method

doc/reference/index.rst

@@ -6,6 +6,6 @@ Reference Documentation
 .. toctree::
    :maxdepth: 2
 
-   zodb.rst
-   storages.rst
- 
+   zodb
+   storages
+   transaction

doc/reference/transaction.rst

+============
+Transactions
+============
+
+Transaction support is provided by the `transaction
+<http://transaction.readthedocs.io/en/latest/>`_ package
+[#transaction-package-can-be-used-wo-ZODB]_, which is installed
+automatically when you install ZODB.  There are two important APIs
+provided by the transaction package, ``ITransactionManager`` and
+``ITransaction``, described below.
+
+ITransactionManager
+===================
+
+.. autointerface:: transaction.interfaces.ITransactionManager
+   :members: begin, get, commit, abort, doom, isDoomed, savepoint
+
+ITransaction
+============
+
+.. autointerface:: transaction.interfaces.ITransaction
+   :members: user, description, commit, abort, doom, savepoint, note,
+             setUser, setExtendedInfo,
+             addBeforeCommitHook, getBeforeCommitHooks,
+             addAfterCommitHook, getAfterCommitHooks
+
+
+.. [#transaction-package-can-be-used-wo-ZODB] The :mod:transaction
+   package is a general purpose package for managing `distributed
+   transactions
+   <https://en.wikipedia.org/wiki/Distributed_transaction>`_ with a
+   `two-phase commit protocol
+   <https://en.wikipedia.org/wiki/Two-phase_commit_protocol>`_.  It
+   can and occasionally is used with packages other than ZODB.

doc/reference/zodb.rst

@@ -84,7 +84,8 @@ Connections
 .. autoclass:: ZODB.Connection.Connection
    :members: add, cacheGC, cacheMinimize, close, db, get,
              getDebugInfo, get_connection, isReadOnly, oldstate,
-             onCloseCallback, root, setDebugInfo, sync
+             onCloseCallback, root, setDebugInfo, sync,
+             transaction_manager
 
 TimeStamp (transaction ids)
 ===========================

src/ZODB/Connection.py

@@ -50,6 +50,8 @@ import six
 
 from .mvccadapter import HistoricalStorageAdapter
 
+from . import valuedoc
+
 global_reset_counter = 0
 
 noop = lambda : None
@@ -88,6 +90,9 @@ class Connection(ExportImport, object):
 
     _code_timestamp = 0
 
+    #: Transaction manager associated with the connection when it was opened.
+    transaction_manager = valuedoc.ValueDoc('current transaction manager')
+
     ##########################################################################
     # Connection methods, ZODB.IConnection
 

src/ZODB/tests/testdocumentation.py

@@ -40,9 +40,12 @@ def test_suite():
 
     return unittest.TestSuite((
         manuel.testing.TestSuite(
-            manuel.doctest.Manuel() + manuel.capture.Manuel(),
+            manuel.doctest.Manuel(
+                optionflags=doctest.IGNORE_EXCEPTION_DETAIL,
+                ) + manuel.capture.Manuel(),
             join(guide, 'writing-persistent-objects.rst'),
             join(guide, 'install-and-run.rst'),
+            join(guide, 'transactions-and-threading.rst'),
             join(reference, 'zodb.rst'),
             join(reference, 'storages.rst'),
             setUp=setUp, tearDown=tearDown,