SqlAlchemy 2.0 中文文档（十四）（5）

SqlAlchemy 2.0 中文文档（十四）（4）https://developer.aliyun.com/article/1562972

集合 API

function sqlalchemy.orm.attribute_keyed_dict(attr_name: str, *, ignore_unpopulated_attribute: bool = False) → Type[KeyFuncDict[Any, Any]]

基于属性的键的字典类型集合。

2.0 版本更改：将attribute_mapped_collection重命名为attribute_keyed_dict()。

返回一个KeyFuncDict工厂，它将根据要添加到字典中的 ORM 映射实例上的特定命名属性的值产生新的字典键。

注意

目标属性的值必须在对象添加到字典集合时被赋值。此外，不会跟踪关键属性的更改，这意味着字典中的键不会自动与目标对象本身的键值同步。有关更多详细信息，请参阅处理键变化和反向填充字典集合。

另请参阅

字典集合 - 使用背景

参数：

• attr_name – 映射类上的 ORM 映射属性的字符串名称，该属性的值将作为该实例的新字典条目的键值。
  
• ignore_unpopulated_attribute –
  如果为 True，并且对象上的目标属性根本未填充，则该操作将被静默跳过。默认情况下，将引发错误。
  新版 2.0 中：如果确定用于字典键的属性从未填充任何值，则默认情况下会引发错误。attribute_keyed_dict.ignore_unpopulated_attribute 参数可以设置，表示应忽略此条件，并且静默跳过追加操作。这与 1.x 系列的行为形成对比，后者会错误地用任意键值None填充字典中的值。
  

function sqlalchemy.orm.column_keyed_dict(mapping_spec: Type[_KT] | Callable[[_KT], _VT], *, ignore_unpopulated_attribute: bool = False) → Type[KeyFuncDict[_KT, _KT]]

基于列的键控字典集合类型。

2.0 中更改：将column_mapped_collection 更名为 column_keyed_dict。

返回一个KeyFuncDict 工厂，它将根据 ORM 映射实例上的特定Column-映射属性的值生成新的字典键，以添加到字典中。

注意

目标属性的值必须在将对象添加到字典集合时分配其值。此外，不跟踪键属性的更改，这意味着字典中的键不会自动与目标对象本身的键值同步。有关详细信息，请参阅处理键变化和向字典集合回填。

也可参阅

字典集合 - 使用背景

参数：

• mapping_spec – 预期由目标映射器映射到映射类上的特定属性的Column对象，该属性的值在特定实例上将用作该实例的新字典条目的键。
  
• ignore_unpopulated_attribute –
  如果为 True，并且对象上由给定Column目标属性指示的映射属性根本未填充，则操作将被静默跳过。默认情况下，会引发错误。
  新版 2.0 中：如果确定用于字典键的属性从未填充任何值，则默认情况下会引发错误。column_keyed_dict.ignore_unpopulated_attribute 参数可以设置，表示应忽略此条件，并且静默跳过追加操作。这与 1.x 系列的行为形成对比，后者会错误地用任意键值None填充字典中的值。
  

function sqlalchemy.orm.keyfunc_mapping(keyfunc: _F, *, ignore_unpopulated_attribute: bool = False) → Type[KeyFuncDict[_KT, Any]]

一个具有任意键的基于字典的集合类型。

从版本 2.0 开始更改：将 mapped_collection 重命名为 keyfunc_mapping()。

返回一个从 keyfunc 生成的键函数的 KeyFuncDict 工厂，keyfunc 是一个可调用对象，接受一个实体并返回一个键值。

注意

给定的 keyfunc 只在将目标对象添加到集合时调用一次。不跟踪对函数返回的有效值的更改。

另请参见

字典集合 - 使用背景

参数：

• keyfunc – 应传递 ORM 映射实例的可调用对象，然后生成一个新的用于字典的键。如果返回的值是 LoaderCallableStatus.NO_VALUE，则会引发错误。
  
• ignore_unpopulated_attribute –
  如果为 True，并且可调用对象对于特定实例返回 LoaderCallableStatus.NO_VALUE，则操作将被静默跳过。默认情况下，会引发错误。
  从版本 2.0 开始：如果用于字典键的可调用对象返回 LoaderCallableStatus.NO_VALUE，默认情况下会引发错误，这在 ORM 属性上下文中表示一个从未填充任何值的属性。可以设置 mapped_collection.ignore_unpopulated_attribute 参数，该参数将指示忽略此条件，并且追加操作将被静默跳过。这与 1.x 系列的行为形成对比，后者会错误地用任意的键值 None 填充字典中的值。
  

