SqlAlchemy 2.0 中文文档（二十七）（1）

原文：docs.sqlalchemy.org/en/20/contents.html

ORM 内部

原文：docs.sqlalchemy.org/en/20/orm/internals.html

重要的 ORM 构造，其他部分未涵盖，列在此处。

class sqlalchemy.orm.AttributeState

为特定映射对象上的特定属性提供相应的检查接口。

AttributeState对象通过特定InstanceState的InstanceState.attrs集合访问：

成员

history, load_history(), loaded_value, value

from sqlalchemy import inspect
insp = inspect(some_mapped_object)
attr_state = insp.attrs.some_attribute

attribute history

返回此属性的当前预刷新更改历史记录，通过History接口。

如果属性的值未加载，则此方法不会发出加载器可调用。

注意

属性历史系统会每次刷新基础上跟踪更改。每次刷新Session时，每个属性的历史记录都会被重置为空。Session默认情况下会在每次调用Query时自动刷新。有关如何控制此行为的选项，请参见刷新。

另请参阅

AttributeState.load_history() - 如果值未在本地存在，则使用加载器可调用检索历史。

get_history() - 底层函数

method load_history() → History

返回此属性的当前预刷新更改历史记录，通过History接口。

如果属性的值未加载，则此方法会发出加载器可调用。

注意

属性历史系统会每次刷新基础上跟踪更改。每次刷新Session时，每个属性的历史记录都会被重置为空。Session默认情况下会在每次调用Query时自动刷新。有关如何控制此行为的选项，请参见刷新。

另请参阅

AttributeState.history

get_history() - 底层函数

attribute loaded_value

从数据库加载的当前属性值。

如果值尚未加载，或者在对象的字典中不存在，则返回 NO_VALUE。

attribute value

返回此属性的值。

此操作相当于直接访问对象的属性或通过 getattr() 访问，并在需要时触发任何挂起的加载器可调用。

class sqlalchemy.orm.CascadeOptions

跟踪发送到 relationship.cascade 的选项。

类签名

类 sqlalchemy.orm.CascadeOptions (builtins.frozenset, typing.Generic)

class sqlalchemy.orm.ClassManager

在类级别跟踪状态信息。

成员

deferred_scalar_loader, expired_attribute_loader, has_parent(), manage(), state_getter(), unregister()

类签名

类 sqlalchemy.orm.ClassManager (sqlalchemy.util.langhelpers.HasMemoized, builtins.dict, typing.Generic, sqlalchemy.event.registry.EventTarget)

attribute deferred_scalar_loader

从版本 1.4 开始已弃用：ClassManager.deferred_scalar_loader 属性现在命名为 expired_attribute_loader

attribute expired_attribute_loader: _ExpiredAttributeLoaderProto

以前称为 deferred_scalar_loader

method has_parent(state: InstanceState[_O], key: str, optimistic: bool = False) → bool

待办事项

method manage()

将此实例标记为其类的管理器。

method state_getter()

返回一个 (实例) -> InstanceState 可调用。

如果找不到实例的 InstanceState，“state getter” 可调用应引发 KeyError 或 AttributeError。

method unregister() → None

删除此 ClassManager 建立的所有检测工具。

class sqlalchemy.orm.ColumnProperty

描述对应于表列或其他列表达式的对象属性。

公共构造函数是 column_property() 函数。

成员

expressions, operate(), reverse_operate(), columns_to_assign,  declarative_scan(), do_init(), expression, instrument_class(),  mapper_property_to_assign, merge()

类签名

类sqlalchemy.orm.ColumnProperty（sqlalchemy.orm._MapsColumns，sqlalchemy.orm.StrategizedProperty，sqlalchemy.orm._IntrospectsAnnotations，sqlalchemy.log.Identified）

class Comparator

为ColumnProperty属性生成布尔值、比较和其他操作符。

请参阅PropComparator的文档以获取简要概述。

另请参见

PropComparator

ColumnOperators

重新定义和创建新操作符

TypeEngine.comparator_factory

类签名

类sqlalchemy.orm.ColumnProperty.Comparator（sqlalchemy.util.langhelpers.MemoizedSlots，sqlalchemy.orm.PropComparator）

