module documentation

Provides the Session class and related utilities.
Class ​ORMExecute​State Represents a call to the _orm.Session.execute method, as passed to the .SessionEvents.do_orm_execute event hook.
Class ​Session Manages persistence operations for ORM-mapped objects.
Class sessionmaker A configurable .Session factory.
Class ​Session​Transaction A .Session-level transaction.
Constant ACTIVE Undocumented
Constant CLOSED Undocumented
Constant COMMITTED Undocumented
Constant DEACTIVE Undocumented
Constant PREPARED Undocumented
Class _​Session​Class​Methods Class-level methods for .Session, .sessionmaker.
Function ​_state​_session Given an .InstanceState, return the .Session associated, if any.
Function close​_all​_sessions Close all sessions in memory.
Function make​_transient Alter the state of the given instance so that it is :term:`transient`.
Function make​_transient​_to​_detached Make the given transient instance :term:`detached`.
Function object​_session Return the .Session to which the given instance belongs.
Variable ​_new​_sessionid Undocumented
Variable ​_sessions Weak-referencing dictionary of .Session objects.
ACTIVE =

Undocumented

Value
util.symbol('ACTIVE')
CLOSED =

Undocumented

Value
util.symbol('CLOSED')
COMMITTED =

Undocumented

Value
util.symbol('COMMITTED')
DEACTIVE =

Undocumented

Value
util.symbol('DEACTIVE')
PREPARED =

Undocumented

Value
util.symbol('PREPARED')
def _state_session(state):
Given an .InstanceState, return the .Session associated, if any.
def close_all_sessions():

Close all sessions in memory.

This function consults a global registry of all .Session objects and calls .Session.close on them, which resets them to a clean state.

This function is not for general use but may be useful for test suites within the teardown scheme.

New in version 1.3.
def make_transient(instance):

Alter the state of the given instance so that it is :term:`transient`.

Note

.make_transient is a special-case function for advanced use cases only.

The given mapped instance is assumed to be in the :term:`persistent` or :term:`detached` state. The function will remove its association with any .Session as well as its .InstanceState.identity. The effect is that the object will behave as though it were newly constructed, except retaining any attribute / collection values that were loaded at the time of the call. The .InstanceState.deleted flag is also reset if this object had been deleted as a result of using .Session.delete.

Warning

.make_transient does not "unexpire" or otherwise eagerly load ORM-mapped attributes that are not currently loaded at the time the function is called. This includes attributes which:

  • were expired via .Session.expire
  • were expired as the natural effect of committing a session transaction, e.g. .Session.commit
  • are normally :term:`lazy loaded` but are not currently loaded
  • are "deferred" via :ref:`deferred` and are not yet loaded
  • were not present in the query which loaded this object, such as that which is common in joined table inheritance and other scenarios.

After .make_transient is called, unloaded attributes such as those above will normally resolve to the value None when accessed, or an empty collection for a collection-oriented attribute. As the object is transient and un-associated with any database identity, it will no longer retrieve these values.

See Also

.make_transient_to_detached

def make_transient_to_detached(instance):

Make the given transient instance :term:`detached`.

Note

.make_transient_to_detached is a special-case function for advanced use cases only.

All attribute history on the given instance will be reset as though the instance were freshly loaded from a query. Missing attributes will be marked as expired. The primary key attributes of the object, which are required, will be made into the "key" of the instance.

The object can then be added to a session, or merged possibly with the load=False flag, at which point it will look as if it were loaded that way, without emitting SQL.

This is a special use case function that differs from a normal call to .Session.merge in that a given persistent state can be manufactured without any SQL calls.

See Also

.make_transient

.Session.enable_relationship_loading

def object_session(instance):

Return the .Session to which the given instance belongs.

This is essentially the same as the .InstanceState.session accessor. See that attribute for details.

_new_sessionid =

Undocumented

_sessions =
Weak-referencing dictionary of .Session objects.