Documentation updates for 1.4

* major additions to 1.4 migration doc; removed additional
  verbosity regarding caching methodology and reorganized the
  doc to present itself more as a "what's changed" guide

* as we now have a path for asyncio, update that doc so that
  we aren't spreading obsolete information

* updates to the 2.0 migration guide with latest info, however
  this is still an architecture doc and not a migration guide
  yet, will need further rework.

* start really talking about 1.x vs. 2.0 style everywhere.  Querying
  is most of the docs so this is going to be a prominent
  theme, start getting it to fit in

* Add introductory documentation for ORM example sections as these
  are too sparse

* new documentation for do_orm_execute(), many separate sections,
  adding deprecation notes to before_compile() and similar

* new example suites to illustrate do_orm_execute(),
  with_loader_criteria()

* modernized horizontal sharding examples and added a separate
  example to distinguish between multiple databases and single
  database w/ multiple tables use case

* introducing DEEP ALCHEMY, will use zzzeeksphinx 1.1.6

* no name for the alchemist yet however the dragon's name
  is Flambé

Change-Id: Id6b5c03b1ce9ddb7b280f66792212a0ef0a1c541

1 files changed, 46 insertions, 15 deletions

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index e9d4ac2c6..ed1af0a80 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -107,6 +107,10 @@ class ORMExecuteState(util.MemoizedSlots):
 
     .. versionadded:: 1.4
 
+    .. seealso::
+
+        :ref:`session_execute_events` - top level documentation on how
+        to use :meth:`_orm.SessionEvents.do_orm_execute`
 
     """
 
@@ -158,14 +162,24 @@ class ORMExecuteState(util.MemoizedSlots):
         bind_arguments=None,
     ):
         """Execute the statement represented by this
-        :class:`.ORMExecuteState`, without re-invoking events.
-
-        This method essentially performs a re-entrant execution of the
-        current statement for which the :meth:`.SessionEvents.do_orm_execute`
-        event is being currently invoked.    The use case for this is
-        for event handlers that want to override how the ultimate results
-        object is returned, such as for schemes that retrieve results from
-        an offline cache or which concatenate results from multiple executions.
+        :class:`.ORMExecuteState`, without re-invoking events that have
+        already proceeded.
+
+        This method essentially performs a re-entrant execution of the current
+        statement for which the :meth:`.SessionEvents.do_orm_execute` event is
+        being currently invoked.    The use case for this is for event handlers
+        that want to override how the ultimate
+        :class:`_engine.Result` object is returned, such as for schemes that
+        retrieve results from an offline cache or which concatenate results
+        from multiple executions.
+
+        When the :class:`_engine.Result` object is returned by the actual
+        handler function within :meth:`_orm.SessionEvents.do_orm_execute` and
+        is propagated to the calling
+        :meth:`_orm.Session.execute` method, the remainder of the
+        :meth:`_orm.Session.execute` method is preempted and the
+        :class:`_engine.Result` object is returned to the caller of
+        :meth:`_orm.Session.execute` immediately.
 
         :param statement: optional statement to be invoked, in place of the
          statement currently represented by :attr:`.ORMExecuteState.statement`.
@@ -970,13 +984,30 @@ class Session(_SessionClassMethods):
            transaction will load from the most recent database state.
 
         :param future: if True, use 2.0 style behavior for the
-          :meth:`_orm.Session.execute` method.  This includes that the
-          :class:`_engine.Result` object returned will return new-style
-          tuple rows, as well as that Core constructs such as
-          :class:`_sql.Select`,
-          :class:`_sql.Update` and :class:`_sql.Delete` will be interpreted
-          in an ORM context if they are made against ORM entities rather than
-          plain :class:`.Table` metadata objects.
+          :meth:`_orm.Session.execute` method.   Future mode includes the
+          following behaviors:
+
+          * The :class:`_engine.Result` object returned by the
+            :meth:`_orm.Session.execute` method will return new-style tuple
+            :class:`_engine.Row` objects
+
+          * The :meth:`_orm.Session.execute` method will invoke ORM style
+            queries given objects like :class:`_sql.Select`,
+            :class:`_sql.Update` and :class:`_sql.Delete` against ORM entities
+
+          * The :class:`_orm.Session` will not use "bound" metadata in order
+            to locate an :class:`_engine.Engine`; the engine or engines in use
+            must be specified to the constructor of :class:`_orm.Session` or
+            otherwise be configured against the :class:`_orm.sessionmaker`
+            in use
+
+          * The "subtransactions" feature of :meth:`_orm.Session.begin` is
+            removed in version 2.0 and is disabled when the future flag is
+            set.
+
+          * The behavior of the :paramref:`_orm.relationship.cascade_backrefs`
+            flag on a :func:`_orm.relationship` will always assume
+            "False" behavior.
 
           The "future" flag is also available on a per-execution basis
           using the :paramref:`_orm.Session.execute.future` flag.