attribute expressions: Sequence[NamedColumn[Any]]

由此引用的列的完整序列

属性，根据正在进行的任何别名调整。

版本 1.3.17 中的新功能。

另请参见

将类映射到多个表 - 用法示例

method operate(op: OperatorType, *other: Any, **kwargs: Any) → ColumnElement[Any]

对参数执行操作。

这是操作的最低级别，默认情况下引发NotImplementedError。

在子类上重写这个方法可以使通用行为应用于所有操作。例如，重写ColumnOperators以将func.lower()应用于左右两侧：

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 操作符可调用。
  
• *other – 操作的‘other’一侧。对于大多数操作，将是单个标量。
  
• **kwargs – 修饰符。这些可以通过特殊操作符（如ColumnOperators.contains()）传递。
  

method reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → ColumnElement[Any]

对参数执行反向操作。

用法与operate()相同。

attribute columns_to_assign

method declarative_scan(decl_scan: _ClassScanMapperConfig, registry: _RegistryType, cls: Type[Any], originating_module: str | None, key: str, mapped_container: Type[Mapped[Any]] | None, annotation: _AnnotationScanType | None, extracted_mapped_annotation: _AnnotationScanType | None, is_dataclass_field: bool) → None

在早期声明扫描时执行类特定的初始化。

版本 2.0 中的新功能。

method do_init() → None

在映射创建后执行子类特定的初始化步骤。

这是由MapperProperty对象的 init()方法调用的模板方法。

attribute expression

返回此 ColumnProperty 的主列或表达式。

例如：

class File(Base):
    # ...
    name = Column(String(64))
    extension = Column(String(8))
    filename = column_property(name + '.' + extension)
    path = column_property('C:/' + filename.expression)

另请参见

在映射时从列属性组合

method instrument_class(mapper: Mapper[Any]) → None

Mapper 调用的钩子，用于初始化由此 MapperProperty 管理的类属性的仪器化。

里的MapperProperty通常会调用属性模块以设置InstrumentedAttribute。

这一步是设置InstrumentedAttribute的两个步骤中的第一步，并且在映射器设置过程的早期调用。

第二步通常是init_class_attribute步骤，通过StrategizedProperty通过post_instrument_class()钩子调用。此步骤为InstrumentedAttribute分配附加状态（特别是“impl”），该状态在MapperProperty确定需要执行什么类型的持久性管理后确定（例如标量，对象，集合等）。

attribute mapper_property_to_assign

method merge(session: Session, source_state: InstanceState[Any], source_dict: _InstanceDict, dest_state: InstanceState[Any], dest_dict: _InstanceDict, load: bool, _recursive: Dict[Any, object], _resolve_conflict_map: Dict[_IdentityKeyType[Any], object]) → None

将此MapperProperty表示的属性从源对象合并到目标对象。

class sqlalchemy.orm.Composite

与CompositeProperty类兼容的声明性前端。

公共构造函数是composite()函数。

在 2.0 版本中更改：将Composite添加为CompositeProperty的声明兼容子类。

另请参见

复合列类型

类签名

类sqlalchemy.orm.Composite（sqlalchemy.orm.descriptor_props.CompositeProperty，sqlalchemy.orm.base._DeclarativeMapped）

class sqlalchemy.orm.CompositeProperty

定义一个“复合”映射属性，表示一组列作为一个属性。

CompositeProperty是使用composite()函数构建的。

另请参见

复合列类型

成员

create_row_processor()，columns_to_assign，declarative_scan()，do_init()，get_history()，instrument_class()，mapper_property_to_assign

类签名

类sqlalchemy.orm.CompositeProperty（sqlalchemy.orm._MapsColumns，sqlalchemy.orm._IntrospectsAnnotations，sqlalchemy.orm.descriptor_props.DescriptorProperty）

class Comparator

为Composite属性生成布尔值，比较和其他运算符。

请参见 Redefining Comparison Operations for Composites 中的示例，以了解用法概述，以及PropComparator的文档。

请参见

PropComparator

ColumnOperators

重新定义和创建新的操作符

TypeEngine.comparator_factory

