sqlalchemy.orm

package documentation

Functional constructs for ORM configuration.

See the SQLAlchemy object relational tutorial and mapper configuration documentation for an overview of how this module is used.

Module	`attributes`	Defines instrumentation for class attributes and their interaction with instances.
Module	`base`	Constants and rudimental functions used throughout the ORM.
Module	`collections`	Support for collections of mapped entities.
Module	`context`	No module docstring; 0/1 variable, 0/2 constant, 1/4 function, 3/10 classes documented
Module	`decl_api`	Public API functions and helpers for declarative.
Module	`descriptor_props`	Descriptor properties are more "auxiliary" properties that exist as configurational elements, but don't participate as actively in the load/persist ORM loop.
Module	`dynamic`	Dynamic collection API.
Module	`events`	ORM event interfaces.
Module	`exc`	SQLAlchemy ORM exceptions.
Module	`identity`	Undocumented
Module	`instrumentation`	Defines SQLAlchemy's system of class instrumentation.
Module	`interfaces`	Contains various base classes used throughout the ORM.
Module	`mapper`	Logic to map Python classes to and from selectables.
Module	`properties`	MapperProperty implementations.
Module	`query`	The Query class and support.
Module	`relationships`	Heuristics related to join conditions as used in `_orm.relationship`.
Module	`scoping`	No module docstring; 1/2 class documented
Module	`session`	Provides the Session class and related utilities.
Module	`state`	Defines instrumentation of instances.
Module	`strategy_options`	No module docstring; 0/15 function, 2/3 classes documented
Module	`unitofwork`	The internals for the unit of work system.
Module	`util`	No module docstring; 0/1 variable, 16/17 functions, 8/8 classes documented
Module	`clsregistry`	Routines to handle the string class registry used by declarative.
Module	`decl_base`	Internal implementation for declarative.
Module	`dependency`	Relationship dependencies.
Module	`evaluator`	Undocumented
Module	`loading`	private module containing functions used to convert database rows into object instances and associated state.
Module	`path_registry`	Path tracking utilities, representing mapper graph traversals.
Module	`persistence`	private module containing functions used to emit INSERT, UPDATE and DELETE statements on behalf of a `_orm.Mapper` and its descending mappers.
Module	`strategies`	sqlalchemy.orm.interfaces.LoaderStrategy implementations, and related MapperOptions.
Module	`sync`	private module containing functions used for copying data between instances based on join conditions.

From __init__.py:

Function	`backref`	Create a back reference with explicit keyword arguments, which are the same arguments one can send to `relationship`.
Function	`clear_mappers`	Remove all mappers from all classes.
Function	`deferred`	Indicate a column-based mapped attribute that by default will not load unless accessed.
Function	`dynamic_loader`	Construct a dynamically-loading mapper property.
Function	`eagerload`	A synonym for `joinedload()`.
Function	`query_expression`	Indicate an attribute that populates from a query-time SQL expression.
Function	`relation`	A synonym for `relationship`.
Variable	`column_property`	Undocumented
Variable	`composite`	Undocumented
Variable	`contains_alias`	Undocumented
Variable	`relationship`	Undocumented
Variable	`synonym`	Undocumented
Variable	`with_loader_criteria`	Undocumented
Function	`__go`	Undocumented
Function	`create_session`	Create a new `.Session` with no automation enabled by default.

def create_session(bind=None, **kwargs):

Create a new .Session with no automation enabled by default.

This function is used primarily for testing. The usual route to .Session creation is via its constructor or the .sessionmaker function.

The defaults of create_session() are the opposite of that of sessionmaker; autoflush and expire_on_commit are False, autocommit is True. In this sense the session acts more like the "classic" SQLAlchemy 0.3 session with these.

Deprecated since version 1.4: The "autocommit" parameter will be removed in SQLAlchemy 2.0. _orm.create_session will return a _orm.Session that does not include "autocommit' behavior in release 2.0.

Usage:

>>> from sqlalchemy.orm import create_session
>>> session = create_session()

It is recommended to use sessionmaker instead of create_session().

Parameters
bind	optional, a single Connectable to use for all database access in the created `~sqlalchemy.orm.session.Session`.
**kwargs	optional, passed through to the `.Session` constructor.
Returns
an `~sqlalchemy.orm.session.Session` instance

with_loader_criteria =

Undocumented

relationship =

Undocumented

@_sa_util.deprecated_20('relation', 'Please use :func:`.relationship`.')
def relation(*arg, **kw):

A synonym for relationship.

def dynamic_loader(argument, **kw):

Construct a dynamically-loading mapper property.

This is essentially the same as using the lazy='dynamic' argument with relationship:

dynamic_loader(SomeClass)

# is the same as

relationship(SomeClass, lazy="dynamic")

See the section :ref:`dynamic_relationship` for more details on dynamic loading.

column_property =

Undocumented

composite =

Undocumented

def backref(name, **kwargs):

Create a back reference with explicit keyword arguments, which are the same arguments one can send to relationship.

Used with the backref keyword argument to relationship in place of a string argument, e.g.:

'items':relationship(
    SomeItem, backref=backref('parent', lazy='subquery'))

See Also

:ref:`mapper_querytime_expression`

Parameters

default_expr

Optional SQL expression object that will be used in all cases if not assigned later with _orm.with_expression. E.g.:

from sqlalchemy.sql import literal

class C(Base):
    #...
    my_expr = query_expression(literal(1))

New in version 1.3.18.

synonym =

Undocumented

def clear_mappers():

Remove all mappers from all classes.

Changed in version 1.4: This function now locates all _orm.registry objects and calls upon the _orm.registry.dispose method of each.

This function removes all instrumentation from classes and disposes of their associated mappers. Once called, the classes are unmapped and can be later re-mapped with new mappers.

.clear_mappers is not for normal use, as there is literally no valid usage for it outside of very specific testing scenarios. Normally, mappers are permanent structural components of user-defined classes, and are never discarded independently of their class. If a mapped class itself is garbage collected, its mapper is automatically disposed of as well. As such, .clear_mappers is only for usage in test suites that re-use the same classes with different mappings, which is itself an extremely rare use case - the only such use case is in fact SQLAlchemy's own test suite, and possibly the test suites of other ORM extension libraries which intend to test various combinations of mapper construction upon a fixed set of classes.

@_sa_util.deprecated_20('eagerload', 'Please use :func:`_orm.joinedload`.')
def eagerload(*args, **kwargs):

A synonym for joinedload().

contains_alias =

Undocumented

def __go(lcls):

Undocumented

Parameters
*columns	columns to be mapped. This is typically a single `_schema.Column` object, however a collection is supported in order to support multiple columns mapped under the same attribute.
**kw	additional keyword arguments passed to `.ColumnProperty`.
raiseload	boolean, if True, indicates an exception should be raised if the load operation is to take place. New in version 1.4. See Also :ref:`deferred_raiseload`