Runtime Inspection API — SQLAlchemy 0.9 Documentation

# SQLAlchemy 0.9 Documentation

Search:
Release: 0.9.0 | Release Date: December 30, 2013

# Runtime Inspection API

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.

New in version 0.8: The `inspect()` system is introduced as of version 0.8.

`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: | subject – the subject to be inspected. raiseerr – When `True`, if the given subject does not correspond to a known SQLAlchemy inspected type, `sqlalchemy.exc.NoInspectionAvailable` is 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, 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.
- mapped attribute - passing a mapped attribute to `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.