From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 28 Nov 2012 16:14:58 +0000 (-0500)
Subject: more warnings
X-Git-Tag: rel_0_8_0b2~22
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1a3383e3fb597948356623904c97fa05ab7af5be;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

more warnings
---

diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst
index d5cc21e82a..3406894dec 100644
--- a/doc/build/orm/session.rst
+++ b/doc/build/orm/session.rst
@@ -1295,6 +1295,7 @@ things like unique constraint exceptions::
             print "Skipped record %s" % record
     session.commit()
 
+.. _session_autocommit:
 
 Autocommit Mode
 ---------------
@@ -1309,16 +1310,21 @@ results have been iterated.   The :meth:`.Session.flush` operation
 still occurs within the scope of a single transaction, though this transaction
 is closed out after the :meth:`.Session.flush` operation completes.
 
-"autocommit" mode should **not be considered for general use**.   While
-very old versions of SQLAlchemy standardized on this mode, the modern
-:class:`.Session` benefits highly from being given a clear point of transaction
-demarcation via :meth:`.Session.rollback` and :meth:`.Session.commit`.
-The autoflush action can safely emit SQL to the database as needed without
-implicitly producing permanent effects, the contents of attributes
-are expired only when a logical series of steps has completed.   If the
-:class:`.Session` were to be used in pure "autocommit" mode without
-an ongoing transaction, these features should be disabled, that is,
-``autoflush=False, expire_on_commit=False``.
+.. warning::
+
+    "autocommit" mode should **not be considered for general use**.
+    If used, it should always be combined with the usage of
+    :meth:`.Session.begin` and :meth:`.Session.commit`, to ensure
+    a transaction demarcation.
+
+    Executing queries outside of a demarcated transaction is a legacy mode
+    of usage, and can in some cases lead to concurrent connection
+    checkouts.
+
+    In the absense of a demarcated transaction, the :class:`.Session`
+    cannot make appropriate decisions as to when autoflush should
+    occur nor when auto-expiration should occur, so these features
+    should be disabled with ``autoflush=False, expire_on_commit=False``.
 
 Modern usage of "autocommit" is for framework integrations that need to control
 specifically when the "begin" state occurs.  A session which is configured with
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index e4cb908479..16c882a412 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -457,22 +457,29 @@ class Session(_SessionClassMethods):
         generate a :class:`.Session`-producing callable with a given
         set of arguments.
 
-        :param autocommit: Defaults to ``False``. When ``True``, the
-          ``Session`` does not keep a persistent transaction running, and
+        :param autocommit:
+
+          .. warning::
+
+             The autocommit flag is **not for general use**, and if it is used,
+             queries should only be invoked within the span of a
+             :meth:`.Session.begin` / :meth:`.Session.commit` pair.   Executing
+             queries outside of a demarcated transaction is a legacy mode
+             of usage, and can in some cases lead to concurrent connection
+             checkouts.
+
+          Defaults to ``False``. When ``True``, the
+          :class:`.Session` does not keep a persistent transaction running, and
           will acquire connections from the engine on an as-needed basis,
           returning them immediately after their use. Flushes will begin and
           commit (or possibly rollback) their own transaction if no
           transaction is present. When using this mode, the
-          `session.begin()` method may be used to begin a transaction
-          explicitly.
-
-          Leaving it on its default value of ``False`` means that the
-          ``Session`` will acquire a connection and begin a transaction the
-          first time it is used, which it will maintain persistently until
-          ``rollback()``, ``commit()``, or ``close()`` is called. When the
-          transaction is released by any of these methods, the ``Session``
-          is ready for the next usage, which will again acquire and maintain
-          a new connection/transaction.
+          :meth:`.Session.begin` method is used to explicitly start
+          transactions.
+
+          .. seealso::
+
+            :ref:`session_autocommit`
 
         :param autoflush: When ``True``, all query operations will issue a
            ``flush()`` call to this ``Session`` before proceeding. This is a