Gunnlaugur Þór Briem committed 42a6501

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

Comments (0)

Files changed (1)


 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