Return a new Mapper object.
This function is typically used behind the scenes via the Declarative extension. When using Declarative, many of the usual mapper() arguments are handled by the Declarative extension itself, including class_, local_table, properties, and inherits. Other options are passed to mapper() using the __mapper_args__ class variable:
class MyClass(Base):
__tablename__ = 'my_table'
id = Column(Integer, primary_key=True)
type = Column(String(50))
alt = Column("some_alt", Integer)
__mapper_args__ = {
'polymorphic_on' : type
}
Explicit use of mapper() is often referred to as classical mapping. The above declarative example is equivalent in classical form to:
my_table = Table("my_table", metadata,
Column('id', Integer, primary_key=True),
Column('type', String(50)),
Column("some_alt", Integer)
)
class MyClass(object):
pass
mapper(MyClass, my_table,
polymorphic_on=my_table.c.type,
properties={
'alt':my_table.c.some_alt
})
See also
Classical Mappings - discussion of direct usage of mapper()
Parameters: |
|
---|
Given an object, return the primary Mapper associated with the object instance.
Raises sqlalchemy.orm.exc.UnmappedInstanceError if no mapping is configured.
This function is available via the inspection system as:
inspect(instance).mapper
Using the inspection system will raise sqlalchemy.exc.NoInspectionAvailable if the instance is not part of a mapping.
Given a class, return the primary Mapper associated with the key.
Raises UnmappedClassError if no mapping is configured on the given class, or ArgumentError if a non-class object is passed.
Equivalent functionality is available via the inspect() function as:
inspect(some_mapped_class)
Using the inspection system will raise sqlalchemy.exc.NoInspectionAvailable if the class is not mapped.
Initialize the inter-mapper relationships of all mappers that have been constructed thus far.
This function can be called any number of times, but in most cases is invoked automatically, the first time mappings are used, as well as whenever mappings are used and additional not-yet-configured mappers have been constructed.
Points at which this occur include when a mapped class is instantiated into an instance, as well as when the Session.query() method is used.
The configure_mappers() function provides several event hooks that can be used to augment its functionality. These methods include:
Remove all mappers from all classes.
This function removes all instrumentation from classes and disposes of their associated mappers. Once called, the classes are unmapped and can be later re-mapped with new mappers.
clear_mappers() is not for normal use, as there is literally no valid usage for it outside of very specific testing scenarios. Normally, mappers are permanent structural components of user-defined classes, and are never discarded independently of their class. If a mapped class itself is garbage collected, its mapper is automatically disposed of as well. As such, clear_mappers() is only for usage in test suites that re-use the same classes with different mappings, which is itself an extremely rare use case - the only such use case is in fact SQLAlchemy’s own test suite, and possibly the test suites of other ORM extension libraries which intend to test various combinations of mapper construction upon a fixed set of classes.
Generate “identity key” tuples, as are used as keys in the Session.identity_map dictionary.
This function has several call styles:
identity_key(class, ident)
This form receives a mapped class and a primary key scalar or tuple as an argument.
E.g.:
>>> identity_key(MyClass, (1, 2))
(<class '__main__.MyClass'>, (1, 2))
param class: | mapped class (must be a positional argument) |
---|---|
param ident: | primary key, may be a scalar or tuple argument. |
identity_key(instance=instance)
This form will produce the identity key for a given instance. The instance need not be persistent, only that its primary key attributes are populated (else the key will contain None for those missing values).
E.g.:
>>> instance = MyClass(1, 2)
>>> identity_key(instance=instance)
(<class '__main__.MyClass'>, (1, 2))
In this form, the given instance is ultimately run though Mapper.identity_key_from_instance(), which will have the effect of performing a database check for the corresponding row if the object is expired.
param instance: | object instance (must be given as a keyword arg) |
---|
identity_key(class, row=row)
This form is similar to the class/tuple form, except is passed a database result row as a RowProxy object.
E.g.:
>>> row = engine.execute("select * from table where a=1 and b=2").first()
>>> identity_key(MyClass, row=row)
(<class '__main__.MyClass'>, (1, 2))
param class: | mapped class (must be a positional argument) |
---|---|
param row: | RowProxy row returned by a ResultProxy (must be given as a keyword arg) |
Create a UNION statement used by a polymorphic mapper.
See Concrete Table Inheritance for an example of how this is used.
Parameters: |
|
---|
Bases: sqlalchemy.orm.base.InspectionAttr
Define the correlation of class attributes to database table columns.
The Mapper object is instantiated using the mapper() function. For information about instantiating new Mapper objects, see that function’s documentation.
When mapper() is used explicitly to link a user defined class with table metadata, this is referred to as classical mapping. Modern SQLAlchemy usage tends to favor the sqlalchemy.ext.declarative extension for class configuration, which makes usage of mapper() behind the scenes.
Given a particular class known to be mapped by the ORM, the Mapper which maintains it can be acquired using the inspect() function:
from sqlalchemy import inspect
mapper = inspect(MyClass)
A class which was mapped by the sqlalchemy.ext.declarative extension will also have its mapper available via the __mapper__ attribute.
Construct a new Mapper object.
This constructor is mirrored as a public API function; see mapper() for a full usage and argument description.
Add the given dictionary of properties to this mapper, using add_property.
Add an individual MapperProperty to this mapper.
If the mapper has not been configured yet, just adds the property to the initial properties dictionary sent to the constructor. If this Mapper has already been configured, then the given MapperProperty is configured immediately.
A namespace of all InspectionAttr attributes associated with the mapped class.
These attributes are in all cases Python descriptors associated with the mapped class or its superclasses.
This namespace includes attributes that are mapped to the class as well as attributes declared by extension modules. It includes any Python descriptor type that inherits from InspectionAttr. This includes QueryableAttribute, as well as extension types such as hybrid_property, hybrid_method and AssociationProxy.
To distinguish between mapped attributes and extension attributes, the attribute InspectionAttr.extension_type will refer to a constant that distinguishes between different extension types.
When dealing with a QueryableAttribute, the QueryableAttribute.property attribute refers to the MapperProperty property, which is what you get when referring to the collection of mapped properties via Mapper.attrs.
Warning
The Mapper.all_orm_descriptors accessor namespace is an instance of OrderedProperties. This is a dictionary-like object which includes a small number of named methods such as OrderedProperties.items() and OrderedProperties.values(). When accessing attributes dynamically, favor using the dict-access scheme, e.g. mapper.all_orm_descriptors[somename] over getattr(mapper.all_orm_descriptors, somename) to avoid name collisions.
New in version 0.8.0.
See also
A namespace of all MapperProperty objects associated this mapper.
This is an object that provides each property based on its key name. For instance, the mapper for a User class which has User.name attribute would provide mapper.attrs.name, which would be the ColumnProperty representing the name column. The namespace object can also be iterated, which would yield each MapperProperty.
Mapper has several pre-filtered views of this attribute which limit the types of properties returned, inclding synonyms, column_attrs, relationships, and composites.
Warning
The Mapper.attrs accessor namespace is an instance of OrderedProperties. This is a dictionary-like object which includes a small number of named methods such as OrderedProperties.items() and OrderedProperties.values(). When accessing attributes dynamically, favor using the dict-access scheme, e.g. mapper.attrs[somename] over getattr(mapper.attrs, somename) to avoid name collisions.
See also
The base-most Mapper in an inheritance chain.
In a non-inheriting scenario, this attribute will always be this Mapper. In an inheritance scenario, it references the Mapper which is parent to all other Mapper objects in the inheritance chain.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
Iterate each element and its mapper in an object graph, for all relationships that meet the given cascade rule.
Parameters: |
|
---|---|
Returns: | the method yields individual object instances. |
See also
How do I walk all objects that are related to a given object? - illustrates a generic function to traverse all objects without relying on cascades.
The Python class which this Mapper maps.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
The ClassManager which maintains event listeners and class-bound descriptors for this Mapper.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
Return a namespace of all ColumnProperty properties maintained by this Mapper.
See also
Mapper.attrs - namespace of all MapperProperty objects.
A collection of Column or other scalar expression objects maintained by this Mapper.
The collection behaves the same as that of the c attribute on any Table object, except that only those columns included in this mapping are present, and are keyed based on the attribute name defined in the mapping, not necessarily the key attribute of the Column itself. Additionally, scalar expressions mapped by column_property() are also present here.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
Return true if the given mapper shares a common inherited parent as this mapper.
Return a namespace of all CompositeProperty properties maintained by this Mapper.
See also
Mapper.attrs - namespace of all MapperProperty objects.
Represent True if this Mapper is a concrete inheritance mapper.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
Represent True if this Mapper has been configured.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
See also
Part of the inspection API.
Returns self.class_.
return a MapperProperty associated with the given key.
Given a Column object, return the MapperProperty which maps this column.
Return the identity key for the given instance, based on its primary key attributes.
If the instance’s state is expired, calling this method will result in a database check to see if the object has been deleted. If the row no longer exists, ObjectDeletedError is raised.
This value is typically also found on the instance state under the attribute name key.
Return an identity-map key for use in storing/retrieving an item from an identity map.
Parameters: | 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.
Parameters: | row¶ – A RowProxy instance. The columns which are mapped by this Mapper should be locatable in the row, preferably via the Column object directly (as is the case when a select() construct is executed), or via string names of the form <tablename>_<colname>. |
---|
References the Mapper which this Mapper inherits from, if any.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
Part of the inspection API.
Return True if the this mapper inherits from the given mapper.
return an iterator of all MapperProperty objects.
The Selectable which this Mapper manages.
Typically is an instance of Table or Alias. May also be None.
The “local” table is the selectable that the Mapper is directly responsible for managing from an attribute access and flush perspective. For non-inheriting mappers, the local table is the same as the “mapped” table. For joined-table inheritance mappers, local_table will be the particular sub-table of the overall “join” which this Mapper represents. If this mapper is a single-table inheriting mapper, local_table will be None.
See also
The Selectable to which this Mapper is mapped.
Typically an instance of Table, Join, or Alias.
The “mapped” table is the selectable that the mapper selects from during queries. For non-inheriting mappers, the mapped table is the same as the “local” table. For joined-table inheritance mappers, mapped_table references the full Join representing full rows for this particular subclass. For single-table inheritance mappers, mapped_table references the base table.
See also
Part of the inspection API.
Returns self.
Represent True if this Mapper is a “non-primary” mapper, e.g. a mapper that is used only to selet rows but not for persistence management.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
Represent an identifier which is matched against the polymorphic_on column during result row loading.
Used only with inheritance, this object can be of any type which is comparable to the type of column represented by polymorphic_on.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
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().
A mapping of “polymorphic identity” identifiers mapped to Mapper instances, within an inheritance scenario.
The identifiers can be of any type which is comparable to the type of column represented by polymorphic_on.
An inheritance chain of mappers will all reference the same polymorphic map object. The object is used to correlate incoming result rows to target mappers.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
The Column or SQL expression specified as the polymorphic_on argument for this Mapper, within an inheritance scenario.
This attribute is normally a Column instance but may also be an expression, such as one derived from cast().
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
An iterable containing the collection of Column objects which comprise the ‘primary key’ of the mapped table, from the perspective of this Mapper.
This list is against the selectable in mapped_table. In the case of inheriting mappers, some columns may be managed by a superclass mapper. For example, in the case of a Join, the primary key is determined by all of the primary key columns across all tables referenced by the Join.
The list is also not necessarily the same as the primary key column collection associated with the underlying tables; the Mapper features a primary_key argument that can override what the Mapper considers as primary key columns.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
Return the list of primary key values for the given instance.
If the instance’s state is expired, calling this method will result in a database check to see if the object has been deleted. If the row no longer exists, ObjectDeletedError is raised.
Return the primary mapper corresponding to this mapper’s class key (class).
A namespace of all RelationshipProperty properties maintained by this Mapper.
Warning
the Mapper.relationships accessor namespace is an instance of OrderedProperties. This is a dictionary-like object which includes a small number of named methods such as OrderedProperties.items() and OrderedProperties.values(). When accessing attributes dynamically, favor using the dict-access scheme, e.g. mapper.relationships[somename] over getattr(mapper.relationships, somename) to avoid name collisions.
See also
Mapper.attrs - namespace of all MapperProperty objects.
The select() construct this Mapper selects from by default.
Normally, this is equivalent to mapped_table, unless the with_polymorphic feature is in use, in which case the full “polymorphic” selectable is returned.
The collection including this mapper and all descendant mappers.
This includes not just the immediately inheriting mappers but all their inheriting mappers as well.
Represent True if this Mapper is a single table inheritance mapper.
local_table will be None if this flag is set.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
Return a namespace of all SynonymProperty properties maintained by this Mapper.
See also
Mapper.attrs - namespace of all MapperProperty objects.
An iterable containing the collection of Table objects which this Mapper is aware of.
If the mapper is mapped to a Join, or an Alias representing a Select, the individual Table objects that comprise the full construct will be represented here.
This is a read only attribute determined during mapper construction. Behavior is undefined if directly modified.
An immutable dictionary of attributes which have been decorated using the validates() decorator.
The dictionary contains string attribute names as keys mapped to the actual validation method.