Merge improvements to transaction interfaces, from ZODB 3.4 branch.

This is revs 29961 and 29965.

src/transaction/_transaction.py

@@ -150,6 +150,9 @@ import warnings
 import traceback
 from cStringIO import StringIO
 
+from zope import interface
+from transaction import interfaces
+
 # Sigh.  In the maze of __init__.py's, ZODB.__init__.py takes 'get'
 # out of transaction.__init__.py, in order to stuff the 'get_transaction'
 # alias in __builtin__.  So here in _transaction.py, we can't import
@@ -178,6 +181,9 @@ class Status:
 
 class Transaction(object):
 
+    interface.implements(interfaces.ITransaction,
+                         interfaces.ITransactionDeprecated)
+
     def __init__(self, synchronizers=None, manager=None):
         self.status = Status.ACTIVE
         # List of resource managers, e.g. MultiObjectResourceAdapters.
@@ -248,6 +254,7 @@ class Transaction(object):
         # be better to use interfaces.  If this is a ZODB4-style
         # resource manager, it needs to be adapted, too.
         if myhasattr(resource, "prepare"):
+            # TODO: deprecate 3.6
             resource = DataManagerAdapter(resource)
         self._resources.append(resource)
 
@@ -602,6 +609,7 @@ def object_hint(o):
         oid = oid_repr(oid)
     return "%s oid=%s" % (klass, oid)
 
+# TODO: deprecate for 3.6.
 class DataManagerAdapter(object):
     """Adapt zodb 4-style data managers to zodb3 style
 

src/transaction/interfaces.py

@@ -18,6 +18,17 @@ $Id$
 
 import zope.interface
 
+class ISynchronizer(zope.interface.Interface):
+    """Objects that participate in the transaction-boundary notification API.
+    """
+
+    def beforeCompletion(transaction):
+        """Hook that is called by the transaction at the start of a commit."""
+
+    def afterCompletion(transaction):
+        """Hook that is called by the transaction after completing a commit."""
+
+
 class IDataManager(zope.interface.Interface):
     """Objects that manage transactional storage.
 
@@ -159,12 +170,6 @@ class IDataManager(zope.interface.Interface):
         #which is good enough to avoid ZEO deadlocks.
         #"""
 
-    def beforeCompletion(transaction):
-        """Hook that is called by the transaction before completing a commit"""
-
-    def afterCompletion(transaction):
-        """Hook that is called by the transaction after completing a commit"""
-
 class ITransaction(zope.interface.Interface):
     """Object representing a running transaction.
 
@@ -174,22 +179,28 @@ class ITransaction(zope.interface.Interface):
     """
 
     user = zope.interface.Attribute(
-        "user",
-        "The name of the user on whose behalf the transaction is being\n"
-        "performed.  The format of the user name is defined by the\n"
-        "application.")
-    # Unsure: required to be a string?
+        """A user name associated with the transaction.
+
+        The format of the user name is defined by the application.  The value
+        is of Python type str.  Storages record the user value, as meta-data,
+        when a transaction commits.
+
+        A storage may impose a limit on the size of the value; behavior is
+        undefined if such a limit is exceeded (for example, a storage may
+        raise an exception, or truncate the value).
+        """)
 
     description = zope.interface.Attribute(
-        "description",
-        "Textual description of the transaction.")
+        """A textual description of the transaction.
 
-    def begin(info=None, subtransaction=None):
-        """Begin a new transaction.
+        The value is of Python type str.  Method note() is the intended
+        way to set the value.  Storages record the description, as meta-data,
+        when a transaction commits.
 
-        If the transaction is in progress, it is aborted and a new
-        transaction is started using the same transaction object.
-        """
+        A storage may impose a limit on the size of the description; behavior
+        is undefined if such a limit is exceeded (for example, a storage may
+        raise an exception, or truncate the value).
+        """)
 
     def commit(subtransaction=None):
         """Finalize the transaction.
@@ -213,9 +224,6 @@ class ITransaction(zope.interface.Interface):
         adaptable to ZODB.interfaces.IDataManager.
         """
 
