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

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

类签名

类sqlalchemy.orm.Relationship（sqlalchemy.orm.RelationshipProperty，sqlalchemy.orm.base._DeclarativeMapped）

class sqlalchemy.orm.RelationshipDirection

枚举指示 RelationshipProperty 的‘方向’。

RelationshipDirection 可从 RelationshipProperty 的 Relationship.direction 属性访问。

成员

MANYTOMANY, MANYTOONE, ONETOMANY

类签名

类 sqlalchemy.orm.RelationshipDirection (enum.Enum)

attribute MANYTOMANY = 3

指示 relationship() 的多对多方向。

此符号通常由内部使用，但可能在某些 API 功能中公开。

attribute MANYTOONE = 2

指示 relationship() 的多对一方向。

此符号通常由内部使用，但可能在某些 API 功能中公开。

attribute ONETOMANY = 1

指示 relationship() 的一对多方向。

此符号通常由内部使用，但可能在某些 API 功能中公开。

class sqlalchemy.orm.RelationshipProperty

描述持有单个项目或与相关数据库表对应的项目列表的对象属性。

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

另请参阅

关系配置

成员

eq(), init(), ne(),  adapt_to_entity(), and_(), any(), contains(), entity, has(), in_(),  mapper, of_type(), cascade, cascade_iterator(), declarative_scan(),  do_init(), entity, instrument_class(), mapper, merge()

类签名

类sqlalchemy.orm.RelationshipProperty (sqlalchemy.orm._IntrospectsAnnotations, sqlalchemy.orm.StrategizedProperty, sqlalchemy.log.Identified)

class Comparator

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

请参阅PropComparator的文档，了解 ORM 级别操作符定义的简要概述。

另请参见

PropComparator

Comparator

ColumnOperators

重新定义和创建新操作符

TypeEngine.comparator_factory

类签名

类sqlalchemy.orm.RelationshipProperty.Comparator (sqlalchemy.util.langhelpers.MemoizedSlots, sqlalchemy.orm.PropComparator)

method __eq__(other: Any) → ColumnElement[bool]

实现==运算符。

在多对一的上下文中，例如：

MyClass.some_prop == <some object>

这通常会生成一个子句，例如：

mytable.related_id == <some id>

其中<some id>是给定对象的主键。

==运算符为非多对一比较提供了部分功能：

• 不支持与集合进行比较。请使用Comparator.contains()。
  
• 与标量一对多相比，将生成一个子句，比较父级中的目标列与给定目标。
  
• 与标量多对多相比，关联表的别名也将被渲染，形成一个自然连接，作为查询主体的一部分。这对于超出简单 AND 比较的查询不起作用，例如使用 OR 的查询。请使用显式连接、外连接或Comparator.has()进行更全面的非多对一标量成员测试。
  
• 在一个一对多或多对多的上下文中与None进行比较会产生一个 NOT EXISTS 子句。
  

method __init__(prop: RelationshipProperty[_PT], parentmapper: _InternalEntityType[Any], adapt_to_entity: AliasedInsp[Any] | None = None, of_type: _EntityType[_PT] | None = None, extra_criteria: Tuple[ColumnElement[bool], ...] = ())

Comparator的构造是 ORM 属性机制的内部实现。

method __ne__(other: Any) → ColumnElement[bool]

实现!=运算符。

在多对一的上下文中，例如：

MyClass.some_prop != <some object>

这通常会生成一个子句，例如：

mytable.related_id != <some id>

其中<some id>是给定对象的主键。

!=运算符为非多对一比较提供了部分功能：

• 不支持对集合的比较。使用 Comparator.contains() 结合 not_()。
  
• 与标量一对多相比，将生成一个在父项中比较目标列与给定目标的子句。
  
• 与标量多对多相比，关联表的别名也将被呈现，形成查询主体的一部分的自然连接。这不适用于超出简单 AND 比较的查询，例如使用 OR 的查询。使用显式联接、外联接或 Comparator.has() 结合 not_() 进行更全面的非一对多标量成员测试。
  