类签名

类sqlalchemy.orm.CompositeProperty.Comparator（sqlalchemy.orm.PropComparator）

class CompositeBundle

类签名

类sqlalchemy.orm.CompositeProperty.CompositeBundle（sqlalchemy.orm.Bundle）

method create_row_processor(query: Select[Any], procs: Sequence[Callable[[Row[Any]], Any]], labels: Sequence[str]) → Callable[[Row[Any]], Any]

为此Bundle生成“行处理”函数。

可以被子类重写以在提取结果时提供自定义行为。该方法在查询执行时传递了语句对象和一组“行处理”函数；当给定一个结果行时，这些处理函数将返回单个属性值，然后可以将其调整为任何类型的返回数据结构。

下面的示例说明了将通常的Row返回结构替换为直接的 Python 字典：

from sqlalchemy.orm import Bundle
class DictBundle(Bundle):
    def create_row_processor(self, query, procs, labels):
        'Override create_row_processor to return values as
        dictionaries'
        def proc(row):
            return dict(
                zip(labels, (proc(row) for proc in procs))
            )
        return proc

上述Bundle的结果将返回字典值：

bn = DictBundle('mybundle', MyClass.data1, MyClass.data2)
for row in session.execute(select(bn)).where(bn.c.data1 == 'd1'):
    print(row.mybundle['data1'], row.mybundle['data2'])

attribute columns_to_assign

method declarative_scan(decl_scan: _ClassScanMapperConfig, registry: _RegistryType, cls: Type[Any], originating_module: str | None, key: str, mapped_container: Type[Mapped[Any]] | None, annotation: _AnnotationScanType | None, extracted_mapped_annotation: _AnnotationScanType | None, is_dataclass_field: bool) → None

在早期的声明扫描时执行类特定的初始化。

自 2.0 版开始。

method do_init() → None

在Composite与其父 Mapper 关联之后发生的初始化。

method get_history(state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = symbol('PASSIVE_OFF')) → History

为使用attributes.get_history()的用户代码提供。

method instrument_class(mapper: Mapper[Any]) → None

由 Mapper 调用的钩子，用于启动由此 MapperProperty 管理的类属性的检测。

这里的 MapperProperty 通常会调用 attributes 模块来设置一个 InstrumentedAttribute。

这一步是设置 InstrumentedAttribute 的两个步骤中的第一个步骤，并且在 Mapper 设置过程中的早期阶段调用。

第二步通常是 init_class_attribute 步骤，通过 post_instrument_class()钩子从  StrategizedProperty 调用。此步骤为 InstrumentedAttribute  分配了附加状态（特别是“impl”），该状态在 MapperProperty 确定需要执行什么类型的持久性管理之后确定。

attribute mapper_property_to_assign

class sqlalchemy.orm.AttributeEventToken

在一系列属性事件中传播的令牌。

用作事件源的指示器，还提供了一种控制在一系列属性操作中传播的方法。

处理事件时，Event对象作为initiator参数发送，例如处理AttributeEvents.append()、AttributeEvents.set()和AttributeEvents.remove()等事件。

Event对象当前由反向引用事件处理程序解释，并用于控制操作在两个相互依赖属性之间的传播。

从版本 2.0 开始更改：将名称从AttributeEvent更改为AttributeEventToken。

属性实现：

当前事件发起者的AttributeImpl。

属性操作：

符号OP_APPEND、OP_REMOVE、OP_REPLACE或OP_BULK_REPLACE，指示源操作。

class sqlalchemy.orm.IdentityMap

成员

check_modified()

method check_modified() → bool

如果存在任何已标记为“修改”的 InstanceState，则返回 True。

class sqlalchemy.orm.InspectionAttr

应用于所有与可以由inspect()函数返回的对象相关的 ORM 对象和属性的基类。

此处定义的属性允许使用简单的布尔检查来测试有关返回对象的基本事实。

成员

extension_type, is_aliased_class, is_attribute, is_bundle, is_clause_element, is_instance, is_mapper, is_property, is_selectable

