From: jonathan vanasco <jonathan@2xlp.com>
Date: Fri, 4 Sep 2020 23:48:38 +0000 (-0400)
Subject: added docstring about expire_on_commit for #5243
X-Git-Tag: rel_1_3_21~25
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e3aa1ffeba58ef37ced669a53aa93ac55ccab3db;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

added docstring about expire_on_commit for #5243

Fixes: #5243
Closes: #5328
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/5328
Pull-request-sha: e760ed4ef1749aadfb8d63d776c764d98b93b1e5

Change-Id: I8e7bc3429dc279d447cc66400c76b4d2a04626aa
(cherry picked from commit 10851b002844fa4f9de7af92dbb15cb1133497eb)
---

diff --git a/doc/build/errors.rst b/doc/build/errors.rst
index a6a36222ef..eab623832e 100644
--- a/doc/build/errors.rst
+++ b/doc/build/errors.rst
@@ -596,15 +596,25 @@ Mitigation of this error is via two general techniques:
   to pass objects off to other systems that can't run in the same context
   even though they're in the same process.  In this case, the application
   should try to make appropriate use of :term:`eager loading` to ensure
-  that objects have what they need up front.   As an additional measure,
-  special directives like the :func:`.raiseload` option can ensure that
-  systems don't call upon lazy loading when its not expected.
+  that objects have what they need up front.
+
+  When using this approach, it is usually necessary that the
+  :paramref:`_orm.Session.expire_on_commit` parameter be set to ``False``, so
+  that after a :meth:`_orm.Session.commit` operation, the objects within the
+  session aren't :term:`expired`, which would incur a lazy load if their
+  attributes were subsequently accessed.  Additionally, the
+  :meth:`_orm.Session.rollback` method unconditionally expires all contents in
+  the :class:`_orm.Session` and should also be avoided in non-error scenarios.
 
   .. seealso::
 
     :ref:`loading_toplevel` - detailed documentation on eager loading and other
     relationship-oriented loading techniques
 
+    :ref:`session_committing` - background on session commit
+
+    :ref:`session_expire` - background on attribute expiry
+
 
 .. _error_7s2a:
 
diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst
index cec9ebf307..bebf5cb596 100644
--- a/doc/build/glossary.rst
+++ b/doc/build/glossary.rst
@@ -460,6 +460,7 @@ Glossary
             :doc:`orm/session`
 
     expire
+    expired
     expires
     expiring
     Expiring
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 5ed79ea503..6c58afa212 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -803,6 +803,10 @@ class Session(_SessionClassMethods):
            so that all attribute/object access subsequent to a completed
            transaction will load from the most recent database state.
 
+            .. seealso::
+
+                :ref:`session_committing`
+
         :param extension: An optional
            :class:`~.SessionExtension` instance, or a list
            of such instances, which will receive pre- and post- commit and
@@ -3255,8 +3259,10 @@ class sessionmaker(_SessionClassMethods):
          :class:`.Session` objects.
         :param autocommit: The autocommit setting to use with newly created
          :class:`.Session` objects.
-        :param expire_on_commit=True: the expire_on_commit setting to use
+        :param expire_on_commit=True: the
+         :paramref:`_orm.Session.expire_on_commit` setting to use
          with newly created :class:`.Session` objects.
+
         :param info: optional dictionary of information that will be available
          via :attr:`.Session.info`.  Note this dictionary is *updated*, not
          replaced, when the ``info`` parameter is specified to the specific