# SQLAlchemy 0.4 Documentation

Multiple Pages | One Page
Version: 0.4.4 Last Updated: 03/11/08 20:04:34

### module sqlalchemy.orm.mapper

Defines the 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 module sqlalchemy.orm.

### Module Functions

def class_mapper(class_, entity_name=None, compile=True, raiseerror=True)

Given a class and optional entity_name, return the primary Mapper associated with the key.

If no mapper can be located, raises `InvalidRequestError`.

def object_mapper(object, entity_name=None, raiseerror=True)

Given an object, return the primary Mapper associated with the object instance.

object
  The object instance.
entity_name
  Entity name of the mapper to retrieve, if the given instance is transient. Otherwise uses the entity name already associated with the instance.
raiseerror
  Defaults to True: raise an `InvalidRequestError` if no mapper can be located. If False, return None.

### class Mapper(object)

Define the correlation of class attributes to database table columns.

Instances of this class should be constructed via the mapper() function.

def __init__(self, class_, local_table, properties=None, primary_key=None, non_primary=False, inherits=None, inherit_condition=None, inherit_foreign_keys=None, extension=None, order_by=False, allow_column_override=False, entity_name=None, always_refresh=False, version_id_col=None, polymorphic_on=None, _polymorphic_map=None, polymorphic_identity=None, polymorphic_fetch=None, concrete=False, select_table=None, allow_null_pks=False, batch=True, column_prefix=None, include_properties=None, exclude_properties=None, eager_defaults=False)

Construct a new mapper.

Mappers are normally constructed via the mapper() function. See for details.

def add_properties(self, dict_of_properties)

Add the given dictionary of properties to this mapper, using add_property.

def add_property(self, key, prop)

Add an individual MapperProperty to this mapper.

If the mapper has not been compiled yet, just adds the property to the initial properties dictionary sent to the constructor. If this Mapper has already been compiled, then the given MapperProperty is compiled immediately.

def cascade_iterator(self, type, state, recursive=None, halt_on=None)

Iterate each element and its mapper in an object graph, for all relations that meet the given cascade rule.

type
  The name of the cascade rule (i.e. save-update, delete, etc.)
state
  The lead InstanceState. child items will be processed per the relations defined for this object's mapper.
recursive
  Used by the function for internal context during recursive calls, leave as None.

the return value are object instances; this provides a strong reference so that they don't fall out of scope immediately.

def common_parent(self, other)

Return true if the given mapper shares a common inherited parent as this mapper.

def compile(self)

Compile this mapper into its final internal format.

compiled = property()

return True if this mapper is compiled

def dispose(self)
def get_property(self, key, resolve_synonyms=False, raiseerr=True)

return a MapperProperty associated with the given key.

def get_select_mapper(self)

Return the mapper used for issuing selects.

This mapper is the same mapper as self unless the select_table argument was specified for this mapper.

def get_session(self)

Return the contextual session provided by the mapper extension chain, if any.

Raise `InvalidRequestError` if a session cannot be retrieved from the extension chain.

def identity_key_from_instance(self, instance)

Return the identity key for the given instance, based on its primary key attributes.

This value is typically also found on the instance itself under the attribute name _instance_key.

def identity_key_from_primary_key(self, primary_key)

Return an identity-map key for use in storing/retrieving an item from an identity map.

primary_key
  A list of values indicating the identifier.

def identity_key_from_row(self, row)

Return an identity-map key for use in storing/retrieving an item from the identity map.

row
  A `sqlalchemy.engine.base.RowProxy` instance or a dictionary corresponding result-set `ColumnElement` instances to their values within a row.

def instances(*args, **kwargs)

Return a list of mapped instances corresponding to the rows in a given ResultProxy.

DEPRECATED.

def isa(self, other)

Return True if the given mapper inherits from this mapper.

iterate_properties = property()

returns an iterator of all MapperProperty objects.

def iterate_to_root(self)
def polymorphic_iterator(self)

Iterate through the collection including this mapper and all descendant mappers.

This includes not just the immediately inheriting mappers but all their inheriting mappers as well.

To iterate through an entire hierarchy, use `mapper.base_mapper.polymorphic_iterator()`.

def populate_instance(self, selectcontext, instance, row, ispostselect=None, isnew=False, only_load_props=None, **flags)

populate an instance from a result row.

def primary_key_from_instance(self, instance)

Return the list of primary key values for the given instance.

def primary_mapper(self)

Return the primary mapper corresponding to this mapper's class key (class + entity_name).

properties = property()
def translate_row(self, tomapper, row)

Translate the column keys of a row into a new or proxied row that can be understood by another mapper.

This can be used in conjunction with populate_instance to populate an instance using an alternate mapper.

back to section top