- add session.close() w/ rationale to top-level "using transactions"

 section.  References #3974

Change-Id: Idb650cbe9825cfae893ee917132b5b9d693f0c6c

diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst
index c508d8b35bf0064c46a65fe1f87a472cf13f27da..955ec02f6e6cf6be48a0afeb52467b8a66aa1a0a 100644 (file)
--- a/doc/build/orm/session_transaction.rst
+++ b/doc/build/orm/session_transaction.rst
@@ -75,6 +75,15 @@ The example below illustrates this lifecycle::
         # as that of commit proceeds.
         session.rollback()
         raise
+    finally:
+        # close the Session.  This will expunge any remaining
+        # objects as well as reset any existing SessionTransaction
+        # state.  Neither of these steps are usually essential.
+        # However, if the commit() or rollback() itself experienced
+        # an unanticipated internal failure (such as due to a mis-behaved
+        # user-defined event handler), .close() will ensure that 
+        # invalid state is removed.
+        session.close()
 
 .. _session_begin_nested: