Document NestedTransaction

Fixes: #3550
Change-Id: Ic2ff36ea434923590d2adbd101580025da319f66

diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index 7d90d1cae02ab89daf5bf7dd12482170a844dd27..17fca63bfe72e834ce6c71e316aa3bda72f516bf 100644 (file)
--- a/doc/build/core/connections.rst
+++ b/doc/build/core/connections.rst
@@ -1804,12 +1804,18 @@ Connection / Engine API
 
 .. autoclass:: NestedTransaction
     :members:
+    :inherited-members:
+
+.. autoclass:: RootTransaction
+    :members:
+    :inherited-members:
 
 .. autoclass:: Transaction
     :members:
 
 .. autoclass:: TwoPhaseTransaction
     :members:
+    :inherited-members:
 
 
 Result Set  API

diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst
index 7daa47ef74d93195ed27c960985b0f8213bc1283..1deefc8df366159b5345b7aff8012e2ac7da2430 100644 (file)
--- a/doc/build/orm/session_transaction.rst
+++ b/doc/build/orm/session_transaction.rst
@@ -171,6 +171,12 @@ session is expired, thus causing all subsequent attribute/instance access to
 reference the full state of the :class:`~sqlalchemy.orm.session.Session` right
 before :meth:`~.Session.begin_nested` was called.
 
+.. seealso::
+
+    :class:`_engine.NestedTransaction` - the :class:`.NestedTransaction` class is the
+    Core-level construct that is used by the :class:`_orm.Session` internally
+    to produce SAVEPOINT blocks.
+
 .. _orm_session_vs_engine:
 
 Session-level vs. Engine level transaction control

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 362c811eeb60766fb62f8b1faf5fc3907ae32da9..906de08bb485fdb141de5da8f3320bf5ba46b080 100644 (file)
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -2211,14 +2211,43 @@ class Transaction(object):
             assert not self.is_active
 
     def rollback(self):
-        """Roll back this :class:`.Transaction`."""
+        """Roll back this :class:`.Transaction`.
+
+        The implementation of this may vary based on the type of transaction in
+        use:
+
+        * For a simple database transaction (e.g. :class:`.RootTransaction`),
+          it corresponds to a ROLLBACK.
+
+        * For a :class:`.NestedTransaction`, it corresponds to a
+          "ROLLBACK TO SAVEPOINT" operation.
+
+        * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
+          phase transactions may be used.
+
+
+        """
         try:
             self._do_rollback()
         finally:
             assert not self.is_active
 
     def commit(self):
-        """Commit this :class:`.Transaction`."""
+        """Commit this :class:`.Transaction`.
+
+        The implementation of this may vary based on the type of transaction in
+        use:
+
+        * For a simple database transaction (e.g. :class:`.RootTransaction`),
+          it corresponds to a COMMIT.
+
+        * For a :class:`.NestedTransaction`, it corresponds to a
+          "RELEASE SAVEPOINT" operation.
+
+        * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
+          phase transactions may be used.
+
+        """
 
         try:
             self._do_commit()
@@ -2296,6 +2325,18 @@ class MarkerTransaction(Transaction):
 
 
 class RootTransaction(Transaction):
+    """Represent the "root" transaction on a :class:`_engine.Connection`.
+
+    This corresponds to the current "BEGIN/COMMIT/ROLLBACK" that's occurring
+    for the :class:`_engine.Connection`.
+
+    The :class:`_engine.RootTransaction` object is accessible via the
+    :attr:`_engine.Connection.get_transaction` method of
+    :class:`_engine.Connection`.
+
+
+    """
+
     _is_root = True
 
     __slots__ = ("connection", "is_active")
@@ -2400,10 +2441,32 @@ class RootTransaction(Transaction):
 class NestedTransaction(Transaction):
     """Represent a 'nested', or SAVEPOINT transaction.
 
-    A new :class:`.NestedTransaction` object may be procured
-    using the :meth:`_engine.Connection.begin_nested` method.
+    The :class:`.NestedTransaction` object is created by calling the
+    :meth:`_engine.Connection.begin_nested` method of
+    :class:`_engine.Connection`.
+
+    When using :class:`.NestedTransaction`, the semantics of "begin" /
+    "commit" / "rollback" are as follows:
+
+    * the "begin" operation corresponds to the "BEGIN SAVEPOINT" command, where
+      the savepoint is given an explicit name that is part of the state
+      of this object.
+
+    * The :meth:`.NestedTransaction.commit` method corresponds to a
+      "RELEASE SAVEPOINT" operation, using the savepoint identifier associated
+      with this :class:`.NestedTransaction`.
+
+    * The :meth:`.NestedTransaction.rollback` method corresponds to a
+      "ROLLBACK TO SAVEPOINT" operation, using the savepoint identifier
+      associated with this :class:`.NestedTransaction`.
+
+    The rationale for mimicking the semantics of an outer transaction in
+    terms of savepoints so that code may deal with a "savepoint" transaction
+    and an "outer" transaction in an agnostic way.
+
+    .. seealso::
 
-    The interface is the same as that of :class:`.Transaction`.
+        :ref:`session_begin_nested` - ORM version of the SAVEPOINT API.
 
     """