From 4c6917e1d68a8baab7efe10e9ce5e5c8187f65ca Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 17 May 2017 10:46:52 -0400
Subject: [PATCH] - add complete parameter /return value docs to
 session.begin() / session.begin_nested().  Fixes #3993

Change-Id: If485d77b364c34d94061d2f48efbde3f8a8adec9
---
 doc/build/orm/session_transaction.rst |  4 +-
 lib/sqlalchemy/orm/session.py         | 58 +++++++++++++++++++++------
 2 files changed, 47 insertions(+), 15 deletions(-)

diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst
index ede455223d..e686fd7f6d 100644
--- a/doc/build/orm/session_transaction.rst
+++ b/doc/build/orm/session_transaction.rst
@@ -114,8 +114,8 @@ reference the full state of the :class:`~sqlalchemy.orm.session.Session` right
 before :meth:`~.Session.begin_nested` was called.
 
 :meth:`~.Session.begin_nested`, in the same manner as the less often
-used :meth:`~.Session.begin` method, returns a transactional object
-which also works as a context manager.
+used :meth:`~.Session.begin` method, returns a :class:`.SessionTransaction` object
+which works as a context manager.
 It can be succinctly used around individual record inserts in order to catch
 things like unique constraint exceptions::
 
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 0d2fe6a7f8..3585166f49 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -776,18 +776,37 @@ class Session(_SessionClassMethods):
     def begin(self, subtransactions=False, nested=False):
         """Begin a transaction on this :class:`.Session`.
 
-        If this Session is already within a transaction, either a plain
-        transaction or nested transaction, an error is raised, unless
-        ``subtransactions=True`` or ``nested=True`` is specified.
+        The :meth:`.Session.begin` method is only
+        meaningful if this session is in **autocommit mode** prior to
+        it being called; see :ref:`session_autocommit` for background
+        on this setting.
+
+        The method will raise an error if this :class:`.Session`
+        is already inside of a transaction, unless
+        :paramref:`.Session.begin.subtransactions` or
+        :paramref:`.Session.begin.nested` are specified.
+
+        :param subtransactions: if True, indicates that this
+         :meth:`~.Session.begin` can create a subtransaction if a transaction
+         is already in progress. For documentation on subtransactions, please
+         see :ref:`session_subtransactions`.
+
+        :param nested: if True, begins a SAVEPOINT transaction and is equivalent
+         to calling :meth:`~.Session.begin_nested`. For documentation on
+         SAVEPOINT transactions, please see :ref:`session_begin_nested`.
+
+        :return: the :class:`.SessionTransaction` object.  Note that
+         :class:`.SessionTransaction`
+         acts as a Python context manager, allowing :meth:`.Session.begin`
+         to be used in a "with" block.  See :ref:`session_autocommit` for
+         an example.
 
-        The ``subtransactions=True`` flag indicates that this
-        :meth:`~.Session.begin` can create a subtransaction if a transaction
-        is already in progress. For documentation on subtransactions, please
-        see :ref:`session_subtransactions`.
+        .. seealso::
+
+            :ref:`session_autocommit`
+
+            :meth:`.Session.begin_nested`
 
-        The ``nested`` flag begins a SAVEPOINT transaction and is equivalent
-        to calling :meth:`~.Session.begin_nested`. For documentation on
-        SAVEPOINT transactions, please see :ref:`session_begin_nested`.
 
         """
         if self.transaction is not None:
@@ -804,14 +823,27 @@ class Session(_SessionClassMethods):
         return self.transaction  # needed for __enter__/__exit__ hook
 
     def begin_nested(self):
-        """Begin a `nested` transaction on this Session.
+        """Begin a "nested" transaction on this Session, e.g. SAVEPOINT.
 
-        The target database(s) must support SQL SAVEPOINTs or a
-        SQLAlchemy-supported vendor implementation of the idea.
+        The target database(s) and associated drivers must support SQL
+        SAVEPOINT for this method to function correctly.
 
         For documentation on SAVEPOINT
         transactions, please see :ref:`session_begin_nested`.
 
+        :return: the :class:`.SessionTransaction` object.  Note that
+         :class:`.SessionTransaction` acts as a context manager, allowing
+         :meth:`.Session.begin_nested` to be used in a "with" block.
+         See :ref:`session_begin_nested` for a usage example.
+
+        .. seealso::
+
+            :ref:`session_begin_nested`
+
+            :ref:`pysqlite_serializable` - special workarounds required
+            with the SQLite driver in order for SAVEPOINT to work
+            correctly.
+
         """
         return self.begin(nested=True)
 
-- 
2.39.5