sqlalchemy.orm.mapper

module documentation

Logic to map Python classes to and from selectables.

Defines the ~sqlalchemy.orm.mapper.Mapper class, the central configurational unit which associates a class with a database table.

This is a semi-private module; the main configurational API of the ORM is available in ~sqlalchemy.orm..

Class	`Mapper`	Defines an association between a Python class and a database table or other relational structure, so that ORM operations against the class may proceed.
Constant	`NO_ATTRIBUTE`	Undocumented
Class	`_ColumnMapping`	Error reporting helper for mapper._columntoproperty.
Class	`_OptGetColumnsNotAvailable`	Undocumented
Function	`_all_registries`	Undocumented
Function	`_configure_registries`	Undocumented
Function	`_dispose_registries`	Undocumented
Function	`_do_configure_registries`	Undocumented
Function	`_event_on_init`	Run init_instance hooks.
Function	`_event_on_load`	Undocumented
Function	`_unconfigured_mappers`	Undocumented
Function	`configure_mappers`	Initialize the inter-mapper relationships of all mappers that have been constructed thus far across all `_orm.registry` collections.
Function	`reconstructor`	Decorate a method as the 'reconstructor' hook.
Function	`validates`	Decorate a method as a 'validator' for one or more named properties.
Constant	`_CONFIGURE_MUTEX`	Undocumented
Variable	`_already_compiling`	Undocumented
Variable	`_legacy_registry`	Undocumented
Variable	`_mapper_registries`	Undocumented

NO_ATTRIBUTE =

Undocumented

Value

util.symbol('NO_ATTRIBUTE')

def _all_registries():

Undocumented

def _configure_registries(registries, cascade):

Undocumented

@util.preload_module('sqlalchemy.orm.decl_api')
def _dispose_registries(registries, cascade):

Undocumented

@util.preload_module('sqlalchemy.orm.decl_api')
def _do_configure_registries(registries, cascade):

Undocumented

def _event_on_init(state, args, kwargs):

Run init_instance hooks.

This also includes mapper compilation, normally not needed here but helps with some piecemeal configuration scenarios (such as in the ORM tutorial).

def _event_on_load(state, ctx):

Undocumented

def _unconfigured_mappers():

Undocumented

def configure_mappers():

Initialize the inter-mapper relationships of all mappers that have been constructed thus far across all _orm.registry collections.

The configure step is used to reconcile and initialize the _orm.relationship linkages between mapped classes, as well as to invoke configuration events such as the _orm.MapperEvents.before_configured and _orm.MapperEvents.after_configured, which may be used by ORM extensions or user-defined extension hooks.

Mapper configuration is normally invoked automatically, the first time mappings from a particular _orm.registry are used, as well as whenever mappings are used and additional not-yet-configured mappers have been constructed. The automatic configuration process however is local only to the _orm.registry involving the target mapper and any related _orm.registry objects which it may depend on; this is equivalent to invoking the _orm.registry.configure method on a particular _orm.registry.

By contrast, the _orm.configure_mappers function will invoke the configuration process on all _orm.registry objects that exist in memory, and may be useful for scenarios where many individual _orm.registry objects that are nonetheless interrelated are in use.

Changed in version 1.4: As of SQLAlchemy 1.4.0b2, this function works on a per-_orm.registry basis, locating all _orm.registry objects present and invoking the _orm.registry.configure method on each. The _orm.registry.configure method may be preferred to limit the configuration of mappers to those local to a particular _orm.registry and/or declarative base class.

Points at which automatic configuration is invoked include when a mapped class is instantiated into an instance, as well as when ORM queries are emitted using .Session.query or _orm.Session.execute with an ORM-enabled statement.

The mapper configure process, whether invoked by _orm.configure_mappers or from _orm.registry.configure, provides several event hooks that can be used to augment the mapper configuration step. These hooks include:

.MapperEvents.before_configured - called once before .configure_mappers or _orm.registry.configure does any work; this can be used to establish additional options, properties, or related mappings before the operation proceeds.
.MapperEvents.mapper_configured - called as each individual _orm.Mapper is configured within the process; will include all mapper state except for backrefs set up by other mappers that are still to be configured.
.MapperEvents.after_configured - called once after .configure_mappers or _orm.registry.configure is complete; at this stage, all _orm.Mapper objects that fall within the scope of the configuration operation will be fully configured. Note that the calling application may still have other mappings that haven't been produced yet, such as if they are in modules as yet unimported, and may also have mappings that are still to be configured, if they are in other _orm.registry collections not part of the current scope of configuration.

def reconstructor(fn):

Decorate a method as the 'reconstructor' hook.

Designates a single method as the "reconstructor", an __init__-like method that will be called by the ORM after the instance has been loaded from the database or otherwise reconstituted.

The reconstructor will be invoked with no arguments. Scalar (non-collection) database-mapped attributes of the instance will be available for use within the function. Eagerly-loaded collections are generally not yet available and will usually only contain the first element. ORM state changes made to objects at this stage will not be recorded for the next flush() operation, so the activity within a reconstructor should be conservative.

Parameters
*names	list of attribute names to be validated.
**kw	Undocumented
include_removes	if True, "remove" events will be sent as well - the validation function must accept an additional argument "is_remove" which will be a boolean.
include_backrefs	defaults to `True`; if `False`, the validation function will not emit if the originator is an attribute event related via a backref. This can be used for bi-directional `.validates` usage where only one validator should emit per attribute operation. New in version 0.9.0.