• 在一对多或多对多的情况下与 None 比较会产生 EXISTS 子句。
  

method adapt_to_entity(adapt_to_entity: AliasedInsp[Any]) → RelationshipProperty.Comparator[Any]

返回此 PropComparator 的副本，该副本将使用给定的AliasedInsp 来生成相应的表达式。

method and_(*criteria: _ColumnExpressionArgument[bool]) → PropComparator[Any]

添加 AND 条件。

请参见PropComparator.and_() 以获取示例。

自 1.4 版本新增。

method any(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]

生成一个根据特定标准测试集合的表达式，使用 EXISTS。

例如：

session.query(MyClass).filter(
    MyClass.somereference.any(SomeRelated.x==2)
)

将生成类似于以下的查询：

SELECT * FROM my_table WHERE
EXISTS (SELECT 1 FROM related WHERE related.my_id=my_table.id
AND related.x=2)

因为 Comparator.any() 使用相关子查询，所以与大型目标表相比，其性能不如使用联接好。

Comparator.any() 特别适用于测试空集合：

session.query(MyClass).filter(
    ~MyClass.somereference.any()
)

将生成：

SELECT * FROM my_table WHERE
NOT (EXISTS (SELECT 1 FROM related WHERE
related.my_id=my_table.id))

Comparator.any() 仅适用于集合，即具有 uselist=True 的relationship()。对于标量引用，请使用 Comparator.has()。

method contains(other: _ColumnExpressionArgument[Any], **kwargs: Any) → ColumnElement[bool]

返回一个简单的表达式，测试集合是否包含特定项。

Comparator.contains() 仅适用于集合，即实现一对多或多对多关系且 uselist=True 的relationship()。

在简单的一对多上下文中使用时，例如表达式：

MyClass.contains(other)

生成的子句类似于：

mytable.id == <some id>

其中 <some id> 是指 other 上的外键属性的值，该属性引用其父对象的主键。因此，Comparator.contains() 在与简单的一对多操作一起使用时非常有用。

对于多对多操作，Comparator.contains() 的行为有更多注意事项。关联表将呈现在语句中，生成一个“隐式”联接，即，在 WHERE 子句中包括多个表：

query(MyClass).filter(MyClass.contains(other))

生成的查询类似于：

SELECT * FROM my_table, my_association_table AS
my_association_table_1 WHERE
my_table.id = my_association_table_1.parent_id
AND my_association_table_1.child_id = <some id>

其中<some id>将是other的主键。从上面可以明显看出，当在超出简单 AND 连接的查询中使用多个由 OR 连接的Comparator.contains()表达式时，Comparator.contains()将不会与多对多集合一起工作。在这种情况下，需要使用子查询或显式“外连接”。查看Comparator.any()以获取使用 EXISTS 的性能较差的替代方案，或者参考Query.outerjoin()以及 Joins 以获取有关构建外连接的更多详细信息。

kwargs 可能会被此运算符忽略，但对于 API 符合性是必需的。

attribute entity: _InternalEntityType[_PT]

被此Comparator引用的目标实体。

这是一个Mapper或AliasedInsp对象。

这是relationship()的“目标”或“远程”端。

method has(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]

生成一个表达式，使用 EXISTS 针对特定标准测试标量引用。

像这样的表达式：

session.query(MyClass).filter(
    MyClass.somereference.has(SomeRelated.x==2)
)

将生成一个查询如下：

SELECT * FROM my_table WHERE
EXISTS (SELECT 1 FROM related WHERE
related.id==my_table.related_id AND related.x=2)

因为Comparator.has()使用相关子查询，所以当与大型目标表进行比较时，其性能不如使用连接。

Comparator.has()仅适用于标量引用，即具有uselist=False的relationship()。对于集合引用，请使用Comparator.any()。

method in_(other: Any) → NoReturn

生成一个 IN 子句 - 目前尚未为基于relationship()的属性实现此功能。

attribute mapper: Mapper[_PT]

被此Comparator引用的目标Mapper。

这是relationship()的“目标”或“远程”端。

