# SQLAlchemy 0.4 Documentation

Multiple Pages | One Page
Version: 0.4.6 Last Updated: 05/14/08 14:36:43

### 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, with_polymorphic=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, 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.

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 and all other non-compiled mappers.

This method checks the local compiled status as well as for any new mappers that have been defined, and is safe to call repeatedly.

compiled = property()

return True if this mapper is compiled

def dispose(self)
def do_with_cache(self, *args, **kwargs)
def do_with_cache(self, *args, **kwargs)
def get_property(self, key, resolve_synonyms=False, raiseerr=True)

return a MapperProperty associated with the given key.

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()
back to section top