# SQLAlchemy 0.8 Documentation

Search:
Release: 0.8.2 | Release Date: July 3, 2013

# ORM Internals

Key ORM constructs, not otherwise covered in other sections, are listed here.

class `sqlalchemy.orm.state.``AttributeState`(state, key)

  Bases: `object`

  Provide an inspection interface corresponding to a particular attribute on a particular mapped object.

  The `AttributeState` object is accessed via the `InstanceState.attr` collection of a particular `InstanceState`:

      from sqlalchemy import inspect

      insp = inspect(some_mapped_object)
      attr_state = insp.attr.some_attribute

  `history`

    Return the current pre-flush change history for this attribute, via the `History` interface.

  `loaded_value`

    The current value of this attribute as loaded from the database.

    If the value has not been loaded, or is otherwise not present in the object’s dictionary, returns NO_VALUE.

  `value`

    Return the value of this attribute.

    This operation is equivalent to accessing the object’s attribute directly or via `getattr()`, and will fire off any pending loader callables if needed.

class `sqlalchemy.orm.instrumentation.``ClassManager`(class_)

  Bases: `dict`

  tracks state information at the class level.

  `__eq__`
    inherited from the `__eq__` attribute of `dict`

    x.__eq__(y) <==> x==y

  `__le__`
    inherited from the `__le__` attribute of `dict`

    x.__le__(y) <==> x<=y

  `__lt__`
    inherited from the `__lt__` attribute of `dict`

    x.__lt__(y) <==> x<y

  `__ne__`
    inherited from the `__ne__` attribute of `dict`

    x.__ne__(y) <==> x!=y

  `clear`() → None. Remove all items from D.
    inherited from the `clear()` method of `dict`
  `copy`() → a shallow copy of D
    inherited from the `copy()` method of `dict`
  `dispose`()

    Dissasociate this manager from its class.

  static `fromkeys`(S[, v]) → New dict with keys from S and values equal to v.
    inherited from the `fromkeys()` method of `dict`

    v defaults to None.

  `get`(k[, d]) → D[k] if k in D, else d. d defaults to None.
    inherited from the `get()` method of `dict`
  `has_key`(k) → True if D has a key k, else False
    inherited from the `has_key()` method of `dict`
  `has_parent`(state, key, optimistic=False)

    TODO

  `items`() → list of D's (key, value) pairs, as 2-tuples
    inherited from the `items()` method of `dict`
  `iteritems`() → an iterator over the (key, value) items of D
    inherited from the `iteritems()` method of `dict`
  `iterkeys`() → an iterator over the keys of D
    inherited from the `iterkeys()` method of `dict`
  `itervalues`() → an iterator over the values of D
    inherited from the `itervalues()` method of `dict`
  `keys`() → list of D's keys
    inherited from the `keys()` method of `dict`
  `manage`()

    Mark this instance as the manager for its class.

  `original_init`

    x.__init__(...) initializes x; see help(type(x)) for signature

  `pop`(k[, d]) → v, remove specified key and return the corresponding value.
    inherited from the `pop()` method of `dict`

    If key is not found, d is returned if given, otherwise KeyError is raised

  `popitem`() → (k, v), remove and return some (key, value) pair as a
    inherited from the `popitem()` method of `dict`

    2-tuple; but raise KeyError if D is empty.

  `setdefault`(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
    inherited from the `setdefault()` method of `dict`
  classmethod `state_getter`()

    Return a (instance) -> InstanceState callable.

    “state getter” callables should raise either KeyError or AttributeError if no InstanceState could be found for the instance.

  `unregister`()

    remove all instrumentation established by this ClassManager.

  `update`([E], **F) → None. Update D from dict/iterable E and F.
    inherited from the `update()` method of `dict`

    If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

  `values`() → list of D's values
    inherited from the `values()` method of `dict`
  `viewitems`() → a set-like object providing a view on D's items
    inherited from the `viewitems()` method of `dict`
  `viewkeys`() → a set-like object providing a view on D's keys
    inherited from the `viewkeys()` method of `dict`
  `viewvalues`() → an object providing a view on D's values
    inherited from the `viewvalues()` method of `dict`

class `sqlalchemy.orm.properties.``ColumnProperty`(*columns, **kwargs)

  Bases: `sqlalchemy.orm.interfaces.StrategizedProperty`

  Describes an object attribute that corresponds to a table column.

  Public constructor is the `orm.column_property()` function.

  `ColumnComparator`

    alias of `Comparator`

  class `Comparator`(prop, parentmapper, adapter=None)

    Bases: `sqlalchemy.orm.interfaces.PropComparator`

    Produce boolean, comparison, and other operators for `ColumnProperty` attributes.

    See the documentation for `PropComparator` for a brief overview.

    See also:

    `PropComparator`

    `ColumnOperators`

    Redefining and Creating New Operators

    `TypeEngine.comparator_factory`

    `__eq__`(other)
      inherited from the `__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`.

    `__le__`(other)
      inherited from the `__le__()` method of `ColumnOperators`

      Implement the `<=` operator.

      In a column context, produces the clause `a <= b`.

    `__lt__`(other)
      inherited from the `__lt__()` method of `ColumnOperators`

      Implement the `<` operator.

      In a column context, produces the clause `a < b`.

    `__ne__`(other)
      inherited from the `__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`.

    `adapted`(adapter)
      inherited from the `adapted()` method of `PropComparator`

      Return a copy of this PropComparator which will use the given adaption function on the local side of generated expressions.

    `any`(criterion=None, **kwargs)
      inherited from the `any()` method of `PropComparator`

      Return true if this collection contains any member that meets the given criterion.

      The usual implementation of `any()` is `RelationshipProperty.Comparator.any()`.

      Parameters:

      - criterion – an optional ClauseElement formulated against the member class’ table or attributes.
      - **kwargs – key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

    `asc`()
      inherited from the `asc()` method of `ColumnOperators`

      Produce a `asc()` clause against the parent object.

    `between`(cleft, cright)
      inherited from the `between()` method of `ColumnOperators`

      Produce a `between()` clause against the parent object, given the lower and upper range.

    `collate`(collation)
      inherited from the `collate()` method of `ColumnOperators`

      Produce a `collate()` clause against the parent object, given the collation string.

    `concat`(other)
      inherited from the `concat()` method of `ColumnOperators`

      Implement the ‘concat’ operator.

      In a column context, produces the clause `a || b`, or uses the `concat()` operator on MySQL.

    `contains`(other, **kwargs)
      inherited from the `contains()` method of `ColumnOperators`

      Implement the ‘contains’ operator.

      In a column context, produces the clause `LIKE '%<other>%'`

    `desc`()
      inherited from the `desc()` method of `ColumnOperators`

      Produce a `desc()` clause against the parent object.

    `distinct`()
      inherited from the `distinct()` method of `ColumnOperators`

      Produce a `distinct()` clause against the parent object.

    `endswith`(other, **kwargs)
      inherited from the `endswith()` method of `ColumnOperators`

      Implement the ‘endswith’ operator.

      In a column context, produces the clause `LIKE '%<other>'`

    `has`(criterion=None, **kwargs)
      inherited from the `has()` method of `PropComparator`

      Return true if this element references a member which meets the given criterion.

      The usual implementation of `has()` is `RelationshipProperty.Comparator.has()`.

      Parameters:

      - criterion – an optional ClauseElement formulated against the member class’ table or attributes.
      - **kwargs – key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

    `ilike`(other, escape=None)
      inherited from the `ilike()` method of `ColumnOperators`

      Implement the `ilike` operator.

      In a column context, produces the clause `a ILIKE other`.

      E.g.:

          select([sometable]).where(sometable.c.column.ilike("%foobar%"))

      Parameters:

      - other – expression to be compared
      - escape –

        optional escape character, renders the `ESCAPE` keyword, e.g.:

            somecolumn.ilike("foo/%bar", escape="/")

      See also

      `ColumnOperators.like()`

    `in_`(other)
      inherited from the `in_()` method of `ColumnOperators`

      Implement the `in` operator.

      In a column context, produces the clause `a IN other`. “other” may be a tuple/list of column expressions, or a `select()` construct.

    `is_`(other)
      inherited from the `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.

      New in version 0.7.9.

      See also

      `ColumnOperators.isnot()`

    `isnot`(other)
      inherited from the `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.

      New in version 0.7.9.

      See also

      `ColumnOperators.is_()`

    `like`(other, escape=None)
      inherited from the `like()` method of `ColumnOperators`

      Implement the `like` operator.

      In a column context, produces the clause `a LIKE other`.

      E.g.:

          select([sometable]).where(sometable.c.column.like("%foobar%"))

      Parameters:

      - other – expression to be compared
      - escape –

        optional escape character, renders the `ESCAPE` keyword, e.g.:

            somecolumn.like("foo/%bar", escape="/")

      See also

      `ColumnOperators.ilike()`

    `match`(other, **kwargs)
      inherited from the `match()` method of `ColumnOperators`

      Implements the ‘match’ operator.

      In a column context, this produces a MATCH clause, i.e. `MATCH '<other>'`. The allowed contents of `other` are database backend specific.

    `notilike`(other, escape=None)
      inherited from the `notilike()` method of `ColumnOperators`

      implement the `NOT ILIKE` operator.

      This is equivalent to using negation with `ColumnOperators.ilike()`, i.e. `~x.ilike(y)`.

      New in version 0.8.

      See also

      `ColumnOperators.ilike()`

    `notin_`(other)
      inherited from the `notin_()` method of `ColumnOperators`

      implement the `NOT IN` operator.

      This is equivalent to using negation with `ColumnOperators.in_()`, i.e. `~x.in_(y)`.

      New in version 0.8.

      See also

      `ColumnOperators.in_()`

    `notlike`(other, escape=None)
      inherited from the `notlike()` method of `ColumnOperators`

      implement the `NOT LIKE` operator.

      This is equivalent to using negation with `ColumnOperators.like()`, i.e. `~x.like(y)`.

      New in version 0.8.

      See also

      `ColumnOperators.like()`

    `nullsfirst`()
      inherited from the `nullsfirst()` method of `ColumnOperators`

      Produce a `nullsfirst()` clause against the parent object.

    `nullslast`()
      inherited from the `nullslast()` method of `ColumnOperators`

      Produce a `nullslast()` clause against the parent object.

    `of_type`(class_)
      inherited from the `of_type()` method of `PropComparator`

      Redefine this object in terms of a polymorphic subclass.

      Returns a new PropComparator from which further criterion can be evaluated.

      e.g.:

          query.join(Company.employees.of_type(Engineer)).\
             filter(Engineer.name=='foo')

      Parameters: | class_ – a class or mapper indicating that criterion will be against this specific subclass.

    `op`(opstring, precedence=0)
      inherited from the `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`.

      Parameters:

      - 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.

        New in version 0.8: - added the ‘precedence’ argument.

      See also

      Redefining and Creating New Operators

    `startswith`(other, **kwargs)
      inherited from the `startswith()` method of `ColumnOperators`

      Implement the `startwith` operator.

      In a column context, produces the clause `LIKE '<other>%'`

  `ColumnProperty.``__init__`(*columns, **kwargs)

    Construct a ColumnProperty.

    Note the public constructor is the `orm.column_property()` function.

    Parameters:

    - *columns – The list of columns describes a single object property. If there are multiple tables joined together for the mapper, this list represents the equivalent column as it appears across each table.
    - group –
    - deferred –
    - comparator_factory –
    - descriptor –
    - expire_on_flush –
    - extension –
    - info – Optional data dictionary which will be populated into the `info` attribute of this object.

  `ColumnProperty.``cascade_iterator`(type_, state, visited_instances=None, halt_on=None)
    inherited from the `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.

    See PropertyLoader for the related instance implementation.

  `ColumnProperty.``class_attribute`
    inherited from the `class_attribute` attribute of `MapperProperty`

    Return the class-bound descriptor corresponding to this MapperProperty.

  `ColumnProperty.``compare`(operator, value, **kw)
    inherited from the `compare()` method of `MapperProperty`

    Return a compare operation for the columns represented by this `MapperProperty` to the given value, which may be a column value or an instance. ‘operator’ is an operator from the operators module, or from sql.Comparator.

    By default uses the PropComparator attached to this MapperProperty under the attribute name “comparator”.

  `ColumnProperty.``expression`

    Return the primary column or expression for this ColumnProperty.

  `ColumnProperty.``info`
    inherited from the `info` attribute of `MapperProperty`

    Info dictionary associated with the object, allowing user-defined data to be associated with this `MapperProperty`.

    The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the `column_property()`, `relationship()`, or `composite()` functions.

    New in version 0.8: Added support for .info to all `MapperProperty` subclasses.

    See also

    `QueryableAttribute.info`

    `SchemaItem.info`

  `ColumnProperty.``init`()
    inherited from the `init()` method of `MapperProperty`

    Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.

  `ColumnProperty.``is_primary`()
    inherited from the `is_primary()` method of `MapperProperty`

    Return True if this `MapperProperty`‘s mapper is the primary mapper for its class.

    This flag is used to indicate that the `MapperProperty` can define attribute instrumentation for the class at the class level (as opposed to the individual instance level).

class `sqlalchemy.orm.descriptor_props.``CompositeProperty`(class_, *attrs, **kwargs)

  Bases: `sqlalchemy.orm.descriptor_props.DescriptorProperty`

  Defines a “composite” mapped attribute, representing a collection of columns as one attribute.

  `CompositeProperty` is constructed using the `composite()` function.

  See also:

  Composite Column Types

  class `Comparator`(prop, parentmapper, adapter=None)

    Bases: `sqlalchemy.orm.interfaces.PropComparator`

    Produce boolean, comparison, and other operators for `CompositeProperty` attributes.

    See the example in Redefining Comparison Operations for Composites for an overview of usage , as well as the documentation for `PropComparator`.

    See also:

    `PropComparator`

    `ColumnOperators`

    Redefining and Creating New Operators

    `TypeEngine.comparator_factory`

  `CompositeProperty.``do_init`()

    Initialization which occurs after the `CompositeProperty` has been associated with its parent mapper.

  `CompositeProperty.``get_history`(state, dict_, passive=<symbol 'PASSIVE_OFF>)

    Provided for userland code that uses attributes.get_history().

class `sqlalchemy.orm.interfaces.``_InspectionAttr`

  Bases: `object`

  A base class applied to all ORM objects that can be returned by the `inspect()` function.

  The attributes defined here allow the usage of simple boolean checks to test basic facts about the object returned.

  While the boolean checks here are basically the same as using the Python isinstance() function, the flags here can be used without the need to import all of these classes, and also such that the SQLAlchemy class system can change while leaving the flags here intact for forwards-compatibility.

  `extension_type` = <symbol 'NOT_EXTENSION>

    The extension type, if any. Defaults to `interfaces.NOT_EXTENSION`

    New in version 0.8.0.

    See also

    `HYBRID_METHOD`

    `HYBRID_PROPERTY`

    `ASSOCIATION_PROXY`

  `is_aliased_class` = False

    True if this object is an instance of `AliasedClass`.

  `is_attribute` = False

    True if this object is a Python descriptor.

    This can refer to one of many types. Usually a `QueryableAttribute` which handles attributes events on behalf of a `MapperProperty`. But can also be an extension type such as `AssociationProxy` or `hybrid_property`. The `_InspectionAttr.extension_type` will refer to a constant identifying the specific subtype.

    See also

    `Mapper.all_orm_descriptors`

  `is_clause_element` = False

    True if this object is an instance of `ClauseElement`.

  `is_instance` = False

    True if this object is an instance of `InstanceState`.

  `is_mapper` = False

    True if this object is an instance of `Mapper`.

  `is_property` = False

    True if this object is an instance of `MapperProperty`.

  `is_selectable` = False

    Return True if this object is an instance of `Selectable`.

class `sqlalchemy.orm.state.``InstanceState`(obj, manager)

  Bases: `sqlalchemy.orm.interfaces._InspectionAttr`

  tracks state information at the instance level.

  `__call__`(passive)

    __call__ allows the InstanceState to act as a deferred callable for loading expired attributes, which is also serializable (picklable).

  `attrs`

    Return a namespace representing each attribute on the mapped object, including its current value and history.

    The returned object is an instance of `AttributeState`.

  `detached`

    Return true if the object is detached.

  `expired_attributes`

    Return the set of keys which are ‘expired’ to be loaded by the manager’s deferred scalar loader, assuming no pending changes.

    see also the `unmodified` collection which is intersected against this set when a refresh operation occurs.

  `has_identity`

    Return `True` if this object has an identity key.

    This should always have the same value as the expression `state.persistent or state.detached`.

  `identity`

    Return the mapped identity of the mapped object. This is the primary key identity as persisted by the ORM which can always be passed directly to `Query.get()`.

    Returns `None` if the object has no primary key identity.

    Note

    An object which is transient or pending does not have a mapped identity until it is flushed, even if its attributes include primary key values.

  `identity_key`

    Return the identity key for the mapped object.

    This is the key used to locate the object within the `Session.identity_map` mapping. It contains the identity as returned by `identity` within it.

  `mapper`

    Return the `Mapper` used for this mapepd object.

  `object`

    Return the mapped object represented by this `InstanceState`.

  `pending`

    Return true if the object is pending.

  `persistent`

    Return true if the object is persistent.

  `session`

    Return the owning `Session` for this instance, or `None` if none available.

  `transient`

    Return true if the object is transient.

  `unloaded`

    Return the set of keys which do not have a loaded value.

    This includes expired attributes and any other attribute that was never populated or modified.

  `unmodified`

    Return the set of keys which have no uncommitted changes

  `unmodified_intersection`(keys)

    Return self.unmodified.intersection(keys).

class `sqlalchemy.orm.attributes.``InstrumentedAttribute`(class_, key, impl=None, comparator=None, parententity=None, of_type=None)

  Bases: `sqlalchemy.orm.attributes.QueryableAttribute`

  Class bound instrumented attribute which adds basic descriptor methods.

  See `QueryableAttribute` for a description of most features.

  `__get__`(instance, owner)
  `__set__`(instance, value)
  `__delete__`(instance)

class `sqlalchemy.orm.interfaces.``MapperProperty`

  Bases: `sqlalchemy.orm.interfaces._MappedAttribute`, `sqlalchemy.orm.interfaces._InspectionAttr`

  Manage the relationship of a `Mapper` to a single class attribute, as well as that attribute as it appears on individual instances of the class, including attribute instrumentation, attribute access, loading behavior, and dependency calculations.

  The most common occurrences of `MapperProperty` are the mapped `Column`, which is represented in a mapping as an instance of `ColumnProperty`, and a reference to another class produced by `relationship()`, represented in the mapping as an instance of `RelationshipProperty`.

  `cascade` = frozenset([])

    The set of ‘cascade’ attribute names.

    This collection is checked before the ‘cascade_iterator’ method is called.

  `cascade_iterator`(type_, state, visited_instances=None, halt_on=None)

    Iterate through instances related to the given instance for a particular ‘cascade’, starting with this MapperProperty.

    Return an iterator3-tuples (instance, mapper, state).

    Note that the ‘cascade’ collection on this MapperProperty is checked first for the given type before cascade_iterator is called.

    See PropertyLoader for the related instance implementation.

  `class_attribute`

    Return the class-bound descriptor corresponding to this MapperProperty.

  `compare`(operator, value, **kw)

    Return a compare operation for the columns represented by this `MapperProperty` to the given value, which may be a column value or an instance. ‘operator’ is an operator from the operators module, or from sql.Comparator.

    By default uses the PropComparator attached to this MapperProperty under the attribute name “comparator”.

  `create_row_processor`(context, path, mapper, row, adapter)

    Return a 3-tuple consisting of three row processing functions.

  `do_init`()

    Perform subclass-specific initialization post-mapper-creation steps.

    This is a template method called by the `MapperProperty` object’s init() method.

  `info`

    Info dictionary associated with the object, allowing user-defined data to be associated with this `MapperProperty`.

    The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the `column_property()`, `relationship()`, or `composite()` functions.

    New in version 0.8: Added support for .info to all `MapperProperty` subclasses.

    See also

    `QueryableAttribute.info`

    `SchemaItem.info`

  `init`()

    Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.

  `is_primary`()

    Return True if this `MapperProperty`‘s mapper is the primary mapper for its class.

    This flag is used to indicate that the `MapperProperty` can define attribute instrumentation for the class at the class level (as opposed to the individual instance level).

  `merge`(session, source_state, source_dict, dest_state, dest_dict, load, _recursive)

    Merge the attribute represented by this `MapperProperty` from source to destination object

  `post_instrument_class`(mapper)

    Perform instrumentation adjustments that need to occur after init() has completed.

  `setup`(context, entity, path, adapter, **kwargs)

    Called by Query for the purposes of constructing a SQL statement.

    Each MapperProperty associated with the target mapper processes the statement referenced by the query context, adding columns and/or criterion as appropriate.

`sqlalchemy.orm.interfaces.``NOT_EXTENSION` = <symbol 'NOT_EXTENSION>

class `sqlalchemy.orm.interfaces.``PropComparator`(prop, parentmapper, adapter=None)

  Bases: `sqlalchemy.sql.operators.ColumnOperators`

  Defines boolean, comparison, and other operators for `MapperProperty` objects.

  SQLAlchemy allows for operators to be redefined at both the Core and ORM level. `PropComparator` is the base class of operator redefinition for ORM-level operations, including those of `ColumnProperty`, `RelationshipProperty`, and `CompositeProperty`.

  Note

  With the advent of Hybrid properties introduced in SQLAlchemy 0.7, as well as Core-level operator redefinition in SQLAlchemy 0.8, the use case for user-defined `PropComparator` instances is extremely rare. See Hybrid Attributes as well as Redefining and Creating New Operators.

  User-defined subclasses of `PropComparator` may be created. The built-in Python comparison and math operator methods, such as `operators.ColumnOperators.__eq__()`, `operators.ColumnOperators.__lt__()`, and `operators.ColumnOperators.__add__()`, can be overridden to provide new operator behavior. The custom `PropComparator` is passed to the `MapperProperty` instance via the `comparator_factory` argument. In each case, the appropriate subclass of `PropComparator` should be used:

      # definition of custom PropComparator subclasses

      from sqlalchemy.orm.properties import \
                              ColumnProperty,\
                              CompositeProperty,\
                              RelationshipProperty

      class MyColumnComparator(ColumnProperty.Comparator):
          def __eq__(self, other):
              return self.__clause_element__() == other

      class MyRelationshipComparator(RelationshipProperty.Comparator):
          def any(self, expression):
              "define the 'any' operation"
              # ...

      class MyCompositeComparator(CompositeProperty.Comparator):
          def __gt__(self, other):
              "redefine the 'greater than' operation"

              return sql.and_(*[a>b for a, b in
                                zip(self.__clause_element__().clauses,
                                    other.__composite_values__())])

      # application of custom PropComparator subclasses

      from sqlalchemy.orm import column_property, relationship, composite
      from sqlalchemy import Column, String

      class SomeMappedClass(Base):
          some_column = column_property(Column("some_column", String),
                              comparator_factory=MyColumnComparator)

          some_relationship = relationship(SomeOtherClass,
                              comparator_factory=MyRelationshipComparator)

          some_composite = composite(
                  Column("a", String), Column("b", String),
                  comparator_factory=MyCompositeComparator
              )

  Note that for column-level operator redefinition, it’s usually simpler to define the operators at the Core level, using the `TypeEngine.comparator_factory` attribute. See Redefining and Creating New Operators for more detail.

  See also:

  `ColumnProperty.Comparator`

  `RelationshipProperty.Comparator`

  `CompositeProperty.Comparator`

  `ColumnOperators`

  Redefining and Creating New Operators

  `TypeEngine.comparator_factory`

  `__eq__`(other)
    inherited from the `__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`.

  `__le__`(other)
    inherited from the `__le__()` method of `ColumnOperators`

    Implement the `<=` operator.

    In a column context, produces the clause `a <= b`.

  `__lt__`(other)
    inherited from the `__lt__()` method of `ColumnOperators`

    Implement the `<` operator.

    In a column context, produces the clause `a < b`.

  `__ne__`(other)
    inherited from the `__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`.

  `adapted`(adapter)

    Return a copy of this PropComparator which will use the given adaption function on the local side of generated expressions.

  `any`(criterion=None, **kwargs)

    Return true if this collection contains any member that meets the given criterion.

    The usual implementation of `any()` is `RelationshipProperty.Comparator.any()`.

    Parameters:

    - criterion – an optional ClauseElement formulated against the member class’ table or attributes.
    - **kwargs – key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

  `asc`()
    inherited from the `asc()` method of `ColumnOperators`

    Produce a `asc()` clause against the parent object.

  `between`(cleft, cright)
    inherited from the `between()` method of `ColumnOperators`

    Produce a `between()` clause against the parent object, given the lower and upper range.

  `collate`(collation)
    inherited from the `collate()` method of `ColumnOperators`

    Produce a `collate()` clause against the parent object, given the collation string.

  `concat`(other)
    inherited from the `concat()` method of `ColumnOperators`

    Implement the ‘concat’ operator.

    In a column context, produces the clause `a || b`, or uses the `concat()` operator on MySQL.

  `contains`(other, **kwargs)
    inherited from the `contains()` method of `ColumnOperators`

    Implement the ‘contains’ operator.

    In a column context, produces the clause `LIKE '%<other>%'`

  `desc`()
    inherited from the `desc()` method of `ColumnOperators`

    Produce a `desc()` clause against the parent object.

  `distinct`()
    inherited from the `distinct()` method of `ColumnOperators`

    Produce a `distinct()` clause against the parent object.

  `endswith`(other, **kwargs)
    inherited from the `endswith()` method of `ColumnOperators`

    Implement the ‘endswith’ operator.

    In a column context, produces the clause `LIKE '%<other>'`

  `has`(criterion=None, **kwargs)

    Return true if this element references a member which meets the given criterion.

    The usual implementation of `has()` is `RelationshipProperty.Comparator.has()`.

    Parameters:

    - criterion – an optional ClauseElement formulated against the member class’ table or attributes.
    - **kwargs – key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

  `ilike`(other, escape=None)
    inherited from the `ilike()` method of `ColumnOperators`

    Implement the `ilike` operator.

    In a column context, produces the clause `a ILIKE other`.

    E.g.:

        select([sometable]).where(sometable.c.column.ilike("%foobar%"))

    Parameters:

    - other – expression to be compared
    - escape –

      optional escape character, renders the `ESCAPE` keyword, e.g.:

          somecolumn.ilike("foo/%bar", escape="/")

    See also

    `ColumnOperators.like()`

  `in_`(other)
    inherited from the `in_()` method of `ColumnOperators`

    Implement the `in` operator.

    In a column context, produces the clause `a IN other`. “other” may be a tuple/list of column expressions, or a `select()` construct.

  `is_`(other)
    inherited from the `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.

    New in version 0.7.9.

    See also

    `ColumnOperators.isnot()`

  `isnot`(other)
    inherited from the `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.

    New in version 0.7.9.

    See also

    `ColumnOperators.is_()`

  `like`(other, escape=None)
    inherited from the `like()` method of `ColumnOperators`

    Implement the `like` operator.

    In a column context, produces the clause `a LIKE other`.

    E.g.:

        select([sometable]).where(sometable.c.column.like("%foobar%"))

    Parameters:

    - other – expression to be compared
    - escape –

      optional escape character, renders the `ESCAPE` keyword, e.g.:

          somecolumn.like("foo/%bar", escape="/")

    See also

    `ColumnOperators.ilike()`

  `match`(other, **kwargs)
    inherited from the `match()` method of `ColumnOperators`

    Implements the ‘match’ operator.

    In a column context, this produces a MATCH clause, i.e. `MATCH '<other>'`. The allowed contents of `other` are database backend specific.

  `notilike`(other, escape=None)
    inherited from the `notilike()` method of `ColumnOperators`

    implement the `NOT ILIKE` operator.

    This is equivalent to using negation with `ColumnOperators.ilike()`, i.e. `~x.ilike(y)`.

    New in version 0.8.

    See also

    `ColumnOperators.ilike()`

  `notin_`(other)
    inherited from the `notin_()` method of `ColumnOperators`

    implement the `NOT IN` operator.

    This is equivalent to using negation with `ColumnOperators.in_()`, i.e. `~x.in_(y)`.

    New in version 0.8.

    See also

    `ColumnOperators.in_()`

  `notlike`(other, escape=None)
    inherited from the `notlike()` method of `ColumnOperators`

    implement the `NOT LIKE` operator.

    This is equivalent to using negation with `ColumnOperators.like()`, i.e. `~x.like(y)`.

    New in version 0.8.

    See also

    `ColumnOperators.like()`

  `nullsfirst`()
    inherited from the `nullsfirst()` method of `ColumnOperators`

    Produce a `nullsfirst()` clause against the parent object.

  `nullslast`()
    inherited from the `nullslast()` method of `ColumnOperators`

    Produce a `nullslast()` clause against the parent object.

  `of_type`(class_)

    Redefine this object in terms of a polymorphic subclass.

    Returns a new PropComparator from which further criterion can be evaluated.

    e.g.:

        query.join(Company.employees.of_type(Engineer)).\
           filter(Engineer.name=='foo')

    Parameters: | class_ – a class or mapper indicating that criterion will be against this specific subclass.

  `op`(opstring, precedence=0)
    inherited from the `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`.

    Parameters:

    - 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.

      New in version 0.8: - added the ‘precedence’ argument.

    See also

    Redefining and Creating New Operators

  `operate`(op, *other, **kwargs)
    inherited from the `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))

    Parameters:

    - op – Operator callable.
    - *other – the ‘other’ side of the operation. Will be a single scalar for most operations.
    - **kwargs – modifiers. These may be passed by special operators such as `ColumnOperators.contains()`.

  `reverse_operate`(op, other, **kwargs)
    inherited from the `reverse_operate()` method of `Operators`

    Reverse operate on an argument.

    Usage is the same as `operate()`.

  `startswith`(other, **kwargs)
    inherited from the `startswith()` method of `ColumnOperators`

    Implement the `startwith` operator.

    In a column context, produces the clause `LIKE '<other>%'`

