From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Tue, 23 May 2017 15:35:12 +0000 (-0400)
Subject: - add session.close() w/ rationale to top-level "using transactions"
X-Git-Tag: rel_1_2_0b1~49
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7fc7492d86f6e5ca105743a184cd07190e9f9b28;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- 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 c508d8b35b..955ec02f6e 100644
--- 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: