SQLAlchemy 0.3 Documentation
module sqlalchemy.orm.mapper
Module Functions
Given a class and optional entity_name, return the primary Mapper associated with the key.
If no mapper can be located, raises InvalidRequestError.
Given an object, return the primary Mapper associated with the object instance.
- object
- The object instance.
- raiseerror
- Defaults to True: raise an InvalidRequestError if no mapper can be located. If False, return None.
class MapperExtension(object)
Base implementation for an object that provides overriding behavior to various Mapper functions. For each method in MapperExtension, a result of EXT_PASS indicates the functionality is not overridden.
Receive an object instance after that instance is DELETEed.
Receive an object instance after that instance is INSERTed.
Receive an object instance after that instance is UPDATEed.
Receive an object instance before that instance is appended to a result list.
If this method returns EXT_PASS, result appending will proceed normally. if this method returns any other value or None, result appending will not proceed for this instance, giving this extension an opportunity to do the appending itself, if desired.
- mapper
- The mapper doing the operation.
- selectcontext
- SelectionContext corresponding to the instances() call.
- row
- The result row from the database.
- instance
- The object instance to be appended to the result.
- identitykey
- The identity key of the instance.
- result
- List to which results are being appended.
- isnew
- Indicates if this is the first time we have seen this object instance in the current result set. if you are selecting from a join, such as an eager load, you might see the same object instance many times in the same result set.
Receive an object instance before that instance is DELETEed.
Receive an object instance before that instance is INSERTed into its table.
This is a good place to set up primary key values and such that aren't handled otherwise.
Receive an object instance before that instance is UPDATEed.
Receive a row when a new object instance is about to be created from that row.
The method can choose to create the instance itself, or it can return None to indicate normal object creation should take place.
- mapper
- The mapper doing the operation
- selectcontext
- SelectionContext corresponding to the instances() call
- row
- The result row from the database
- class_
- The class we are mapping.
Override the get method of the Query object.
The return value of this method is used as the result of query.get() if the value is anything other than EXT_PASS.
Override the get_by method of the Query object.
The return value of this method is used as the result of query.get_by() if the value is anything other than EXT_PASS.
Retrieve a contextual Session instance with which to register a new object.
Note: this is not called if a session is provided with the __init__ params (i.e. _sa_session).
Override the load method of the Query object.
The return value of this method is used as the result of query.load() if the value is anything other than EXT_PASS.
Receive a newly-created instance before that instance has its attributes populated.
The normal population of attributes is according to each attribute's corresponding MapperProperty (which includes column-based attributes as well as relationships to other classes). If this method returns EXT_PASS, instance population will proceed normally. If any other value or None is returned, instance population will not proceed, giving this extension an opportunity to populate the instance itself, if desired.
Override the select method of the Query object.
The return value of this method is used as the result of query.select() if the value is anything other than EXT_PASS.
Override the select_by method of the Query object.
The return value of this method is used as the result of query.select_by() if the value is anything other than EXT_PASS.
Perform pre-processing on the given result row and return a new row instance.
This is called as the very first step in the _instance() method.
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.
Construct a new mapper.
All arguments may be sent to the sqlalchemy.orm.mapper() function where they are passed through to here.
- class_
- The class to be mapped.
- local_table
- The table to which the class is mapped, or None if this mapper inherits from another mapper using concrete table inheritance.
- properties
- A dictionary mapping the string names of object attributes to MapperProperty instances, which define the persistence behavior of that attribute. Note that the columns in the mapped table are automatically converted into ColumnProperty instances based on the key property of each Column (although they can be overridden using this dictionary).
- primary_key
- A list of Column objects which define the primary key to be used against this mapper's selectable unit. This is normally simply the primary key of the local_table, but can be overridden here.
- non_primary
- Construct a Mapper that will define only the selection of instances, not their persistence.
- inherits
- Another Mapper for which this Mapper will have an inheritance relationship with.
- inherit_condition
- For joined table inheritance, a SQL expression (constructed ClauseElement) which will define how the two tables are joined; defaults to a natural join between the two tables.
- extension
- A MapperExtension instance or list of MapperExtension instances which will be applied to all operations by this Mapper.
- order_by
- A single Column or list of Columns for which selection operations should use as the default ordering for entities. Defaults to the OID/ROWID of the table if any, or the first primary key column of the table.
- allow_column_override
- If True, allows the usage of a relation() which has the same name as a column in the mapped table. The table column will no longer be mapped.
- entity_name
- A name to be associated with the class, to allow alternate mappings for a single class.
- always_refresh
- If True, all query operations for this mapped class will overwrite all data within object instances that already exist within the session, erasing any in-memory changes with whatever information was loaded from the database.
- version_id_col
- A Column which must have an integer type that will be used to keep a running version id of mapped entities in the database. this is used during save operations to ensure that no other thread or process has updated the instance during the lifetime of the entity, else a ConcurrentModificationError exception is thrown.
- polymorphic_on
- Used with mappers in an inheritance relationship, a Column which will identify the class/mapper combination to be used with a particular row. requires the polymorphic_identity value to be set for all mappers in the inheritance hierarchy.
- _polymorphic_map
- Used internally to propigate the full map of polymorphic identifiers to surrogate mappers.
- polymorphic_identity
- A value which will be stored in the Column denoted by polymorphic_on, corresponding to the class identity of this mapper.
- concrete
- If True, indicates this mapper should use concrete table inheritance with its parent mapper.
- select_table
- A Table or (more commonly) Selectable which will be used to select instances of this mapper's class. usually used to provide polymorphic loading among several classes in an inheritance hierarchy.
- allow_null_pks
- Indicates that composite primary keys where one or more (but not all) columns contain NULL is a valid primary key. Primary keys which contain NULL values usually indicate that a result row does not contain an entity and should be skipped.
- batch
- Indicates that save operations of multiple entities can be batched together for efficiency. setting to False indicates that an instance will be fully saved before saving the next instance, which includes inserting/updating all table rows corresponding to the entity as well as calling all MapperExtension methods corresponding to the save operation.
- column_prefix
- A string which will be prepended to the key name of all Columns when creating column-based properties from the given Table. Does not affect explicitly specified column-based properties
Add the given dictionary of properties to this mapper, using add_property.
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.
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.
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.
Return true if the given mapper shares a common inherited parent as this mapper.
Compile this mapper into its final internal format.
This is the external version of the method which is not reentrant.
Issue DELETE statements for a list of objects.
This is called within the context of a UOWTransaction during a flush operation.
Return an instance attribute using a Column as the key.
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.
Return the contextual session provided by the mapper extension chain, if any.
Raise InvalidRequestError if a session cannot be retrieved from the extension chain.
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.
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.
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.
Return a list of mapped instances corresponding to the rows in a given ResultProxy.
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.
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().
populate an instance from a result row.
This method iterates through the list of MapperProperty objects attached to this Mapper and calls each properties execute() method.
Return the list of primary key values for the given instance.
Return the primary mapper corresponding to this mapper's class key (class + entity_name).
compiles this mapper if needed, and returns the dictionary of MapperProperty objects associated with this mapper.
Register DependencyProcessor instances with a unitofwork.UOWTransaction.
This call register_dependencies on all attached MapperProperty instances.
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.