- move documentation of available execution options to Connection - this is the main

place these should be used
- Executable disallows "compiled_cache" option for now which was previously being ignored
[ticket:2131]
- Query now passes execution options to the Connection rather than the statement
so that all options are allowed including compiled cache.

1 files changed, 24 insertions, 46 deletions

diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index c552f055f..1013f9397 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -2678,55 +2678,29 @@ class Executable(_Generative):
     def execution_options(self, **kw):
         """ Set non-SQL options for the statement which take effect during
         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
-          rules applied to different kinds of statements to determine if
-          COMMIT will be invoked in order to provide its "autocommit" feature.
-          Typically, all INSERT/UPDATE/DELETE statements as well as
-          CREATE/DROP statements have autocommit behavior enabled; SELECT
-          constructs do not. Use this option when invoking a SELECT or other
-          specific SQL construct where COMMIT is desired (typically when
-          calling stored procedures and such).
-
-        :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.
-
-        :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
-          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, 
-          as well as the "batch" mode for an INSERT or UPDATE statement.
-          The format of this dictionary is not guaranteed to stay the
-          same in future releases.
-
-          This option is usually more appropriate
-          to use via the 
-          :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 supersedes a cache dictionary
-          specified here.
+        
+        Execution options can be set on a per-statement or 
+        per :class:`.Connection` basis.   Additionally, the 
+        :class:`.Engine` and ORM :class:`~.orm.query.Query` objects provide access
+        to execution options which they in turn configure upon connections.
+        
+        The :meth:`execution_options` method is generative.  A new 
+        instance of this statement is returned that contains the options::
+        
+            statement = select([table.c.x, table.c.y])
+            statement = statement.execution_options(autocommit=True)
+        
+        Note that only a subset of possible execution options can be applied
+        to a statement - these include "autocommit" and "stream_results",
+        but not "isolation_level" or "compiled_cache".  
+        See :meth:`.Connection.execution_options` for a full list of 
+        possible options.
 
         See also:
 
-            :meth:`.Connection.execution_options()` -
-            includes a connection-only option to specify transaction isolation
-            level.
+            :meth:`.Connection.execution_options()`
 
-            :meth:`.Query.execution_options()` - applies options to 
-                the statement
-            generated by a :class:`.orm.Query` object.
+            :meth:`.Query.execution_options()`
 
         """
         if 'isolation_level' in kw:
@@ -2736,7 +2710,11 @@ class Executable(_Generative):
                 "per-engine using the isolation_level "
                 "argument to create_engine()."
             )
-
+        if 'compiled_cache' in kw:
+            raise exc.ArgumentError(
+                "'compiled_cache' execution option may only be specified "
+                "on Connection.execution_options(), not per statement."
+            )
         self._execution_options = self._execution_options.union(kw)
 
     def execute(self, *multiparams, **params):