- execution_options() on Connection accepts

"isolation_level" argument, sets transaction isolation
level for that connection only until returned to the
connection pool, for thsoe backends which support it
(SQLite, Postgresql) [ticket:2001]
- disallow the option on Engine (use isolation_level to create_engine()),
Executable (we don't want to check/set per statement)
- docs

1 files changed, 25 insertions, 11 deletions

diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 6a368b8c0..8a9d33d55 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -2563,9 +2563,7 @@ class Executable(_Generative):
         """ Set non-SQL options for the statement which take effect during
         execution.
 
-        Current options include:
-
-        * autocommit - when True, a COMMIT will be invoked after execution 
+        :param autocommit: when True, a COMMIT will be invoked after execution 
           when executed in 'autocommit' mode, i.e. when an explicit
           transaction is not begun on the connection. Note that DBAPI
           connections by default are always in a transaction - SQLAlchemy uses
@@ -2577,15 +2575,15 @@ class Executable(_Generative):
           specific SQL construct where COMMIT is desired (typically when
           calling stored procedures and such).
 
-        * stream_results - indicate to the dialect that results should be 
+        :param stream_results: indicate to the dialect that results should be 
           "streamed" and not pre-buffered, if possible.  This is a limitation
           of many DBAPIs.  The flag is currently understood only by the
           psycopg2 dialect.
 
-        * compiled_cache - a dictionary where :class:`Compiled` objects
-          will be cached when the :class:`Connection` compiles a clause 
+        :param compiled_cache: a dictionary where :class:`.Compiled` objects
+          will be cached when the :class:`.Connection` compiles a clause 
           expression into a dialect- and parameter-specific 
-          :class:`Compiled` object.   It is the user's responsibility to
+          :class:`.Compiled` object.   It is the user's responsibility to
           manage the size of this dictionary, which will have keys
           corresponding to the dialect, clause element, the column
           names within the VALUES or SET clause of an INSERT or UPDATE, 
@@ -2595,17 +2593,33 @@ class Executable(_Generative):
 
           This option is usually more appropriate
           to use via the 
-          :meth:`sqlalchemy.engine.base.Connection.execution_options()`
-          method of :class:`Connection`, rather than upon individual 
+          :meth:`.Connection.execution_options()`
+          method of :class:`.Connection`, rather than upon individual 
           statement objects, though the effect is the same.
+          
+          Note that the ORM makes use of its own "compiled" caches for 
+          some operations, including flush operations.  The caching
+          used by the ORM internally supercedes a cache dictionary
+          specified here.
 
         See also:
 
-            :meth:`sqlalchemy.engine.base.Connection.execution_options()`
+            :meth:`.Connection.execution_options()` -
+            includes a connection-only option to specify transaction isolation
+            level.
 
-            :meth:`sqlalchemy.orm.query.Query.execution_options()`
+            :meth:`.Query.execution_options()` - applies options to the statement
+            generated by a :class:`.orm.Query` object.
 
         """
+        if 'isolation_level' in kw:
+            raise exc.ArgumentError(
+                "'isolation_level' execution option may only be specified "
+                "on Connection.execution_options(), or "
+                "per-engine using the isolation_level "
+                "argument to create_engine()."
+            )
+
         self._execution_options = self._execution_options.union(kw)
 
     def execute(self, *multiparams, **params):