Alternate Class Instrumentation

Extensible class instrumentation.

The sqlalchemy.ext.instrumentation package provides for alternatesystems of class instrumentation within the ORM. Class instrumentationrefers to how the ORM places attributes on the class which maintaindata and track changes to that data, as well as event hooks installedon the class.

Note

The extension package is provided for the benefit of integrationwith other object management packages, which already performtheir own instrumentation. It is not intended for general use.

For examples of how the instrumentation extension is used,see the example Attribute Instrumentation.

API Reference

  • sqlalchemy.ext.instrumentation.INSTRUMENTATIONMANAGER = 'sa_instrumentation_manager'_
  • Attribute, elects custom instrumentation when present on a mapped class.

Allows a class to specify a slightly or wildly different technique fortracking changes made to mapped attributes and collections.

Only one instrumentation implementation is allowed in a given objectinheritance hierarchy.

The value of this attribute must be a callable and will be passed a classobject. The callable must return one of:

  • An instance of an InstrumentationManager or subclass

  • An object implementing all or some of InstrumentationManager (TODO)

  • A dictionary of callables, implementing all or some of the above (TODO)

  • An instance of a ClassManager or subclass

This attribute is consulted by SQLAlchemy instrumentationresolution, once the sqlalchemy.ext.instrumentation modulehas been imported. If custom finders are installed in the globalinstrumentation_finders list, they may or may not choose to honor thisattribute.

  • class sqlalchemy.orm.instrumentation.InstrumentationFactory

  • Factory for new ClassManager instances.

  • class sqlalchemy.ext.instrumentation.InstrumentationManager(class_)

  • User-defined class instrumentation extension.

InstrumentationManager can be subclassed in orderto changehow class instrumentation proceeds. This class exists forthe purposes of integration with other object managementframeworks which would like to entirely modify theinstrumentation methodology of the ORM, and is not intendedfor regular usage. For interception of class instrumentationevents, see InstrumentationEvents.

The API for this class should be considered as semi-stable,and may change slightly with new releases.

  • dictgetter(class)
  • dispose(class__, _manager)
  • getinstancedict(class, _instance)
  • initializeinstancedict(class, _instance)
  • installdescriptor(class_, _key, inst)
  • installmember(class_, _key, implementation)
  • installstate(class_, _instance, state)
  • instrumentattribute(class_, _key, inst)
  • instrumentcollectionclass(class, _key, collection_class)
  • manage(class__, _manager)
  • managergetter(class)
  • postconfigureattribute(class, _key, inst)
  • removestate(class_, _instance)
  • stategetter(class)
  • uninstalldescriptor(class_, _key)
  • uninstallmember(class_, _key)
    • sqlalchemy.ext.instrumentation.instrumentationfinders = []_
    • An extensible sequence of callables which return instrumentationimplementations

When a class is registered, each callable will be passed a class object.If None is returned, thenext finder in the sequence is consulted. Otherwise the return must be aninstrumentation factory that follows the same guidelines assqlalchemy.ext.instrumentation.INSTRUMENTATION_MANAGER.

By default, the only finder is find_native_user_instrumentation_hook, whichsearches for INSTRUMENTATION_MANAGER. If all finders return None, standardClassManager instrumentation is used.

Extends InstrumentationFactory with additionalbookkeeping, to accommodate multiple types ofclass managers.