class `sqlalchemy.orm.properties.``RelationshipProperty`(argument, secondary=None, primaryjoin=None, secondaryjoin=None, foreign_keys=None, uselist=None, order_by=False, backref=None, back_populates=None, post_update=False, cascade=False, extension=None, viewonly=False, lazy=True, collection_class=None, passive_deletes=False, passive_updates=True, remote_side=None, enable_typechecks=True, join_depth=None, comparator_factory=None, single_parent=False, innerjoin=False, doc=None, active_history=False, cascade_backrefs=True, load_on_pending=False, strategy_class=None, _local_remote_pairs=None, query_class=None, info=None)

  Bases: `sqlalchemy.orm.interfaces.StrategizedProperty`

  Describes an object property that holds a single item or list of items that correspond to a related database table.

  Public constructor is the `orm.relationship()` function.

  See also:

  Relationship Configuration

  class `Comparator`(prop, parentmapper, of_type=None, adapter=None)

    Bases: `sqlalchemy.orm.interfaces.PropComparator`

    Produce boolean, comparison, and other operators for `RelationshipProperty` attributes.

    See the documentation for `PropComparator` for a brief overview of ORM level operator definition.

    See also:

    `PropComparator`

    `ColumnProperty.Comparator`

    `ColumnOperators`

    Redefining and Creating New Operators

    `TypeEngine.comparator_factory`

    `__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 `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 `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.
    `__init__`(prop, parentmapper, of_type=None, adapter=None)

      Construction of `RelationshipProperty.Comparator` is internal to the ORM’s attribute mechanics.

    `__le__`(other)
      inherited from the `__le__()` method of `ColumnOperators`

      Implement the `<=` operator.

      In a column context, produces the clause `a <= b`.

    `__lt__`(other)
      inherited from the `__lt__()` method of `ColumnOperators`

      Implement the `<` operator.

      In a column context, produces the clause `a < b`.

    `__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 `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 `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.
    `adapted`(adapter)

      Return a copy of this PropComparator which will use the given adaption function on the local side of generated expressions.

    `any`(criterion=None, **kwargs)

      Produce an expression that tests a collection against particular criterion, using EXISTS.

      An expression like:

          session.query(MyClass).filter(
              MyClass.somereference.any(SomeRelated.x==2)
          )

      Will produce a query like:

          SELECT * FROM my_table WHERE
          EXISTS (SELECT 1 FROM related WHERE related.my_id=my_table.id
          AND related.x=2)

      Because `any()` uses a correlated subquery, its performance is not nearly as good when compared against large target tables as that of using a join.

      `any()` is particularly useful for testing for empty collections:

          session.query(MyClass).filter(
              ~MyClass.somereference.any()
          )

      will produce:

          SELECT * FROM my_table WHERE
          NOT EXISTS (SELECT 1 FROM related WHERE
          related.my_id=my_table.id)

      `any()` is only valid for collections, i.e. a `relationship()` that has `uselist=True`. For scalar references, use `has()`.

    `asc`()
      inherited from the `asc()` method of `ColumnOperators`

      Produce a `asc()` clause against the parent object.

    `between`(cleft, cright)
      inherited from the `between()` method of `ColumnOperators`

      Produce a `between()` clause against the parent object, given the lower and upper range.

    `collate`(collation)
      inherited from the `collate()` method of `ColumnOperators`

      Produce a `collate()` clause against the parent object, given the collation string.

    `concat`(other)
      inherited from the `concat()` method of `ColumnOperators`

      Implement the ‘concat’ operator.

      In a column context, produces the clause `a || b`, or uses the `concat()` operator on MySQL.

    `contains`(other, **kwargs)

      Return a simple expression that tests a collection for containment of a particular item.

      `contains()` is only valid for a collection, i.e. a `relationship()` that implements one-to-many or many-to-many with `uselist=True`.

      When used in a simple one-to-many context, an expression like:

          MyClass.contains(other)

      Produces a clause like:

          mytable.id == <some id>

      Where `<some id>` is the value of the foreign key attribute on `other` which refers to the primary key of its parent object. From this it follows that `contains()` is very useful when used with simple one-to-many operations.

      For many-to-many operations, the behavior of `contains()` has more caveats. The association table will be rendered in the statement, producing an “implicit” join, that is, includes multiple tables in the FROM clause which are equated in the WHERE clause:

          query(MyClass).filter(MyClass.contains(other))

      Produces a query like:

          SELECT * FROM my_table, my_association_table AS
          my_association_table_1 WHERE
          my_table.id = my_association_table_1.parent_id
          AND my_association_table_1.child_id = <some id>

      Where `<some id>` would be the primary key of `other`. From the above, it is clear that `contains()` will not work with many-to-many collections when used in queries that move beyond simple AND conjunctions, such as multiple `contains()` expressions joined by OR. In such cases subqueries or explicit “outer joins” will need to be used instead. See `any()` for a less-performant alternative using EXISTS, or refer to `Query.outerjoin()` as well as Querying with Joins for more details on constructing outer joins.

    `desc`()
      inherited from the `desc()` method of `ColumnOperators`

      Produce a `desc()` clause against the parent object.

    `distinct`()
      inherited from the `distinct()` method of `ColumnOperators`

      Produce a `distinct()` clause against the parent object.

    `endswith`(other, **kwargs)
      inherited from the `endswith()` method of `ColumnOperators`

      Implement the ‘endswith’ operator.

      In a column context, produces the clause `LIKE '%<other>'`

    `has`(criterion=None, **kwargs)

      Produce an expression that tests a scalar reference against particular criterion, using EXISTS.

      An expression like:

          session.query(MyClass).filter(
              MyClass.somereference.has(SomeRelated.x==2)
          )

      Will produce a query like:

          SELECT * FROM my_table WHERE
          EXISTS (SELECT 1 FROM related WHERE
          related.id==my_table.related_id AND related.x=2)

      Because `has()` uses a correlated subquery, its performance is not nearly as good when compared against large target tables as that of using a join.

      `has()` is only valid for scalar references, i.e. a `relationship()` that has `uselist=False`. For collection references, use `any()`.

    `ilike`(other, escape=None)
      inherited from the `ilike()` method of `ColumnOperators`

      Implement the `ilike` operator.

      In a column context, produces the clause `a ILIKE other`.

      E.g.:

          select([sometable]).where(sometable.c.column.ilike("%foobar%"))

      Parameters:

      - other – expression to be compared
      - escape –

        optional escape character, renders the `ESCAPE` keyword, e.g.:

            somecolumn.ilike("foo/%bar", escape="/")

      See also

      `ColumnOperators.like()`

    `in_`(other)

      Produce an IN clause - this is not implemented for `relationship()`-based attributes at this time.

    `is_`(other)
      inherited from the `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.

      New in version 0.7.9.

      See also

      `ColumnOperators.isnot()`

    `isnot`(other)
      inherited from the `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.

      New in version 0.7.9.

      See also

      `ColumnOperators.is_()`

    `like`(other, escape=None)
      inherited from the `like()` method of `ColumnOperators`

      Implement the `like` operator.

      In a column context, produces the clause `a LIKE other`.

      E.g.:

          select([sometable]).where(sometable.c.column.like("%foobar%"))

      Parameters:

      - other – expression to be compared
      - escape –

        optional escape character, renders the `ESCAPE` keyword, e.g.:

            somecolumn.like("foo/%bar", escape="/")

      See also

      `ColumnOperators.ilike()`

    `mapper`

      The target `Mapper` referred to by this :class:`.RelationshipProperty.Comparator.

      This is the “target” or “remote” side of the `relationship()`.

    `match`(other, **kwargs)
      inherited from the `match()` method of `ColumnOperators`

      Implements the ‘match’ operator.

      In a column context, this produces a MATCH clause, i.e. `MATCH '<other>'`. The allowed contents of `other` are database backend specific.

    `notilike`(other, escape=None)
      inherited from the `notilike()` method of `ColumnOperators`

      implement the `NOT ILIKE` operator.

      This is equivalent to using negation with `ColumnOperators.ilike()`, i.e. `~x.ilike(y)`.

      New in version 0.8.

      See also

      `ColumnOperators.ilike()`

    `notin_`(other)
      inherited from the `notin_()` method of `ColumnOperators`

      implement the `NOT IN` operator.

      This is equivalent to using negation with `ColumnOperators.in_()`, i.e. `~x.in_(y)`.

      New in version 0.8.

      See also

      `ColumnOperators.in_()`

    `notlike`(other, escape=None)
      inherited from the `notlike()` method of `ColumnOperators`

      implement the `NOT LIKE` operator.

      This is equivalent to using negation with `ColumnOperators.like()`, i.e. `~x.like(y)`.

      New in version 0.8.

      See also

      `ColumnOperators.like()`

    `nullsfirst`()
      inherited from the `nullsfirst()` method of `ColumnOperators`

      Produce a `nullsfirst()` clause against the parent object.

    `nullslast`()
      inherited from the `nullslast()` method of `ColumnOperators`

      Produce a `nullslast()` clause against the parent object.

    `of_type`(cls)

      Produce a construct that represents a particular ‘subtype’ of attribute for the parent class.

      Currently this is usable in conjunction with `Query.join()` and `Query.outerjoin()`.

    `op`(opstring, precedence=0)
      inherited from the `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`.

      Parameters:

      - 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.

        New in version 0.8: - added the ‘precedence’ argument.

      See also

      Redefining and Creating New Operators

    `operate`(op, *other, **kwargs)
      inherited from the `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))

      Parameters:

      - op – Operator callable.
      - *other – the ‘other’ side of the operation. Will be a single scalar for most operations.
      - **kwargs – modifiers. These may be passed by special operators such as `ColumnOperators.contains()`.

    `reverse_operate`(op, other, **kwargs)
      inherited from the `reverse_operate()` method of `Operators`

      Reverse operate on an argument.

      Usage is the same as `operate()`.

    `startswith`(other, **kwargs)
      inherited from the `startswith()` method of `ColumnOperators`

      Implement the `startwith` operator.

      In a column context, produces the clause `LIKE '<other>%'`

  `RelationshipProperty.``cascade`

    Return the current cascade setting for this `RelationshipProperty`.

  `RelationshipProperty.``class_attribute`
    inherited from the `class_attribute` attribute of `MapperProperty`

    Return the class-bound descriptor corresponding to this MapperProperty.

  `RelationshipProperty.``info`
    inherited from the `info` attribute of `MapperProperty`

    Info dictionary associated with the object, allowing user-defined data to be associated with this `MapperProperty`.

    The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the `column_property()`, `relationship()`, or `composite()` functions.

    New in version 0.8: Added support for .info to all `MapperProperty` subclasses.

    See also

    `QueryableAttribute.info`

    `SchemaItem.info`

  `RelationshipProperty.``init`()
    inherited from the `init()` method of `MapperProperty`

    Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.

  `RelationshipProperty.``is_primary`()
    inherited from the `is_primary()` method of `MapperProperty`

    Return True if this `MapperProperty`‘s mapper is the primary mapper for its class.

    This flag is used to indicate that the `MapperProperty` can define attribute instrumentation for the class at the class level (as opposed to the individual instance level).

  `RelationshipProperty.``mapper`

    Return the targeted `Mapper` for this `RelationshipProperty`.

    This is a lazy-initializing static attribute.

  `RelationshipProperty.``table`

    Return the selectable linked to this

    Deprecated since version 0.7: Use .target

    `RelationshipProperty` object’s target `Mapper`.

