From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 29 Apr 2021 12:31:57 +0000 (-0400)
Subject: Remove session.begin() example that was for 1.4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=da61b46bbbdb2490a21a5961b22e646967747fb4;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Remove session.begin() example that was for 1.4

the isolation level example here was likely cherry-picked
from 1.4 ; "with session.begin()" isn't normally available
in 1.3.   will also update the 1.4 example for clarity

Change-Id: Ib86019f4b1b70392079596604ec9b0319941e4dc
---

diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst
index 9afbe134a4..5aaf4f2748 100644
--- a/doc/build/orm/session_transaction.rst
+++ b/doc/build/orm/session_transaction.rst
@@ -513,12 +513,22 @@ level on a per-connection basis can be affected by using the
 
     from sqlalchemy.orm import Session
 
+    # assume session just constructed
     sess = Session(bind=engine)
-    with sess.begin():
-        sess.connection(execution_options={'isolation_level': 'SERIALIZABLE'})
 
-    # commits transaction.  the connection is released
+    # call connection() with options before any other operations proceed.
+    # this will procure a new connection from the bound engine and begin a real
+    # database transaction.
+    sess.connection(execution_options={'isolation_level': 'SERIALIZABLE'})
+
+    # ... work with session in SERIALIZABLE isolation level...
+
+    # commit transaction.  the connection is released
     # and reverted to its previous isolation level.
+    sess.commit()
+
+    # here, a new "transaction" is in play and isolation level may be set
+    # again if another transaction is to be used
 
 Above, we first produce a :class:`.Session` using either the constructor
 or a :class:`.sessionmaker`.   Then we explicitly set up the start of