Runtime Inspection API¶
The inspection module provides the
which delivers runtime information about a wide variety
of SQLAlchemy objects, both within the Core as well as the
inspect() function is the entry point to SQLAlchemy’s
public API for viewing the configuration and construction
of in-memory objects. Depending on the type of object
inspect(), the return value will either be
a related object which provides a known interface, or in many
cases it will return the object itself.
The rationale for
inspect() is twofold. One is that
it replaces the need to be aware of a large variety of “information
getting” functions in SQLAlchemy, such as
and others. The other is that the return value of
is guaranteed to obey a documented API, thus allowing third party
tools which build on top of SQLAlchemy configurations to be constructed
in a forwards-compatible way.
Produce an inspection object for the given target.
The returned value in some cases may be the same object as the one given, such as if a
Mapperobject is passed. In other cases, it will be an instance of the registered inspection type for the given object, such as if an
engine.Engineis passed, an
Inspectorobject is returned.
subject – the subject to be inspected.
raiseerr – When
True, if the given subject does not correspond to a known SQLAlchemy inspected type,
sqlalchemy.exc.NoInspectionAvailableis raised. If
Available Inspection Targets¶
Below is a listing of many of the most common inspection targets.
object- an object given will be checked by the ORM for a mapping - if so, an
InstanceStateis returned representing the mapped state of the object. The
InstanceStatealso provides access to per attribute state via the
AttributeStateinterface as well as the per-flush “history” of any attribute via the
type(i.e. a class) - a class given will be checked by the ORM for a mapping - if so, a
Mapperfor that class is returned.
mapped attribute - passing a mapped attribute to
inspect(), such as
inspect(MyClass.some_attribute), returns a
QueryableAttributeobject, which is the descriptor associated with a mapped class. This descriptor refers to a
MapperProperty, which is usually an instance of
RelationshipProperty, via its