SqlAlchemy 2.0 中文文档（二十七）（2）-阿里云开发者社区

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

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

热门文章

最新文章

相关电子书

热门

活动广场

任务中心

开发者评测

高校计划

乘风者计划

训练营

阿里云MVP

话题

直播

下载

镜像站

技术资料

插件

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

热门文章

最新文章

相关电子书