Add note on begin_nested requiring rollback/commit

Avoid confusion about rollback/commit "must be issued" after
``session.begin_nested()`` --- this might be taken to mean call must be
*added*, but that's only true if not using the return value as a context
manager.

diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst
index b47e70d53725b229ccd4075f7eeab01c7104a56b..78ae1ba81466f6c0f62a29d810c92b7868f822f9 100644 (file)
--- a/doc/build/orm/session.rst
+++ b/doc/build/orm/session.rst
@@ -1773,7 +1773,10 @@ method::
 of times, which will issue a new SAVEPOINT with a unique identifier for each
 call. For each :meth:`~.Session.begin_nested` call, a
 corresponding :meth:`~.Session.rollback` or
-:meth:`~.Session.commit` must be issued.
+:meth:`~.Session.commit` must be issued. (But note that if the return value is
+used as a context manager, i.e. in a with-statement, then this rollback/commit
+is issued by the context manager upon exiting the context, and so should not be
+added explicitly.)
 
 When :meth:`~.Session.begin_nested` is called, a
 :meth:`~.Session.flush` is unconditionally issued