]> git.ipfire.org Git - thirdparty/sqlalchemy/sqlalchemy.git/commitdiff
added docstring about expire_on_commit for #5243
authorjonathan vanasco <jonathan@2xlp.com>
Fri, 4 Sep 2020 23:48:38 +0000 (19:48 -0400)
committerMike Bayer <mike_mp@zzzcomputing.com>
Mon, 26 Oct 2020 14:49:27 +0000 (10:49 -0400)
Fixes: #5243
Closes: #5328
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/5328
Pull-request-sha: e760ed4ef1749aadfb8d63d776c764d98b93b1e5

Change-Id: I8e7bc3429dc279d447cc66400c76b4d2a04626aa

doc/build/errors.rst
doc/build/glossary.rst
lib/sqlalchemy/orm/session.py

index 6a3c6a3dd2e90808115da4f7346ef71d25b18662..69664ae1df29fbc3f3cf0cd5241d9a18eabc0681 100644 (file)
@@ -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:
 
index 3997b95249b0cdafa52201bf774091fb7325c8b4..d51d696e30f74e761c62f989fc1624a103ca79d2 100644 (file)
@@ -549,6 +549,7 @@ Glossary
             :doc:`orm/session`
 
     expire
+    expired
     expires
     expiring
     Expiring
index af0ac63e0d26510eb55646309f61a2dfcfec7ce0..37ca1523ad2b4e2ee22c53873682925d6f2bf1c7 100644 (file)
@@ -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