Key ORM constructs, not otherwise covered in other sections, are listed here.
Object Name | Description |
---|---|
Provide an inspection interface corresponding to a particular attribute on a particular mapped object. |
|
Keeps track of the options sent to
|
|
Tracks state information at the class level. |
|
Describes an object attribute that corresponds to a table column. |
|
Instruments a Python property for use in query expressions. |
|
Defines a “composite” mapped attribute, representing a collection of columns as one attribute. |
|
A token propagated throughout the course of a chain of attribute events. |
|
A base class applied to all ORM objects that can be returned
by the |
|
Adds the |
|
tracks state information at the instance level. |
|
Class bound instrumented attribute which adds basic descriptor methods. |
|
Indicates the many-to-many direction for a |
|
Indicates the many-to-one direction for a |
|
Represent a particular class attribute mapped by |
|
Symbol indicating an |
|
Indicates the one-to-many direction for a |
|
Defines SQL operators for |
|
Base class for descriptor objects that intercept
attribute events on behalf of a |
|
Describes an object property that holds a single item or list of items that correspond to a related database table. |
|
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
sqlalchemy.orm.state.AttributeState.
history
¶Return the current pre-flush change history for
this attribute, via the History
interface.
This method will not emit loader callables if the value of the attribute is unloaded.
Note
The attribute history system tracks changes on a per flush
basis. Each time the Session
is flushed, the history
of each attribute is reset to empty. The Session
by
default autoflushes each time a Query
is invoked.
For
options on how to control this, see Flushing.
See also
AttributeState.load_history()
- retrieve history
using loader callables if the value is not locally present.
get_history()
- underlying function
sqlalchemy.orm.state.AttributeState.
load_history
()¶Return the current pre-flush change history for
this attribute, via the History
interface.
This method will emit loader callables if the value of the attribute is unloaded.
Note
The attribute history system tracks changes on a per flush
basis. Each time the Session
is flushed, the history
of each attribute is reset to empty. The Session
by
default autoflushes each time a Query
is invoked.
For
options on how to control this, see Flushing.
New in version 0.9.0.
sqlalchemy.orm.state.AttributeState.
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.
sqlalchemy.orm.state.AttributeState.
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.util.
CascadeOptions
(value_list)¶Keeps track of the options sent to
relationship.cascade
Class signature
class sqlalchemy.orm.util.CascadeOptions
(builtins.frozenset
)
sqlalchemy.orm.instrumentation.
ClassManager
(class_)¶Tracks state information at the class level.
Class signature
class sqlalchemy.orm.instrumentation.ClassManager
(builtins.dict
)
sqlalchemy.orm.instrumentation.ClassManager.
clear
() → None. Remove all items from D.¶inherited from the builtins.dict.clear
method of builtins.dict
sqlalchemy.orm.instrumentation.ClassManager.
copy
() → a shallow copy of D¶inherited from the builtins.dict.copy
method of builtins.dict
sqlalchemy.orm.instrumentation.ClassManager.
dispose
()¶Disassociate this manager from its class.
sqlalchemy.orm.instrumentation.ClassManager.
fromkeys
(value=None, /)¶inherited from the builtins.dict.fromkeys
method of builtins.dict
Create a new dictionary with keys from iterable and values set to value.
sqlalchemy.orm.instrumentation.ClassManager.
get
(key, default=None, /)¶inherited from the builtins.dict.get
method of builtins.dict
Return the value for key if key is in the dictionary, else default.
sqlalchemy.orm.instrumentation.ClassManager.
has_parent
(state, key, optimistic=False)¶TODO
sqlalchemy.orm.instrumentation.ClassManager.
items
() → a set-like object providing a view on D’s items¶inherited from the builtins.dict.items
method of builtins.dict
sqlalchemy.orm.instrumentation.ClassManager.
keys
() → a set-like object providing a view on D’s keys¶inherited from the builtins.dict.keys
method of builtins.dict
sqlalchemy.orm.instrumentation.ClassManager.
manage
()¶Mark this instance as the manager for its class.
sqlalchemy.orm.instrumentation.ClassManager.
original_init
()¶Initialize self. See help(type(self)) for accurate signature.
sqlalchemy.orm.instrumentation.ClassManager.
pop
(k[, d]) → v, remove specified key and return the corresponding value.¶inherited from the builtins.dict.pop
method of builtins.dict
If key is not found, default is returned if given, otherwise KeyError is raised
sqlalchemy.orm.instrumentation.ClassManager.
popitem
()¶inherited from the builtins.dict.popitem
method of builtins.dict
Remove and return a (key, value) pair as a 2-tuple.
Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.
sqlalchemy.orm.instrumentation.ClassManager.
setdefault
(key, default=None, /)¶inherited from the builtins.dict.setdefault
method of builtins.dict
Insert key with a value of default if key is not in the dictionary.
Return the value for key if key is in the dictionary, else default.
sqlalchemy.orm.instrumentation.ClassManager.
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.
sqlalchemy.orm.instrumentation.ClassManager.
unregister
()¶remove all instrumentation established by this ClassManager.
sqlalchemy.orm.instrumentation.ClassManager.
update
([E, ]**F) → None. Update D from dict/iterable E and F.¶inherited from the builtins.dict.update
method of builtins.dict
If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
sqlalchemy.orm.instrumentation.ClassManager.
values
() → an object providing a view on D’s values¶inherited from the builtins.dict.values
method of builtins.dict
sqlalchemy.orm.
ColumnProperty
(*columns, **kwargs)¶Describes an object attribute that corresponds to a table column.
Public constructor is the column_property()
function.
Class signature
class sqlalchemy.orm.ColumnProperty
(sqlalchemy.orm.StrategizedProperty
)
sqlalchemy.orm.ColumnProperty.
Comparator.
expressions
¶The full sequence of columns referenced by this attribute, adjusted for any aliasing in progress.
New in version 1.3.17.
See also
Mapping a Class against Multiple Tables - usage example
Comparator
(prop, parentmapper, adapt_to_entity=None)¶Produce boolean, comparison, and other operators for
ColumnProperty
attributes.
See the documentation for PropComparator
for a brief
overview.
Class signature
class sqlalchemy.orm.ColumnProperty.Comparator
(sqlalchemy.util.langhelpers.MemoizedSlots
, sqlalchemy.orm.PropComparator
)
sqlalchemy.orm.ColumnProperty.Comparator.
operate
(op, *other, **kwargs)¶Operate on an argument.
This is the lowest level of operation, raises
NotImplementedError
by default.
Overriding this on a subclass can allow common
behavior to be applied to all operations.
For example, overriding ColumnOperators
to apply func.lower()
to the left and right
side:
class MyComparator(ColumnOperators):
def operate(self, op, other):
return op(func.lower(self), func.lower(other))
sqlalchemy.orm.ColumnProperty.Comparator.
reverse_operate
(op, other, **kwargs)¶Reverse operate on an argument.
Usage is the same as operate()
.
sqlalchemy.orm.ColumnProperty.
__init__
(*columns, **kwargs)¶Construct a new ColumnProperty
object.
This constructor is mirrored as a public API function; see sqlalchemy.orm.column_property()
for a full usage and argument description.
sqlalchemy.orm.ColumnProperty.
do_init
()¶Perform subclass-specific initialization post-mapper-creation steps.
This is a template method called by the MapperProperty
object’s init() method.
sqlalchemy.orm.ColumnProperty.
expression
¶Return the primary column or expression for this ColumnProperty.
E.g.:
class File(Base):
# ...
name = Column(String(64))
extension = Column(String(8))
filename = column_property(name + '.' + extension)
path = column_property('C:/' + filename.expression)
sqlalchemy.orm.ColumnProperty.
instrument_class
(mapper)¶Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.
The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute.
This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process.
The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the “impl”) which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).
sqlalchemy.orm.ColumnProperty.
merge
(session, source_state, source_dict, dest_state, dest_dict, load, _recursive, _resolve_conflict_map)¶Merge the attribute represented by this MapperProperty
from source to destination object.
sqlalchemy.orm.
ComparableProperty
(comparator_factory, descriptor=None, doc=None, info=None)¶Instruments a Python property for use in query expressions.
Deprecated since version 0.7: comparable_property()
is deprecated and will be removed in a future release. Please refer to the hybrid
extension.
Class signature
class sqlalchemy.orm.ComparableProperty
(sqlalchemy.orm.descriptor_props.DescriptorProperty
)
sqlalchemy.orm.ComparableProperty.
__init__
(comparator_factory, descriptor=None, doc=None, info=None)¶Construct a new ComparableProperty
object.
This constructor is mirrored as a public API function; see sqlalchemy.orm.comparable_property()
for a full usage and argument description.
sqlalchemy.orm.
CompositeProperty
(class_, *attrs, **kwargs)¶Defines a “composite” mapped attribute, representing a collection of columns as one attribute.
CompositeProperty
is constructed using the composite()
function.
See also
Class signature
class sqlalchemy.orm.CompositeProperty
(sqlalchemy.orm.descriptor_props.DescriptorProperty
)
Comparator
(prop, parentmapper, adapt_to_entity=None)¶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
.
Class signature
class sqlalchemy.orm.CompositeProperty.Comparator
(sqlalchemy.orm.PropComparator
)
sqlalchemy.orm.CompositeProperty.Comparator.
clauses
¶CompositeBundle
(property_, expr)¶Class signature
class sqlalchemy.orm.CompositeProperty.CompositeBundle
(sqlalchemy.orm.query.Bundle
)
sqlalchemy.orm.CompositeProperty.CompositeBundle.
create_row_processor
(query, procs, labels)¶Produce the “row processing” function for this Bundle
.
May be overridden by subclasses.
See also
Column Bundles - includes an example of subclassing.
sqlalchemy.orm.CompositeProperty.
__init__
(class_, *attrs, **kwargs)¶Construct a new CompositeProperty
object.
This constructor is mirrored as a public API function; see sqlalchemy.orm.composite()
for a full usage and argument description.
sqlalchemy.orm.CompositeProperty.
do_init
()¶Initialization which occurs after the CompositeProperty
has been associated with its parent mapper.
sqlalchemy.orm.CompositeProperty.
get_history
(state, dict_, passive=symbol('PASSIVE_OFF'))¶Provided for userland code that uses attributes.get_history().
sqlalchemy.orm.CompositeProperty.
instrument_class
(mapper)¶Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.
The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute.
This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process.
The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the “impl”) which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).
sqlalchemy.orm.attributes.
Event
(attribute_impl, op)¶A token propagated throughout the course of a chain of attribute events.
Serves as an indicator of the source of the event and also provides a means of controlling propagation across a chain of attribute operations.
The Event
object is sent as the initiator
argument
when dealing with events such as AttributeEvents.append()
,
AttributeEvents.set()
,
and AttributeEvents.remove()
.
The Event
object is currently interpreted by the backref
event handlers, and is used to control the propagation of operations
across two mutually-dependent attributes.
New in version 0.9.0.
The AttributeImpl
which is the current event
initiator.
The symbol OP_APPEND
, OP_REMOVE
,
OP_REPLACE
, or OP_BULK_REPLACE
, indicating the
source operation.
sqlalchemy.orm.identity.
IdentityMap
¶sqlalchemy.orm.identity.IdentityMap.
check_modified
()¶return True if any InstanceStates present have been marked as ‘modified’.
sqlalchemy.orm.base.
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.
sqlalchemy.orm.base.InspectionAttr.
extension_type
= symbol('NOT_EXTENSION')¶The extension type, if any.
Defaults to NOT_EXTENSION
sqlalchemy.orm.base.InspectionAttr.
is_aliased_class
= False¶True if this object is an instance of AliasedClass
.
sqlalchemy.orm.base.InspectionAttr.
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
sqlalchemy.orm.base.InspectionAttr.
is_clause_element
= False¶True if this object is an instance of
ClauseElement
.
sqlalchemy.orm.base.InspectionAttr.
is_instance
= False¶True if this object is an instance of InstanceState
.
sqlalchemy.orm.base.InspectionAttr.
is_mapper
= False¶True if this object is an instance of Mapper
.
sqlalchemy.orm.base.InspectionAttr.
is_property
= False¶True if this object is an instance of MapperProperty
.
sqlalchemy.orm.base.InspectionAttr.
is_selectable
= False¶Return True if this object is an instance of
Selectable
.
sqlalchemy.orm.base.
InspectionAttrInfo
¶Adds the .info
attribute to InspectionAttr
.
The rationale for InspectionAttr
vs. InspectionAttrInfo
is that the former is compatible as a mixin for classes that specify
__slots__
; this is essentially an implementation artifact.
Class signature
class sqlalchemy.orm.base.InspectionAttrInfo
(sqlalchemy.orm.base.InspectionAttr
)
sqlalchemy.orm.base.InspectionAttrInfo.
info
¶Info dictionary associated with the object, allowing user-defined
data to be associated with this InspectionAttr
.
The dictionary is generated when first accessed. Alternatively,
it can be specified as a constructor argument to the
column_property()
, relationship()
, or
composite()
functions.
Changed in version 1.0.0: MapperProperty.info
is also
available on extension types via the
InspectionAttrInfo.info
attribute, so that it can apply
to a wider variety of ORM and extension constructs.
sqlalchemy.orm.state.
InstanceState
(obj, manager)¶tracks state information at the instance level.
The InstanceState
is a key object used by the
SQLAlchemy ORM in order to track the state of an object;
it is created the moment an object is instantiated, typically
as a result of instrumentation which SQLAlchemy applies
to the __init__()
method of the class.
InstanceState
is also a semi-public object,
available for runtime inspection as to the state of a
mapped instance, including information such as its current
status within a particular Session
and details
about data on individual attributes. The public API
in order to acquire a InstanceState
object
is to use the inspect()
system:
>>> from sqlalchemy import inspect
>>> insp = inspect(some_mapped_object)
See also
Class signature
class sqlalchemy.orm.state.InstanceState
(sqlalchemy.orm.base.InspectionAttrInfo
)
sqlalchemy.orm.state.InstanceState.
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
.
This object allows inspection of the current data
within an attribute as well as attribute history
since the last flush.
sqlalchemy.orm.state.InstanceState.
callables
= ()¶A namespace where a per-state loader callable can be associated.
In SQLAlchemy 1.0, this is only used for lazy loaders / deferred loaders that were set up via query option.
Previously, callables was used also to indicate expired attributes by storing a link to the InstanceState itself in this dictionary. This role is now handled by the expired_attributes set.
sqlalchemy.orm.state.InstanceState.
deleted
¶Return True
if the object is deleted.
An object that is in the deleted state is guaranteed to
not be within the Session.identity_map
of its parent
Session
; however if the session’s transaction is rolled
back, the object will be restored to the persistent state and
the identity map.
Note
The InstanceState.deleted
attribute refers to a specific
state of the object that occurs between the “persistent” and
“detached” states; once the object is detached, the
InstanceState.deleted
attribute no longer returns
True; in order to detect that a state was deleted, regardless
of whether or not the object is associated with a
Session
, use the InstanceState.was_deleted
accessor.
See also
sqlalchemy.orm.state.InstanceState.
detached
¶Return True
if the object is detached.
See also
sqlalchemy.orm.state.InstanceState.
dict
¶Return the instance dict used by the object.
Under normal circumstances, this is always synonymous
with the __dict__
attribute of the mapped object,
unless an alternative instrumentation system has been
configured.
In the case that the actual object has been garbage collected, this accessor returns a blank dictionary.
sqlalchemy.orm.state.InstanceState.
expired_attributes
= None¶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.
sqlalchemy.orm.state.InstanceState.
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
.
sqlalchemy.orm.state.InstanceState.
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.
sqlalchemy.orm.state.InstanceState.
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.
sqlalchemy.orm.state.InstanceState.
mapper
¶Return the Mapper
used for this mapped object.
sqlalchemy.orm.state.InstanceState.
object
¶Return the mapped object represented by this
InstanceState
.
sqlalchemy.orm.state.InstanceState.
pending
¶Return True
if the object is pending.
See also
sqlalchemy.orm.state.InstanceState.
persistent
¶Return True
if the object is persistent.
An object that is in the persistent state is guaranteed to
be within the Session.identity_map
of its parent
Session
.
Changed in version 1.1: The InstanceState.persistent
accessor no longer returns True for an object that was
“deleted” within a flush; use the InstanceState.deleted
accessor to detect this state. This allows the “persistent”
state to guarantee membership in the identity map.
See also
sqlalchemy.orm.state.InstanceState.
session
¶Return the owning Session
for this instance,
or None
if none available.
Note that the result here can in some cases be different
from that of obj in session
; an object that’s been deleted
will report as not in session
, however if the transaction is
still in progress, this attribute will still refer to that session.
Only when the transaction is completed does the object become
fully detached under normal circumstances.
sqlalchemy.orm.state.InstanceState.
transient
¶Return True
if the object is transient.
See also
sqlalchemy.orm.state.InstanceState.
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.
sqlalchemy.orm.state.InstanceState.
unloaded_expirable
¶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.
sqlalchemy.orm.state.InstanceState.
unmodified
¶Return the set of keys which have no uncommitted changes
sqlalchemy.orm.state.InstanceState.
unmodified_intersection
(keys)¶Return self.unmodified.intersection(keys).
sqlalchemy.orm.state.InstanceState.
was_deleted
¶Return True if this object is or was previously in the “deleted” state and has not been reverted to persistent.
This flag returns True once the object was deleted in flush. When the object is expunged from the session either explicitly or via transaction commit and enters the “detached” state, this flag will continue to report True.
New in version 1.1: - added a local method form of
was_deleted()
.
sqlalchemy.orm.attributes.
InstrumentedAttribute
(class_, key, impl=None, comparator=None, parententity=None, of_type=None)¶Class bound instrumented attribute which adds basic descriptor methods.
See QueryableAttribute
for a description of most features.
Class signature
class sqlalchemy.orm.attributes.InstrumentedAttribute
(sqlalchemy.orm.attributes.QueryableAttribute
)
sqlalchemy.orm.attributes.InstrumentedAttribute.
__delete__
(instance)¶sqlalchemy.orm.attributes.InstrumentedAttribute.
__get__
(instance, owner)¶sqlalchemy.orm.attributes.InstrumentedAttribute.
__set__
(instance, value)¶sqlalchemy.orm.interfaces.
MANYTOONE
= symbol('MANYTOONE')¶Indicates the many-to-one direction for a relationship()
.
This symbol is typically used by the internals but may be exposed within certain API features.
sqlalchemy.orm.interfaces.
MANYTOMANY
= symbol('MANYTOMANY')¶Indicates the many-to-many direction for a relationship()
.
This symbol is typically used by the internals but may be exposed within certain API features.
sqlalchemy.orm.interfaces.
MapperProperty
¶Represent a particular class attribute mapped by Mapper
.
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
.
Class signature
class sqlalchemy.orm.MapperProperty
(sqlalchemy.orm.base._MappedAttribute
, sqlalchemy.orm.base.InspectionAttr
, sqlalchemy.util.langhelpers.MemoizedSlots
)
sqlalchemy.orm.interfaces.MapperProperty.
info
¶Info dictionary associated with the object, allowing user-defined
data to be associated with this InspectionAttr
.
The dictionary is generated when first accessed. Alternatively,
it can be specified as a constructor argument to the
column_property()
, relationship()
, or composite()
functions.
Changed in version 1.0.0: InspectionAttr.info
moved
from MapperProperty
so that it can apply to a wider
variety of ORM and extension constructs.
sqlalchemy.orm.interfaces.MapperProperty.
cascade
= frozenset({})¶The set of ‘cascade’ attribute names.
This collection is checked before the ‘cascade_iterator’ method is called.
The collection typically only applies to a RelationshipProperty.
sqlalchemy.orm.interfaces.MapperProperty.
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.
This method typically only applies to RelationshipProperty.
sqlalchemy.orm.interfaces.MapperProperty.
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
sqlalchemy.orm.interfaces.MapperProperty.
create_row_processor
(context, path, mapper, result, adapter, populators)¶Produce row processing functions and append to the given set of populators lists.
sqlalchemy.orm.interfaces.MapperProperty.
do_init
()¶Perform subclass-specific initialization post-mapper-creation steps.
This is a template method called by the MapperProperty
object’s init() method.
sqlalchemy.orm.interfaces.MapperProperty.
init
()¶Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.
sqlalchemy.orm.interfaces.MapperProperty.
instrument_class
(mapper)¶Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.
The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute.
This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process.
The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the “impl”) which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).
sqlalchemy.orm.interfaces.MapperProperty.
is_property
= True¶Part of the InspectionAttr interface; states this object is a mapper property.
sqlalchemy.orm.interfaces.MapperProperty.
merge
(session, source_state, source_dict, dest_state, dest_dict, load, _recursive, _resolve_conflict_map)¶Merge the attribute represented by this MapperProperty
from source to destination object.
sqlalchemy.orm.interfaces.MapperProperty.
post_instrument_class
(mapper)¶Perform instrumentation adjustments that need to occur after init() has completed.
The given Mapper is the Mapper invoking the operation, which may not be the same Mapper as self.parent in an inheritance scenario; however, Mapper will always at least be a sub-mapper of self.parent.
This method is typically used by StrategizedProperty, which delegates it to LoaderStrategy.init_class_attribute() to perform final setup on the class-bound InstrumentedAttribute.
sqlalchemy.orm.interfaces.MapperProperty.
set_parent
(parent, init)¶Set the parent mapper that references this MapperProperty.
This method is overridden by some subclasses to perform extra setup when the mapper is first known.
sqlalchemy.orm.interfaces.MapperProperty.
setup
(context, query_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')¶Symbol indicating an InspectionAttr
that’s
not part of sqlalchemy.ext.
Is assigned to the InspectionAttr.extension_type
attribute.
sqlalchemy.orm.interfaces.
ONETOMANY
= symbol('ONETOMANY')¶Indicates the one-to-many direction for a relationship()
.
This symbol is typically used by the internals but may be exposed within certain API features.
sqlalchemy.orm.
PropComparator
(prop, parentmapper, adapt_to_entity=None)¶Defines SQL 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
ColumnOperators.__eq__()
,
ColumnOperators.__lt__()
, and
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.
Class signature
class sqlalchemy.orm.PropComparator
(sqlalchemy.sql.operators.ColumnOperators
)
sqlalchemy.orm.PropComparator.
__eq__
(other)¶inherited from the sqlalchemy.sql.operators.ColumnOperators.__eq__
method of ColumnOperators
Implement the ==
operator.
In a column context, produces the clause a = b
.
If the target is None
, produces a IS NULL
.
sqlalchemy.orm.PropComparator.
__le__
(other)¶inherited from the sqlalchemy.sql.operators.ColumnOperators.__le__
method of ColumnOperators
Implement the <=
operator.
In a column context, produces the clause a <= b
.
sqlalchemy.orm.PropComparator.
__lt__
(other)¶inherited from the sqlalchemy.sql.operators.ColumnOperators.__lt__
method of ColumnOperators
Implement the <
operator.
In a column context, produces the clause a < b
.
sqlalchemy.orm.PropComparator.
__ne__
(other)¶inherited from the sqlalchemy.sql.operators.ColumnOperators.__ne__
method of ColumnOperators
Implement the !=
operator.
In a column context, produces the clause a != b
.
If the target is None
, produces a IS NOT NULL
.
sqlalchemy.orm.PropComparator.
adapt_to_entity
(adapt_to_entity)¶Return a copy of this PropComparator which will use the given
AliasedInsp
to produce corresponding expressions.
sqlalchemy.orm.PropComparator.
adapter
¶Produce a callable that adapts column expressions to suit an aliased version of this comparator.
sqlalchemy.orm.PropComparator.
all_
()¶inherited from the ColumnOperators.all_()
method of ColumnOperators
Produce a all_()
clause against the
parent object.
This operator is only appropriate against a scalar subquery object, or for some backends an column expression that is against the ARRAY type, e.g.:
# postgresql '5 = ALL (somearray)'
expr = 5 == mytable.c.somearray.all_()
# mysql '5 = ALL (SELECT value FROM table)'
expr = 5 == select([table.c.value]).as_scalar().all_()
New in version 1.1.
sqlalchemy.orm.PropComparator.
any
(criterion=None, **kwargs)¶Return true if this collection contains any member that meets the given criterion.
The usual implementation of any()
is
Comparator.any()
.
sqlalchemy.orm.PropComparator.
any_
()¶inherited from the ColumnOperators.any_()
method of ColumnOperators
Produce a any_()
clause against the
parent object.
This operator is only appropriate against a scalar subquery object, or for some backends an column expression that is against the ARRAY type, e.g.:
# postgresql '5 = ANY (somearray)'
expr = 5 == mytable.c.somearray.any_()
# mysql '5 = ANY (SELECT value FROM table)'
expr = 5 == select([table.c.value]).as_scalar().any_()
New in version 1.1.
sqlalchemy.orm.PropComparator.
asc
()¶inherited from the ColumnOperators.asc()
method of ColumnOperators
Produce a asc()
clause against the
parent object.
sqlalchemy.orm.PropComparator.
between
(cleft, cright, symmetric=False)¶inherited from the ColumnOperators.between()
method of ColumnOperators
Produce a between()
clause against
the parent object, given the lower and upper range.
sqlalchemy.orm.PropComparator.
bool_op
(opstring, precedence=0)¶inherited from the Operators.bool_op()
method of Operators
Return a custom boolean operator.
This method is shorthand for calling
Operators.op()
and passing the
Operators.op.is_comparison
flag with True.
New in version 1.2.0b3.
See also
sqlalchemy.orm.PropComparator.
collate
(collation)¶inherited from the ColumnOperators.collate()
method of ColumnOperators
Produce a collate()
clause against
the parent object, given the collation string.
See also
sqlalchemy.orm.PropComparator.
concat
(other)¶inherited from the ColumnOperators.concat()
method of ColumnOperators
Implement the ‘concat’ operator.
In a column context, produces the clause a || b
,
or uses the concat()
operator on MySQL.
sqlalchemy.orm.PropComparator.
contains
(other, **kwargs)¶inherited from the ColumnOperators.contains()
method of ColumnOperators
Implement the ‘contains’ operator.
Produces a LIKE expression that tests against a match for the middle of a string value:
column LIKE '%' || <other> || '%'
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.contains("foobar"))
Since the operator uses LIKE
, wildcard characters
"%"
and "_"
that are present inside the <other> expression
will behave like wildcards as well. For literal string
values, the ColumnOperators.contains.autoescape
flag
may be set to True
to apply escaping to occurrences of these
characters within the string value so that they match as themselves
and not as wildcard characters. Alternatively, the
ColumnOperators.contains.escape
parameter will establish
a given character as an escape character which can be of use when
the target expression is not a literal string.
other¶ – expression to be compared. This is usually a plain
string value, but can also be an arbitrary SQL expression. LIKE
wildcard characters %
and _
are not escaped by default unless
the ColumnOperators.contains.autoescape
flag is
set to True.
autoescape¶ –
boolean; when True, establishes an escape character
within the LIKE expression, then applies it to all occurrences of
"%"
, "_"
and the escape character itself within the
comparison value, which is assumed to be a literal string and not a
SQL expression.
An expression such as:
somecolumn.contains("foo%bar", autoescape=True)
Will render as:
somecolumn LIKE '%' || :param || '%' ESCAPE '/'
With the value of :param
as "foo/%bar"
.
New in version 1.2.
Changed in version 1.2.0: The
ColumnOperators.contains.autoescape
parameter is
now a simple boolean rather than a character; the escape
character itself is also escaped, and defaults to a forwards
slash, which itself can be customized using the
ColumnOperators.contains.escape
parameter.
escape¶ –
a character which when given will render with the
ESCAPE
keyword to establish that character as the escape
character. This character can then be placed preceding occurrences
of %
and _
to allow them to act as themselves and not
wildcard characters.
An expression such as:
somecolumn.contains("foo/%bar", escape="^")
Will render as:
somecolumn LIKE '%' || :param || '%' ESCAPE '^'
The parameter may also be combined with
ColumnOperators.contains.autoescape
:
somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
Where above, the given literal parameter will be converted to
"foo^%bar^^bat"
before being passed to the database.
sqlalchemy.orm.PropComparator.
desc
()¶inherited from the ColumnOperators.desc()
method of ColumnOperators
Produce a desc()
clause against the
parent object.
sqlalchemy.orm.PropComparator.
distinct
()¶inherited from the ColumnOperators.distinct()
method of ColumnOperators
Produce a distinct()
clause against the
parent object.
sqlalchemy.orm.PropComparator.
endswith
(other, **kwargs)¶inherited from the ColumnOperators.endswith()
method of ColumnOperators
Implement the ‘endswith’ operator.
Produces a LIKE expression that tests against a match for the end of a string value:
column LIKE '%' || <other>
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.endswith("foobar"))
Since the operator uses LIKE
, wildcard characters
"%"
and "_"
that are present inside the <other> expression
will behave like wildcards as well. For literal string
values, the ColumnOperators.endswith.autoescape
flag
may be set to True
to apply escaping to occurrences of these
characters within the string value so that they match as themselves
and not as wildcard characters. Alternatively, the
ColumnOperators.endswith.escape
parameter will establish
a given character as an escape character which can be of use when
the target expression is not a literal string.
other¶ – expression to be compared. This is usually a plain
string value, but can also be an arbitrary SQL expression. LIKE
wildcard characters %
and _
are not escaped by default unless
the ColumnOperators.endswith.autoescape
flag is
set to True.
autoescape¶ –
boolean; when True, establishes an escape character
within the LIKE expression, then applies it to all occurrences of
"%"
, "_"
and the escape character itself within the
comparison value, which is assumed to be a literal string and not a
SQL expression.
An expression such as:
somecolumn.endswith("foo%bar", autoescape=True)
Will render as:
somecolumn LIKE '%' || :param ESCAPE '/'
With the value of :param
as "foo/%bar"
.
New in version 1.2.
Changed in version 1.2.0: The
ColumnOperators.endswith.autoescape
parameter is
now a simple boolean rather than a character; the escape
character itself is also escaped, and defaults to a forwards
slash, which itself can be customized using the
ColumnOperators.endswith.escape
parameter.
escape¶ –
a character which when given will render with the
ESCAPE
keyword to establish that character as the escape
character. This character can then be placed preceding occurrences
of %
and _
to allow them to act as themselves and not
wildcard characters.
An expression such as:
somecolumn.endswith("foo/%bar", escape="^")
Will render as:
somecolumn LIKE '%' || :param ESCAPE '^'
The parameter may also be combined with
ColumnOperators.endswith.autoescape
:
somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
Where above, the given literal parameter will be converted to
"foo^%bar^^bat"
before being passed to the database.
sqlalchemy.orm.PropComparator.
has
(criterion=None, **kwargs)¶Return true if this element references a member which meets the given criterion.
The usual implementation of has()
is
Comparator.has()
.
sqlalchemy.orm.PropComparator.
ilike
(other, escape=None)¶inherited from the ColumnOperators.ilike()
method of ColumnOperators
Implement the ilike
operator, e.g. case insensitive LIKE.
In a column context, produces an expression either of the form:
lower(a) LIKE lower(other)
Or on backends that support the ILIKE operator:
a ILIKE other
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.ilike("%foobar%"))
See also
sqlalchemy.orm.PropComparator.
in_
(other)¶inherited from the ColumnOperators.in_()
method of ColumnOperators
Implement the in
operator.
In a column context, produces the clause column IN <other>
.
The given parameter other
may be:
A list of literal values, e.g.:
stmt.where(column.in_([1, 2, 3]))
In this calling form, the list of items is converted to a set of bound parameters the same length as the list given:
WHERE COL IN (?, ?, ?)
A list of tuples may be provided if the comparison is against a
tuple_()
containing multiple expressions:
from sqlalchemy import tuple_
stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
An empty list, e.g.:
stmt.where(column.in_([]))
In this calling form, the expression renders a “false” expression, e.g.:
WHERE 1 != 1
This “false” expression has historically had different behaviors
in older SQLAlchemy versions, see
create_engine.empty_in_strategy
for behavioral options.
Changed in version 1.2: simplified the behavior of “empty in” expressions
A bound parameter, e.g. bindparam()
, may be used if it
includes the bindparam.expanding
flag:
stmt.where(column.in_(bindparam('value', expanding=True)))
In this calling form, the expression renders a special non-SQL placeholder expression that looks like:
WHERE COL IN ([EXPANDING_value])
This placeholder expression is intercepted at statement execution time to be converted into the variable number of bound parameter form illustrated earlier. If the statement were executed as:
connection.execute(stmt, {"value": [1, 2, 3]})
The database would be passed a bound parameter for each value:
WHERE COL IN (?, ?, ?)
New in version 1.2: added “expanding” bound parameters
If an empty list is passed, a special “empty list” expression, which is specific to the database in use, is rendered. On SQLite this would be:
WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
New in version 1.3: “expanding” bound parameters now support empty lists
a select()
construct,
which is usually a correlated
scalar select:
stmt.where(
column.in_(
select([othertable.c.y]).
where(table.c.x == othertable.c.x)
)
)
In this calling form, ColumnOperators.in_()
renders as given:
WHERE COL IN (SELECT othertable.y
FROM othertable WHERE othertable.x = table.x)
other¶ – a list of literals, a select()
construct,
or a bindparam()
construct that includes the
bindparam.expanding
flag set to True.
sqlalchemy.orm.PropComparator.
is_
(other)¶inherited from the ColumnOperators.is_()
method of ColumnOperators
Implement the IS
operator.
Normally, IS
is generated automatically when comparing to a
value of None
, which resolves to NULL
. However, explicit
usage of IS
may be desirable if comparing to boolean values
on certain platforms.
See also
sqlalchemy.orm.PropComparator.
is_distinct_from
(other)¶inherited from the ColumnOperators.is_distinct_from()
method of ColumnOperators
Implement the IS DISTINCT FROM
operator.
Renders “a IS DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS NOT b”.
New in version 1.1.
sqlalchemy.orm.PropComparator.
isnot
(other)¶inherited from the ColumnOperators.isnot()
method of ColumnOperators
Implement the IS NOT
operator.
Normally, IS NOT
is generated automatically when comparing to a
value of None
, which resolves to NULL
. However, explicit
usage of IS NOT
may be desirable if comparing to boolean values
on certain platforms.
See also
sqlalchemy.orm.PropComparator.
isnot_distinct_from
(other)¶inherited from the ColumnOperators.isnot_distinct_from()
method of ColumnOperators
Implement the IS NOT DISTINCT FROM
operator.
Renders “a IS NOT DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS b”.
New in version 1.1.
sqlalchemy.orm.PropComparator.
like
(other, escape=None)¶inherited from the ColumnOperators.like()
method of ColumnOperators
Implement the like
operator.
In a column context, produces the expression:
a LIKE other
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.like("%foobar%"))
See also
sqlalchemy.orm.PropComparator.
match
(other, **kwargs)¶inherited from the ColumnOperators.match()
method of ColumnOperators
Implements a database-specific ‘match’ operator.
ColumnOperators.match()
attempts to resolve to
a MATCH-like function or operator provided by the backend.
Examples include:
PostgreSQL - renders x @@ to_tsquery(y)
MySQL - renders MATCH (x) AGAINST (y IN BOOLEAN MODE)
Oracle - renders CONTAINS(x, y)
other backends may provide special implementations.
Backends without any special implementation will emit the operator as “MATCH”. This is compatible with SQLite, for example.
sqlalchemy.orm.PropComparator.
notilike
(other, escape=None)¶inherited from the ColumnOperators.notilike()
method of ColumnOperators
implement the NOT ILIKE
operator.
This is equivalent to using negation with
ColumnOperators.ilike()
, i.e. ~x.ilike(y)
.
See also
sqlalchemy.orm.PropComparator.
notin_
(other)¶inherited from the ColumnOperators.notin_()
method of ColumnOperators
implement the NOT IN
operator.
This is equivalent to using negation with
ColumnOperators.in_()
, i.e. ~x.in_(y)
.
In the case that other
is an empty sequence, the compiler
produces an “empty not in” expression. This defaults to the
expression “1 = 1” to produce true in all cases. The
create_engine.empty_in_strategy
may be used to
alter this behavior.
Changed in version 1.2: The ColumnOperators.in_()
and
ColumnOperators.notin_()
operators
now produce a “static” expression for an empty IN sequence
by default.
See also
sqlalchemy.orm.PropComparator.
notlike
(other, escape=None)¶inherited from the ColumnOperators.notlike()
method of ColumnOperators
implement the NOT LIKE
operator.
This is equivalent to using negation with
ColumnOperators.like()
, i.e. ~x.like(y)
.
See also
sqlalchemy.orm.PropComparator.
nullsfirst
()¶inherited from the ColumnOperators.nullsfirst()
method of ColumnOperators
Produce a nullsfirst()
clause against the
parent object.
sqlalchemy.orm.PropComparator.
nullslast
()¶inherited from the ColumnOperators.nullslast()
method of ColumnOperators
Produce a nullslast()
clause against the
parent object.
sqlalchemy.orm.PropComparator.
of_type
(class_)¶Redefine this object in terms of a polymorphic subclass,
with_polymorphic()
construct, or aliased()
construct.
Returns a new PropComparator from which further criterion can be evaluated.
e.g.:
query.join(Company.employees.of_type(Engineer)).\
filter(Engineer.name=='foo')
class_¶ – a class or mapper indicating that criterion will be against this specific subclass.
sqlalchemy.orm.PropComparator.
op
(opstring, precedence=0, is_comparison=False, return_type=None)¶inherited from the Operators.op()
method of Operators
Produce a generic operator function.
e.g.:
somecolumn.op("*")(5)
produces:
somecolumn * 5
This function can also be used to make bitwise operators explicit. For example:
somecolumn.op('&')(0xff)
is a bitwise AND of the value in somecolumn
.
operator¶ – a string which will be output as the infix operator between this element and the expression passed to the generated function.
precedence¶ – precedence to apply to the operator, when
parenthesizing expressions. A lower number will cause the expression
to be parenthesized when applied against another operator with
higher precedence. The default value of 0
is lower than all
operators except for the comma (,
) and AS
operators.
A value of 100 will be higher or equal to all operators, and -100
will be lower than or equal to all operators.
is_comparison¶ –
if True, the operator will be considered as a
“comparison” operator, that is which evaluates to a boolean
true/false value, like ==
, >
, etc. This flag should be set
so that ORM relationships can establish that the operator is a
comparison operator when used in a custom join condition.
New in version 0.9.2: - added the
Operators.op.is_comparison
flag.
return_type¶ –
a TypeEngine
class or object that will
force the return type of an expression produced by this operator
to be of that type. By default, operators that specify
Operators.op.is_comparison
will resolve to
Boolean
, and those that do not will be of the same
type as the left-hand operand.
New in version 1.2.0b3: - added the
Operators.op.return_type
argument.
sqlalchemy.orm.PropComparator.
operate
(op, *other, **kwargs)¶inherited from the Operators.operate()
method of Operators
Operate on an argument.
This is the lowest level of operation, raises
NotImplementedError
by default.
Overriding this on a subclass can allow common
behavior to be applied to all operations.
For example, overriding ColumnOperators
to apply func.lower()
to the left and right
side:
class MyComparator(ColumnOperators):
def operate(self, op, other):
return op(func.lower(self), func.lower(other))
sqlalchemy.orm.PropComparator.
reverse_operate
(op, other, **kwargs)¶inherited from the Operators.reverse_operate()
method of Operators
Reverse operate on an argument.
Usage is the same as operate()
.
sqlalchemy.orm.PropComparator.
startswith
(other, **kwargs)¶inherited from the ColumnOperators.startswith()
method of ColumnOperators
Implement the startswith
operator.
Produces a LIKE expression that tests against a match for the start of a string value:
column LIKE <other> || '%'
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.startswith("foobar"))
Since the operator uses LIKE
, wildcard characters
"%"
and "_"
that are present inside the <other> expression
will behave like wildcards as well. For literal string
values, the ColumnOperators.startswith.autoescape
flag
may be set to True
to apply escaping to occurrences of these
characters within the string value so that they match as themselves
and not as wildcard characters. Alternatively, the
ColumnOperators.startswith.escape
parameter will establish
a given character as an escape character which can be of use when
the target expression is not a literal string.
other¶ – expression to be compared. This is usually a plain
string value, but can also be an arbitrary SQL expression. LIKE
wildcard characters %
and _
are not escaped by default unless
the ColumnOperators.startswith.autoescape
flag is
set to True.
autoescape¶ –
boolean; when True, establishes an escape character
within the LIKE expression, then applies it to all occurrences of
"%"
, "_"
and the escape character itself within the
comparison value, which is assumed to be a literal string and not a
SQL expression.
An expression such as:
somecolumn.startswith("foo%bar", autoescape=True)
Will render as:
somecolumn LIKE :param || '%' ESCAPE '/'
With the value of :param
as "foo/%bar"
.
New in version 1.2.
Changed in version 1.2.0: The
ColumnOperators.startswith.autoescape
parameter is
now a simple boolean rather than a character; the escape
character itself is also escaped, and defaults to a forwards
slash, which itself can be customized using the
ColumnOperators.startswith.escape
parameter.
escape¶ –
a character which when given will render with the
ESCAPE
keyword to establish that character as the escape
character. This character can then be placed preceding occurrences
of %
and _
to allow them to act as themselves and not
wildcard characters.
An expression such as:
somecolumn.startswith("foo/%bar", escape="^")
Will render as:
somecolumn LIKE :param || '%' ESCAPE '^'
The parameter may also be combined with
ColumnOperators.startswith.autoescape
:
somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
Where above, the given literal parameter will be converted to
"foo^%bar^^bat"
before being passed to the database.
sqlalchemy.orm.
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='select', 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=None, doc=None, active_history=False, cascade_backrefs=True, load_on_pending=False, bake_queries=True, _local_remote_pairs=None, query_class=None, info=None, omit_join=None, sync_backref=None)¶Describes an object property that holds a single item or list of items that correspond to a related database table.
Public constructor is the relationship()
function.
See also
Class signature
class sqlalchemy.orm.RelationshipProperty
(sqlalchemy.orm.StrategizedProperty
)
Comparator
(prop, parentmapper, adapt_to_entity=None, of_type=None)¶Produce boolean, comparison, and other operators for
RelationshipProperty
attributes.
See the documentation for PropComparator
for a brief
overview of ORM level operator definition.
Class signature
class sqlalchemy.orm.RelationshipProperty.Comparator
(sqlalchemy.orm.PropComparator
)
sqlalchemy.orm.RelationshipProperty.Comparator.
__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:
Comparisons against collections are not supported.
Use Comparator.contains()
.
Compared to a scalar one-to-many, will produce a clause that compares the target columns in the parent to the given target.
Compared to a scalar many-to-many, an alias
of the association table will be rendered as
well, forming a natural join that is part of the
main body of the query. This will not work for
queries that go beyond simple AND conjunctions of
comparisons, such as those which use OR. Use
explicit joins, outerjoins, or
Comparator.has()
for
more comprehensive non-many-to-one scalar
membership tests.
Comparisons against None
given in a one-to-many
or many-to-many context produce a NOT EXISTS clause.
sqlalchemy.orm.RelationshipProperty.Comparator.
__init__
(prop, parentmapper, adapt_to_entity=None, of_type=None)¶Construction of Comparator
is internal to the ORM’s attribute mechanics.
sqlalchemy.orm.RelationshipProperty.Comparator.
__le__
(other)¶inherited from the sqlalchemy.sql.operators.ColumnOperators.__le__
method of ColumnOperators
Implement the <=
operator.
In a column context, produces the clause a <= b
.
sqlalchemy.orm.RelationshipProperty.Comparator.
__lt__
(other)¶inherited from the sqlalchemy.sql.operators.ColumnOperators.__lt__
method of ColumnOperators
Implement the <
operator.
In a column context, produces the clause a < b
.
sqlalchemy.orm.RelationshipProperty.Comparator.
__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:
Comparisons against collections are not supported.
Use
Comparator.contains()
in conjunction with not_()
.
Compared to a scalar one-to-many, will produce a clause that compares the target columns in the parent to the given target.
Compared to a scalar many-to-many, an alias
of the association table will be rendered as
well, forming a natural join that is part of the
main body of the query. This will not work for
queries that go beyond simple AND conjunctions of
comparisons, such as those which use OR. Use
explicit joins, outerjoins, or
Comparator.has()
in
conjunction with not_()
for
more comprehensive non-many-to-one scalar
membership tests.
Comparisons against None
given in a one-to-many
or many-to-many context produce an EXISTS clause.
sqlalchemy.orm.RelationshipProperty.Comparator.
adapt_to_entity
(adapt_to_entity)¶Return a copy of this PropComparator which will use the given
AliasedInsp
to produce corresponding expressions.
sqlalchemy.orm.RelationshipProperty.Comparator.
adapter
¶inherited from the PropComparator.adapter
attribute of PropComparator
Produce a callable that adapts column expressions to suit an aliased version of this comparator.
sqlalchemy.orm.RelationshipProperty.Comparator.
all_
()¶inherited from the ColumnOperators.all_()
method of ColumnOperators
Produce a all_()
clause against the
parent object.
This operator is only appropriate against a scalar subquery object, or for some backends an column expression that is against the ARRAY type, e.g.:
# postgresql '5 = ALL (somearray)'
expr = 5 == mytable.c.somearray.all_()
# mysql '5 = ALL (SELECT value FROM table)'
expr = 5 == select([table.c.value]).as_scalar().all_()
New in version 1.1.
sqlalchemy.orm.RelationshipProperty.Comparator.
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 Comparator.any()
uses
a correlated subquery, its performance is not nearly as
good when compared against large target tables as that of
using a join.
Comparator.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)
Comparator.any()
is only
valid for collections, i.e. a relationship()
that has uselist=True
. For scalar references,
use Comparator.has()
.
sqlalchemy.orm.RelationshipProperty.Comparator.
any_
()¶inherited from the ColumnOperators.any_()
method of ColumnOperators
Produce a any_()
clause against the
parent object.
This operator is only appropriate against a scalar subquery object, or for some backends an column expression that is against the ARRAY type, e.g.:
# postgresql '5 = ANY (somearray)'
expr = 5 == mytable.c.somearray.any_()
# mysql '5 = ANY (SELECT value FROM table)'
expr = 5 == select([table.c.value]).as_scalar().any_()
New in version 1.1.
sqlalchemy.orm.RelationshipProperty.Comparator.
static any_op
(a, b, **kwargs)¶inherited from the PropComparator.any_op()
method of PropComparator
sqlalchemy.orm.RelationshipProperty.Comparator.
asc
()¶inherited from the ColumnOperators.asc()
method of ColumnOperators
Produce a asc()
clause against the
parent object.
sqlalchemy.orm.RelationshipProperty.Comparator.
between
(cleft, cright, symmetric=False)¶inherited from the ColumnOperators.between()
method of ColumnOperators
Produce a between()
clause against
the parent object, given the lower and upper range.
sqlalchemy.orm.RelationshipProperty.Comparator.
bool_op
(opstring, precedence=0)¶inherited from the Operators.bool_op()
method of Operators
Return a custom boolean operator.
This method is shorthand for calling
Operators.op()
and passing the
Operators.op.is_comparison
flag with True.
New in version 1.2.0b3.
See also
sqlalchemy.orm.RelationshipProperty.Comparator.
collate
(collation)¶inherited from the ColumnOperators.collate()
method of ColumnOperators
Produce a collate()
clause against
the parent object, given the collation string.
See also
sqlalchemy.orm.RelationshipProperty.Comparator.
concat
(other)¶inherited from the ColumnOperators.concat()
method of ColumnOperators
Implement the ‘concat’ operator.
In a column context, produces the clause a || b
,
or uses the concat()
operator on MySQL.
sqlalchemy.orm.RelationshipProperty.Comparator.
contains
(other, **kwargs)¶Return a simple expression that tests a collection for containment of a particular item.
Comparator.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
Comparator.contains()
is
very useful when used with simple one-to-many
operations.
For many-to-many operations, the behavior of
Comparator.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
Comparator.contains()
will not work with many-to-many collections when
used in queries that move beyond simple AND
conjunctions, such as multiple
Comparator.contains()
expressions joined by OR. In such cases subqueries or
explicit “outer joins” will need to be used instead.
See Comparator.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.
sqlalchemy.orm.RelationshipProperty.Comparator.
desc
()¶inherited from the ColumnOperators.desc()
method of ColumnOperators
Produce a desc()
clause against the
parent object.
sqlalchemy.orm.RelationshipProperty.Comparator.
distinct
()¶inherited from the ColumnOperators.distinct()
method of ColumnOperators
Produce a distinct()
clause against the
parent object.
sqlalchemy.orm.RelationshipProperty.Comparator.
endswith
(other, **kwargs)¶inherited from the ColumnOperators.endswith()
method of ColumnOperators
Implement the ‘endswith’ operator.
Produces a LIKE expression that tests against a match for the end of a string value:
column LIKE '%' || <other>
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.endswith("foobar"))
Since the operator uses LIKE
, wildcard characters
"%"
and "_"
that are present inside the <other> expression
will behave like wildcards as well. For literal string
values, the ColumnOperators.endswith.autoescape
flag
may be set to True
to apply escaping to occurrences of these
characters within the string value so that they match as themselves
and not as wildcard characters. Alternatively, the
ColumnOperators.endswith.escape
parameter will establish
a given character as an escape character which can be of use when
the target expression is not a literal string.
other¶ – expression to be compared. This is usually a plain
string value, but can also be an arbitrary SQL expression. LIKE
wildcard characters %
and _
are not escaped by default unless
the ColumnOperators.endswith.autoescape
flag is
set to True.
autoescape¶ –
boolean; when True, establishes an escape character
within the LIKE expression, then applies it to all occurrences of
"%"
, "_"
and the escape character itself within the
comparison value, which is assumed to be a literal string and not a
SQL expression.
An expression such as:
somecolumn.endswith("foo%bar", autoescape=True)
Will render as:
somecolumn LIKE '%' || :param ESCAPE '/'
With the value of :param
as "foo/%bar"
.
New in version 1.2.
Changed in version 1.2.0: The
ColumnOperators.endswith.autoescape
parameter is
now a simple boolean rather than a character; the escape
character itself is also escaped, and defaults to a forwards
slash, which itself can be customized using the
ColumnOperators.endswith.escape
parameter.
escape¶ –
a character which when given will render with the
ESCAPE
keyword to establish that character as the escape
character. This character can then be placed preceding occurrences
of %
and _
to allow them to act as themselves and not
wildcard characters.
An expression such as:
somecolumn.endswith("foo/%bar", escape="^")
Will render as:
somecolumn LIKE '%' || :param ESCAPE '^'
The parameter may also be combined with
ColumnOperators.endswith.autoescape
:
somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
Where above, the given literal parameter will be converted to
"foo^%bar^^bat"
before being passed to the database.
sqlalchemy.orm.RelationshipProperty.Comparator.
entity
¶The target entity referred to by this
Comparator
.
This is either a Mapper
or AliasedInsp
object.
This is the “target” or “remote” side of the
relationship()
.
sqlalchemy.orm.RelationshipProperty.Comparator.
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 Comparator.has()
uses
a correlated subquery, its performance is not nearly as
good when compared against large target tables as that of
using a join.
Comparator.has()
is only
valid for scalar references, i.e. a relationship()
that has uselist=False
. For collection references,
use Comparator.any()
.
sqlalchemy.orm.RelationshipProperty.Comparator.
static has_op
(a, b, **kwargs)¶inherited from the PropComparator.has_op()
method of PropComparator
sqlalchemy.orm.RelationshipProperty.Comparator.
ilike
(other, escape=None)¶inherited from the ColumnOperators.ilike()
method of ColumnOperators
Implement the ilike
operator, e.g. case insensitive LIKE.
In a column context, produces an expression either of the form:
lower(a) LIKE lower(other)
Or on backends that support the ILIKE operator:
a ILIKE other
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.ilike("%foobar%"))
See also
sqlalchemy.orm.RelationshipProperty.Comparator.
in_
(other)¶Produce an IN clause - this is not implemented
for relationship()
-based attributes at this time.
sqlalchemy.orm.RelationshipProperty.Comparator.
info
¶inherited from the PropComparator.info
attribute of PropComparator
sqlalchemy.orm.RelationshipProperty.Comparator.
is_
(other)¶inherited from the ColumnOperators.is_()
method of ColumnOperators
Implement the IS
operator.
Normally, IS
is generated automatically when comparing to a
value of None
, which resolves to NULL
. However, explicit
usage of IS
may be desirable if comparing to boolean values
on certain platforms.
See also
sqlalchemy.orm.RelationshipProperty.Comparator.
is_distinct_from
(other)¶inherited from the ColumnOperators.is_distinct_from()
method of ColumnOperators
Implement the IS DISTINCT FROM
operator.
Renders “a IS DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS NOT b”.
New in version 1.1.
sqlalchemy.orm.RelationshipProperty.Comparator.
isnot
(other)¶inherited from the ColumnOperators.isnot()
method of ColumnOperators
Implement the IS NOT
operator.
Normally, IS NOT
is generated automatically when comparing to a
value of None
, which resolves to NULL
. However, explicit
usage of IS NOT
may be desirable if comparing to boolean values
on certain platforms.
See also
sqlalchemy.orm.RelationshipProperty.Comparator.
isnot_distinct_from
(other)¶inherited from the ColumnOperators.isnot_distinct_from()
method of ColumnOperators
Implement the IS NOT DISTINCT FROM
operator.
Renders “a IS NOT DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS b”.
New in version 1.1.
sqlalchemy.orm.RelationshipProperty.Comparator.
like
(other, escape=None)¶inherited from the ColumnOperators.like()
method of ColumnOperators
Implement the like
operator.
In a column context, produces the expression:
a LIKE other
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.like("%foobar%"))
See also
sqlalchemy.orm.RelationshipProperty.Comparator.
mapper
¶The target Mapper
referred to by this
Comparator
.
This is the “target” or “remote” side of the
relationship()
.
sqlalchemy.orm.RelationshipProperty.Comparator.
match
(other, **kwargs)¶inherited from the ColumnOperators.match()
method of ColumnOperators
Implements a database-specific ‘match’ operator.
ColumnOperators.match()
attempts to resolve to
a MATCH-like function or operator provided by the backend.
Examples include:
PostgreSQL - renders x @@ to_tsquery(y)
MySQL - renders MATCH (x) AGAINST (y IN BOOLEAN MODE)
Oracle - renders CONTAINS(x, y)
other backends may provide special implementations.
Backends without any special implementation will emit the operator as “MATCH”. This is compatible with SQLite, for example.
sqlalchemy.orm.RelationshipProperty.Comparator.
notilike
(other, escape=None)¶inherited from the ColumnOperators.notilike()
method of ColumnOperators
implement the NOT ILIKE
operator.
This is equivalent to using negation with
ColumnOperators.ilike()
, i.e. ~x.ilike(y)
.
See also
sqlalchemy.orm.RelationshipProperty.Comparator.
notin_
(other)¶inherited from the ColumnOperators.notin_()
method of ColumnOperators
implement the NOT IN
operator.
This is equivalent to using negation with
ColumnOperators.in_()
, i.e. ~x.in_(y)
.
In the case that other
is an empty sequence, the compiler
produces an “empty not in” expression. This defaults to the
expression “1 = 1” to produce true in all cases. The
create_engine.empty_in_strategy
may be used to
alter this behavior.
Changed in version 1.2: The ColumnOperators.in_()
and
ColumnOperators.notin_()
operators
now produce a “static” expression for an empty IN sequence
by default.
See also
sqlalchemy.orm.RelationshipProperty.Comparator.
notlike
(other, escape=None)¶inherited from the ColumnOperators.notlike()
method of ColumnOperators
implement the NOT LIKE
operator.
This is equivalent to using negation with
ColumnOperators.like()
, i.e. ~x.like(y)
.
See also
sqlalchemy.orm.RelationshipProperty.Comparator.
nullsfirst
()¶inherited from the ColumnOperators.nullsfirst()
method of ColumnOperators
Produce a nullsfirst()
clause against the
parent object.
sqlalchemy.orm.RelationshipProperty.Comparator.
nullslast
()¶inherited from the ColumnOperators.nullslast()
method of ColumnOperators
Produce a nullslast()
clause against the
parent object.
sqlalchemy.orm.RelationshipProperty.Comparator.
of_type
(cls)¶Redefine this object in terms of a polymorphic subclass.
See PropComparator.of_type()
for an example.
sqlalchemy.orm.RelationshipProperty.Comparator.
static of_type_op
(a, class_)¶inherited from the PropComparator.of_type_op()
method of PropComparator
sqlalchemy.orm.RelationshipProperty.Comparator.
op
(opstring, precedence=0, is_comparison=False, return_type=None)¶inherited from the Operators.op()
method of Operators
Produce a generic operator function.
e.g.:
somecolumn.op("*")(5)
produces:
somecolumn * 5
This function can also be used to make bitwise operators explicit. For example:
somecolumn.op('&')(0xff)
is a bitwise AND of the value in somecolumn
.
operator¶ – a string which will be output as the infix operator between this element and the expression passed to the generated function.
precedence¶ – precedence to apply to the operator, when
parenthesizing expressions. A lower number will cause the expression
to be parenthesized when applied against another operator with
higher precedence. The default value of 0
is lower than all
operators except for the comma (,
) and AS
operators.
A value of 100 will be higher or equal to all operators, and -100
will be lower than or equal to all operators.
is_comparison¶ –
if True, the operator will be considered as a
“comparison” operator, that is which evaluates to a boolean
true/false value, like ==
, >
, etc. This flag should be set
so that ORM relationships can establish that the operator is a
comparison operator when used in a custom join condition.
New in version 0.9.2: - added the
Operators.op.is_comparison
flag.
return_type¶ –
a TypeEngine
class or object that will
force the return type of an expression produced by this operator
to be of that type. By default, operators that specify
Operators.op.is_comparison
will resolve to
Boolean
, and those that do not will be of the same
type as the left-hand operand.
New in version 1.2.0b3: - added the
Operators.op.return_type
argument.
sqlalchemy.orm.RelationshipProperty.Comparator.
operate
(op, *other, **kwargs)¶inherited from the Operators.operate()
method of Operators
Operate on an argument.
This is the lowest level of operation, raises
NotImplementedError
by default.
Overriding this on a subclass can allow common
behavior to be applied to all operations.
For example, overriding ColumnOperators
to apply func.lower()
to the left and right
side:
class MyComparator(ColumnOperators):
def operate(self, op, other):
return op(func.lower(self), func.lower(other))
sqlalchemy.orm.RelationshipProperty.Comparator.
reverse_operate
(op, other, **kwargs)¶inherited from the Operators.reverse_operate()
method of Operators
Reverse operate on an argument.
Usage is the same as operate()
.
sqlalchemy.orm.RelationshipProperty.Comparator.
startswith
(other, **kwargs)¶inherited from the ColumnOperators.startswith()
method of ColumnOperators
Implement the startswith
operator.
Produces a LIKE expression that tests against a match for the start of a string value:
column LIKE <other> || '%'
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.startswith("foobar"))
Since the operator uses LIKE
, wildcard characters
"%"
and "_"
that are present inside the <other> expression
will behave like wildcards as well. For literal string
values, the ColumnOperators.startswith.autoescape
flag
may be set to True
to apply escaping to occurrences of these
characters within the string value so that they match as themselves
and not as wildcard characters. Alternatively, the
ColumnOperators.startswith.escape
parameter will establish
a given character as an escape character which can be of use when
the target expression is not a literal string.
other¶ – expression to be compared. This is usually a plain
string value, but can also be an arbitrary SQL expression. LIKE
wildcard characters %
and _
are not escaped by default unless
the ColumnOperators.startswith.autoescape
flag is
set to True.
autoescape¶ –
boolean; when True, establishes an escape character
within the LIKE expression, then applies it to all occurrences of
"%"
, "_"
and the escape character itself within the
comparison value, which is assumed to be a literal string and not a
SQL expression.
An expression such as:
somecolumn.startswith("foo%bar", autoescape=True)
Will render as:
somecolumn LIKE :param || '%' ESCAPE '/'
With the value of :param
as "foo/%bar"
.
New in version 1.2.
Changed in version 1.2.0: The
ColumnOperators.startswith.autoescape
parameter is
now a simple boolean rather than a character; the escape
character itself is also escaped, and defaults to a forwards
slash, which itself can be customized using the
ColumnOperators.startswith.escape
parameter.
escape¶ –
a character which when given will render with the
ESCAPE
keyword to establish that character as the escape
character. This character can then be placed preceding occurrences
of %
and _
to allow them to act as themselves and not
wildcard characters.
An expression such as:
somecolumn.startswith("foo/%bar", escape="^")
Will render as:
somecolumn LIKE :param || '%' ESCAPE '^'
The parameter may also be combined with
ColumnOperators.startswith.autoescape
:
somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
Where above, the given literal parameter will be converted to
"foo^%bar^^bat"
before being passed to the database.
sqlalchemy.orm.RelationshipProperty.Comparator.
timetuple
= None¶inherited from the ColumnOperators.timetuple
attribute of ColumnOperators
Hack, allows datetime objects to be compared on the LHS.
sqlalchemy.orm.RelationshipProperty.
__init__
(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='select', 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=None, doc=None, active_history=False, cascade_backrefs=True, load_on_pending=False, bake_queries=True, _local_remote_pairs=None, query_class=None, info=None, omit_join=None, sync_backref=None)¶Construct a new RelationshipProperty
object.
This constructor is mirrored as a public API function; see sqlalchemy.orm.relationship()
for a full usage and argument description.
sqlalchemy.orm.RelationshipProperty.
cascade
¶The set of ‘cascade’ attribute names.
This collection is checked before the ‘cascade_iterator’ method is called.
The collection typically only applies to a RelationshipProperty.
sqlalchemy.orm.RelationshipProperty.
cascade_iterator
(type_, state, dict_, visited_states, 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.
This method typically only applies to RelationshipProperty.
sqlalchemy.orm.RelationshipProperty.
class_attribute
¶inherited from the MapperProperty.class_attribute
attribute of MapperProperty
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
sqlalchemy.orm.RelationshipProperty.
create_row_processor
(context, path, mapper, result, adapter, populators)¶inherited from the StrategizedProperty.create_row_processor()
method of StrategizedProperty
Produce row processing functions and append to the given set of populators lists.
sqlalchemy.orm.RelationshipProperty.
do_init
()¶Perform subclass-specific initialization post-mapper-creation steps.
This is a template method called by the MapperProperty
object’s init() method.
sqlalchemy.orm.RelationshipProperty.
entity
¶Return the target mapped entity, which is an inspect() of the class or aliased class tha is referred towards.
sqlalchemy.orm.RelationshipProperty.
extension_type
= symbol('NOT_EXTENSION')¶inherited from the InspectionAttr.extension_type
attribute of InspectionAttr
The extension type, if any.
Defaults to NOT_EXTENSION
sqlalchemy.orm.RelationshipProperty.
init
()¶inherited from the MapperProperty.init()
method of MapperProperty
Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.
sqlalchemy.orm.RelationshipProperty.
instrument_class
(mapper)¶Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.
The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute.
This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process.
The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the “impl”) which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).
sqlalchemy.orm.RelationshipProperty.
mapper
¶Return the targeted Mapper
for this
RelationshipProperty
.
This is a lazy-initializing static attribute.
sqlalchemy.orm.RelationshipProperty.
merge
(session, source_state, source_dict, dest_state, dest_dict, load, _recursive, _resolve_conflict_map)¶Merge the attribute represented by this MapperProperty
from source to destination object.
sqlalchemy.orm.RelationshipProperty.
post_instrument_class
(mapper)¶inherited from the StrategizedProperty.post_instrument_class()
method of StrategizedProperty
Perform instrumentation adjustments that need to occur after init() has completed.
The given Mapper is the Mapper invoking the operation, which may not be the same Mapper as self.parent in an inheritance scenario; however, Mapper will always at least be a sub-mapper of self.parent.
This method is typically used by StrategizedProperty, which delegates it to LoaderStrategy.init_class_attribute() to perform final setup on the class-bound InstrumentedAttribute.
sqlalchemy.orm.RelationshipProperty.
set_parent
(parent, init)¶inherited from the MapperProperty.set_parent()
method of MapperProperty
Set the parent mapper that references this MapperProperty.
This method is overridden by some subclasses to perform extra setup when the mapper is first known.
sqlalchemy.orm.RelationshipProperty.
setup
(context, query_entity, path, adapter, **kwargs)¶inherited from the StrategizedProperty.setup()
method of StrategizedProperty
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.
SynonymProperty
(name, map_column=None, descriptor=None, comparator_factory=None, doc=None, info=None)¶Class signature
class sqlalchemy.orm.SynonymProperty
(sqlalchemy.orm.descriptor_props.DescriptorProperty
)
sqlalchemy.orm.SynonymProperty.
__init__
(name, map_column=None, descriptor=None, comparator_factory=None, doc=None, info=None)¶Construct a new SynonymProperty
object.
This constructor is mirrored as a public API function; see sqlalchemy.orm.synonym()
for a full usage and argument description.
sqlalchemy.orm.SynonymProperty.
cascade_iterator
(type_, state, visited_instances=None, halt_on=None)¶inherited from the MapperProperty.cascade_iterator()
method of MapperProperty
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.
This method typically only applies to RelationshipProperty.
sqlalchemy.orm.SynonymProperty.
class_attribute
¶inherited from the MapperProperty.class_attribute
attribute of MapperProperty
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
sqlalchemy.orm.SynonymProperty.
create_row_processor
(context, path, mapper, result, adapter, populators)¶inherited from the MapperProperty.create_row_processor()
method of MapperProperty
Produce row processing functions and append to the given set of populators lists.
sqlalchemy.orm.SynonymProperty.
do_init
()¶inherited from the MapperProperty.do_init()
method of MapperProperty
Perform subclass-specific initialization post-mapper-creation steps.
This is a template method called by the MapperProperty
object’s init() method.
sqlalchemy.orm.SynonymProperty.
extension_type
= symbol('NOT_EXTENSION')¶inherited from the InspectionAttr.extension_type
attribute of InspectionAttr
The extension type, if any.
Defaults to NOT_EXTENSION
sqlalchemy.orm.SynonymProperty.
init
()¶inherited from the MapperProperty.init()
method of MapperProperty
Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.
sqlalchemy.orm.SynonymProperty.
instrument_class
(mapper)¶inherited from the DescriptorProperty.instrument_class()
method of DescriptorProperty
Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.
The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute.
This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process.
The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the “impl”) which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).
sqlalchemy.orm.SynonymProperty.
merge
(session, source_state, source_dict, dest_state, dest_dict, load, _recursive, _resolve_conflict_map)¶inherited from the MapperProperty.merge()
method of MapperProperty
Merge the attribute represented by this MapperProperty
from source to destination object.
sqlalchemy.orm.SynonymProperty.
post_instrument_class
(mapper)¶inherited from the MapperProperty.post_instrument_class()
method of MapperProperty
Perform instrumentation adjustments that need to occur after init() has completed.
The given Mapper is the Mapper invoking the operation, which may not be the same Mapper as self.parent in an inheritance scenario; however, Mapper will always at least be a sub-mapper of self.parent.
This method is typically used by StrategizedProperty, which delegates it to LoaderStrategy.init_class_attribute() to perform final setup on the class-bound InstrumentedAttribute.
sqlalchemy.orm.SynonymProperty.
set_parent
(parent, init)¶Set the parent mapper that references this MapperProperty.
This method is overridden by some subclasses to perform extra setup when the mapper is first known.
sqlalchemy.orm.SynonymProperty.
setup
(context, query_entity, path, adapter, **kwargs)¶inherited from the MapperProperty.setup()
method of MapperProperty
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.SynonymProperty.
uses_objects
¶sqlalchemy.orm.query.
QueryContext
(query)¶sqlalchemy.orm.attributes.
QueryableAttribute
(class_, key, impl=None, comparator=None, parententity=None, of_type=None)¶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.
Class signature
class sqlalchemy.orm.attributes.QueryableAttribute
(sqlalchemy.orm.base._MappedAttribute
, sqlalchemy.orm.base.InspectionAttr
, sqlalchemy.orm.PropComparator
)
sqlalchemy.orm.attributes.QueryableAttribute.
__eq__
(other)¶inherited from the sqlalchemy.sql.operators.ColumnOperators.__eq__
method of ColumnOperators
Implement the ==
operator.
In a column context, produces the clause a = b
.
If the target is None
, produces a IS NULL
.
sqlalchemy.orm.attributes.QueryableAttribute.
__le__
(other)¶inherited from the sqlalchemy.sql.operators.ColumnOperators.__le__
method of ColumnOperators
Implement the <=
operator.
In a column context, produces the clause a <= b
.
sqlalchemy.orm.attributes.QueryableAttribute.
__lt__
(other)¶inherited from the sqlalchemy.sql.operators.ColumnOperators.__lt__
method of ColumnOperators
Implement the <
operator.
In a column context, produces the clause a < b
.
sqlalchemy.orm.attributes.QueryableAttribute.
__ne__
(other)¶inherited from the sqlalchemy.sql.operators.ColumnOperators.__ne__
method of ColumnOperators
Implement the !=
operator.
In a column context, produces the clause a != b
.
If the target is None
, produces a IS NOT NULL
.
sqlalchemy.orm.attributes.QueryableAttribute.
adapt_to_entity
(adapt_to_entity)¶Return a copy of this PropComparator which will use the given
AliasedInsp
to produce corresponding expressions.
sqlalchemy.orm.attributes.QueryableAttribute.
adapter
¶inherited from the PropComparator.adapter
attribute of PropComparator
Produce a callable that adapts column expressions to suit an aliased version of this comparator.
sqlalchemy.orm.attributes.QueryableAttribute.
all_
()¶inherited from the ColumnOperators.all_()
method of ColumnOperators
Produce a all_()
clause against the
parent object.
This operator is only appropriate against a scalar subquery object, or for some backends an column expression that is against the ARRAY type, e.g.:
# postgresql '5 = ALL (somearray)'
expr = 5 == mytable.c.somearray.all_()
# mysql '5 = ALL (SELECT value FROM table)'
expr = 5 == select([table.c.value]).as_scalar().all_()
New in version 1.1.
sqlalchemy.orm.attributes.QueryableAttribute.
any
(criterion=None, **kwargs)¶inherited from the PropComparator.any()
method of PropComparator
Return true if this collection contains any member that meets the given criterion.
The usual implementation of any()
is
Comparator.any()
.
sqlalchemy.orm.attributes.QueryableAttribute.
any_
()¶inherited from the ColumnOperators.any_()
method of ColumnOperators
Produce a any_()
clause against the
parent object.
This operator is only appropriate against a scalar subquery object, or for some backends an column expression that is against the ARRAY type, e.g.:
# postgresql '5 = ANY (somearray)'
expr = 5 == mytable.c.somearray.any_()
# mysql '5 = ANY (SELECT value FROM table)'
expr = 5 == select([table.c.value]).as_scalar().any_()
New in version 1.1.
sqlalchemy.orm.attributes.QueryableAttribute.
asc
()¶inherited from the ColumnOperators.asc()
method of ColumnOperators
Produce a asc()
clause against the
parent object.
sqlalchemy.orm.attributes.QueryableAttribute.
between
(cleft, cright, symmetric=False)¶inherited from the ColumnOperators.between()
method of ColumnOperators
Produce a between()
clause against
the parent object, given the lower and upper range.
sqlalchemy.orm.attributes.QueryableAttribute.
bool_op
(opstring, precedence=0)¶inherited from the Operators.bool_op()
method of Operators
Return a custom boolean operator.
This method is shorthand for calling
Operators.op()
and passing the
Operators.op.is_comparison
flag with True.
New in version 1.2.0b3.
See also
sqlalchemy.orm.attributes.QueryableAttribute.
collate
(collation)¶inherited from the ColumnOperators.collate()
method of ColumnOperators
Produce a collate()
clause against
the parent object, given the collation string.
See also
sqlalchemy.orm.attributes.QueryableAttribute.
concat
(other)¶inherited from the ColumnOperators.concat()
method of ColumnOperators
Implement the ‘concat’ operator.
In a column context, produces the clause a || b
,
or uses the concat()
operator on MySQL.
sqlalchemy.orm.attributes.QueryableAttribute.
contains
(other, **kwargs)¶inherited from the ColumnOperators.contains()
method of ColumnOperators
Implement the ‘contains’ operator.
Produces a LIKE expression that tests against a match for the middle of a string value:
column LIKE '%' || <other> || '%'
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.contains("foobar"))
Since the operator uses LIKE
, wildcard characters
"%"
and "_"
that are present inside the <other> expression
will behave like wildcards as well. For literal string
values, the ColumnOperators.contains.autoescape
flag
may be set to True
to apply escaping to occurrences of these
characters within the string value so that they match as themselves
and not as wildcard characters. Alternatively, the
ColumnOperators.contains.escape
parameter will establish
a given character as an escape character which can be of use when
the target expression is not a literal string.
other¶ – expression to be compared. This is usually a plain
string value, but can also be an arbitrary SQL expression. LIKE
wildcard characters %
and _
are not escaped by default unless
the ColumnOperators.contains.autoescape
flag is
set to True.
autoescape¶ –
boolean; when True, establishes an escape character
within the LIKE expression, then applies it to all occurrences of
"%"
, "_"
and the escape character itself within the
comparison value, which is assumed to be a literal string and not a
SQL expression.
An expression such as:
somecolumn.contains("foo%bar", autoescape=True)
Will render as:
somecolumn LIKE '%' || :param || '%' ESCAPE '/'
With the value of :param
as "foo/%bar"
.
New in version 1.2.
Changed in version 1.2.0: The
ColumnOperators.contains.autoescape
parameter is
now a simple boolean rather than a character; the escape
character itself is also escaped, and defaults to a forwards
slash, which itself can be customized using the
ColumnOperators.contains.escape
parameter.
escape¶ –
a character which when given will render with the
ESCAPE
keyword to establish that character as the escape
character. This character can then be placed preceding occurrences
of %
and _
to allow them to act as themselves and not
wildcard characters.
An expression such as:
somecolumn.contains("foo/%bar", escape="^")
Will render as:
somecolumn LIKE '%' || :param || '%' ESCAPE '^'
The parameter may also be combined with
ColumnOperators.contains.autoescape
:
somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
Where above, the given literal parameter will be converted to
"foo^%bar^^bat"
before being passed to the database.
sqlalchemy.orm.attributes.QueryableAttribute.
desc
()¶inherited from the ColumnOperators.desc()
method of ColumnOperators
Produce a desc()
clause against the
parent object.
sqlalchemy.orm.attributes.QueryableAttribute.
distinct
()¶inherited from the ColumnOperators.distinct()
method of ColumnOperators
Produce a distinct()
clause against the
parent object.
sqlalchemy.orm.attributes.QueryableAttribute.
endswith
(other, **kwargs)¶inherited from the ColumnOperators.endswith()
method of ColumnOperators
Implement the ‘endswith’ operator.
Produces a LIKE expression that tests against a match for the end of a string value:
column LIKE '%' || <other>
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.endswith("foobar"))
Since the operator uses LIKE
, wildcard characters
"%"
and "_"
that are present inside the <other> expression
will behave like wildcards as well. For literal string
values, the ColumnOperators.endswith.autoescape
flag
may be set to True
to apply escaping to occurrences of these
characters within the string value so that they match as themselves
and not as wildcard characters. Alternatively, the
ColumnOperators.endswith.escape
parameter will establish
a given character as an escape character which can be of use when
the target expression is not a literal string.
other¶ – expression to be compared. This is usually a plain
string value, but can also be an arbitrary SQL expression. LIKE
wildcard characters %
and _
are not escaped by default unless
the ColumnOperators.endswith.autoescape
flag is
set to True.
autoescape¶ –
boolean; when True, establishes an escape character
within the LIKE expression, then applies it to all occurrences of
"%"
, "_"
and the escape character itself within the
comparison value, which is assumed to be a literal string and not a
SQL expression.
An expression such as:
somecolumn.endswith("foo%bar", autoescape=True)
Will render as:
somecolumn LIKE '%' || :param ESCAPE '/'
With the value of :param
as "foo/%bar"
.
New in version 1.2.
Changed in version 1.2.0: The
ColumnOperators.endswith.autoescape
parameter is
now a simple boolean rather than a character; the escape
character itself is also escaped, and defaults to a forwards
slash, which itself can be customized using the
ColumnOperators.endswith.escape
parameter.
escape¶ –
a character which when given will render with the
ESCAPE
keyword to establish that character as the escape
character. This character can then be placed preceding occurrences
of %
and _
to allow them to act as themselves and not
wildcard characters.
An expression such as:
somecolumn.endswith("foo/%bar", escape="^")
Will render as:
somecolumn LIKE '%' || :param ESCAPE '^'
The parameter may also be combined with
ColumnOperators.endswith.autoescape
:
somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
Where above, the given literal parameter will be converted to
"foo^%bar^^bat"
before being passed to the database.
sqlalchemy.orm.attributes.QueryableAttribute.
expression
¶The SQL expression object represented by this
QueryableAttribute
.
This will typically be an instance of a ColumnElement
subclass representing a column expression.
sqlalchemy.orm.attributes.QueryableAttribute.
extension_type
= symbol('NOT_EXTENSION')¶inherited from the InspectionAttr.extension_type
attribute of InspectionAttr
The extension type, if any.
Defaults to NOT_EXTENSION
sqlalchemy.orm.attributes.QueryableAttribute.
has
(criterion=None, **kwargs)¶inherited from the PropComparator.has()
method of PropComparator
Return true if this element references a member which meets the given criterion.
The usual implementation of has()
is
Comparator.has()
.
sqlalchemy.orm.attributes.QueryableAttribute.
ilike
(other, escape=None)¶inherited from the ColumnOperators.ilike()
method of ColumnOperators
Implement the ilike
operator, e.g. case insensitive LIKE.
In a column context, produces an expression either of the form:
lower(a) LIKE lower(other)
Or on backends that support the ILIKE operator:
a ILIKE other
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.ilike("%foobar%"))
See also
sqlalchemy.orm.attributes.QueryableAttribute.
in_
(other)¶inherited from the ColumnOperators.in_()
method of ColumnOperators
Implement the in
operator.
In a column context, produces the clause column IN <other>
.
The given parameter other
may be:
A list of literal values, e.g.:
stmt.where(column.in_([1, 2, 3]))
In this calling form, the list of items is converted to a set of bound parameters the same length as the list given:
WHERE COL IN (?, ?, ?)
A list of tuples may be provided if the comparison is against a
tuple_()
containing multiple expressions:
from sqlalchemy import tuple_
stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
An empty list, e.g.:
stmt.where(column.in_([]))
In this calling form, the expression renders a “false” expression, e.g.:
WHERE 1 != 1
This “false” expression has historically had different behaviors
in older SQLAlchemy versions, see
create_engine.empty_in_strategy
for behavioral options.
Changed in version 1.2: simplified the behavior of “empty in” expressions
A bound parameter, e.g. bindparam()
, may be used if it
includes the bindparam.expanding
flag:
stmt.where(column.in_(bindparam('value', expanding=True)))
In this calling form, the expression renders a special non-SQL placeholder expression that looks like:
WHERE COL IN ([EXPANDING_value])
This placeholder expression is intercepted at statement execution time to be converted into the variable number of bound parameter form illustrated earlier. If the statement were executed as:
connection.execute(stmt, {"value": [1, 2, 3]})
The database would be passed a bound parameter for each value:
WHERE COL IN (?, ?, ?)
New in version 1.2: added “expanding” bound parameters
If an empty list is passed, a special “empty list” expression, which is specific to the database in use, is rendered. On SQLite this would be:
WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
New in version 1.3: “expanding” bound parameters now support empty lists
a select()
construct,
which is usually a correlated
scalar select:
stmt.where(
column.in_(
select([othertable.c.y]).
where(table.c.x == othertable.c.x)
)
)
In this calling form, ColumnOperators.in_()
renders as given:
WHERE COL IN (SELECT othertable.y
FROM othertable WHERE othertable.x = table.x)
other¶ – a list of literals, a select()
construct,
or a bindparam()
construct that includes the
bindparam.expanding
flag set to True.
sqlalchemy.orm.attributes.QueryableAttribute.
info
¶Return the ‘info’ dictionary for the underlying SQL element.
The behavior here is as follows:
If the attribute is a column-mapped property, i.e.
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.
If the attribute is a 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 its own .info
attribute (which should be the case, unless a user-defined SQL
construct has defined one).
If the attribute refers to any other kind of
MapperProperty
, including RelationshipProperty
,
the attribute will refer to the MapperProperty.info
dictionary associated with that MapperProperty
.
To access the MapperProperty.info
dictionary of the
MapperProperty
unconditionally, including for a
ColumnProperty
that’s associated directly with a
Column
, the attribute can be referred to using
QueryableAttribute.property
attribute, as
MyClass.someattribute.property.info
.
sqlalchemy.orm.attributes.QueryableAttribute.
is_
(other)¶inherited from the ColumnOperators.is_()
method of ColumnOperators
Implement the IS
operator.
Normally, IS
is generated automatically when comparing to a
value of None
, which resolves to NULL
. However, explicit
usage of IS
may be desirable if comparing to boolean values
on certain platforms.
See also
sqlalchemy.orm.attributes.QueryableAttribute.
is_distinct_from
(other)¶inherited from the ColumnOperators.is_distinct_from()
method of ColumnOperators
Implement the IS DISTINCT FROM
operator.
Renders “a IS DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS NOT b”.
New in version 1.1.
sqlalchemy.orm.attributes.QueryableAttribute.
isnot
(other)¶inherited from the ColumnOperators.isnot()
method of ColumnOperators
Implement the IS NOT
operator.
Normally, IS NOT
is generated automatically when comparing to a
value of None
, which resolves to NULL
. However, explicit
usage of IS NOT
may be desirable if comparing to boolean values
on certain platforms.
See also
sqlalchemy.orm.attributes.QueryableAttribute.
isnot_distinct_from
(other)¶inherited from the ColumnOperators.isnot_distinct_from()
method of ColumnOperators
Implement the IS NOT DISTINCT FROM
operator.
Renders “a IS NOT DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS b”.
New in version 1.1.
sqlalchemy.orm.attributes.QueryableAttribute.
like
(other, escape=None)¶inherited from the ColumnOperators.like()
method of ColumnOperators
Implement the like
operator.
In a column context, produces the expression:
a LIKE other
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.like("%foobar%"))
See also
sqlalchemy.orm.attributes.QueryableAttribute.
match
(other, **kwargs)¶inherited from the ColumnOperators.match()
method of ColumnOperators
Implements a database-specific ‘match’ operator.
ColumnOperators.match()
attempts to resolve to
a MATCH-like function or operator provided by the backend.
Examples include:
PostgreSQL - renders x @@ to_tsquery(y)
MySQL - renders MATCH (x) AGAINST (y IN BOOLEAN MODE)
Oracle - renders CONTAINS(x, y)
other backends may provide special implementations.
Backends without any special implementation will emit the operator as “MATCH”. This is compatible with SQLite, for example.
sqlalchemy.orm.attributes.QueryableAttribute.
notilike
(other, escape=None)¶inherited from the ColumnOperators.notilike()
method of ColumnOperators
implement the NOT ILIKE
operator.
This is equivalent to using negation with
ColumnOperators.ilike()
, i.e. ~x.ilike(y)
.
See also
sqlalchemy.orm.attributes.QueryableAttribute.
notin_
(other)¶inherited from the ColumnOperators.notin_()
method of ColumnOperators
implement the NOT IN
operator.
This is equivalent to using negation with
ColumnOperators.in_()
, i.e. ~x.in_(y)
.
In the case that other
is an empty sequence, the compiler
produces an “empty not in” expression. This defaults to the
expression “1 = 1” to produce true in all cases. The
create_engine.empty_in_strategy
may be used to
alter this behavior.
Changed in version 1.2: The ColumnOperators.in_()
and
ColumnOperators.notin_()
operators
now produce a “static” expression for an empty IN sequence
by default.
See also
sqlalchemy.orm.attributes.QueryableAttribute.
notlike
(other, escape=None)¶inherited from the ColumnOperators.notlike()
method of ColumnOperators
implement the NOT LIKE
operator.
This is equivalent to using negation with
ColumnOperators.like()
, i.e. ~x.like(y)
.
See also
sqlalchemy.orm.attributes.QueryableAttribute.
nullsfirst
()¶inherited from the ColumnOperators.nullsfirst()
method of ColumnOperators
Produce a nullsfirst()
clause against the
parent object.
sqlalchemy.orm.attributes.QueryableAttribute.
nullslast
()¶inherited from the ColumnOperators.nullslast()
method of ColumnOperators
Produce a nullslast()
clause against the
parent object.
sqlalchemy.orm.attributes.QueryableAttribute.
of_type
(cls)¶Redefine this object in terms of a polymorphic subclass,
with_polymorphic()
construct, or aliased()
construct.
Returns a new PropComparator from which further criterion can be evaluated.
e.g.:
query.join(Company.employees.of_type(Engineer)).\
filter(Engineer.name=='foo')
class_¶ – a class or mapper indicating that criterion will be against this specific subclass.
sqlalchemy.orm.attributes.QueryableAttribute.
op
(opstring, precedence=0, is_comparison=False, return_type=None)¶inherited from the Operators.op()
method of Operators
Produce a generic operator function.
e.g.:
somecolumn.op("*")(5)
produces:
somecolumn * 5
This function can also be used to make bitwise operators explicit. For example:
somecolumn.op('&')(0xff)
is a bitwise AND of the value in somecolumn
.
operator¶ – a string which will be output as the infix operator between this element and the expression passed to the generated function.
precedence¶ – precedence to apply to the operator, when
parenthesizing expressions. A lower number will cause the expression
to be parenthesized when applied against another operator with
higher precedence. The default value of 0
is lower than all
operators except for the comma (,
) and AS
operators.
A value of 100 will be higher or equal to all operators, and -100
will be lower than or equal to all operators.
is_comparison¶ –
if True, the operator will be considered as a
“comparison” operator, that is which evaluates to a boolean
true/false value, like ==
, >
, etc. This flag should be set
so that ORM relationships can establish that the operator is a
comparison operator when used in a custom join condition.
New in version 0.9.2: - added the
Operators.op.is_comparison
flag.
return_type¶ –
a TypeEngine
class or object that will
force the return type of an expression produced by this operator
to be of that type. By default, operators that specify
Operators.op.is_comparison
will resolve to
Boolean
, and those that do not will be of the same
type as the left-hand operand.
New in version 1.2.0b3: - added the
Operators.op.return_type
argument.
sqlalchemy.orm.attributes.QueryableAttribute.
operate
(op, *other, **kwargs)¶Operate on an argument.
This is the lowest level of operation, raises
NotImplementedError
by default.
Overriding this on a subclass can allow common
behavior to be applied to all operations.
For example, overriding ColumnOperators
to apply func.lower()
to the left and right
side:
class MyComparator(ColumnOperators):
def operate(self, op, other):
return op(func.lower(self), func.lower(other))
sqlalchemy.orm.attributes.QueryableAttribute.
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.
sqlalchemy.orm.attributes.QueryableAttribute.
property
¶Return the MapperProperty
associated with this
QueryableAttribute
.
Return values here will commonly be instances of
ColumnProperty
or RelationshipProperty
.
sqlalchemy.orm.attributes.QueryableAttribute.
reverse_operate
(op, other, **kwargs)¶Reverse operate on an argument.
Usage is the same as operate()
.
sqlalchemy.orm.attributes.QueryableAttribute.
startswith
(other, **kwargs)¶inherited from the ColumnOperators.startswith()
method of ColumnOperators
Implement the startswith
operator.
Produces a LIKE expression that tests against a match for the start of a string value:
column LIKE <other> || '%'
E.g.:
stmt = select([sometable]).\
where(sometable.c.column.startswith("foobar"))
Since the operator uses LIKE
, wildcard characters
"%"
and "_"
that are present inside the <other> expression
will behave like wildcards as well. For literal string
values, the ColumnOperators.startswith.autoescape
flag
may be set to True
to apply escaping to occurrences of these
characters within the string value so that they match as themselves
and not as wildcard characters. Alternatively, the
ColumnOperators.startswith.escape
parameter will establish
a given character as an escape character which can be of use when
the target expression is not a literal string.
other¶ – expression to be compared. This is usually a plain
string value, but can also be an arbitrary SQL expression. LIKE
wildcard characters %
and _
are not escaped by default unless
the ColumnOperators.startswith.autoescape
flag is
set to True.
autoescape¶ –
boolean; when True, establishes an escape character
within the LIKE expression, then applies it to all occurrences of
"%"
, "_"
and the escape character itself within the
comparison value, which is assumed to be a literal string and not a
SQL expression.
An expression such as:
somecolumn.startswith("foo%bar", autoescape=True)
Will render as:
somecolumn LIKE :param || '%' ESCAPE '/'
With the value of :param
as "foo/%bar"
.
New in version 1.2.
Changed in version 1.2.0: The
ColumnOperators.startswith.autoescape
parameter is
now a simple boolean rather than a character; the escape
character itself is also escaped, and defaults to a forwards
slash, which itself can be customized using the
ColumnOperators.startswith.escape
parameter.
escape¶ –
a character which when given will render with the
ESCAPE
keyword to establish that character as the escape
character. This character can then be placed preceding occurrences
of %
and _
to allow them to act as themselves and not
wildcard characters.
An expression such as:
somecolumn.startswith("foo/%bar", escape="^")
Will render as:
somecolumn LIKE :param || '%' ESCAPE '^'
The parameter may also be combined with
ColumnOperators.startswith.autoescape
:
somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
Where above, the given literal parameter will be converted to
"foo^%bar^^bat"
before being passed to the database.
sqlalchemy.orm.session.
UOWTransaction
(session)¶sqlalchemy.orm.session.UOWTransaction.
filter_states_for_dep
(dep, states)¶Filter the given list of InstanceStates to those relevant to the given DependencyProcessor.
sqlalchemy.orm.session.UOWTransaction.
finalize_flush_changes
()¶Mark processed objects as clean / deleted after a successful flush().
This method is called within the flush() method after the execute() method has succeeded and the transaction has been committed.
sqlalchemy.orm.session.UOWTransaction.
get_attribute_history
(state, key, passive=symbol('PASSIVE_NO_INITIALIZE'))¶Facade to attributes.get_state_history(), including caching of results.
sqlalchemy.orm.session.UOWTransaction.
is_deleted
(state)¶Return True
if the given state is marked as deleted
within this uowtransaction.
sqlalchemy.orm.session.UOWTransaction.
remove_state_actions
(state)¶Remove pending actions for a state from the uowtransaction.
sqlalchemy.orm.session.UOWTransaction.
was_already_deleted
(state)¶Return True
if the given state is expired and was deleted
previously.
flambé! the dragon and The Alchemist image designs created and generously donated by Rotem Yaari.
Created using Sphinx 3.5.3.