sqlalchemy.orm.attribute_mapped_collection = <function attribute_keyed_dict>

一个基于字典的集合类型，具有基于属性的键。

从版本 2.0 开始更改：将 attribute_mapped_collection 重命名为 attribute_keyed_dict()。

返回一个根据要添加到字典中的 ORM 映射实例的特定命名属性的值生成新字典键的 KeyFuncDict 工厂。

注意

目标属性的值必须在将对象添加到字典集合时分配其值。此外，不跟踪键属性的更改，这意味着字典中的键不会自动与目标对象本身的键值同步。有关详细信息，请参见处理键变异和向字典集合反填充。

另请参见

字典集合 - 使用背景

参数：

• attr_name – 映射类上的 ORM 映射属性的字符串名称，在特定实例上的值将用作该实例的新字典条目的键。
  
• ignore_unpopulated_attribute –
  如果为 True，并且对象上的目标属性根本未填充，则操作将被静默跳过。默认情况下，将引发错误。
  新版本 2.0 中：如果确定用于字典键的属性从未填充任何值，则默认会引发错误。 attribute_keyed_dict.ignore_unpopulated_attribute 参数可以设置，以指示应忽略此条件，并且附加操作将被静默跳过。这与 1.x 系列的行为相反，后者会错误地使用任意键值为None填充字典中的值。
  

sqlalchemy.orm.column_mapped_collection = <function column_keyed_dict>

基于字典的集合类型，以列为键。

2.0 版更改：将column_mapped_collection重命名为column_keyed_dict。

返回一个KeyFuncDict工厂，它将根据 ORM 映射实例上的特定Column属性的值生成新的字典键，以添加到字典中。

注意

目标属性的值必须在将对象添加到字典集合时分配其值。此外，不跟踪键属性的更改，这意味着字典中的键不会自动与目标对象本身的键值同步。有关详细信息，请参见处理键变异和向字典集合反填充。

另请参见

字典集合 - 使用背景

参数：

• mapping_spec – 预期由目标映射器映射到映射类上的特定属性的Column对象，在特定实例上的值将用作该实例的新字典条目的键。
  
• ignore_unpopulated_attribute –
  如果为 True，并且对象上的给定Column目标属性指示的映射属性根本未填充，则操作将被静默跳过。默认情况下，会引发错误。
  版本 2.0 中的新功能：如果确定用于字典键的属性从未填充任何值，则默认情况下会引发错误。可以设置column_keyed_dict.ignore_unpopulated_attribute参数，该参数将指示忽略此条件，并静默跳过追加操作。这与 1.x 系列的行为相反，后者将错误地用任意键值None填充字典中的值。
  

sqlalchemy.orm.mapped_collection = <function keyfunc_mapping>

具有任意键的基于字典的集合类型。

自版本 2.0 起更改：将mapped_collection重命名为keyfunc_mapping()。

返回一个由 keyfunc 生成的键函数的KeyFuncDict工厂，keyfunc 是一个可调用的函数，它接受一个实体并返回一个键值。

注意

给定的 keyfunc 仅在将目标对象添加到集合时调用一次。不跟踪函数返回的有效值的更改。

另请参阅

字典集合 - 使用背景

参数：

• keyfunc – 一个可调用的函数，将传递 ORM 映射实例，然后生成一个新的键用于字典中。如果返回的值为LoaderCallableStatus.NO_VALUE，则会引发错误。
  
• ignore_unpopulated_attribute –
  如果为 True，并且可调用函数对于特定实例返回LoaderCallableStatus.NO_VALUE，则操作将被静默跳过。默认情况下，会引发错误。
  新版本 2.0 中，默认情况下，如果用于字典键的可调用函数返回LoaderCallableStatus.NO_VALUE，则会引发错误。在 ORM 属性上下文中，这表示从未填充任何值的属性。可以设置mapped_collection.ignore_unpopulated_attribute参数，该参数将表示应忽略此条件，并且附加操作会被静默跳过。这与 1.x 系列的行为形成对比，后者会错误地使用任意键值None填充字典中的值。
  

class sqlalchemy.orm.KeyFuncDict

ORM 映射字典类的基类。

通过向 SQLAlchemy ORM 集合类添加所需的附加方法来扩展dict类型。最直接使用attribute_keyed_dict()或column_keyed_dict()类工厂来使用KeyFuncDict。KeyFuncDict也可以用作用户定义的自定义字典类的基类。

2.0 中的变更：将MappedCollection重命名为KeyFuncDict。

另请参见

attribute_keyed_dict()

column_keyed_dict()

字典集合

自定义集合实现

成员

init(), clear(), pop(), popitem(), remove(), set(), setdefault(), update()

