From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 8 Apr 2022 14:56:54 +0000 (-0400)
Subject: i forgot about begin_nested()
X-Git-Tag: rel_2_0_0b1~366
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4acf50c8e86b6b047853b2bc96ccaa494811085f;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

i forgot about begin_nested()

make bulleted lists of what is autoflush and what's not.

Change-Id: Id3bc4714013e9df243d804d7b5b60c6ef75e1316
---

diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst
index c877ae3b84..992e64e31c 100644
--- a/doc/build/orm/session_basics.rst
+++ b/doc/build/orm/session_basics.rst
@@ -429,11 +429,26 @@ A :class:`.Session` flush can be forced at any time by calling the
 
     session.flush()
 
-The flush which occurs automatically within the scope of
-:meth:`_orm.Session.execute`, :class:`_query.Query`, as well as other
-:class:`.Session` methods such as :meth:`.Session.merge` (but **not** including
-the :meth:`.Session.commit` method) is known as **autoflush**. This "autoflush"
-behavior can be disabled by constructing a :class:`.Session` or
+The flush which occurs automatically within the scope of certain methods
+is known as **autoflush**.  Autoflush is defined as a configurable,
+automatic flush call which occurs at the beginning of methods including:
+
+* :meth:`_orm.Session.execute` and other SQL-executing methods
+* When a :class:`_query.Query` is invoked to send SQL to the database
+* Within the :meth:`.Session.merge` method before querying the database
+* When objects are :ref:`refreshed <session_expiring>`
+* When ORM :term:`lazy load` operations occur against unloaded object
+  attributes.
+
+There are also points at which flushes occur **unconditionally**; these
+points are within key transactional boundaries which include:
+
+* Within the process of the :meth:`.Session.commit` method
+* When :meth:`.Session.begin_nested` is called
+* When the :meth:`.Session.prepare` 2PC method is used.
+
+The **autoflush** behavior, as applied to the previous list of items,
+can be disabled by constructing a :class:`.Session` or
 :class:`.sessionmaker` passing the :paramref:`.Session.autoflush` parameter as
 ``False``::
 
@@ -447,7 +462,8 @@ of using a :class:`.Session` using the
         mysession.add(some_object)
         mysession.flush()
 
-The flush process **always occurs** when the :meth:`.Session.commit` method is
+**To reiterate:** The flush process **always occurs** when transactional
+methods such as :meth:`.Session.commit` and :meth:`.Session.begin_nested` are
 called, regardless of any "autoflush" settings, when the :class:`.Session` has
 remaining pending changes to process.