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_4_0b1~15
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=10851b002844fa4f9de7af92dbb15cb1133497eb;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
---

diff --git a/doc/build/errors.rst b/doc/build/errors.rst
index 6a3c6a3dd2..69664ae1df 100644
--- a/doc/build/errors.rst
+++ b/doc/build/errors.rst
@@ -854,15 +854,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 3997b95249..d51d696e30 100644
--- a/doc/build/glossary.rst
+++ b/doc/build/glossary.rst
@@ -549,6 +549,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 af0ac63e0d..37ca1523ad 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -953,6 +953,11 @@ 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 future: if True, use 2.0 style behavior for the
           :meth:`_orm.Session.execute` method.   Future mode includes the
           following behaviors:
@@ -3838,8 +3843,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