method of_type(class_: _EntityType[Any]) → PropComparator[_PT]

重新定义此对象以多态子类的术语。

查看PropComparator.of_type()的示例。

attribute cascade

返回此RelationshipProperty的当前级联设置。

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[Any, Mapper[Any], InstanceState[Any], _InstanceDict]]

遍历与特定‘cascade’相关联的给定实例的实例，从此 MapperProperty 开始。

返回一个迭代器三元组（实例，映射器，状态）。

请注意，在调用 cascade_iterator 之前，将首先检查此 MapperProperty 上的‘cascade’集合是否具有给定类型。

此方法通常仅适用于 Relationship。

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 entity

返回目标映射实体，这是由此RelationshipProperty引用的类或别名类的 inspect()。

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

由 Mapper 调用的钩子，用于启动由此 MapperProperty 管理的类属性的工具化。

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

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

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

attribute mapper

返回此RelationshipProperty的目标Mapper。

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.SQLORMExpression

一种可用于指示任何 ORM 级别属性或对象的类型，用于 SQL 表达式构建的上下文中。

SQLORMExpression从核心SQLColumnExpression扩展，添加了额外的 ORM 特定的 SQL 方法，例如PropComparator.of_type()，并且是InstrumentedAttribute的基础之一。它可以在PEP 484类型提示中用于指示应该作为 ORM 级别属性表达式行为的参数或返回值。

版本 2.0.0b4 中的新功能。

类签名

类sqlalchemy.orm.SQLORMExpression（sqlalchemy.orm.base.SQLORMOperations，sqlalchemy.sql.expression.SQLColumnExpression，sqlalchemy.util.langhelpers.TypingOnly)

class sqlalchemy.orm.Synonym

SynonymProperty类的声明性前端。

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

2.0 版中的变更：将 Synonym 添加为与 SynonymProperty 兼容的声明式子类。

另请参阅

同义词 - 同义词概述

类签名

类 sqlalchemy.orm.Synonym (sqlalchemy.orm.descriptor_props.SynonymProperty, sqlalchemy.orm.base._DeclarativeMapped)

class sqlalchemy.orm.SynonymProperty

将属性名标记为映射属性的同义词，即属性将反映另一个属性的值和表达行为。

同义词 是使用 synonym() 函数构建的。

另请参阅

同义词 - 同义词概述

成员

doc, info, key, parent, set_parent(), uses_objects

类签名

类 sqlalchemy.orm.SynonymProperty (sqlalchemy.orm.descriptor_props.DescriptorProperty)

attribute doc: str | None

继承自 DescriptorProperty.doc 属性的 DescriptorProperty

可选的文档字符串

attribute info: _InfoType

继承自 MapperProperty.info 属性的 MapperProperty

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

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

另请参阅

QueryableAttribute.info

SchemaItem.info

attribute key: str

继承自 MapperProperty.key 属性的 MapperProperty

类属性的名称

attribute parent: Mapper[Any]

继承自 MapperProperty.parent 属性的 MapperProperty

管理此属性的Mapper。

method set_parent(parent: Mapper[Any], init: bool) → None

设置引用此 MapperProperty 的父 Mapper。

一些子类会重写此方法，在首次了解 Mapper 时执行额外的设置。

attribute uses_objects

class sqlalchemy.orm.QueryContext

class default_load_options

类签名

类sqlalchemy.orm.QueryContext.default_load_options (sqlalchemy.sql.expression.Options)

class sqlalchemy.orm.QueryableAttribute

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

另请参阅

InstrumentedAttribute

MapperProperty

Mapper.all_orm_descriptors

Mapper.attrs

成员

adapt_to_entity(), and_(), expression, info, is_attribute, of_type(), operate(), parent, reverse_operate()

类签名