类签名

class sqlalchemy.orm.KeyFuncDict (builtins.dict, typing.Generic)

method __init__(keyfunc: _F, *dict_args: Any, ignore_unpopulated_attribute: bool = False) → None

使用 keyfunc 提供的键制作新集合。

keyfunc 可以是任何接受对象并返回对象以用作字典键的可调用函数。

每当 ORM 需要通过仅基于值的方式添加成员（例如从数据库加载实例时）或删除成员时，都会调用 keyfunc。通常的字典键的注意事项也适用 - keyfunc(object) 应该在集合的生命周期内返回相同的输出。基于可变属性的键值可能导致集合中“丢失”的不可达实例。

method clear() → None.  Remove all items from D.

method pop(k[, d]) → v, remove specified key and return the corresponding value.

如果找不到键，则如果给定默认值，则返回默认值；否则，引发 KeyError。

method popitem()

移除并返回一个 (key, value) 对作为 2-元组。

以 LIFO（后进先出）顺序返回对。如果字典为空，则引发 KeyError。

method remove(value: _KT, _sa_initiator: AttributeEventToken | Literal[None, False] = None) → None

通过值删除项目，并查询键的键函数。

method set(value: _KT, _sa_initiator: AttributeEventToken | Literal[None, False] = None) → None

通过值添加项目，并查询键的键函数。

method setdefault(key, default=None)

插入具有默认值的键，如果键不在字典中。

如果键在字典中，则返回键的值，否则返回默认值。

method update([E, ]**F) → None.  Update D from dict/iterable E and F.

如果 E 存在且具有 .keys() 方法，则执行以下操作：for k in E: D[k] = E[k] 如果 E 存在且缺少  .keys() 方法，则执行以下操作：for k, v in E: D[k] = v 在任何一种情况下，都会执行以下操作：for k in F:  D[k] = F[k]

sqlalchemy.orm.MappedCollection = <class 'sqlalchemy.orm.mapped_collection.KeyFuncDict'>

ORM 映射字典类的基础。

扩展了 dict 类型，以包含 SQLAlchemy ORM 集合类所需的附加方法。最直接使用 attribute_keyed_dict() 或 column_keyed_dict() 类工厂来使用 KeyFuncDict。KeyFuncDict 也可以作为用户定义的自定义字典类的基础。

在 2.0 版本中更改：将 MappedCollection 重命名为 KeyFuncDict。

另请参阅

attribute_keyed_dict()

column_keyed_dict()

字典集合

自定义集合实现

集合内部

function sqlalchemy.orm.collections.bulk_replace(values, existing_adapter, new_adapter, initiator=None)

加载一个新的集合，并根据先前的相似成员资格触发事件。

将values中的实例追加到new_adapter中。对于existing_adapter中不存在的任何实例，将触发事件。existing_adapter中存在但在values中不存在的任何实例将触发删除事件。

参数：

• values – 一个包含集合成员实例的可迭代对象
  
• existing_adapter – 一个要替换的实例的CollectionAdapter
  
• new_adapter – 一个空的CollectionAdapter，用于加载values
  

class sqlalchemy.orm.collections.collection

用于实体集合类的装饰器。

装饰器分为两组：注解和拦截配方。

注解装饰器（appender、remover、iterator、converter、internally_instrumented）指示方法的目的并且不带参数。它们不带括号写成：

@collection.appender
def append(self, append): ...

所有的装饰器都需要括号，即使没有参数：

成员

adds(), appender(), converter(), internally_instrumented(), iterator(), remover(), removes(), removes_return(), replaces()

@collection.adds('entity')
def insert(self, position, entity): ...
@collection.removes_return()
def popitem(self): ...

method static adds(arg)

将方法标记为向集合添加实体。

将“添加到集合”处理添加到方法中。装饰器参数指示哪个方法参数保存了与 SQLAlchemy 相关的值。参数可以按位置指定（即整数）或按名称指定：

@collection.adds(1)
def push(self, item): ...
@collection.adds('entity')
def do_stuff(self, thing, entity=None): ...

method static appender(fn)

将方法标记为集合追加器。

如果追加器方法调用时带有一个位置参数：要追加的值。如果尚未装饰，则该方法将自动装饰为‘adds(1)’：

@collection.appender
def add(self, append): ...
# or, equivalently
@collection.appender
@collection.adds(1)
def add(self, append): ...
# for mapping type, an 'append' may kick out a previous value
# that occupies that slot.  consider d['a'] = 'foo'- any previous
# value in d['a'] is discarded.
@collection.appender
@collection.replaces(1)
def add(self, entity):
    key = some_key_func(entity)
    previous = None
    if key in self:
        previous = self[key]
    self[key] = entity
    return previous

