# SQLAlchemy 0.7 Documentation

Search:
Release: 0.7.10 | Release Date: February 7, 2013

# ORM Internals

Some key internal constructs are listed here.

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

  Bases: `dict`

  tracks state information at the class level.

  `dispose`()

    Dissasociate this manager from its class.

  `has_parent`(state, key, optimistic=False)

    TODO

  `manage`()

    Mark this instance as the manager for its class.

  `original_init`

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

  `state_getter`()

    Return a (instance) -> InstanceState callable.

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

  `unregister`()

    remove all instrumentation established by this ClassManager.

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.

  `__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 –

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

  Bases: `sqlalchemy.orm.descriptor_props.DescriptorProperty`

  `do_init`()

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

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

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

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

  Bases: `object`

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

  `commit`(dict_, keys)

    Commit attributes.

    This is used by a partial-attribute load operation to mark committed those attributes which were refreshed from the database.

    Attributes marked as “expired” can potentially remain “expired” after this step if a value was not populated in state.dict.

  `commit_all`(dict_, instance_dict=None)

    commit all attributes unconditionally.

    This is used after a flush() or a full load/refresh to remove all pending state from the instance.

    > - all attributes are marked as “committed”
    > - the “strong dirty reference” is removed
    > - the “modified” flag is set to False
    > - any “expired” markers/callables for attributes loaded are removed.

    Attributes marked as “expired” can potentially remain “expired” after this step if a value was not populated in state.dict.

  `expire_attribute_pre_commit`(dict_, key)

    a fast expire that can be called by column loaders during a load.

    The additional bookkeeping is finished up in commit_all().

    This method is actually called a lot with joined-table loading, when the second table isn’t present in the result.

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

  `initialize`(key)

    Set this attribute to an empty value or collection, based on the AttributeImpl in use.

  `reset`(dict_, key)

    Remove the given attribute and any callables associated with it.

  `set_callable`(dict_, key, callable_)

    Remove the given attribute and set the given callable as a loader.

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

  `value_as_iterable`(dict_, key, passive=<symbol 'PASSIVE_OFF>)

    Return a list of tuples (state, obj) for the given key.

    returns an empty list if the value is None/empty/PASSIVE_NO_RESULT

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

  Bases: `object`

  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` = ()

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

  `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, reduced_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.

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

  Bases: `sqlalchemy.sql.operators.ColumnOperators`

  Defines comparison operations for MapperProperty objects.

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

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

      class MyColumnComparator(ColumnProperty.Comparator):
          pass

      class MyCompositeComparator(CompositeProperty.Comparator):
          pass

      class MyRelationshipComparator(RelationshipProperty.Comparator):
          pass

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

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

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

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)

  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.

  Of note here is the `RelationshipProperty.Comparator` class, which implements comparison operations for scalar- and collection-referencing mapped attributes.

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

    Bases: `sqlalchemy.orm.interfaces.PropComparator`

    Produce comparison operations for `relationship()`-based attributes.

    `__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, mapper, of_type=None, adapter=None)

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

    `__ne__`(other)

      Implement the `!=` operator.

      In a many-to-one context, such as:

          MyClass.some_prop != <some object>

      This will typically produce a clause such as:

          mytable.related_id != <some id>

      Where `<some id>` is the primary key of the given object.

      The `!=` operator provides partial functionality for non- many-to-one comparisons:

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

    `contains`(other, **kwargs)

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

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

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

          MyClass.contains(other)

      Produces a clause like:

          mytable.id == <some id>

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

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

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

      Produces a query like:

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

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

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

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

      An expression like:

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

      Will produce a query like:

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

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

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

    `in_`(other)

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

    `of_type`(cls)

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

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

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

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

  Bases: `object`