sqlalchemy.engine.interfaces.ExecutionContext

class documentation

class ExecutionContext(object):

Known subclasses: sqlalchemy.engine.default.DefaultExecutionContext

A messenger object for a Dialect that corresponds to a single execution.

ExecutionContext should have these data members:

connection: Connection object which can be freely used by default value generators to execute SQL. This Connection should reference the same underlying connection/transactional resources of root_connection.
root_connection: Connection object which is the source of this ExecutionContext. This Connection may have close_with_result=True set, in which case it can only be used once.
dialect: dialect which created this ExecutionContext.
cursor: DB-API cursor procured from the connection,
compiled: if passed to constructor, sqlalchemy.engine.base.Compiled object being executed,
statement: string version of the statement to be executed. Is either passed to the constructor, or must be created from the sql.Compiled object by the time pre_exec() has completed.
parameters: bind parameters passed to the execute() method. For compiled statements, this is a dictionary or list of dictionaries. For textual statements, it should be in a format suitable for the dialect's paramstyle (i.e. dict or list of dicts for non positional, list or list of lists/tuples for positional).
isinsert: True if the statement is an INSERT.
isupdate: True if the statement is an UPDATE.
should_autocommit: True if the statement is a "committable" statement.
prefetch_cols: a list of Column objects for which a client-side default was fired off. Applies to inserts and updates.
postfetch_cols: a list of Column objects for which a server-side default or inline SQL expression value was fired off. Applies to inserts and updates.

Method	`create_cursor`	Return a new cursor generated from this ExecutionContext's connection.
Method	`get_out_parameter_values`	Return a sequence of OUT parameter values from a cursor.
Method	`get_result_cursor_strategy`	Return a result cursor strategy for a given result object.
Method	`get_rowcount`	Return the DBAPI `cursor.rowcount` value, or in some cases an interpreted value.
Method	`handle_dbapi_exception`	Receive a DBAPI exception which occurred upon execute, result fetch, etc.
Method	`lastrow_has_defaults`	Return True if the last INSERT or UPDATE row contained inlined or database-side defaults.
Method	`post_exec`	Called after the execution of a compiled statement.
Method	`pre_exec`	Called before an execution of a compiled statement.
Method	`should_autocommit_text`	Parse the given textual statement and return True if it refers to a "committable" statement

def create_cursor(self):

overridden in sqlalchemy.engine.default.DefaultExecutionContext

Return a new cursor generated from this ExecutionContext's connection.

Some dialects may wish to change the behavior of connection.cursor(), such as postgresql which may return a PG "server side" cursor.

def get_out_parameter_values(self, out_param_names):

overridden in sqlalchemy.engine.default.DefaultExecutionContext

Return a sequence of OUT parameter values from a cursor.

For dialects that support OUT parameters, this method will be called when there is a .SQLCompiler object which has the .SQLCompiler.has_out_parameters flag set. This flag in turn will be set to True if the statement itself has .BindParameter objects that have the .isoutparam flag set which are consumed by the .SQLCompiler.visit_bindparam method. If the dialect compiler produces .BindParameter objects with .isoutparam set which are not handled by .SQLCompiler.visit_bindparam, it should set this flag explicitly.

The list of names that were rendered for each bound parameter is passed to the method. The method should then return a sequence of values corresponding to the list of parameter objects. Unlike in previous SQLAlchemy versions, the values can be the raw values from the DBAPI; the execution context will apply the appropriate type handler based on what's present in self.compiled.binds and update the values. The processed dictionary will then be made available via the .out_parameters collection on the result object. Note that SQLAlchemy 1.4 has multiple kinds of result object as part of the 2.0 transition.

New in version 1.4: - added .ExecutionContext.get_out_parameter_values, which is invoked automatically by the .DefaultExecutionContext when there are .BindParameter objects with the .isoutparam flag set. This replaces the practice of setting out parameters within the now-removed get_result_proxy() method.

See Also

.ExecutionContext.get_result_cursor_strategy

def get_result_cursor_strategy(self, result):

overridden in sqlalchemy.databases.mssql.MSExecutionContext

Return a result cursor strategy for a given result object.

This method is implemented by the .DefaultDialect and is only needed by implementing dialects in the case where some special steps regarding the cursor must be taken, such as manufacturing fake results from some other element of the cursor, or pre-buffering the cursor's results.

A simplified version of the default implementation is:

from sqlalchemy.engine.result import DefaultCursorFetchStrategy

class MyExecutionContext(DefaultExecutionContext):
    def get_result_cursor_strategy(self, result):
        return DefaultCursorFetchStrategy.create(result)

Above, the .DefaultCursorFetchStrategy will be applied to the result object. For results that are pre-buffered from a cursor that might be closed, an implementation might be:

from sqlalchemy.engine.result import (
    FullyBufferedCursorFetchStrategy
)

class MyExecutionContext(DefaultExecutionContext):
    _pre_buffered_result = None

    def pre_exec(self):
        if self.special_condition_prebuffer_cursor():
            self._pre_buffered_result = (
                self.cursor.description,
                self.cursor.fetchall()
            )

    def get_result_cursor_strategy(self, result):
        if self._pre_buffered_result:
            description, cursor_buffer = self._pre_buffered_result
            return (
                FullyBufferedCursorFetchStrategy.
                    create_from_buffer(
                        result, description, cursor_buffer
                )
            )
        else:
            return DefaultCursorFetchStrategy.create(result)

This method replaces the previous not-quite-documented get_result_proxy() method.

New in version 1.4: - result objects now interpret cursor results based on a pluggable "strategy" object, which is delivered by the .ExecutionContext via the .ExecutionContext.get_result_cursor_strategy method.