class documentation

class ORMExecuteState(util.MemoizedSlots):

View In Hierarchy

Represents a call to the _orm.Session.execute method, as passed to the .SessionEvents.do_orm_execute event hook.

New in version 1.4.

See Also

:ref:`session_execute_events` - top level documentation on how to use _orm.SessionEvents.do_orm_execute

Method __init__ Undocumented
Method ​_orm​_compile​_options Undocumented
Method ​_remaining​_events Undocumented
Method invoke​_statement Execute the statement represented by this .ORMExecuteState, without re-invoking events that have already proceeded.
Method update​_execution​_options Undocumented
Class Variable __slots__ Undocumented
Instance Variable ​_compile​_state​_cls Undocumented
Instance Variable ​_events​_todo Undocumented
Instance Variable bind​_arguments Undocumented
Instance Variable execution​_options Undocumented
Instance Variable local​_execution​_options Undocumented
Instance Variable parameters Undocumented
Instance Variable session Undocumented
Instance Variable statement Undocumented
Property ​_is​_crud Undocumented
Property all​_mappers Return a sequence of all _orm.Mapper objects that are involved at the top level of this statement.
Property bind​_mapper Return the _orm.Mapper that is the primary "bind" mapper.
Property is​_column​_load Return True if the operation is refreshing column-oriented attributes on an existing ORM object.
Property is​_delete return True if this is a DELETE operation.
Property is​_insert return True if this is an INSERT operation.
Property is​_orm​_statement return True if the operation is an ORM statement.
Property is​_relationship​_load Return True if this load is loading objects on behalf of a relationship.
Property is​_select return True if this is a SELECT operation.
Property is​_update return True if this is an UPDATE operation.
Property lazy​_loaded​_from An .InstanceState that is using this statement execution for a lazy load operation.
Property load​_options Return the load_options that will be used for this execution.
Property loader​_strategy​_path Return the .PathRegistry for the current load path.
Property update​_delete​_options Return the update_delete_options that will be used for this execution.
Property user​_defined​_options The sequence of .UserDefinedOptions that have been associated with the statement being invoked.

Inherited from MemoizedSlots:

Method __getattr__ Undocumented
Method ​_fallback​_getattr Undocumented
def __init__(self, session, statement, parameters, execution_options, bind_arguments, compile_state_cls, events_todo):

Undocumented

def _orm_compile_options(self):

Undocumented

def _remaining_events(self):

Undocumented

def invoke_statement(self, statement=None, params=None, execution_options=None, bind_arguments=None):

Execute the statement represented by this .ORMExecuteState, without re-invoking events that have already proceeded.

This method essentially performs a re-entrant execution of the current statement for which the .SessionEvents.do_orm_execute event is being currently invoked. The use case for this is for event handlers that want to override how the ultimate _engine.Result object is returned, such as for schemes that retrieve results from an offline cache or which concatenate results from multiple executions.

When the _engine.Result object is returned by the actual handler function within _orm.SessionEvents.do_orm_execute and is propagated to the calling _orm.Session.execute method, the remainder of the _orm.Session.execute method is preempted and the _engine.Result object is returned to the caller of _orm.Session.execute immediately.

See Also

:ref:`do_orm_execute_re_executing` - background and examples on the appropriate usage of _orm.ORMExecuteState.invoke_statement.

Parameters
statementoptional statement to be invoked, in place of the statement currently represented by .ORMExecuteState.statement.
paramsoptional dictionary of parameters which will be merged into the existing .ORMExecuteState.parameters of this .ORMExecuteState.
execution​_optionsoptional dictionary of execution options will be merged into the existing .ORMExecuteState.execution_options of this .ORMExecuteState.
bind​_argumentsoptional dictionary of bind_arguments which will be merged amongst the current .ORMExecuteState.bind_arguments of this .ORMExecuteState.
Returns
a _engine.Result object with ORM-level results.
def update_execution_options(self, **opts):

Undocumented

__slots__: tuple[str, ...] =
_compile_state_cls =

Undocumented

_events_todo =

Undocumented

bind_arguments =

Undocumented

execution_options =

Undocumented

local_execution_options =

Undocumented

parameters =

Undocumented

session =

Undocumented

statement =

Undocumented

@property
_is_crud =

Undocumented

@property
all_mappers =

Return a sequence of all _orm.Mapper objects that are involved at the top level of this statement.

By "top level" we mean those _orm.Mapper objects that would be represented in the result set rows for a _sql.select query, or for a _dml.update or _dml.delete query, the mapper that is the main subject of the UPDATE or DELETE.

New in version 1.4.0b2.

See Also

_orm.ORMExecuteState.bind_mapper

@property
bind_mapper =

Return the _orm.Mapper that is the primary "bind" mapper.

For an _orm.ORMExecuteState object invoking an ORM statement, that is, the _orm.ORMExecuteState.is_orm_statement attribute is True, this attribute will return the _orm.Mapper that is considered to be the "primary" mapper of the statement. The term "bind mapper" refers to the fact that a _orm.Session object may be "bound" to multiple _engine.Engine objects keyed to mapped classes, and the "bind mapper" determines which of those _engine.Engine objects would be selected.

For a statement that is invoked against a single mapped class, _orm.ORMExecuteState.bind_mapper is intended to be a reliable way of getting this mapper.

New in version 1.4.0b2.

See Also

_orm.ORMExecuteState.all_mappers

@property
is_column_load =

Return True if the operation is refreshing column-oriented attributes on an existing ORM object.

This occurs during operations such as _orm.Session.refresh, as well as when an attribute deferred by _orm.defer is being loaded, or an attribute that was expired either directly by _orm.Session.expire or via a commit operation is being loaded.

Handlers will very likely not want to add any options to queries when such an operation is occurring as the query should be a straight primary key fetch which should not have any additional WHERE criteria, and loader options travelling with the instance will have already been added to the query.

New in version 1.4.0b2.

See Also

_orm.ORMExecuteState.is_relationship_load

@property
is_delete =
return True if this is a DELETE operation.
@property
is_insert =
return True if this is an INSERT operation.
@property
is_orm_statement =

return True if the operation is an ORM statement.

This indicates that the select(), update(), or delete() being invoked contains ORM entities as subjects. For a statement that does not have ORM entities and instead refers only to .Table metadata, it is invoked as a Core SQL statement and no ORM-level automation takes place.

@property
is_relationship_load =

Return True if this load is loading objects on behalf of a relationship.

This means, the loader in effect is either a LazyLoader, SelectInLoader, SubqueryLoader, or similar, and the entire SELECT statement being emitted is on behalf of a relationship load.

Handlers will very likely not want to add any options to queries when such an operation is occurring, as loader options are already capable of being propagated to relationship loaders and should be already present.

See Also

_orm.ORMExecuteState.is_column_load

@property
is_select =
return True if this is a SELECT operation.
@property
is_update =
return True if this is an UPDATE operation.
@property
lazy_loaded_from =

An .InstanceState that is using this statement execution for a lazy load operation.

The primary rationale for this attribute is to support the horizontal sharding extension, where it is available within specific query execution time hooks created by this extension. To that end, the attribute is only intended to be meaningful at query execution time, and importantly not any time prior to that, including query compilation time.

@property
load_options =
Return the load_options that will be used for this execution.
@property
loader_strategy_path =

Return the .PathRegistry for the current load path.

This object represents the "path" in a query along relationships when a particular object or collection is being loaded.

@property
update_delete_options =
Return the update_delete_options that will be used for this execution.
@property
user_defined_options =
The sequence of .UserDefinedOptions that have been associated with the statement being invoked.