Defines SQLAlchemy's system of class instrumentation..
This module is usually not directly visible to user applications, but defines a large part of the ORM's interactivity.
SQLA's instrumentation system is completely customizable, in which case an understanding of the general mechanics of this module is helpful. An example of full customization is in /examples/custom_attributes.
Return a collection of factories in play or specified for a hierarchy.
Traverses the entire inheritance graph of a cls and returns a collection of instrumentation factories for those classes. Factories are extracted from active ClassManagers, if available, otherwise instrumentation_finders is consulted.
Find user-specified instrumentation management for a class.
Initialize a collection attribute and return the collection adapter.
Create an InstrumentedAttribute / user descriptor hybrid.
Returns a new InstrumentedAttribute type that delegates descriptor behavior and getattr() to the given descriptor.
internal implementation for instrumented attributes.
Construct an AttributeImpl.
Retrieve a value from the given object.
If a callable is assembled on this object's attribute, and passive is False, the callable will be executed and the resulting value will be set as the new value for this attribute.
Return the boolean value of a hasparent flag attached to the given item.
The optimistic flag determines what the default return value should be if no hasparent flag can be located.
As this function is used to determine if an instance is an orphan, instances that were loaded from storage should be assumed to not be orphans, until a True/False value for this flag is set.
An instance attribute that is loaded by a callable function will also not have a hasparent flag.
Initialize this attribute on the given object instance with an empty value.
Set a callable function for this attribute on the given object.
This callable will be executed when the attribute is next accessed, and is assumed to construct part of the instances previously stored state. When its value or values are loaded, they will be established as part of the instance's committed state. While trackparent information will be assembled for these instances, attribute-level event handlers will not be fired.
The callable overrides the class level callable set in the InstrumentedAttribute constructor.
set an attribute value on the given instance and 'commit' it.
Set a boolean flag on the given item corresponding to whether or not it is attached to a parent object via the attribute represented by this InstrumentedAttribute.
tracks state information at the class level.
Apply a scalar loader to the given state.
Unimplemented by default, is patched by the mapper.
Return a (instance) -> InstanceState callable.
"state getter" callables should raise either KeyError or AttributeError if no InstanceState could be found for the instance.
A collection-holding attribute that instruments changes in membership.
Only handles collections of instrumented objects.
InstrumentedCollectionAttribute holds an arbitrary, user-specified container object (defaulting to a list) and brokers access to the CollectionAdapter, a "view" onto that object that presents consistent bag semantics to the orm layer independent of the user data implementation.
Construct a new CollectionAttributeImpl.
Retrieve the CollectionAdapter associated with the given state.
Creates a new CollectionAdapter if one does not exist.
Set a value on the given object.
initiator is the InstrumentedAttribute that initiated the set() operation and is used to control the depth of a circular setter operation.
Set an attribute value on the given instance and 'commit' it.
An extension which synchronizes a two-way relationship.
A typical two-way relationship is a parent object containing a list of child objects, where each child object references the parent. The other are two objects which contain scalar references to each other.
A 3-tuple of added, unchanged and deleted values.
Each tuple member is an iterable sequence.
itemgetter(item, ...) --> itemgetter object
Return a callable object that fetches the given item(s) from its operand. After, f=itemgetter(2), the call f(r) returns r[2]. After, g=itemgetter(2,5,3), the call g(r) returns (r[2], r[5], r[3])
itemgetter(item, ...) --> itemgetter object
Return a callable object that fetches the given item(s) from its operand. After, f=itemgetter(2), the call f(r) returns r[2]. After, g=itemgetter(2,5,3), the call g(r) returns (r[2], r[5], r[3])
itemgetter(item, ...) --> itemgetter object
Return a callable object that fetches the given item(s) from its operand. After, f=itemgetter(2), the call f(r) returns r[2]. After, g=itemgetter(2,5,3), the call g(r) returns (r[2], r[5], r[3])
tracks state information at the instance level.
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 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 are removed.
Attributes marked as "expired" can potentially remain "expired" after this step if a value was not populated in state.dict.
a set of keys which do not have a loaded value.
This includes expired attributes and any other attribute that was never populated or modified.
return an InstanceState attribute as a list, regardless of it being a scalar or collection-based attribute.
returns None if passive is not PASSIVE_OFF and the getter returns PASSIVE_NORESULT.
__call__ allows the InstanceState to act as a deferred callable for loading expired attributes, which is also serializable (picklable).
Private instrumentation registration singleton.
Public-facing descriptor, placed in the mapped class dictionary.
represents a scalar value-holding InstrumentedAttribute, which can detect changes within the value itself.
Construct a new MutableScalarAttributeImpl.
A writable placeholder for an unloaded collection.
Stores items appended to and removed from a collection that has not yet been loaded. When the collection is loaded, the changes stored in PendingCollection are applied to it to produce the final result.
Construct an InstrumentedAttribute.
represents a scalar value-holding InstrumentedAttribute.
represents a scalar-holding InstrumentedAttribute, where the target object is also instrumented.
Adds events to delete/set operations.
Construct a new ScalarObjectAttributeImpl.
Set a value on the given InstanceState.
initiator is the InstrumentedAttribute that initiated the set() operation and is used to control the depth of a circular setter operation.
attrgetter(attr, ...) --> attrgetter object
Return a callable object that fetches the given attribute(s) from its operand. After, f=attrgetter('name'), the call f(r) returns r.name. After, g=attrgetter('name', 'date'), the call g(r) returns (r.name, r.date).
itemgetter(item, ...) --> itemgetter object
Return a callable object that fetches the given item(s) from its operand. After, f=itemgetter(2), the call f(r) returns r[2]. After, g=itemgetter(2,5,3), the call g(r) returns (r[2], r[5], r[3])