类sqlalchemy.orm.QueryableAttribute (sqlalchemy.orm.base._DeclarativeMapped, sqlalchemy.orm.base.SQLORMExpression, sqlalchemy.orm.base.InspectionAttr, sqlalchemy.orm.PropComparator, sqlalchemy.sql.roles.JoinTargetRole, sqlalchemy.sql.roles.OnClauseRole, sqlalchemy.sql.expression.Immutable, sqlalchemy.sql.cache_key.SlotsMemoizedHasCacheKey, sqlalchemy.util.langhelpers.MemoizedSlots, sqlalchemy.event.registry.EventTarget)

method adapt_to_entity(adapt_to_entity: AliasedInsp[Any]) → Self

返回此 PropComparator 的副本，该副本将使用给定的AliasedInsp来生成相应的表达式。

method and_(*clauses: _ColumnExpressionArgument[bool]) → QueryableAttribute[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 版中的新功能。

另请参阅

将关联与自定义 ON 条件组合

向加载器选项添加条件

with_loader_criteria()

attribute expression: ColumnElement[_T_co]

由此QueryableAttribute表示的 SQL 表达式对象。

通常情况下，这将是一个ColumnElement子类的实例，代表着一个列表达式。

attribute info

返回底层 SQL 元素的‘info’字典。

此处的行为如下：

• 如果属性是一个列映射属性，即ColumnProperty，它直接映射到模式级Column对象，那么此属性将返回与核心级Column对象关联的SchemaItem.info字典。
  
• 如果属性是一个ColumnProperty，但映射到除Column之外的任何其他类型的 SQL 表达式，该属性将直接指向与ColumnProperty关联的MapperProperty.info字典，假设 SQL 表达式本身没有自己的.info属性（这应该是情况，除非用户定义的 SQL 构造已定义了一个）。
  
• 如果属性指的是任何其他类型的MapperProperty，包括Relationship，那么该属性将指向与该MapperProperty相关联的MapperProperty.info字典。
  
• 要无条件访问MapperProperty.info字典的MapperProperty，包括与Column直接关联的ColumnProperty，可以使用QueryableAttribute.property属性引用属性，如MyClass.someattribute.property.info。
  

另请参阅

SchemaItem.info

MapperProperty.info

attribute is_attribute = True

如果此对象是 Python 的描述符，则为 True。

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

另请参阅

Mapper.all_orm_descriptors

method of_type(entity: _EntityType[Any]) → QueryableAttribute[_T]

重新定义此对象以多态子类，with_polymorphic()构造或aliased()构造。

返回一个新的PropComparator，可以进一步评估标准。

例如：

query.join(Company.employees.of_type(Engineer)).\
   filter(Engineer.name=='foo')

参数：

class_ – 一个表示标准将针对特定子类的类或映射器。

另请参阅

使用关系在别名目标之间进行连接 - 在 ORM 查询指南中

连接到特定子类型或with_polymorphic()实体

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 – 操作的‘另一’方。对于大多数操作来说，将是一个单一标量。
  
• **kwargs – 修饰符。这些可能由特殊操作符（如ColumnOperators.contains()）传递。
  

attribute parent: _InternalEntityType[Any]

返回表示父实体的检查实例。

这将是Mapper或AliasedInsp的实例，取决于此属性所关联的父实体的性质。

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

对参数执行反向操作。

使用方式与operate()相同。

class sqlalchemy.orm.UOWTransaction

method filter_states_for_dep(dep, states)

将给定的 InstanceState 列表过滤为与给定 DependencyProcessor 相关的实例。

method finalize_flush_changes() → None

在成功的 flush()后，将已处理的对象标记为干净/已删除。

在 execute()方法成功执行且事务已提交后，在 flush()方法内调用此方法。

method get_attribute_history(state, key, passive=symbol('PASSIVE_NO_INITIALIZE'))

作为 attributes.get_state_history()的门面，包括结果的缓存。

method is_deleted(state)

如果给定状态在此 uowtransaction 中标记为已删除，则返回True。

method remove_state_actions(state)

从 uowtransaction 中移除状态的待处理操作。

成员

filter_states_for_dep(), finalize_flush_changes(),  get_attribute_history(), is_deleted(), remove_state_actions(),  was_already_deleted()

method was_already_deleted(state)

如果给定状态已过期且先前已被删除，则返回True。