虽然这里的布尔检查基本上与使用 Python 的 isinstance()函数相同，但这里的标志可以在不需要导入所有这些类的情况下使用，并且 SQLAlchemy 类系统可以更改，同时保持这里的标志不变以实现向前兼容性。

attribute extension_type: InspectionAttrExtensionType = 'not_extension'

扩展类型，如果有的话。默认为NotExtension.NOT_EXTENSION。

另请参阅

HybridExtensionType

AssociationProxyExtensionType

attribute is_aliased_class = False

如果此对象是AliasedClass的实例，则返回 True。

attribute is_attribute = False

如果此对象是 Python 的描述符的实例，则返回 True。

这可以指代许多类型之一。通常是一个QueryableAttribute，它代表一个MapperProperty处理属性事件。但也可以是一个扩展类型，如AssociationProxy或hybrid_property。InspectionAttr.extension_type将指代一个标识特定子类型的常量。

另请参阅

Mapper.all_orm_descriptors

attribute is_bundle = False

如果此对象是Bundle的实例，则返回 True。

attribute is_clause_element = False

如果此对象是ClauseElement的实例，则返回 True。

attribute is_instance = False

如果此对象是InstanceState的实例，则返回 True。

attribute is_mapper = False

如果此对象是Mapper的实例，则返回 True。

attribute is_property = False

如果此对象是MapperProperty的实例，则返回 True。

attribute is_selectable = False

如果此对象是Selectable的实例，则返回 True。

class sqlalchemy.orm.InspectionAttrInfo

将.info属性添加到InspectionAttr。

InspectionAttr与InspectionAttrInfo之间的理由是前者兼容作为指定__slots__的类的 mixin；这本质上是一种实现工件。

成员

info

类签名

类 sqlalchemy.orm.InspectionAttrInfo（sqlalchemy.orm.base.InspectionAttr）

attribute info

与对象关联的信息字典，允许将用户定义的数据与此 InspectionAttr 关联。

字典在首次访问时生成。或者，它可以作为构造函数参数指定给 column_property()、relationship() 或 composite() 函数。

另请参阅

QueryableAttribute.info

SchemaItem.info

class sqlalchemy.orm.InstanceState

在实例级别跟踪状态信息。

InstanceState 是 SQLAlchemy ORM 中用于跟踪对象状态的关键对象；它在对象实例化时创建，通常是作为 SQLAlchemy 应用于类的 __init__() 方法的 instrumentation 的结果。

InstanceState 也是一个半公开对象，可用于运行时检查映射实例的状态，包括其在特定 Session 中的当前状态以及有关各个属性的数据的详细信息。获取 InstanceState 对象的公共 API 是使用 inspect() 系统：

>>> from sqlalchemy import inspect
>>> insp = inspect(some_mapped_object)
>>> insp.attrs.nickname.history
History(added=['new nickname'], unchanged=(), deleted=['nickname'])

另请参阅

映射实例的检查

成员

async_session, attrs, callables, deleted, detached, dict,  expired_attributes, has_identity, identity, identity_key, is_instance,  mapper, object, pending, persistent, session, transient, unloaded,  unloaded_expirable, unmodified, unmodified_intersection(), was_deleted

类签名

类 sqlalchemy.orm.InstanceState (sqlalchemy.orm.base.InspectionAttrInfo, typing.Generic)

attribute async_session

返回此实例的拥有 AsyncSession，如果没有可用，则返回 None。

仅当此 ORM 对象使用 sqlalchemy.ext.asyncio API 时，此属性才不为 None。返回的 AsyncSession 对象将是一个代理，用于表示此 InstanceState 的 InstanceState.session 属性将返回的 Session 对象。

版本 1.4.18 中的新功能。

另请参阅

异步 I/O（asyncio）

attribute attrs

返回一个表示映射对象上每个属性的命名空间，包括其当前值和历史记录。

返回的对象是 AttributeState 的实例。此对象允许检查属性内的当前数据以及自上次刷新以来的属性历史记录。

attribute callables: Dict[str, Callable[[InstanceState[_O], PassiveFlag], Any]] = {}

可以关联每个状态加载器可调用的命名空间。

在 SQLAlchemy 1.0 中，这仅用于通过查询选项设置的延迟加载器/延迟加载器。

