Key ORM constructs, not otherwise covered in other sections, are listed here.
sqlalchemy.orm.state.
AttributeState
(state, key)¶Provide an inspection interface corresponding to a particular attribute on a particular mapped object.
The AttributeState
object is accessed
via the InstanceState.attrs
collection
of a particular InstanceState
:
from sqlalchemy import inspect
insp = inspect(some_mapped_object)
attr_state = insp.attrs.some_attribute
Inherited-members: | |
---|---|
loaded_value
¶The current value of this attribute as loaded from the database.
If the value has not been loaded, or is otherwise not present in the object’s dictionary, returns NO_VALUE.
value
¶Return the value of this attribute.
This operation is equivalent to accessing the object’s
attribute directly or via getattr()
, and will fire
off any pending loader callables if needed.
sqlalchemy.orm.instrumentation.
ClassManager
(class_)¶Bases: __builtin__.dict
tracks state information at the class level.
Inherited-members: | |
---|---|
dispose
()¶Dissasociate this manager from its class.
has_parent
(state, key, optimistic=False)¶TODO
manage
()¶Mark this instance as the manager for its class.
original_init
¶x.__init__(...) initializes x; see help(type(x)) for signature
state_getter
()¶Return a (instance) -> InstanceState callable.
“state getter” callables should raise either KeyError or AttributeError if no InstanceState could be found for the instance.
unregister
()¶remove all instrumentation established by this ClassManager.
sqlalchemy.orm.properties.
ColumnProperty
(*columns, **kwargs)¶Bases: sqlalchemy.orm.interfaces.StrategizedProperty
Describes an object attribute that corresponds to a table column.
Public constructor is the orm.column_property()
function.
Inherited-members: | |
---|---|
ColumnComparator
¶alias of Comparator
Comparator
(prop, parentmapper, adapter=None)¶Bases: sqlalchemy.orm.interfaces.PropComparator
Produce boolean, comparison, and other operators for
ColumnProperty
attributes.
See the documentation for PropComparator
for a brief
overview.
See also:
ColumnProperty.
__init__
(*columns, **kwargs)¶Construct a ColumnProperty.
Note the public constructor is the orm.column_property()
function.
Parameters: |
|
---|
ColumnProperty.
expression
¶Return the primary column or expression for this ColumnProperty.
sqlalchemy.orm.descriptor_props.
CompositeProperty
(class_, *attrs, **kwargs)¶Bases: sqlalchemy.orm.descriptor_props.DescriptorProperty
Defines a “composite” mapped attribute, representing a collection of columns as one attribute.
CompositeProperty
is constructed using the composite()
function.
See also:
Comparator
(prop, parentmapper, adapter=None)¶Bases: sqlalchemy.orm.interfaces.PropComparator
Produce boolean, comparison, and other operators for
CompositeProperty
attributes.
See the example in Redefining Comparison Operations for Composites for an overview
of usage , as well as the documentation for PropComparator
.
See also:
CompositeProperty.
do_init
()¶Initialization which occurs after the CompositeProperty
has been associated with its parent mapper.
CompositeProperty.
get_history
(state, dict_, passive=<symbol 'PASSIVE_OFF>)¶Provided for userland code that uses attributes.get_history().
sqlalchemy.orm.interfaces.
_InspectionAttr
¶A base class applied to all ORM objects that can be returned
by the inspect()
function.
The attributes defined here allow the usage of simple boolean checks to test basic facts about the object returned.
While the boolean checks here are basically the same as using the Python isinstance() function, the flags here can be used without the need to import all of these classes, and also such that the SQLAlchemy class system can change while leaving the flags here intact for forwards-compatibility.
extension_type
= <symbol 'NOT_EXTENSION>¶The extension type, if any.
Defaults to interfaces.NOT_EXTENSION
New in version 0.8.0.
is_aliased_class
= False¶True if this object is an instance of AliasedClass
.
is_attribute
= False¶True if this object is a Python descriptor.
This can refer to one of many types. Usually a
QueryableAttribute
which handles attributes events on behalf
of a MapperProperty
. But can also be an extension type
such as AssociationProxy
or hybrid_property
.
The _InspectionAttr.extension_type
will refer to a constant
identifying the specific subtype.
See also
is_clause_element
= False¶True if this object is an instance of ClauseElement
.
is_instance
= False¶True if this object is an instance of InstanceState
.
is_property
= False¶True if this object is an instance of MapperProperty
.
is_selectable
= False¶Return True if this object is an instance of Selectable
.
sqlalchemy.orm.state.
InstanceState
(obj, manager)¶Bases: sqlalchemy.orm.interfaces._InspectionAttr
tracks state information at the instance level.
__call__
(state, passive)¶__call__ allows the InstanceState to act as a deferred callable for loading expired attributes, which is also serializable (picklable).
attrs
¶Return a namespace representing each attribute on the mapped object, including its current value and history.
The returned object is an instance of AttributeState
.
detached
¶Return true if the object is detached.
expired_attributes
¶Return the set of keys which are ‘expired’ to be loaded by the manager’s deferred scalar loader, assuming no pending changes.
see also the unmodified
collection which is intersected
against this set when a refresh operation occurs.
has_identity
¶Return True
if this object has an identity key.
This should always have the same value as the
expression state.persistent or state.detached
.
identity
¶Return the mapped identity of the mapped object.
This is the primary key identity as persisted by the ORM
which can always be passed directly to
Query.get()
.
Returns None
if the object has no primary key identity.
Note
An object which is transient or pending does not have a mapped identity until it is flushed, even if its attributes include primary key values.
identity_key
¶Return the identity key for the mapped object.
This is the key used to locate the object within
the Session.identity_map
mapping. It contains
the identity as returned by identity
within it.
object
¶Return the mapped object represented by this
InstanceState
.
pending
¶Return true if the object is pending.
persistent
¶Return true if the object is persistent.
transient
¶Return true if the object is transient.
unloaded
¶Return the set of keys which do not have a loaded value.
This includes expired attributes and any other attribute that was never populated or modified.
unmodified
¶Return the set of keys which have no uncommitted changes
unmodified_intersection
(keys)¶Return self.unmodified.intersection(keys).
sqlalchemy.orm.attributes.
InstrumentedAttribute
(class_, key, impl=None, comparator=None, parententity=None, of_type=None)¶Bases: sqlalchemy.orm.attributes.QueryableAttribute
Class bound instrumented attribute which adds basic descriptor methods.
See QueryableAttribute
for a description of most features.
Undoc-members: |
---|
sqlalchemy.orm.interfaces.
MapperProperty
¶Bases: sqlalchemy.orm.interfaces._MappedAttribute
, sqlalchemy.orm.interfaces._InspectionAttr
Manage the relationship of a Mapper
to a single class
attribute, as well as that attribute as it appears on individual
instances of the class, including attribute instrumentation,
attribute access, loading behavior, and dependency calculations.
The most common occurrences of MapperProperty
are the
mapped Column
, which is represented in a mapping as
an instance of ColumnProperty
,
and a reference to another class produced by relationship()
,
represented in the mapping as an instance of
RelationshipProperty
.
cascade
= frozenset([])¶The set of ‘cascade’ attribute names.
This collection is checked before the ‘cascade_iterator’ method is called.
cascade_iterator
(type_, state, visited_instances=None, halt_on=None)¶Iterate through instances related to the given instance for a particular ‘cascade’, starting with this MapperProperty.
Return an iterator3-tuples (instance, mapper, state).
Note that the ‘cascade’ collection on this MapperProperty is checked first for the given type before cascade_iterator is called.
See PropertyLoader for the related instance implementation.
class_attribute
¶Return the class-bound descriptor corresponding to this
MapperProperty
.
This is basically a getattr()
call:
return getattr(self.parent.class_, self.key)
I.e. if this MapperProperty
were named addresses
,
and the class to which it is mapped is User
, this sequence
is possible:
>>> from sqlalchemy import inspect
>>> mapper = inspect(User)
>>> addresses_property = mapper.attrs.addresses
>>> addresses_property.class_attribute is User.addresses
True
>>> User.addresses.property is addresses_property
True
compare
(operator, value, **kw)¶Return a compare operation for the columns represented by
this MapperProperty
to the given value, which may be a
column value or an instance. ‘operator’ is an operator from
the operators module, or from sql.Comparator.
By default uses the PropComparator attached to this MapperProperty under the attribute name “comparator”.
create_row_processor
(context, path, mapper, row, adapter)¶Return a 3-tuple consisting of three row processing functions.
do_init
()¶Perform subclass-specific initialization post-mapper-creation steps.
This is a template method called by the MapperProperty
object’s init() method.
info
¶Info dictionary associated with the object, allowing user-defined
data to be associated with this MapperProperty
.
The dictionary is generated when first accessed. Alternatively,
it can be specified as a constructor argument to the
column_property()
, relationship()
, or composite()
functions.
New in version 0.8: Added support for .info to all
MapperProperty
subclasses.
init
()¶Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.
is_primary
()¶Return True if this MapperProperty
‘s mapper is the
primary mapper for its class.
This flag is used to indicate that the MapperProperty
can
define attribute instrumentation for the class at the class
level (as opposed to the individual instance level).
merge
(session, source_state, source_dict, dest_state, dest_dict, load, _recursive)¶Merge the attribute represented by this MapperProperty
from source to destination object
post_instrument_class
(mapper)¶Perform instrumentation adjustments that need to occur after init() has completed.
setup
(context, entity, path, adapter, **kwargs)¶Called by Query for the purposes of constructing a SQL statement.
Each MapperProperty associated with the target mapper processes the statement referenced by the query context, adding columns and/or criterion as appropriate.
sqlalchemy.orm.interfaces.
NOT_EXTENSION
= <symbol 'NOT_EXTENSION>¶sqlalchemy.orm.interfaces.
PropComparator
(prop, parentmapper, adapter=None)¶Bases: sqlalchemy.sql.operators.ColumnOperators
Defines boolean, comparison, and other operators for
MapperProperty
objects.
SQLAlchemy allows for operators to
be redefined at both the Core and ORM level. PropComparator
is the base class of operator redefinition for ORM-level operations,
including those of ColumnProperty
,
RelationshipProperty
, and CompositeProperty
.
Note
With the advent of Hybrid properties introduced in SQLAlchemy
0.7, as well as Core-level operator redefinition in
SQLAlchemy 0.8, the use case for user-defined PropComparator
instances is extremely rare. See Hybrid Attributes as well
as Redefining and Creating New Operators.
User-defined subclasses of PropComparator
may be created. The
built-in Python comparison and math operator methods, such as
operators.ColumnOperators.__eq__()
,
operators.ColumnOperators.__lt__()
, and
operators.ColumnOperators.__add__()
, can be overridden to provide
new operator behavior. The custom PropComparator
is passed to
the MapperProperty
instance via the comparator_factory
argument. In each case,
the appropriate subclass of PropComparator
should be used:
# definition of custom PropComparator subclasses
from sqlalchemy.orm.properties import \
ColumnProperty,\
CompositeProperty,\
RelationshipProperty
class MyColumnComparator(ColumnProperty.Comparator):
def __eq__(self, other):
return self.__clause_element__() == other
class MyRelationshipComparator(RelationshipProperty.Comparator):
def any(self, expression):
"define the 'any' operation"
# ...
class MyCompositeComparator(CompositeProperty.Comparator):
def __gt__(self, other):
"redefine the 'greater than' operation"
return sql.and_(*[a>b for a, b in
zip(self.__clause_element__().clauses,
other.__composite_values__())])
# application of custom PropComparator subclasses
from sqlalchemy.orm import column_property, relationship, composite
from sqlalchemy import Column, String
class SomeMappedClass(Base):
some_column = column_property(Column("some_column", String),
comparator_factory=MyColumnComparator)
some_relationship = relationship(SomeOtherClass,
comparator_factory=MyRelationshipComparator)
some_composite = composite(
Column("a", String), Column("b", String),
comparator_factory=MyCompositeComparator
)
Note that for column-level operator redefinition, it’s usually
simpler to define the operators at the Core level, using the
TypeEngine.comparator_factory
attribute. See
Redefining and Creating New Operators for more detail.
See also:
RelationshipProperty.Comparator
Redefining and Creating New Operators
Inherited-members: | |
---|---|
adapted
(adapter)¶Return a copy of this PropComparator which will use the given adaption function on the local side of generated expressions.
any
(criterion=None, **kwargs)¶Return true if this collection contains any member that meets the given criterion.
The usual implementation of any()
is
RelationshipProperty.Comparator.any()
.
Parameters: |
|
---|
has
(criterion=None, **kwargs)¶Return true if this element references a member which meets the given criterion.
The usual implementation of has()
is
RelationshipProperty.Comparator.has()
.
Parameters: |
|
---|
of_type
(class_)¶Redefine this object in terms of a polymorphic subclass.
Returns a new PropComparator from which further criterion can be evaluated.
e.g.:
query.join(Company.employees.of_type(Engineer)).\
filter(Engineer.name=='foo')
Parameters: | class_ – a class or mapper indicating that criterion will be against this specific subclass. |
---|
sqlalchemy.orm.properties.
RelationshipProperty
(argument, secondary=None, primaryjoin=None, secondaryjoin=None, foreign_keys=None, uselist=None, order_by=False, backref=None, back_populates=None, post_update=False, cascade=False, extension=None, viewonly=False, lazy=True, collection_class=None, passive_deletes=False, passive_updates=True, remote_side=None, enable_typechecks=True, join_depth=None, comparator_factory=None, single_parent=False, innerjoin=False, distinct_target_key=False, doc=None, active_history=False, cascade_backrefs=True, load_on_pending=False, strategy_class=None, _local_remote_pairs=None, query_class=None, info=None)¶Bases: sqlalchemy.orm.interfaces.StrategizedProperty
Describes an object property that holds a single item or list of items that correspond to a related database table.
Public constructor is the orm.relationship()
function.
See also:
Inherited-members: | |
---|---|
Comparator
(prop, parentmapper, of_type=None, adapter=None)¶Bases: sqlalchemy.orm.interfaces.PropComparator
Produce boolean, comparison, and other operators for
RelationshipProperty
attributes.
See the documentation for PropComparator
for a brief overview
of ORM level operator definition.
See also:
Redefining and Creating New Operators
__eq__
(other)¶Implement the ==
operator.
In a many-to-one context, such as:
MyClass.some_prop == <some object>
this will typically produce a clause such as:
mytable.related_id == <some id>
Where <some id>
is the primary key of the given
object.
The ==
operator provides partial functionality for non-
many-to-one comparisons:
contains()
.has()
for
more comprehensive non-many-to-one scalar
membership tests.None
given in a one-to-many
or many-to-many context produce a NOT EXISTS clause.__init__
(prop, parentmapper, of_type=None, adapter=None)¶Construction of RelationshipProperty.Comparator
is internal to the ORM’s attribute mechanics.
__ne__
(other)¶Implement the !=
operator.
In a many-to-one context, such as:
MyClass.some_prop != <some object>
This will typically produce a clause such as:
mytable.related_id != <some id>
Where <some id>
is the primary key of the
given object.
The !=
operator provides partial functionality for non-
many-to-one comparisons:
contains()
in conjunction with not_()
.has()
in
conjunction with not_()
for
more comprehensive non-many-to-one scalar
membership tests.None
given in a one-to-many
or many-to-many context produce an EXISTS clause.adapted
(adapter)¶Return a copy of this PropComparator which will use the given adaption function on the local side of generated expressions.
any
(criterion=None, **kwargs)¶Produce an expression that tests a collection against particular criterion, using EXISTS.
An expression like:
session.query(MyClass).filter(
MyClass.somereference.any(SomeRelated.x==2)
)
Will produce a query like:
SELECT * FROM my_table WHERE
EXISTS (SELECT 1 FROM related WHERE related.my_id=my_table.id
AND related.x=2)
Because any()
uses
a correlated subquery, its performance is not nearly as
good when compared against large target tables as that of
using a join.
any()
is particularly
useful for testing for empty collections:
session.query(MyClass).filter(
~MyClass.somereference.any()
)
will produce:
SELECT * FROM my_table WHERE
NOT EXISTS (SELECT 1 FROM related WHERE
related.my_id=my_table.id)
any()
is only
valid for collections, i.e. a relationship()
that has uselist=True
. For scalar references,
use has()
.
contains
(other, **kwargs)¶Return a simple expression that tests a collection for containment of a particular item.
contains()
is
only valid for a collection, i.e. a
relationship()
that implements
one-to-many or many-to-many with uselist=True
.
When used in a simple one-to-many context, an expression like:
MyClass.contains(other)
Produces a clause like:
mytable.id == <some id>
Where <some id>
is the value of the foreign key
attribute on other
which refers to the primary
key of its parent object. From this it follows that
contains()
is
very useful when used with simple one-to-many
operations.
For many-to-many operations, the behavior of
contains()
has more caveats. The association table will be
rendered in the statement, producing an “implicit”
join, that is, includes multiple tables in the FROM
clause which are equated in the WHERE clause:
query(MyClass).filter(MyClass.contains(other))
Produces a query like:
SELECT * FROM my_table, my_association_table AS
my_association_table_1 WHERE
my_table.id = my_association_table_1.parent_id
AND my_association_table_1.child_id = <some id>
Where <some id>
would be the primary key of
other
. From the above, it is clear that
contains()
will not work with many-to-many collections when
used in queries that move beyond simple AND
conjunctions, such as multiple
contains()
expressions joined by OR. In such cases subqueries or
explicit “outer joins” will need to be used instead.
See any()
for
a less-performant alternative using EXISTS, or refer
to Query.outerjoin()
as well as Querying with Joins
for more details on constructing outer joins.
has
(criterion=None, **kwargs)¶Produce an expression that tests a scalar reference against particular criterion, using EXISTS.
An expression like:
session.query(MyClass).filter(
MyClass.somereference.has(SomeRelated.x==2)
)
Will produce a query like:
SELECT * FROM my_table WHERE
EXISTS (SELECT 1 FROM related WHERE
related.id==my_table.related_id AND related.x=2)
Because has()
uses
a correlated subquery, its performance is not nearly as
good when compared against large target tables as that of
using a join.
has()
is only
valid for scalar references, i.e. a relationship()
that has uselist=False
. For collection references,
use any()
.
in_
(other)¶Produce an IN clause - this is not implemented
for relationship()
-based attributes at this time.
mapper
¶The target Mapper
referred to by this
:class:`.RelationshipProperty.Comparator.
This is the “target” or “remote” side of the
relationship()
.
of_type
(cls)¶Produce a construct that represents a particular ‘subtype’ of attribute for the parent class.
Currently this is usable in conjunction with Query.join()
and Query.outerjoin()
.
RelationshipProperty.
cascade
¶Return the current cascade setting for this
RelationshipProperty
.
RelationshipProperty.
mapper
¶Return the targeted Mapper
for this
RelationshipProperty
.
This is a lazy-initializing static attribute.
RelationshipProperty.
table
¶Return the selectable linked to this
Deprecated since version 0.7: Use .target
RelationshipProperty
object’s target
Mapper
.
sqlalchemy.orm.descriptor_props.
SynonymProperty
(name, map_column=None, descriptor=None, comparator_factory=None, doc=None)¶Bases: sqlalchemy.orm.descriptor_props.DescriptorProperty
Inherited-members: | |
---|---|
sqlalchemy.orm.query.
QueryContext
(query)¶sqlalchemy.orm.attributes.
QueryableAttribute
(class_, key, impl=None, comparator=None, parententity=None, of_type=None)¶Bases: sqlalchemy.orm.interfaces._MappedAttribute
, sqlalchemy.orm.interfaces._InspectionAttr
, sqlalchemy.orm.interfaces.PropComparator
Base class for descriptor objects that intercept
attribute events on behalf of a MapperProperty
object. The actual MapperProperty
is accessible
via the QueryableAttribute.property
attribute.
Inherited-members: | |
---|---|
info
¶Return the ‘info’ dictionary for the underlying SQL element.
The behavior here is as follows:
ColumnProperty
, which is mapped directly
to a schema-level Column
object, this attribute
will return the SchemaItem.info
dictionary associated
with the core-level Column
object.ColumnProperty
but is mapped to
any other kind of SQL expression other than a Column
,
the attribute will refer to the MapperProperty.info
dictionary
associated directly with the ColumnProperty
, assuming the SQL
expression itself does not have it’s own .info
attribute
(which should be the case, unless a user-defined SQL construct
has defined one).MapperProperty
,
including RelationshipProperty
, the attribute will refer
to the MapperProperty.info
dictionary associated with
that MapperProperty
.MapperProperty.info
dictionary of the MapperProperty
unconditionally, including for a ColumnProperty
that’s
associated directly with a schema.Column
, the attribute
can be referred to using QueryableAttribute.property
attribute, as MyClass.someattribute.property.info
.New in version 0.8.0.
parent
¶Return an inspection instance representing the parent.
This will be either an instance of Mapper
or AliasedInsp
, depending upon the nature
of the parent entity which this attribute is associated
with.
property
¶Return the MapperProperty
associated with this
QueryableAttribute
.
Return values here will commonly be instances of
ColumnProperty
or RelationshipProperty
.