Runtime Inspection API

The inspection module provides the inspect() function,which delivers runtime information about a wide varietyof SQLAlchemy objects, both within the Core as well as theORM.

The inspect() function is the entry point to SQLAlchemy’spublic API for viewing the configuration and constructionof in-memory objects. Depending on the type of objectpassed to inspect(), the return value will either bea related object which provides a known interface, or in manycases it will return the object itself.

The rationale for inspect() is twofold. One is thatit replaces the need to be aware of a large variety of “informationgetting” 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 partytools which build on top of SQLAlchemy configurations to be constructedin 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 thesame object as the one given, such as if aMapper object is passed. In othercases, it will be an instance of the registeredinspection type for the given object, such asif an engine.Engine is passed, anInspector object is returned.

• Parameters

• • subject – the subject to be inspected.

  • raiseerr – When True, if the given subjectdoes notcorrespond to a known SQLAlchemy inspected type,sqlalchemy.exc.NoInspectionAvailableis raised. If False, None is returned.

Available Inspection Targets

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, includingTable, 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 mappedstate of the object. The InstanceState also provides accessto per attribute state via the AttributeState interface as wellas the per-flush “history” of any attribute via the Historyobject.

• type (i.e. a class) - a class given will be checked by the ORM for amapping - if so, a Mapper for that class is returned.

• mapped attribute - passing a mapped attribute to inspect(), suchas inspect(MyClass.some_attribute), returns a QueryableAttributeobject, which is the descriptor associated with a mapped class.This descriptor refers to a MapperProperty, which is usuallyan instance of ColumnPropertyor RelationshipProperty, via its QueryableAttribute.propertyattribute.

• AliasedClass - returns an AliasedInsp object.