SqlAlchemy 2.0 中文文档（二十七）（1）https://developer.aliyun.com/article/1560492
类签名
class sqlalchemy.orm.InstrumentedAttribute (sqlalchemy.orm.QueryableAttribute)
class sqlalchemy.orm.LoaderCallableStatus
一个枚举。
成员
ATTR_EMPTY, ATTR_WAS_SET, NEVER_SET, NO_VALUE, PASSIVE_CLASS_MISMATCH, PASSIVE_NO_RESULT
类签名
class sqlalchemy.orm.LoaderCallableStatus (enum.Enum)
attribute ATTR_EMPTY = 3
用于内部表示属性没有可调用。
attribute ATTR_WAS_SET = 2
由加载器可调用返回的符号，表示检索到的值或值已分配给目标对象上的属性。
attribute NEVER_SET = 4
与 NO_VALUE 同义
从 1.4 版本开始更改：NEVER_SET 已与 NO_VALUE 合并
attribute NO_VALUE = 4
符号，可放置为属性的“前一个”值，表示修改属性时未加载任何值，并且标志指示我们不加载它。
attribute PASSIVE_CLASS_MISMATCH = 1
表示对象在给定的主键标识下本地存在，但它不是请求的类。因此，返回值为 None，不应发出任何 SQL。
attribute PASSIVE_NO_RESULT = 0
当值无法确定时，由加载器可调用或其他属性/历史检索操作返回的符号，基于加载器可调用标志。
class sqlalchemy.orm.Mapped
在映射类上表示 ORM 映射属性。
该类表示任何将由 ORM Mapper类检测的类属性的完整描述符接口。为类型检查器（如 pylance 和 mypy）提供适当的信息，以便正确对 ORM 映射属性进行类型化。
Mapped最突出的用途是在声明式映射形式的Mapper配置中，当显式使用时，它驱动 ORM 属性（如mapped_class()和relationship()）的配置。
另请参见
使用声明式基类
使用mapped_column()声明式表
提示
Mapped类表示由Mapper类直接处理的属性。它不包括其他作为扩展提供的 Python 描述符类，包括混合属性和关联代理。虽然这些系统仍然使用 ORM 特定的超类和结构，但当它们在类上被访问时，它们不会被Mapper所检测，而是在访问时提供自己的功能。
版本 1.4 中的新功能。
类签名
类sqlalchemy.orm.Mapped（sqlalchemy.orm.base.SQLORMExpression，sqlalchemy.orm.base.ORMDescriptor，sqlalchemy.orm.base._MappedAnnotationBase，sqlalchemy.sql.roles.DDLConstraintColumnRole)
class sqlalchemy.orm.MappedColumn
在类上映射单个Column。
MappedColumn是ColumnProperty类的一个特化，面向声明式配置。
要构建MappedColumn对象，请使用mapped_column()构造函数。
版本 2.0 中的新功能。
类签名
class sqlalchemy.orm.MappedColumn (sqlalchemy.orm._IntrospectsAnnotations, sqlalchemy.orm._MapsColumns, sqlalchemy.orm.base._DeclarativeMapped)
class sqlalchemy.orm.MapperProperty
表示由Mapper映射的特定类属性。
MapperProperty最常见的出现是映射为ColumnProperty实例的映射Column，以及由relationship()生成的对另一个类的引用，表示为Relationship实例。
成员
cascade_iterator(), class_attribute, comparator, create_row_processor(), do_init(), doc, info, init(), instrument_class(), is_property, key, merge(), parent, post_instrument_class(), set_parent(), setup()
类签名
class sqlalchemy.orm.MapperProperty (sqlalchemy.sql.cache_key.HasCacheKey, sqlalchemy.orm._DCAttributeOptions, sqlalchemy.orm.base._MappedAttribute, sqlalchemy.orm.base.InspectionAttrInfo, sqlalchemy.util.langhelpers.MemoizedSlots)
method cascade_iterator(type_: str, state: InstanceState[Any], dict_: _InstanceDict, visited_states: Set[InstanceState[Any]], halt_on: Callable[[InstanceState[Any]], bool] | None = None) → Iterator[Tuple[object, Mapper[Any], InstanceState[Any], _InstanceDict]]
迭代与特定“cascade”相关的给定实例的实例，从这个 MapperProperty 开始。
返回一个迭代器 3 元组（实例，映射器，状态）。
注意，在调用 cascade_iterator 之前，首先检查此 MapperProperty 上的“cascade”集合是否适用于给定类型。
这个方法通常只适用于关系（Relationship）。
attribute class_attribute
返回与此MapperProperty对应的类绑定描述符。
这基本上是一个getattr()调用：
return getattr(self.parent.class_, self.key)
即，如果此MapperProperty被命名为addresses，并且将其映射到的类是User，则此序列是可能的：
>>> from sqlalchemy import inspect >>> mapper = inspect(User) >>> addresses_property = mapper.attrs.addresses >>> addresses_property.class_attribute is User.addresses True >>> User.addresses.property is addresses_property True
attribute comparator: PropComparator[_T]
实现此映射属性的 SQL 表达式构造的PropComparator实例。
method create_row_processor(context: ORMCompileState, query_entity: _MapperEntity, path: AbstractEntityRegistry, mapper: Mapper[Any], result: Result[Any], adapter: ORMAdapter | None, populators: _PopulatorDict) → None
生成行处理函数并附加到给定的填充器列表。
method do_init() → None
执行子类特定的初始化后映射器创建步骤。
这是由MapperProperty对象的init()方法调用的模板方法。
attribute doc: str | None
可选的文档字符串
attribute info: _InfoType
与对象关联的信息字典，允许将用户定义的数据与此InspectionAttr相关联。
第一次访问时生成字典。或者，它可以作为构造函数参数指定给column_property()、relationship()或composite()函数。
另请参阅
QueryableAttribute.info
SchemaItem.info
method init() → None
在创建所有映射器后调用，以组装映射器之间的关系并执行其他后映射器创建初始化步骤。
method instrument_class(mapper: Mapper[Any]) → None
由映射器调用到属性的挂钩，以启动由此MapperProperty管理的类属性的仪器化。
此处的MapperProperty通常会调用属性模块以设置InstrumentedAttribute。
这一步是设置InstrumentedAttribute的两个步骤中的第一个步骤，并在映射器设置过程中的早期阶段调用。
第二步通常是init_class_attribute步骤，通过post_instrument_class()挂钩从StrategizedProperty调用。此步骤分配了额外的状态给InstrumentedAttribute（具体为“impl”），该状态在MapperProperty确定其需要执行的持久性管理类型（例如标量、对象、集合等）后确定。
attribute is_property = True
InspectionAttr 接口的一部分；说明此对象是一个映射器属性。
attribute key: str
类属性的名称
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表示的属性从源对象合并到目标对象。
attribute parent: Mapper[Any]
管理此属性的Mapper。
method post_instrument_class(mapper: Mapper[Any]) → None
在init()完成后需要进行的仪器化调整。
给定的Mapper是调用操作的Mapper，这可能不是相同的Mapper作为继承场景中的self.parent的Mapper；然而，Mapper将始终至少是self.parent的子映射器。
此方法通常由 StrategizedProperty 使用，后者将其委派给 LoaderStrategy.init_class_attribute() 以在类绑定的 InstrumentedAttribute 上执行最终设置。
method set_parent(parent: Mapper[Any], init: bool) → None
设置引用此 MapperProperty 的父映射器。
某些子类重写此方法以在首次了解映射器时执行额外的设置。
method setup(context: ORMCompileState, query_entity: _MapperEntity, path: AbstractEntityRegistry, adapter: ORMAdapter | None, **kwargs: Any) → None
由 Query 调用，用于构造 SQL 语句。
与目标映射器关联的每个 MapperProperty 处理查询上下文引用的语句，根据需要添加列和/或条件。
class sqlalchemy.orm.MappedSQLExpression
ColumnProperty 类的声明式前端。
公共构造函数是 column_property() 函数。
在 2.0 版本中更改：将 MappedSQLExpression 添加为 ColumnProperty 的声明式兼容子类。
另请参见
MappedColumn
类签名
类 sqlalchemy.orm.MappedSQLExpression (sqlalchemy.orm.properties.ColumnProperty, sqlalchemy.orm.base._DeclarativeMapped)
class sqlalchemy.orm.InspectionAttrExtensionType
表示 InspectionAttr 所属扩展类型的符号。
类签名
类 sqlalchemy.orm.InspectionAttrExtensionType (enum.Enum)
class sqlalchemy.orm.NotExtension
一个枚举。
成员
NOT_EXTENSION
类签名
类 sqlalchemy.orm.NotExtension (sqlalchemy.orm.base.InspectionAttrExtensionType)
attribute NOT_EXTENSION = 'not_extension'
表示 InspectionAttr 不是 sqlalchemy.ext 的一部分的符号。
被赋给 InspectionAttr.extension_type 属性。
function sqlalchemy.orm.merge_result(query: Query[Any], iterator: FrozenResult | Iterable[Sequence[Any]] | Iterable[object], load: bool = True) → FrozenResult | Iterable[Any]
将结果合并到给定的 Query 对象的会话中。
自 2.0 版本起弃用：merge_result()函数在 SQLAlchemy 1.x 系列中被视为遗留函数，并在 2.0 版中成为遗留结构。该函数以及Query上的方法被merge_frozen_result()函数取代。（有关 SQLAlchemy 2.0 的背景，请参见：SQLAlchemy 2.0 - 主要迁移指南）
有关此函数的顶层文档，请参见Query.merge_result()。
function sqlalchemy.orm.merge_frozen_result(session, statement, frozen_result, load=True)
将FrozenResult合并回Session，返回一个新的Result对象，其中包含持久化对象。
有关示例，请参见重新执行语句部分。
另请参见
重新执行语句
Result.freeze()
FrozenResult
class sqlalchemy.orm.PropComparator
定义 ORM 映射属性的 SQL 操作。
SQLAlchemy 允许在核心和 ORM 级别重新定义运算符。PropComparator是 ORM 级别操作重新定义的基类，包括ColumnProperty、Relationship和Composite的操作。
可以创建PropComparator的用户定义子类。可以重写内置的 Python 比较和数学运算符方法，如ColumnOperators.__eq__()，ColumnOperators.__lt__()和ColumnOperators.__add__()，以提供新的操作行为。定制的PropComparator通过comparator_factory参数传递给MapperProperty实例。在每种情况下，应使用适当的PropComparator子类：
# definition of custom PropComparator subclasses from sqlalchemy.orm.properties import \ ColumnProperty,\ Composite,\ Relationship class MyColumnComparator(ColumnProperty.Comparator): def __eq__(self, other): return self.__clause_element__() == other class MyRelationshipComparator(Relationship.Comparator): def any(self, expression): "define the 'any' operation" # ... class MyCompositeComparator(Composite.Comparator): def __gt__(self, other): "redefine the 'greater than' operation" return sql.and_(*[a>b for a, b in zip(self.__clause_element__().clauses, other.__composite_values__())]) # application of custom PropComparator subclasses from sqlalchemy.orm import column_property, relationship, composite from sqlalchemy import Column, String class SomeMappedClass(Base): some_column = column_property(Column("some_column", String), comparator_factory=MyColumnComparator) some_relationship = relationship(SomeOtherClass, comparator_factory=MyRelationshipComparator) some_composite = composite( Column("a", String), Column("b", String), comparator_factory=MyCompositeComparator )
请注意，对于列级操作符的重新定义，通常更简单的方法是在核心级别定义操作符，使用TypeEngine.comparator_factory属性。有关更多详细信息，请参阅重新定义和创建新操作符。
另请参阅
比较器
比较器
比较器
ColumnOperators
重新定义和创建新操作符
TypeEngine.comparator_factory
成员
eq(), le(), lt(), ne(), adapt_to_entity(), adapter, all_(), and_(), any(), any_(), asc(), between(), bitwise_and(), bitwise_lshift(), bitwise_not(), bitwise_or(), bitwise_rshift(), bitwise_xor(), bool_op(), collate(), concat(), contains(), desc(), distinct(), endswith(), has(), icontains(), iendswith(), ilike(), in_(), is_(), is_distinct_from(), is_not(), is_not_distinct_from(), isnot(), isnot_distinct_from(), istartswith(), like(), match(), not_ilike(), not_in(), not_like(), notilike(), notin_(), notlike(), nulls_first(), nulls_last(), nullsfirst(), nullslast(), of_type(), op(), operate(), property, regexp_match(), regexp_replace(), reverse_operate(), startswith(), timetuple
类签名
类 sqlalchemy.orm.PropComparator (sqlalchemy.orm.base.SQLORMOperations, typing.Generic, sqlalchemy.sql.expression.ColumnOperators)
method __eq__(other: Any) → ColumnOperators
从 ColumnOperators 的 sqlalchemy.sql.expression.ColumnOperators.__eq__ 方法继承
实现 == 运算符。
在列上下文中，生成子句 a = b。如果目标是 None，则生成 a IS NULL。
method __le__(other: Any) → ColumnOperators
从 ColumnOperators 的 sqlalchemy.sql.expression.ColumnOperators.__le__ 方法继承
实现 <= 运算符。
在列上下文中，生成子句 a <= b。
method __lt__(other: Any) → ColumnOperators
从 ColumnOperators 的 sqlalchemy.sql.expression.ColumnOperators.__lt__ 方法继承
实现 < 运算符。
在列上下文中，生成子句 a < b。
method __ne__(other: Any) → ColumnOperators
从 ColumnOperators 的 sqlalchemy.sql.expression.ColumnOperators.__ne__ 方法继承
实现 != 运算符。
在列上下文中，生成子句 a != b。如果目标是 None，则生成 a IS NOT NULL。
method adapt_to_entity(adapt_to_entity: AliasedInsp[Any]) → PropComparator[_T_co]
返回此 PropComparator 的副本，将使用给定的AliasedInsp 来生成相应的表达式。
attribute adapter
生成一个可调用对象，以使列表达式适合此比较器的别名版本。
method all_() → ColumnOperators
从 ColumnOperators 的 ColumnOperators.all_() 方法继承
对父对象产生一个 all_() 子句。
参见 all_() 的文档以获取示例。
注意
请务必不要将新的ColumnOperators.all_()方法与此方法的传统版本混淆，后者是专用于ARRAY的方法，采用不同的调用风格，Comparator.all()方法。
method and_(*criteria: _ColumnExpressionArgument[bool]) → PropComparator[bool]
向由此关系属性表示的 ON 子句添加额外的条件。
例如：
stmt = select(User).join( User.addresses.and_(Address.email_address != 'foo') ) stmt = select(User).options( joinedload(User.addresses.and_(Address.email_address != 'foo')) )
版本 1.4 中的新功能。
请参阅
将 Relationship 与自定义 ON 条件结合
向加载器选项添加条件
with_loader_criteria()
method any(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]
返回一个 SQL 表达式，如果此元素引用满足给定条件的成员，则表示为真。
any()的常规实现是Comparator.any()。
参数：
criterion– 针对成员类表或属性制定的可选 ClauseElement。**kwargs– 键/值对应于成员类属性名称，这些属性将通过等式与相应的值进行比较。
method any_() → ColumnOperators
继承自 ColumnOperators.any_() 方法的 ColumnOperators
对父对象生成一个any_()子句。
请参阅 any_() 的文档以获取示例。
注意
请务必不要将新的ColumnOperators.any_()方法与此方法的传统版本混淆，后者是专用于ARRAY的方法，采用不同的调用风格，Comparator.any()方法。
method asc() → ColumnOperators
继承自 ColumnOperators.asc() 方法的 ColumnOperators
对父对象生成一个asc()子句。
method between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators
继承自 ColumnOperators.between() 方法的 ColumnOperators
针对父对象生成一个between()子句，给定下限和上限范围。
method bitwise_and(other: Any) → ColumnOperators
继承自 ColumnOperators.bitwise_and() 方法的 ColumnOperators
执行按位与操作，通常通过&运算符。
新功能在版本 2.0.2 中。
另请参阅
按位运算符
method bitwise_lshift(other: Any) → ColumnOperators
继承自 ColumnOperators.bitwise_lshift() 方法的 ColumnOperators
执行按位左移操作，通常通过<<运算符。
新功能在版本 2.0.2 中。
另请参阅
按位运算符
method bitwise_not() → ColumnOperators
继承自 ColumnOperators.bitwise_not() 方法的 ColumnOperators
执行按位非操作，通常通过~运算符。
新功能在版本 2.0.2 中。
另请参阅
按位运算符
method bitwise_or(other: Any) → ColumnOperators
继承自 ColumnOperators.bitwise_or() 方法的 ColumnOperators
执行按位或操作，通常通过|运算符。
新功能在版本 2.0.2 中。
另请参阅
按位运算符
method bitwise_rshift(other: Any) → ColumnOperators
继承自 ColumnOperators.bitwise_rshift() 方法的 ColumnOperators
执行按位右移操作，通常通过>>运算符。
新功能在版本 2.0.2 中。
另请参阅
按位运算符
method bitwise_xor(other: Any) → ColumnOperators
继承自 ColumnOperators.bitwise_xor() 方法的 ColumnOperators
产生一个按位异或操作，通常通过^运算符实现，或者在 PostgreSQL 中使用#。
在 2.0.2 版中新增。
另请参阅
位运算符
method bool_op(opstring: str, precedence: int = 0, python_impl: Callable[[...], Any] | None = None) → Callable[[Any], Operators]
继承自 Operators.bool_op() 方法的 Operators
返回一个自定义的布尔运算符。
此方法是调用 Operators.op() 并传递 Operators.op.is_comparison 标志为 True 的简写。使用 Operators.bool_op() 的一个关键优势是，在使用列构造时，返回的表达式的“布尔”特性将存在于 PEP 484 目的上。
另请参阅
Operators.op()
method collate(collation: str) → ColumnOperators
继承自 ColumnOperators.collate() 方法的 ColumnOperators
生成一个针对父对象的 collate() 子句，给定排序规则字符串。
另请参阅
collate()
method concat(other: Any) → ColumnOperators
继承自 ColumnOperators.concat() 方法的 ColumnOperators
实现 ‘concat’ 运算符。
在列上下文中，生成子句 a || b，或在 MySQL 上使用 concat() 运算符。
method contains(other: Any, **kw: Any) → ColumnOperators
继承自 ColumnOperators.contains() 方法的 ColumnOperators
实现‘contains’运算符。
生成一个 LIKE 表达式，用于测试字符串值中间的匹配：
column LIKE '%' || <other> || '%'
例如：
stmt = select(sometable).\ where(sometable.c.column.contains("foobar"))
由于该运算符使用LIKE，存在于表达式内部的通配符字符"%"和"_"也将像通配符一样起作用。对于字面字符串值，可以将ColumnOperators.contains.autoescape标志设置为True，以对字符串值内这些字符的出现应用转义，使它们作为自身而不是通配符字符进行匹配。或者，ColumnOperators.contains.escape参数将建立一个给定字符作为转义字符，当目标表达式不是字面字符串时可能会有用。
SqlAlchemy 2.0 中文文档（二十七）（3）https://developer.aliyun.com/article/1560501
