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 c877ae3b843a05666c3e226a02680137dcf9a956..992e64e31c7796fe6318fcd57ee1d0834ddf02cb 100644 (file)
--- 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.