Convert execution to move through Session

This patch replaces the ORM execution flow with a
single pathway through Session.execute() for all queries,
including Core and ORM.

Currently included is full support for ORM Query,
Query.from_statement(), select(), as well as the
baked query and horizontal shard systems.  Initial
changes have also been made to the dogpile caching
example, which like baked query makes use of a
new ORM-specific execution hook that replaces the
use of both QueryEvents.before_compile() as well
as Query._execute_and_instances() as the central
ORM interception hooks.

select() and Query() constructs alike can be passed to
Session.execute() where they will return ORM
results in a Results object.   This API is currently
used internally by Query.   Full support for
Session.execute()->results to behave in a fully
2.0 fashion will be in later changesets.

bulk update/delete with ORM support will also
be delivered via the update() and delete()
constructs, however these have not yet been adapted
to the new system and may follow in a subsequent
update.

Performance is also beginning to lag as of this
commit and some previous ones.   It is hoped that
a few central functions such as the coercions
functions can be rewritten in C to re-gain
performance.  Additionally, query caching
is now available and some subsequent patches
will attempt to cache more of the per-execution
work from the ORM layer, e.g. column getters
and adapters.

This patch also contains initial "turn on" of the
caching system enginewide via the query_cache_size
parameter to create_engine(). Still defaulting at
zero for "no caching".   The caching system still
needs adjustments in order to gain adequate performance.

Change-Id: I047a7ebb26aa85dc01f6789fac2bff561dcd555d

2 files changed, 42 insertions, 3 deletions

diff --git a/doc/build/orm/extensions/baked.rst b/doc/build/orm/extensions/baked.rst
index 8614cd048..951f35e6a 100644
--- a/doc/build/orm/extensions/baked.rst
+++ b/doc/build/orm/extensions/baked.rst
@@ -20,6 +20,11 @@ cache the **return results** from the database.  A technique that demonstrates
 the caching of the SQL calls and result sets themselves is available in
 :ref:`examples_caching`.
 
+.. deprecated:: 1.4  SQLAlchemy 1.4 and 2.0 feature an all-new direct query
+   caching system that removes the need for the :class:`.BakedQuery` system.
+   Caching is now built in to all Core and ORM queries using the
+   :paramref:`.create_engine.query_cache_size` parameter.
+
 
 .. versionadded:: 1.0.0
 
diff --git a/doc/build/orm/session_api.rst b/doc/build/orm/session_api.rst
index e247a8de7..849472e9f 100644
--- a/doc/build/orm/session_api.rst
+++ b/doc/build/orm/session_api.rst
@@ -1,4 +1,4 @@
-.. currentmodule:: sqlalchemy.orm.session
+.. currentmodule:: sqlalchemy.orm
 
 Session API
 ===========
@@ -10,11 +10,45 @@ Session and sessionmaker()
     :members:
     :inherited-members:
 
-.. autoclass:: sqlalchemy.orm.session.Session
+.. autoclass:: ORMExecuteState
+   :members:
+
+
+  .. attribute::  session
+
+      The :class:`_orm.Session` in use.
+
+  .. attribute:: statement
+
+      The SQL statement being invoked.  For an ORM selection as would
+      be retrieved from :class:`_orm.Query`, this is an instance of
+      :class:`_future.select` that was generated from the ORM query.
+
+  .. attribute:: parameters
+
+      Dictionary of parameters that was passed to :meth:`_orm.Session.execute`.
+
+  .. attribute:: execution_options
+
+      Dictionary of execution options passed to :meth:`_orm.Session.execute`.
+      Note that this dictionary does not include execution options that may
+      be associated with the statement itself, or with any underlying
+      :class:`_engine.Connection` that may be used to invoke this statement.
+
+  .. attribute:: bind_arguments
+
+      The dictionary passed as the
+      :paramref:`_orm.Session.execute.bind_arguments` dictionary.  This
+      dictionary may be used by extensions to :class:`_orm.Session` to pass
+      arguments that will assist in determining amongst a set of database
+      connections which one should be used to invoke this statement.
+
+
+.. autoclass:: Session
    :members:
    :inherited-members:
 
-.. autoclass:: sqlalchemy.orm.session.SessionTransaction
+.. autoclass:: SessionTransaction
    :members:
 
 Session Utilities