-    def register(object):
-        """Register the given object for transaction control."""
-
     def note(text):
         """Add text to the transaction description.
 
@@ -230,7 +238,8 @@ class ITransaction(zope.interface.Interface):
         """Set the user name.
 
         path should be provided if needed to further qualify the
-        identified user.
+        identified user.  This is a convenience method used by Zope.
+        It sets the .user attribute to str(path) + " " + str(user_name).
         """
 
     def setExtendedInfo(name, value):
@@ -270,18 +279,17 @@ class ITransaction(zope.interface.Interface):
         instead.
         """
 
-class IRollback(zope.interface.Interface):
-
-    def rollback():
-        """Rollback changes since savepoint.
+class ITransactionDeprecated(zope.interface.Interface):
+    """Deprecated parts of the transaction API."""
 
-        IOW, rollback to the last savepoint.
-
-        It is an error to rollback to a savepoint if:
-
-        - An earlier savepoint within the same transaction has been
-          rolled back to, or
+    # TODO: deprecated36
+    def begin(info=None):
+        """Begin a new transaction.
 
-        - The transaction has ended.
+        If the transaction is in progress, it is aborted and a new
+        transaction is started using the same transaction object.
         """
 
+    # TODO: deprecate this for 3.6.
+    def register(object):
+        """Register the given object for transaction control."""

src/transaction/tests/abstestIDataManager.py

@@ -31,7 +31,6 @@ $Id$
 """
 
 from unittest import TestCase
-from transaction.interfaces import IRollback
 
 class IDataManagerTests(TestCase, object):
 
@@ -56,8 +55,3 @@ class IDataManagerTests(TestCase, object):
         tran = self.get_transaction()
         self.datamgr.prepare(tran)
         self.datamgr.abort(tran)
-
-    def testRollback(self):
-        tran = self.get_transaction()
-        rb = self.datamgr.savepoint(tran)
-        self.assert_(IRollback.providedBy(rb))

src/transaction/tests/test_util.py

-##############################################################################
-#
-# Copyright (c) 2004 Zope Corporation and Contributors.
-# All Rights Reserved.
-#
-# This software is subject to the provisions of the Zope Public License,
-# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
-# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
-# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
-# FOR A PARTICULAR PURPOSE.
-#
-##############################################################################
-"""Test transaction utilities
-
-$Id$
-"""
-import unittest
-from zope.testing.doctest import DocTestSuite
-
-def test_suite():
-    return DocTestSuite('transaction.util')
-
-if __name__ == '__main__':
-    unittest.main(defaultTest='test_suite')

src/transaction/util.py

-##############################################################################
-#
-# Copyright (c) 2004 Zope Corporation and Contributors.
-# All Rights Reserved.
-#
-# This software is subject to the provisions of the Zope Public License,
-# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
-# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
-# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
-# FOR A PARTICULAR PURPOSE.
-#
-##############################################################################
-"""Utility classes or functions
-
-$Id$
-"""
-
-from transaction.interfaces import IRollback
-
-try:
-    from zope.interface import implements
-except ImportError:
-    def implements(*args):
-        pass
-
-class NoSavepointSupportRollback:
-    """Rollback for data managers that don't support savepoints
-
-    >>> class DataManager:
-    ...     def savepoint(self, txn):
-    ...         return NoSavepointSupportRollback(self)
-    >>> rb = DataManager().savepoint('some transaction')
-    >>> rb.rollback()
-    Traceback (most recent call last):
-    ...
-    NotImplementedError: """ \
-           """DataManager data managers do not support """ \
-           """savepoints (aka subtransactions
-
-    """
-
-    implements(IRollback)
-
-    def __init__(self, dm):
-        self.dm = dm.__class__.__name__
-
-    def rollback(self):
-        raise NotImplementedError(
-            "%s data managers do not support savepoints (aka subtransactions"
-            % self.dm)