以前，可调用函数还用于通过在此字典中存储与 InstanceState 本身的链接来指示过期属性。现在，这个角色由 expired_attributes 集合处理。

attribute deleted

如果对象已被删除，则返回True。

处于删除状态的对象保证不在其父Session的Session.identity_map 中；但是如果会话的事务被回滚，对象将被恢复到持久状态和标识映射。

注意

InstanceState.deleted 属性指的是对象在“持久”状态和“分离”状态之间发生的特定状态；一旦对象被分离，InstanceState.deleted 属性不再返回 True；为了检测状态是否已删除，无论对象是否与Session相关联，都可以使用InstanceState.was_deleted 访问器。

另请参见

对象状态简介

attribute detached

如果对象是分离，则返回True。

另请参见

对象状态简介

attribute dict

返回对象使用的实例字典。

在正常情况下，这通常与映射对象的__dict__属性同义，除非已配置了替代的仪器系统。

如果实际对象已经被垃圾回收，此访问器将返回一个空字典。

attribute expired_attributes: Set[str]

由管理器的延迟标量加载器加载的‘过期’键集合，假设没有挂起的更改。

还请参见在刷新操作发生时与此集合相交的unmodified集合。

attribute has_identity

如果此对象具有标识键，则返回True。

这应始终具有与表达式 state.persistent 或 state.detached 相同的值。

attribute identity

返回映射对象的映射标识。这是 ORM 持久化的主键标识，始终可以直接传递给Query.get()。

如果对象没有主键标识，则返回None。

注意

对象在刷新之前是瞬态或挂起的情况下，没有映射的标识，即使其属性包括主键值。

attribute identity_key

返回映射对象的标识键。

这是用于在Session.identity_map映射中定位对象的键。它包含由identity返回的标识。

attribute is_instance: bool = True

如果此对象是InstanceState的实例，则返回True。

attribute mapper

返回用于此映射对象的Mapper。

attribute object

返回由此InstanceState表示的映射对象。

如果对象已被垃圾收集，则返回None。

attribute pending

如果对象是挂起的，则返回True。

另请参阅

对象状态简介

attribute persistent

如果对象是持久的，则返回True。

处于持久状态的对象保证位于其父Session的Session.identity_map中。

另请参阅

对象状态简介

attribute session

返回此实例的拥有Session，如果没有可用的则返回None。

注意，此处的结果在某些情况下可能与obj in session的结果不同；已删除的对象将报告为不在session中，但是如果事务仍在进行中，则此属性仍将指向该会话。通常情况下，只有在事务完成时，对象才会完全分离。

另请参阅

InstanceState.async_session

attribute transient

如果对象是瞬时的，则返回True。

另请参阅

对象状态简介

attribute unloaded

返回不具有加载值的键的集合。

这包括已过期的属性和任何未填充或未修改的属性。

attribute unloaded_expirable

与InstanceState.unloaded同义。

自版本 2.0 起已弃用：InstanceState.unloaded_expirable属性已弃用。请使用InstanceState.unloaded。

此属性在某个时候添加为实现特定的细节，并且应被视为私有。

attribute unmodified

返回没有未提交更改的键的集合。

method unmodified_intersection(keys: Iterable[str]) → Set[str]

返回 self.unmodified.intersection(keys)。

attribute was_deleted

如果此对象处于“已删除”状态或先前处于“已删除”状态，并且未恢复为持久状态，则返回 True。

该标志一旦对象在刷新时被删除就会返回 True。当对象被从会话中显式地删除或通过事务提交并进入“分离”状态时，此标志将继续报告 True。

请参阅

InstanceState.deleted - 指的是“已删除”状态

was_deleted() - 独立函数

对象状态简介

class sqlalchemy.orm.InstrumentedAttribute

用于代表MapperProperty对象拦截属性事件的描述符对象的基类。实际的MapperProperty可通过QueryableAttribute.property属性访问。

请参阅

InstrumentedAttribute

MapperProperty

Mapper.all_orm_descriptors

Mapper.attrs

SqlAlchemy 2.0 中文文档（二十七）（2）https://developer.aliyun.com/article/1560498