class `sqlalchemy.orm.descriptor_props.``SynonymProperty`(name, map_column=None, descriptor=None, comparator_factory=None, doc=None)

  Bases: `sqlalchemy.orm.descriptor_props.DescriptorProperty`

  `cascade_iterator`(type_, state, visited_instances=None, halt_on=None)
    inherited from the `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.

    See PropertyLoader for the related instance implementation.

  `class_attribute`
    inherited from the `class_attribute` attribute of `MapperProperty`

    Return the class-bound descriptor corresponding to this MapperProperty.

  `compare`(operator, value, **kw)
    inherited from the `compare()` method of `MapperProperty`

    Return a compare operation for the columns represented by this `MapperProperty` to the given value, which may be a column value or an instance. ‘operator’ is an operator from the operators module, or from sql.Comparator.

    By default uses the PropComparator attached to this MapperProperty under the attribute name “comparator”.

  `create_row_processor`(context, path, mapper, row, adapter)
    inherited from the `create_row_processor()` method of `MapperProperty`

    Return a 3-tuple consisting of three row processing functions.

  `do_init`()
    inherited from the `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.

  `info`
    inherited from the `info` attribute of `MapperProperty`

    Info dictionary associated with the object, allowing user-defined data to be associated with this `MapperProperty`.

    The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the `column_property()`, `relationship()`, or `composite()` functions.

    New in version 0.8: Added support for .info to all `MapperProperty` subclasses.

    See also

    `QueryableAttribute.info`

    `SchemaItem.info`

  `init`()
    inherited from the `init()` method of `MapperProperty`

    Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.

  `is_primary`()
    inherited from the `is_primary()` method of `MapperProperty`

    Return True if this `MapperProperty`‘s mapper is the primary mapper for its class.

    This flag is used to indicate that the `MapperProperty` can define attribute instrumentation for the class at the class level (as opposed to the individual instance level).

  `merge`(session, source_state, source_dict, dest_state, dest_dict, load, _recursive)
    inherited from the `merge()` method of `MapperProperty`

    Merge the attribute represented by this `MapperProperty` from source to destination object

  `post_instrument_class`(mapper)
    inherited from the `post_instrument_class()` method of `MapperProperty`

    Perform instrumentation adjustments that need to occur after init() has completed.

  `setup`(context, entity, path, adapter, **kwargs)
    inherited from the `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.

class `sqlalchemy.orm.query.``QueryContext`(query)

  Bases: `object`

class `sqlalchemy.orm.attributes.``QueryableAttribute`(class_, key, impl=None, comparator=None, parententity=None, of_type=None)

  Bases: `sqlalchemy.orm.interfaces._MappedAttribute`, `sqlalchemy.orm.interfaces._InspectionAttr`, `sqlalchemy.orm.interfaces.PropComparator`

  Base class for descriptor objects that intercept attribute events on behalf of a `MapperProperty` object. The actual `MapperProperty` is accessible via the `QueryableAttribute.property` attribute.

  See also

  `InstrumentedAttribute`

  `MapperProperty`

  `Mapper.all_orm_descriptors`

  `Mapper.attrs`

  `__eq__`(other)
    inherited from the `__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`.

  `__le__`(other)
    inherited from the `__le__()` method of `ColumnOperators`

    Implement the `<=` operator.

    In a column context, produces the clause `a <= b`.

  `__lt__`(other)
    inherited from the `__lt__()` method of `ColumnOperators`

    Implement the `<` operator.

    In a column context, produces the clause `a < b`.

  `__ne__`(other)
    inherited from the `__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`.

  `adapted`(adapter)
    inherited from the `adapted()` method of `PropComparator`

    Return a copy of this PropComparator which will use the given adaption function on the local side of generated expressions.

  `any`(criterion=None, **kwargs)
    inherited from the `any()` method of `PropComparator`

    Return true if this collection contains any member that meets the given criterion.

    The usual implementation of `any()` is `RelationshipProperty.Comparator.any()`.

    Parameters:

    - criterion – an optional ClauseElement formulated against the member class’ table or attributes.
    - **kwargs – key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

  `asc`()
    inherited from the `asc()` method of `ColumnOperators`

    Produce a `asc()` clause against the parent object.

  `between`(cleft, cright)
    inherited from the `between()` method of `ColumnOperators`

    Produce a `between()` clause against the parent object, given the lower and upper range.

  `collate`(collation)
    inherited from the `collate()` method of `ColumnOperators`

    Produce a `collate()` clause against the parent object, given the collation string.

  `concat`(other)
    inherited from the `concat()` method of `ColumnOperators`

    Implement the ‘concat’ operator.

    In a column context, produces the clause `a || b`, or uses the `concat()` operator on MySQL.

  `contains`(other, **kwargs)
    inherited from the `contains()` method of `ColumnOperators`

    Implement the ‘contains’ operator.

    In a column context, produces the clause `LIKE '%<other>%'`

  `desc`()
    inherited from the `desc()` method of `ColumnOperators`

    Produce a `desc()` clause against the parent object.

  `distinct`()
    inherited from the `distinct()` method of `ColumnOperators`

    Produce a `distinct()` clause against the parent object.

  `endswith`(other, **kwargs)
    inherited from the `endswith()` method of `ColumnOperators`

    Implement the ‘endswith’ operator.

    In a column context, produces the clause `LIKE '%<other>'`

  `has`(criterion=None, **kwargs)
    inherited from the `has()` method of `PropComparator`

    Return true if this element references a member which meets the given criterion.

    The usual implementation of `has()` is `RelationshipProperty.Comparator.has()`.

    Parameters:

    - criterion – an optional ClauseElement formulated against the member class’ table or attributes.
    - **kwargs – key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

  `ilike`(other, escape=None)
    inherited from the `ilike()` method of `ColumnOperators`

    Implement the `ilike` operator.

    In a column context, produces the clause `a ILIKE other`.

    E.g.:

        select([sometable]).where(sometable.c.column.ilike("%foobar%"))

    Parameters:

    - other – expression to be compared
    - escape –

      optional escape character, renders the `ESCAPE` keyword, e.g.:

          somecolumn.ilike("foo/%bar", escape="/")

    See also

    `ColumnOperators.like()`

  `in_`(other)
    inherited from the `in_()` method of `ColumnOperators`

    Implement the `in` operator.

    In a column context, produces the clause `a IN other`. “other” may be a tuple/list of column expressions, or a `select()` construct.

  `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 it’s 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 `schema.Column`, the attribute can be referred to using `QueryableAttribute.property` attribute, as `MyClass.someattribute.property.info`.

    New in version 0.8.0.

    See also

    `SchemaItem.info`

    `MapperProperty.info`

  `is_`(other)
    inherited from the `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.

    New in version 0.7.9.

    See also

    `ColumnOperators.isnot()`

  `isnot`(other)
    inherited from the `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.

    New in version 0.7.9.

    See also

    `ColumnOperators.is_()`

  `like`(other, escape=None)
    inherited from the `like()` method of `ColumnOperators`

    Implement the `like` operator.

    In a column context, produces the clause `a LIKE other`.

    E.g.:

        select([sometable]).where(sometable.c.column.like("%foobar%"))

    Parameters:

    - other – expression to be compared
    - escape –

      optional escape character, renders the `ESCAPE` keyword, e.g.:

          somecolumn.like("foo/%bar", escape="/")

    See also

    `ColumnOperators.ilike()`

  `match`(other, **kwargs)
    inherited from the `match()` method of `ColumnOperators`

    Implements the ‘match’ operator.

    In a column context, this produces a MATCH clause, i.e. `MATCH '<other>'`. The allowed contents of `other` are database backend specific.

  `notilike`(other, escape=None)
    inherited from the `notilike()` method of `ColumnOperators`

    implement the `NOT ILIKE` operator.

    This is equivalent to using negation with `ColumnOperators.ilike()`, i.e. `~x.ilike(y)`.

    New in version 0.8.

    See also

    `ColumnOperators.ilike()`

  `notin_`(other)
    inherited from the `notin_()` method of `ColumnOperators`

    implement the `NOT IN` operator.

    This is equivalent to using negation with `ColumnOperators.in_()`, i.e. `~x.in_(y)`.

    New in version 0.8.

    See also

    `ColumnOperators.in_()`

  `notlike`(other, escape=None)
    inherited from the `notlike()` method of `ColumnOperators`

    implement the `NOT LIKE` operator.

    This is equivalent to using negation with `ColumnOperators.like()`, i.e. `~x.like(y)`.

    New in version 0.8.

    See also

    `ColumnOperators.like()`

  `nullsfirst`()
    inherited from the `nullsfirst()` method of `ColumnOperators`

    Produce a `nullsfirst()` clause against the parent object.

  `nullslast`()
    inherited from the `nullslast()` method of `ColumnOperators`

    Produce a `nullslast()` clause against the parent object.

  `op`(opstring, precedence=0)
    inherited from the `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`.

    Parameters:

    - 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.

      New in version 0.8: - added the ‘precedence’ argument.

    See also

    Redefining and Creating New Operators

  `parent`

    Return an inspection instance representing the parent.

    This will be either an instance of `Mapper` or `AliasedInsp`, depending upon the nature of the parent entity which this attribute is associated with.

  `property`

    Return the `MapperProperty` associated with this `QueryableAttribute`.

    Return values here will commonly be instances of `ColumnProperty` or `RelationshipProperty`.

  `startswith`(other, **kwargs)
    inherited from the `startswith()` method of `ColumnOperators`

    Implement the `startwith` operator.

    In a column context, produces the clause `LIKE '<other>%'`