SQLAlchemy 2.1 Documentation
SQLAlchemy Core
- SQL Statements and Expressions API
- Schema Definition Language
- SQL Datatype Objects
- Engine and Connection Use
- Core API Basics
- Events
- Runtime Inspection API¶
- Core Exceptions
- Core Internals
Project Versions
- Previous: Events
- Next: Core Exceptions
- Up: Home
- On this page:
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()
(deprecated in 1.4),
instance_state()
, 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.
Object Name | Description |
---|---|
inspect(subject[, raiseerr]) |
Produce an inspection object for the given target. |
- function sqlalchemy.inspect(subject: Any, raiseerr: bool = True) → Any¶
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 anEngine
is passed, anInspector
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. IfFalse
,None
is returned.
Available Inspection Targets¶
Below is a listing of many of the most common inspection targets.
Connectable
(i.e.Engine
,Connection
) - returns anInspector
object.ClauseElement
- all SQL expression components, includingTable
,Column
, serve as their own inspection objects, meaning any of these objects passed toinspect()
return themselves.object
- an object given will be checked by the ORM for a mapping - if so, anInstanceState
is returned representing the mapped state of the object. TheInstanceState
also provides access to per attribute state via theAttributeState
interface as well as the per-flush “history” of any attribute via theHistory
object.See also
type
(i.e. a class) - a class given will be checked by the ORM for a mapping - if so, aMapper
for that class is returned.See also
mapped attribute - passing a mapped attribute to
inspect()
, such asinspect(MyClass.some_attribute)
, returns aQueryableAttribute
object, which is the descriptor associated with a mapped class. This descriptor refers to aMapperProperty
, which is usually an instance ofColumnProperty
orRelationshipProperty
, via itsQueryableAttribute.property
attribute.AliasedClass
- returns anAliasedInsp
object.
flambé! the dragon and The Alchemist image designs created and generously donated by Rotem Yaari.
Created using Sphinx 7.2.6. Documentation last generated: Fri 08 Nov 2024 08:32:22 AM EST