如果要追加的值不允许在集合中，您可以引发异常。需要记住的是，追加器将针对数据库查询映射的每个对象调用。如果数据库包含违反集合语义的行，则您需要有创意地解决问题，因为通过集合访问将无法工作。

如果追加器方法在内部被检测到，您还必须接收关键字参数‘_sa_initiator’并确保将其传播到集合事件。

method static converter(fn)

将方法标记为集合转换器。

自版本 1.3 弃用：collection.converter() 处理程序已弃用，并将在未来的版本中移除。请参考 listen() 函数结合 bulk_replace 监听器接口。

当集合被完全替换时，将调用此可选方法，如下所示：

myobj.acollection = [newvalue1, newvalue2]

转换器方法将接收到要分配的对象，并应返回适用于 appender 方法使用的值的可迭代对象。转换器不得分配值或更改集合，它的唯一任务是将用户提供的值适应为 ORM 使用的值的可迭代对象。

默认的转换器实现将使用鸭子类型进行转换。类似字典的集合将被转换为字典值的可迭代对象，而其他类型将简单地进行迭代：

@collection.converter
def convert(self, other): ...

如果对象的鸭子类型与此集合的类型不匹配，则会引发 TypeError。

如果您希望扩展可以批量分配的可能类型的范围或对即将分配的值进行验证，请提供此方法的实现。

method static internally_instrumented(fn)

将该方法标记为受检测的。

此标记将阻止对该方法应用任何装饰。如果您正在 orchestrating 在基本的 SQLAlchemy 接口方法之一中调用 collection_adapter()，或者要防止自动 ABC 方法装饰器包装您的实现，请使用此标记：

# normally an 'extend' method on a list-like class would be
# automatically intercepted and re-implemented in terms of
# SQLAlchemy events and append().  your implementation will
# never be called, unless:
@collection.internally_instrumented
def extend(self, items): ...

method static iterator(fn)

将该方法标记为集合移除器。

迭代器方法无需参数调用。它应返回所有集合成员的迭代器：

@collection.iterator
def __iter__(self): ...

method static remover(fn)

将该方法标记为集合移除器。

移除器方法使用一个位置参数调用：要移除的值。如果尚未被其他装饰器装饰，该方法将自动使用 removes_return() 进行装饰：

@collection.remover
def zap(self, entity): ...
# or, equivalently
@collection.remover
@collection.removes_return()
def zap(self, ): ...

如果要移除的值不存在于集合中，则可以引发异常或返回 None 以忽略错误。

如果移除方法在内部进行了检测，请确保也接收关键字参数 ‘_sa_initiator’ 并确保其在集合事件中传播。

method static removes(arg)

将该方法标记为从集合中移除实体。

为方法添加“从集合中移除”的处理。修饰器参数指示哪个方法参数包含要移除的与 SQLAlchemy 相关的值。参数可以按位置指定（即整数），也可以按名称指定：

@collection.removes(1)
def zap(self, item): ...

对于在调用时未知要移除的值的方法，请使用 collection.removes_return。

method static removes_return()

将该方法标记为从集合中移除实体。

为方法添加“从集合中移除”的处理。如果没有被其他装饰器装饰，该方法的返回值（如果有）将被视为要移除的值。不会检查方法参数：

@collection.removes_return()
def pop(self): ...

对于在调用时已知要移除的值的方法，请使用 collection.remove。

method static replaces(arg)

标记该方法用于替换集合中的实体。

为方法添加“添加到集合”和“从集合中移除”处理。装饰器参数指示哪个方法参数保存了要添加的与 SQLAlchemy 相关的值，以及返回值（如果有）将被视为要移除的值。

参数可以通过位置（即整数）或名称指定：

@collection.replaces(2)
def __setitem__(self, index, item): ...

sqlalchemy.orm.collections.collection_adapter = operator.attrgetter('_sa_adapter')

attrgetter(attr, …) –> attrgetter 对象

返回一个可调用对象，从其操作数中提取给定的属性。在 f = attrgetter(‘name’) 后，调用 f® 返回 r.name。在 g  = attrgetter(‘name’, ‘date’) 后，调用 g® 返回 (r.name, r.date)。在 h =  attrgetter(‘name.first’, ‘name.last’) 后，调用 h® 返回 (r.name.first,  r.name.last)。

class sqlalchemy.orm.collections.CollectionAdapter

在 ORM 和任意 Python 集合之间建立桥梁。

将基本级别的集合操作（追加、删除、迭代）代理给底层的 Python 集合，并为进入或离开集合的实体发出添加/删除事件。

