SQLAlchemy 0.4 Documentation

Multiple Pages | One Page
Version: 0.4beta6 Last Updated: 09/26/07 20:38:24

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, **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).

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
Up: API Documentation | Previous: module sqlalchemy.orm.interfaces | Next: module sqlalchemy.orm.properties