SQLAlchemy 0.7.0 Documentation

Version: 0.7.0 Last Updated: 05/20/2011 17:59:22

ORM Internals

Some key internal constructs are listed here.

class sqlalchemy.orm.instrumentation.ClassManager(class_)

Bases: dict

tracks state information at the class level.

__init__(class_)
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.

__init__(*columns, **kwargs)

Construct a ColumnProperty.

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
  • extension
class sqlalchemy.orm.descriptor_props.CompositeProperty(class_, *attrs, **kwargs)

Bases: sqlalchemy.orm.descriptor_props.DescriptorProperty

__init__(class_, *attrs, **kwargs)
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.

__init__(obj, manager)
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.

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(selectcontext, 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.expression.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 behaivor. 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
__init__(prop, mapper, adapter=None)
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.

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.

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

__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=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)
class sqlalchemy.orm.descriptor_props.SynonymProperty(name, map_column=None, descriptor=None, comparator_factory=None, doc=None)

Bases: sqlalchemy.orm.descriptor_props.DescriptorProperty

__init__(name, map_column=None, descriptor=None, comparator_factory=None, doc=None)
class sqlalchemy.orm.query.QueryContext(query)

Bases: object

__init__(query)
Previous: ORM Exceptions Next: SQLAlchemy Core