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 a6a36222ef18389213270b1b4e6255a1ca74e292..eab623832ea2787bd804bc9f0212e0218e4e1a25 100644 (file)
--- 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 cec9ebf307a79049d2230df23bbcfd3ad377a8b4..bebf5cb5963a9fa66d25a4f7d2f181c305626841 100644 (file)
--- 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 5ed79ea5039750fe491ac5bebd738e09808aa4eb..6c58afa21247072c22431cce4754c6bb564c4bd9 100644 (file)
--- 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