The inspection module provides the inspect() function,
which delivers runtime information about a wide variety
of SQLAlchemy objects, both within the Core as well as the
ORM.
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
passed to 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 Inspector.from_engine(),
orm.attributes.instance_state(), orm.class_mapper(),
and others. The other is that the return value of inspect()
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.
sqlalchemy.inspection.inspect(subject, raiseerr=True)¶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
Mapper object is passed. In other
cases, it will be an instance of the registered
inspection type for the given object, such as
if an engine.Engine is passed, an
Inspector object is returned.
| Parameters: |
|
|---|
Below is a listing of many of the most common inspection targets.
Connectable (i.e. Engine,
Connection) - returns an Inspector object.ClauseElement - all SQL expression components, including
Table, Column, serve as their own inspection objects,
meaning any of these objects passed to inspect() return themselves.object - an object given will be checked by the ORM for a mapping -
if so, an InstanceState is returned representing the mapped
state of the object. The InstanceState also provides access
to per attribute state via the AttributeState interface as well
as the per-flush “history” of any attribute via the History
object.type (i.e. a class) - a class given will be checked by the ORM for a
mapping - if so, a Mapper for that class is returned.inspect(), such
as inspect(MyClass.some_attribute), returns a QueryableAttribute
object, which is the descriptor associated with a mapped class.
This descriptor refers to a MapperProperty, which is usually
an instance of ColumnProperty
or RelationshipProperty, via its QueryableAttribute.property
attribute.AliasedClass - returns an AliasedInsp object.