运行时审查 API¶
Runtime Inspection API
inspection 模块提供了 inspect()
函数,用于在运行时获取 SQLAlchemy 各类对象的信息,适用于 Core 与 ORM 两个层面。
inspect()
是 SQLAlchemy 公共 API 中用于查看内存中对象配置与构造信息的入口函数。根据传入对象的类型,inspect()
会返回一个相关对象,该对象提供一个已知的接口;在许多情况下,也可能直接返回传入的对象本身。
设计 inspect()
的初衷有两个方面:一是为了替代需要记住大量“信息获取”函数的情况,例如 from_engine`(在 1.4 中已弃用)、:func:()
.orm.attributes.instance_state`、class_mapper()
等。二是因为 inspect()
的返回值会遵循一个已记录的 API 规范,这使得构建在 SQLAlchemy 配置之上的第三方工具可以以向前兼容的方式进行开发。
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.- 参数:
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
以下是许多最常见的检查目标列表。
Connectable
(即Engine
,Connection
) - 返回Inspector
对象。ClauseElement
- 所有SQL表达式组件,包括Table
,Column
,作为它们自己的检查对象,这意味着传递给inspect()
的任何这些对象都会返回它们自己。object
- 给定的对象将由ORM检查其映射 - 如果是,则返回表示对象的映射状态的InstanceState
。InstanceState
还通过AttributeState
接口提供对每个属性状态的访问,以及通过History
对象提供任何属性的每次刷新“历史”。参见
type
(即类) - 给定的类将由ORM检查其映射 - 如果是,则返回该类的Mapper
。参见
已映射的属性 - 将已映射的属性传递给
inspect()
,例如inspect(MyClass.some_attribute)
,返回QueryableAttribute
对象,这是与已映射类关联的 描述符。此描述符通过其QueryableAttribute.property
属性引用MapperProperty
,通常是ColumnProperty
或RelationshipProperty
的实例。AliasedClass
- 返回AliasedInsp
对象。
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.参见
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.参见
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.