# SQLAlchemy 0.4 Documentation

Multiple Pages | One Page
Version: 0.4.1 Last Updated: 11/18/07 17:50:18

### module sqlalchemy.orm.mapper

### Module Functions

def class_mapper(class_, entity_name=None, compile=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 `sqlalchemy.orm.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)

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 indiviual 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 canload(self, instance)

return true if this mapper is capable of loading the given instance

def cascade_callable(self, type, object, callable_, recursive=None, halt_on=None)

Execute a callable for each element 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.)
object
  The lead object instance. child items will be processed per the relations defined for this object's mapper.
callable_
  The callable function.
recursive
  Used by the function for internal context during recursive calls, leave as None.

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

Iterate each element in an object graph, for all relations taht meet the given cascade rule.

type
  The name of the cascade rule (i.e. save-update, delete, etc.)
object
  The lead object instance. 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.

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.

def delete_obj(self, objects, uowtransaction)

Issue `DELETE` statements for a list of objects.

This is called within the context of a UOWTransaction during a flush operation.

def dispose(self)
def get_attr_by_column(self, obj, column, raiseerror=True)

Return an instance attribute using a Column as the key.

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

return MapperProperty 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 has_eager(self)

Return True if one of the properties attached to this Mapper is eager loading.

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(self, cursor, session, *mappers, **kwargs)

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

def is_assigned(self, instance)

Return True if this mapper handles the given instance.

This is dependent not only on class assignment but the optional entity_name parameter as well.

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 register_dependencies(self, uowcommit, *args, **kwargs)

Register `DependencyProcessor` instances with a `unitofwork.UOWTransaction`.

This call register_dependencies on all attached `MapperProperty` instances.

def save_obj(self, objects, uowtransaction, postupdate=False, post_update_cols=None, single=False)

Issue `INSERT` and/or `UPDATE` statements for a list of objects.

This is called within the context of a UOWTransaction during a flush operation.

save_obj issues SQL statements not just for instances mapped directly by this mapper, but for instances mapped by all inheriting mappers as well. This is to maintain proper insert ordering among a polymorphic chain of instances. Therefore save_obj is typically called only on a base mapper, or a mapper which does not inherit from any other mapper.

def set_attr_by_column(self, obj, column, value)

Set the value of an instance attribute using a Column as the key.

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