ORM 专门使用CollectionAdapter 与实体集合进行交互。

class sqlalchemy.orm.collections.InstrumentedDict

内置字典的受检版本。

类签名

类sqlalchemy.orm.collections.InstrumentedDict (builtins.dict, typing.Generic)

class sqlalchemy.orm.collections.InstrumentedList

内置列表的受检版本。

类签名

类sqlalchemy.orm.collections.InstrumentedList (builtins.list, typing.Generic)

class sqlalchemy.orm.collections.InstrumentedSet

内置集合的受检版本。

类签名

类sqlalchemy.orm.collections.InstrumentedSet (builtins.set, typing.Generic)

function sqlalchemy.orm.collections.prepare_instrumentation(factory: Type[Collection[Any]] | Callable[[], _AdaptedCollectionProtocol]) → Callable[[], _AdaptedCollectionProtocol]

准备一个可调用对象，以便将来用作集合类工厂。

给定一个集合类工厂（类型或无参数可调用对象），返回另一个工厂，当调用时将生成兼容的实例。

该函数负责将 collection_class=list 转换为 collection_class=InstrumentedList 的运行时行为。

_return()` 进行装饰：

@collection.remover
def zap(self, entity): ...
# or, equivalently
@collection.remover
@collection.removes_return()
def zap(self, ): ...

如果要移除的值不存在于集合中，则可以引发异常或返回 None 以忽略错误。

如果移除方法在内部进行了检测，请确保也接收关键字参数 ‘_sa_initiator’ 并确保其在集合事件中传播。

method static removes(arg)

将该方法标记为从集合中移除实体。

为方法添加“从集合中移除”的处理。修饰器参数指示哪个方法参数包含要移除的与 SQLAlchemy 相关的值。参数可以按位置指定（即整数），也可以按名称指定：

@collection.removes(1)
def zap(self, item): ...

对于在调用时未知要移除的值的方法，请使用 collection.removes_return。

method static removes_return()

将该方法标记为从集合中移除实体。

为方法添加“从集合中移除”的处理。如果没有被其他装饰器装饰，该方法的返回值（如果有）将被视为要移除的值。不会检查方法参数：

@collection.removes_return()
def pop(self): ...

对于在调用时已知要移除的值的方法，请使用 collection.remove。

method static replaces(arg)

标记该方法用于替换集合中的实体。

为方法添加“添加到集合”和“从集合中移除”处理。装饰器参数指示哪个方法参数保存了要添加的与 SQLAlchemy 相关的值，以及返回值（如果有）将被视为要移除的值。

参数可以通过位置（即整数）或名称指定：

@collection.replaces(2)
def __setitem__(self, index, item): ...

sqlalchemy.orm.collections.collection_adapter = operator.attrgetter('_sa_adapter')

attrgetter(attr, …) –> attrgetter 对象

返回一个可调用对象，从其操作数中提取给定的属性。在 f = attrgetter(‘name’) 后，调用 f® 返回 r.name。在 g  = attrgetter(‘name’, ‘date’) 后，调用 g® 返回 (r.name, r.date)。在 h =  attrgetter(‘name.first’, ‘name.last’) 后，调用 h® 返回 (r.name.first,  r.name.last)。

class sqlalchemy.orm.collections.CollectionAdapter

在 ORM 和任意 Python 集合之间建立桥梁。

将基本级别的集合操作（追加、删除、迭代）代理给底层的 Python 集合，并为进入或离开集合的实体发出添加/删除事件。

ORM 专门使用CollectionAdapter 与实体集合进行交互。

class sqlalchemy.orm.collections.InstrumentedDict

内置字典的受检版本。

类签名

类sqlalchemy.orm.collections.InstrumentedDict (builtins.dict, typing.Generic)

class sqlalchemy.orm.collections.InstrumentedList

内置列表的受检版本。

类签名

类sqlalchemy.orm.collections.InstrumentedList (builtins.list, typing.Generic)

class sqlalchemy.orm.collections.InstrumentedSet

内置集合的受检版本。

类签名

类sqlalchemy.orm.collections.InstrumentedSet (builtins.set, typing.Generic)

function sqlalchemy.orm.collections.prepare_instrumentation(factory: Type[Collection[Any]] | Callable[[], _AdaptedCollectionProtocol]) → Callable[[], _AdaptedCollectionProtocol]

准备一个可调用对象，以便将来用作集合类工厂。

给定一个集合类工厂（类型或无参数可调用对象），返回另一个工厂，当调用时将生成兼容的实例。

该函数负责将 collection_class=list 转换为 collection_class=InstrumentedList 的运行时行为。