Create initial 2.0 engine implementation

Implemented the SQLAlchemy 2 :func:`.future.create_engine` function which
is used for forwards compatibility with SQLAlchemy 2.   This engine
features always-transactional behavior with autobegin.

Allow execution options per statement execution.  This includes
that the before_execute() and after_execute() events now accept
an additional dictionary with these options, empty if not
passed; a legacy event decorator is added for backwards compatibility
which now also emits a deprecation warning.

Add some basic tests for execution, transactions, and
the new result object.   Build out on a new testing fixture
that swaps in the future engine completely to start with.

Change-Id: I70e7338bb3f0ce22d2f702537d94bb249bd9fb0a
Fixes: #4644

1 files changed, 64 insertions, 4 deletions

diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py
index 65b73002c..2ab707b8a 100644
--- a/lib/sqlalchemy/engine/events.py
+++ b/lib/sqlalchemy/engine/events.py
@@ -107,9 +107,15 @@ class ConnectionEvents(event.Events):
                 orig_fn = fn
 
                 def wrap_before_execute(
-                    conn, clauseelement, multiparams, params
+                    conn, clauseelement, multiparams, params, execution_options
                 ):
-                    orig_fn(conn, clauseelement, multiparams, params)
+                    orig_fn(
+                        conn,
+                        clauseelement,
+                        multiparams,
+                        params,
+                        execution_options,
+                    )
                     return clauseelement, multiparams, params
 
                 fn = wrap_before_execute
@@ -143,7 +149,19 @@ class ConnectionEvents(event.Events):
             )
         event_key.with_wrapper(fn).base_listen()
 
-    def before_execute(self, conn, clauseelement, multiparams, params):
+    @event._legacy_signature(
+        "1.4",
+        ["conn", "clauseelement", "multiparams", "params"],
+        lambda conn, clauseelement, multiparams, params, execution_options: (
+            conn,
+            clauseelement,
+            multiparams,
+            params,
+        ),
+    )
+    def before_execute(
+        self, conn, clauseelement, multiparams, params, execution_options
+    ):
         """Intercept high level execute() events, receiving uncompiled
         SQL constructs and other objects prior to rendering into SQL.
 
@@ -166,6 +184,17 @@ class ConnectionEvents(event.Events):
          :meth:`_engine.Connection.execute`.
         :param multiparams: Multiple parameter sets, a list of dictionaries.
         :param params: Single parameter set, a single dictionary.
+        :param execution_options: dictionary of per-execution execution
+         options passed along with the statement, if any.  This only applies to
+         the the SQLAlchemy 2.0 version of  :meth:`_engine.Connection.execute`
+         .   To
+         view all execution options associated with the connection, access the
+         :meth:`_engine.Connection.get_execution_options`
+         method to view the fixed
+         execution options dictionary, then consider elements within this local
+         dictionary to be unioned into that dictionary.
+
+         .. versionadded: 1.4
 
         .. seealso::
 
@@ -173,7 +202,26 @@ class ConnectionEvents(event.Events):
 
         """
 
-    def after_execute(self, conn, clauseelement, multiparams, params, result):
+    @event._legacy_signature(
+        "1.4",
+        ["conn", "clauseelement", "multiparams", "params", "result"],
+        lambda conn, clauseelement, multiparams, params, execution_options, result: (  # noqa
+            conn,
+            clauseelement,
+            multiparams,
+            params,
+            result,
+        ),
+    )
+    def after_execute(
+        self,
+        conn,
+        clauseelement,
+        multiparams,
+        params,
+        execution_options,
+        result,
+    ):
         """Intercept high level execute() events after execute.
 
 
@@ -183,6 +231,18 @@ class ConnectionEvents(event.Events):
          :meth:`_engine.Connection.execute`.
         :param multiparams: Multiple parameter sets, a list of dictionaries.
         :param params: Single parameter set, a single dictionary.
+        :param execution_options: dictionary of per-execution execution
+         options passed along with the statement, if any.  This only applies to
+         the the SQLAlchemy 2.0 version of  :meth:`_engine.Connection.execute`
+         .   To
+         view all execution options associated with the connection, access the
+         :meth:`_engine.Connection.get_execution_options`
+         method to view the fixed
+         execution options dictionary, then consider elements within this local
+         dictionary to be unioned into that dictionary.
+
+         .. versionadded: 1.4
+
         :param result: :class:`_engine.ResultProxy` generated by the execution
                       .