SqlAlchemy 2.0 中文文档（二十五）（4）

SqlAlchemy 2.0 中文文档（二十五）（3）https://developer.aliyun.com/article/1560581

参数：

对象 –

可选；限制刷新操作仅对给定集合中存在的元素进行操作。

这个功能适用于极少数情况，特定对象可能需要在完全刷新（flush()）之前进行操作。它不适用于一般用途。

method get(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None) → _O | None

返回基于给定主键标识符的实例，如果找不到则返回None。

例如：

my_user = session.get(User, 5)
some_object = session.get(VersionedFoo, (5, 10))
some_object = session.get(
    VersionedFoo,
    {"id": 5, "version_id": 10}
)

从版本 1.4 开始：添加了Session.get()，该方法已从现在过时的Query.get()方法中移动。

Session.get()是特殊的，因为它直接提供了对Session的标识映射的访问。如果给定的主键标识符存在于本地标识映射中，则直接从该集合返回对象，而不会发出任何 SQL，除非对象已被标记为完全过期。如果不存在，则执行 SELECT 以定位对象。

Session.get()还将执行检查，如果对象存在于标识映射中并标记为过期，则发出 SELECT 以刷新对象以及确保行仍然存在。如果不存在，则引发ObjectDeletedError。

参数：

• entity – 表示要加载的实体类型的映射类或Mapper。
  
• ident –
  表示主键的标量、元组或字典。对于复合（例如，多列）主键，应传递元组或字典。
  对于单列主键，标量调用形式通常是最方便的。如果行的主键是值“5”，调用如下所示：

my_object = session.get(SomeClass, 5)

• 元组形式包含主键值，通常按照它们与映射的Table对象的主键列对应的顺序排列，或者如果使用了Mapper.primary_key配置参数，则按照该参数的顺序排列。例如，如果行的主键由整数数字“5，10”表示，则调用如下所示：

my_object = session.get(SomeClass, (5, 10))

• 字典形式应包含作为主键每个元素相应的映射属性名称的键。如果映射类具有存储对象主键值的属性id、version_id，则调用如下所示：

my_object = session.get(SomeClass, {"id": 5, "version_id": 10})

• options – 可选的加载器选项序列，将应用于查询（如果有的话）。
  
• populate_existing – 导致该方法无条件地发出 SQL 查询，并使用新加载的数据刷新对象，无论对象是否已存在。
  
• with_for_update – 可选的布尔值True，表示应使用 FOR UPDATE，或者可以是一个包含用于指示 SELECT 的更具体的一组 FOR UPDATE 标志的字典；标志应与Query.with_for_update()参数的参数相匹配。取代Session.refresh.lockmode参数。
  
• execution_options –
  可选的执行选项字典，如果发出了查询执行，则将其与查询执行相关联。该字典可以提供Connection.execution_options()接受的选项的子集，并且还可以提供只有在 ORM 上下文中理解的其他选项。
  1.4.29 版中新增。
  另请参阅
  ORM 执行选项 - ORM 特定的执行选项
  
• bind_arguments –
  用于确定绑定的其他参数的字典。可能包括“mapper”、“bind”或其他自定义参数。该字典的内容将传递给Session.get_bind()方法。
  

返回：

对象实例，或None。

method get_bind(mapper: _EntityBindKey[_O] | None = None, *, clause: ClauseElement | None = None, bind: _SessionBind | None = None, _sa_skip_events: bool | None = None, _sa_skip_for_implicit_returning: bool = False, **kw: Any) → Engine | Connection

返回此Session绑定到的“bind”。

“bind”通常是Engine的实例，除非Session已被明确地直接绑定到Connection的情况。

对于多次绑定或未绑定的Session，使用mapper或clause参数来确定返回的适当绑定。

注意当通过 ORM 操作调用Session.get_bind()时通常存在“mapper”参数，例如Session.query()中的每个个体 INSERT/UPDATE/DELETE 操作，Session.flush()调用等。

解析顺序为：

1. 如果给定了mapper并且Session.binds存在，则首先基于正在使用的映射器，然后基于正在使用的映射类，然后基于映射类的__mro__中存在的任何基类，从更具体的超类到更一般的类来定位一个绑定。
   
2. 如果给定了条件并且Session.binds存在，则基于Session.binds中的给定条件中找到的Table对象定位绑定。
   
3. 如果Session.binds存在，则返回该绑定。
   
4. 如果给定了条件，则尝试返回与该条件最终关联的MetaData绑定。
   
5. 如果提供了映射器，尝试返回与最终与该映射器映射的Table或其他可选择对象关联的MetaData绑定。
   
6. 如果找不到绑定，则会引发UnboundExecutionError。
   

请注意，Session.get_bind()方法可以在Session的用户定义子类上被重写，以提供任何类型的绑定解析方案。请参阅自定义垂直分区中的示例。

参数：

• mapper – 可选的映射类或相应的Mapper实例。绑定可以首先从此Session关联的“绑定”映射中派生，其次是从该Mapper映射到的Table关联的MetaData中派生。
  
• clause – 一个ClauseElement（即select()，text()等）。如果mapper参数不存在或无法生成绑定，则将搜索给定的表达式构造，通常是与绑定的MetaData关联的Table。
  

另请参阅

分区策略（例如每个会话的多个数据库后端）

Session.binds

Session.bind_mapper()

Session.bind_table()

method get_nested_transaction() → SessionTransaction | None

返回正在进行的当前嵌套事务（如果有）。

新版本 1.4 中新增。

method get_one(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None) → _O

根据给定的主键标识符返回精确的一个实例，如果未找到则引发异常。

如果查询未选择任何行，则引发sqlalchemy.orm.exc.NoResultFound。

有关参数的详细文档，请参阅方法Session.get()。

新版本 2.0.22 中新增。

返回：

对象实例。

另请参见

Session.get() - 相当的方法，代替

如果未找到具有提供的主键的行，则返回None。

method get_transaction() → SessionTransaction | None

返回正在进行的当前根事务（如果有）。

新版本 1.4 中新增。

classmethod identity_key(class_: Type[Any] | None = None, ident: Any | Tuple[Any, ...] = None, *, instance: Any | None = None, row: Row[Any] | RowMapping | None = None, identity_token: Any | None = None) → _IdentityKeyType[Any]

继承自 sqlalchemy.orm.session._SessionClassMethods.identity_key 的方法 sqlalchemy.orm.session._SessionClassMethods

返回一个标识键。

这是 identity_key() 的别名。

attribute identity_map: IdentityMap

对象标识到对象本身的映射。

通过Session.identity_map.values()迭代提供对当前会话中当前持久对象（即具有行标识的对象）的完整集合的访问。

另请参见

identity_key() - 辅助函数，用于生成此字典中使用的键。

method in_nested_transaction() → bool

如果此 Session 已开始嵌套事务（例如，SAVEPOINT），则返回 True。

新版本 1.4 中新增。

method in_transaction() → bool

如果此 Session 已开始事务，则返回 True。

新版本 1.4 中新增。

另请参见

Session.is_active

attribute info

一个用户可修改的字典。

此字典的初始值可以使用 info 参数来填充到 Session 构造函数或 sessionmaker 构造函数或工厂方法中。此处的字典始终局限于此 Session 并且可以独立于所有其他 Session 对象进行修改。

method invalidate() → None

关闭此会话，使用连接失效。

这是 Session.close() 的变体，还将确保对每个当前用于事务的 Connection 对象调用 Connection.invalidate() 方法（通常只有一个连接，除非 Session 与多个引擎一起使用）。

当已知数据库处于不再安全使用连接的状态时，可以调用此方法。

以下示例说明了在使用 gevent 时可能出现的可导致底层连接应被丢弃的 Timeout 异常情况：

import gevent
try:
    sess = Session()
    sess.add(User())
    sess.commit()
except gevent.Timeout:
    sess.invalidate()
    raise
except:
    sess.rollback()
    raise

此方法还会执行 Session.close() 所做的所有操作，包括清除所有 ORM 对象。

attribute is_active

如果此 Session 未处于“部分回滚”状态，则返回 True。

版本 1.4 中的更改：Session 不再立即开始新事务，因此当首次实例化 Session 时，此属性将为 False。

“部分回滚”状态通常表示 Session 的刷新过程失败，并且必须发出 Session.rollback() 方法以完全回滚事务。

如果此 Session 未处于事务中，则当首次使用时，Session 将自动开始，因此在这种情况下，Session.is_active 将返回 True。

否则，如果此 Session 处于事务中，并且该事务尚未在内部回滚，则 Session.is_active 也将返回 True。

另请参阅

“由于刷新期间的先前异常，此会话的事务已回滚。”（或类似内容）

Session.in_transaction()

method is_modified(instance: object, include_collections: bool = True) → bool

如果给定实例具有本地修改的属性，则返回 True。

此方法检索实例上每个受仪器化的属性的历史记录，并将当前值与其先前提交的值进行比较（如果有）。

实际上，这是检查 Session.dirty 集合中给定实例的更昂贵和准确的版本；对每个属性的净“脏”状态进行全面测试。

例如：

return session.is_modified(someobject)

这种方法有一些注意事项：

• 在 Session.dirty 集合中存在的实例在使用此方法进行测试时可能会报告 False。这是因为对象可能通过属性突变接收到更改事件，从而将其置于 Session.dirty 中，但最终状态与从数据库加载的状态相同，在这里没有净更改。
  
• 当新值被应用时，标量属性可能没有记录先前设置的值，如果在接收新值时该属性未加载或已过期，则假定该属性有一个更改，即使最终对其数据库值没有净更改也是如此。在这些情况下，即使最终没有针对数据库值的净更改，也假定该属性有一个更改。在大多数情况下，当发生  set 事件时，SQLAlchemy 不需要“旧”值，因此如果旧值不存在，则跳过 SQL 调用的开销，这是基于标量值通常需要 UPDATE  的假设，并且在那几种情况下它不需要的情况下，平均比发出防御性的 SELECT 更便宜。
  仅当属性容器的 active_history 标志设置为 True 时，才无条件地在 set 时获取“旧”值。这个标志通常设置为主键属性和不是简单多对一的标量对象引用。要为任意映射列设置此标志，请使用 column_property() 的 active_history 参数。
  

参数：

• instance – 被测试的映射实例。
  
• include_collections – 表示是否应包含多值集合在操作中。将其设置为 False 是一种检测仅基于本地列的属性（即标量列或多对一外键），这些属性会导致此实例在刷新时进行 UPDATE 的方法。
  

method merge(instance: _O, *, load: bool = True, options: Sequence[ORMOption] | None = None) → _O

将给定实例的状态复制到此 Session 中的相应实例。

Session.merge()检查源实例的主键属性，并尝试将其与会话中具有相同主键的实例进行协调。如果在本地找不到，则尝试根据主键从数据库加载对象，如果找不到，则创建一个新实例。然后将源实例上的每个属性的状态复制到目标实例。然后该方法返回生成的目标实例；原始源实例保持不变，并且如果尚未与Session相关联，则不与之相关联。

如果关联使用cascade="merge"进行映射，则此操作会级联到关联的实例。

有关合并的详细讨论，请参见合并。

参数：

• instance – 要合并的实例。
  
• load –
  布尔值，当为 False 时，merge()切换到“高性能”模式，使其放弃发出历史事件以及所有数据库访问。此标志用于诸如将对象图传输到从第二级缓存中的Session中，或者将刚加载的对象传输到由工作线程或进程拥有的Session中，而无需重新查询数据库的情况。
  load=False用例增加了这样一个警告，即给定对象必须处于“干净”状态，也就是说，没有要刷新的挂起更改-即使传入对象已从任何Session分离。这样，当合并操作填充本地属性并级联到相关对象和集合时，值可以原样“打印”到目标对象上，而不会生成任何历史记录或属性事件，并且无需将传入数据与可能未加载的任何现有相关对象或集合进行协调。来自load=False的结果对象始终生成为“干净”，因此只有给定对象也应该是“干净”的，否则这表明方法的错误使用。
  
• options –
  在合并操作从数据库加载对象的现有版本时，会将一系列可选的加载器选项应用于Session.get()方法。
  版本 1.4.24 中的新功能。
  

另请参见

make_transient_to_detached() - 提供了一种将单个对象“合并”到Session中的替代方法

attribute new

在此Session中标记为“new”的所有实例的集合。

attribute no_autoflush

返回一个禁用自动刷新的上下文管理器。

例如：

with session.no_autoflush:
    some_object = SomeClass()
    session.add(some_object)
    # won't autoflush
    some_object.related_thing = session.query(SomeRelated).first()

在 with: 块内进行的操作不会受到在查询访问时发生的刷新的影响。当初始化一系列涉及现有数据库查询的对象时，尚未完成的对象不应立即被刷新时，这是有用的。

classmethod object_session(instance: object) → Session | None

继承自 sqlalchemy.orm.session._SessionClassMethods.object_session 方法的 sqlalchemy.orm.session._SessionClassMethods

返回一个对象所属的 Session。

这是 object_session() 的别名。

method prepare() → None

准备当前进行中的事务以进行两阶段提交。

如果没有进行事务，则此方法会引发一个 InvalidRequestError。

仅两阶段会话的根事务可以被准备。如果当前事务不是这样的事务，则会引发一个 InvalidRequestError。

method query(*entities: _ColumnsClauseArgument[Any], **kwargs: Any) → Query[Any]

返回一个与此 Session 对应的新 Query 对象。

请注意，Query 对象自 SQLAlchemy 2.0 起已被视为遗留；现在使用 select() 构造 ORM 查询。

另请参阅

SQLAlchemy 统一教程

ORM 查询指南

遗留查询 API - 遗留 API 文档

method refresh(instance: object, attribute_names: Iterable[str] | None = None, with_for_update: ForUpdateParameter = None) → None

使给定实例的属性过期并刷新。

首先将选定的属性作为当使用 Session.expire() 时会过期的那样进行过期处理；然后将发出 SELECT 语句到数据库，以使用当前事务中可用的当前值刷新基于列的属性。

如果对象已经被急切加载，那么 relationship() 定向属性也将立即被加载，使用它们最初加载时使用的急切加载策略。

版本 1.4 中的新功能：- Session.refresh() 方法也可以刷新急切加载的属性。

relationship() 导向属性通常会使用 select（或“延迟加载”）加载策略，如果它们在 attribute_names 集合中被明确命名，也会加载**，使用 immediate 加载策略对属性发出 SELECT 语句。如果惰性加载的关系未在Session.refresh.attribute_names中命名，则它们保持为“惰性加载”属性，不会被隐式刷新。

在版本 2.0.4 中更改：Session.refresh() 方法现在将刷新那些在Session.refresh.attribute_names集合中明确命名的惰性加载的relationship() 导向属性。

提示

虽然 Session.refresh() 方法能够刷新列和关系导向的属性，但其主要重点是在单个实例上刷新本地列导向的属性。要获得更开放的“刷新”功能，包括能够同时刷新许多对象的属性并明确控制关系加载策略，请使用 populate existing 功能。

请注意，高度隔离的事务将返回与在同一事务中先前读取的值相同的值，而不管该事务之外的数据库状态是否发生了变化。通常仅在事务开始时，尚未访问数据库行时刷新属性才有意义。

参数：

• attribute_names – 可选。一个字符串属性名称的可迭代集合，指示要刷新的属性的子集。
  
• with_for_update – 可选布尔值 True，指示是否应使用 FOR UPDATE，或者可能是一个包含标志的字典，用于指示更具体的 FOR UPDATE 标志集合用于 SELECT；标志应该与 Query.with_for_update() 的参数匹配。取代Session.refresh.lockmode 参数。
  

另请参阅

刷新/过期 - 初级材料

Session.expire()

Session.expire_all()

填充现有对象 - 允许任何 ORM 查询刷新对象，就像它们通常加载的那样。

method reset() → None

关闭此Session使用的事务资源和 ORM 对象，将会话重置为其初始状态。

此方法提供了与Session.close()方法在历史上提供的相同的“仅重置”行为，其中Session的状态被重置，就像对象是全新的一样，准备好再次使用。然后，此方法可能对将Session.close_resets_only设置为False的Session对象有用，以便仍然可以使用“仅重置”行为。

新版本 2.0.22。

另请参阅

关闭 - 详细介绍了 Session.close() 和 Session.reset() 的语义。

Session.close() - 当参数 Session.close_resets_only 设置为 False 时，此类方法还将阻止会话的重复使用。

method rollback() → None

回滚当前进行中的事务。

如果没有进行中的事务，则此方法是一个直通方法。

该方法始终回滚最顶层的数据库事务，丢弃可能正在进行的任何嵌套事务。

另请参阅

回滚

事务管理

method scalar(statement: Executable, params: _CoreSingleExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Any

执行一条语句并返回一个标量结果。

用法和参数与Session.execute()相同；返回结果是一个标量 Python 值。

method scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → ScalarResult[Any]

执行一条语句并将结果作为标量返回。

用法和参数与Session.execute()相同；返回结果是一个ScalarResult过滤对象，它将返回单个元素而不是Row对象。

返回：

一个ScalarResult对象

新版本 1.4.24 中添加：Session.scalars()

新版本 1.4.26 中添加：scoped_session.scalars()

另请参阅

选择 ORM 实体 - 将 Session.execute() 的行为与 Session.scalars() 进行对比

class sqlalchemy.orm.SessionTransaction

一个 Session 级别的事务。

SessionTransaction 是由 Session.begin() 和 Session.begin_nested() 方法生成的。它在现代用法中主要是一个内部对象，为会话事务提供上下文管理器。

与 SessionTransaction 交互的文档位于：管理事务。

自版本 1.4 更改：直接处理 SessionTransaction 对象的范围和 API 方法已经简化。

另请参阅

管理事务

Session.begin()

Session.begin_nested()

Session.rollback()

Session.commit()

Session.in_transaction()

Session.in_nested_transaction()

Session.get_transaction()

Session.get_nested_transaction()

成员

嵌套, 原始, 父级

类签名

类 sqlalchemy.orm.SessionTransaction (sqlalchemy.orm.state_changes._StateChange, sqlalchemy.engine.util.TransactionalContext)

attribute nested: bool = False

指示这是否为嵌套或 SAVEPOINT 事务。

当 SessionTransaction.nested 为 True 时，预计 SessionTransaction.parent 也会出现，链接到封闭的 SessionTransaction。

另请参见

SessionTransaction.origin

attribute origin: SessionTransactionOrigin

此 SessionTransaction 的来源。

指的是一个 SessionTransactionOrigin 实例，该实例是指导致构造此 SessionTransaction 的源事件的枚举。

新版本 2.0 中添加。

attribute parent

此 SessionTransaction 的父级 SessionTransaction。

如果此属性为 None，表示此 SessionTransaction 位于堆栈顶部，并且对应于真实的 “COMMIT”/”ROLLBACK” 块。如果非 None，则这是一个 “子事务”（由刷新进程使用的内部标记对象）或 “嵌套” / SAVEPOINT 事务。如果 SessionTransaction.nested 属性为 True，则这是一个 SAVEPOINT，如果为 False，表示这是一个子事务。

class sqlalchemy.orm.SessionTransactionOrigin

表示SessionTransaction的来源。

此枚举存在于任何 SessionTransaction 对象的 SessionTransaction.origin 属性上。

新版本 2.0 中添加。

成员

AUTOBEGIN, BEGIN, BEGIN_NESTED, SUBTRANSACTION

类签名

类sqlalchemy.orm.SessionTransactionOrigin (enum.Enum)

attribute AUTOBEGIN = 0

通过自动开始开始的事务

attribute BEGIN = 1

通过调用 Session.begin() 开始事务。

attribute BEGIN_NESTED = 2

通过 Session.begin_nested() 开始事务。

attribute SUBTRANSACTION = 3

事务是内部的 “子事务”

会话工具

function sqlalchemy.orm.close_all_sessions() → None

关闭内存中的所有会话。

此函数会查询所有 Session 对象的全局注册表，并对它们调用 Session.close() ，将它们重置为干净的状态。

此函数不适用于一般用途，但在拆卸方案中的测试套件中可能有用。

版本 1.3 中的新功能。

function sqlalchemy.orm.make_transient(instance: object) → None

改变给定实例的状态，使其成为瞬态的。

注意

make_transient() 是仅用于高级用例的特殊情况函数。

假定给定的映射实例处于持久的或脱离的状态。 该函数将删除其与任何 Session 的关联以及其 InstanceState.identity。 其效果是对象将表现得像它是新构造的，除了保留在调用时加载的任何属性/集合值。 如果此对象已因使用 Session.delete() 而被删除，则还将重置 InstanceState.deleted 标志。

警告

make_transient() 不“取消过期”或以其他方式急切加载目前未加载的 ORM 映射属性。 这包括：

• 通过 Session.expire() 过期
  
• 由于提交会话事务的自然效果，会话过期，例如 Session.commit()
  
• 通常是惰性加载，但目前未加载
  
• 是“延迟加载”（参见 限制哪些列与列延迟加载）并且尚未加载
  
• 在加载此对象的查询中不存在，例如，在连接表继承和其他场景中常见的情况下。
  

在调用make_transient()之后，通常会解析为None的未加载属性，例如上面的属性，或者是针对集合导向属性的空集合。 由于对象是临时的，并且与任何数据库标识都没有关联，因此将不再检索这些值。

另请参阅

make_transient_to_detached()

function sqlalchemy.orm.make_transient_to_detached(instance: object) → None

使给定的临时实例脱离。

注意

make_transient_to_detached()是一个仅用于高级用例的特殊情况函数。

给定实例的所有属性历史记录都将被重置，就好像该实例是从查询中新加载的一样。 缺少的属性将被标记为过期。 对象的主键属性将被制成实例的“键”，这些主键属性是必需的。

然后可以将对象添加到会话中，或者可能与 load=False 标志合并，此时它看起来就像是以这种方式加载的，而不会发出 SQL。

这是一个特殊的用例函数，它与对Session.merge()的普通调用不同，因为可以在不进行任何 SQL 调用的情况下制造给定的持久状态。

另请参阅

make_transient()

Session.enable_relationship_loading()

function sqlalchemy.orm.object_session(instance: object) → Session | None

返回给定实例所属的Session。

这基本上与InstanceState.session访问器相同。 有关详细信息，请参阅该属性。

function sqlalchemy.orm.util.was_deleted(object_: object) → bool

如果给定对象在会话刷新时被删除，则返回 True。

无论对象是否持久还是分离，都是如此。

另请参阅

InstanceState.was_deleted

属性和状态管理工具

这些函数由 SQLAlchemy 属性检测 API 提供，用于提供详细的接口来处理实例、属性值和历史记录。 在构建事件监听器函数时，其中一些函数非常有用，例如在 ORM 事件中描述的函数。

function sqlalchemy.orm.util.object_state(instance: _T) → InstanceState[_T]

给定一个对象，返回与该对象关联的InstanceState。

如果没有配置映射，则会引发sqlalchemy.orm.exc.UnmappedInstanceError。

通过 inspect() 函数可以获得等效功能，如下所示：

inspect(instance)

使用检查系统将会在实例不属于映射的情况下引发sqlalchemy.exc.NoInspectionAvailable。

function sqlalchemy.orm.attributes.del_attribute(instance: object, key: str) → None

删除属性的值，触发历史事件。

无论直接应用于类的工具化如何，都可以使用此函数，即不需要描述符。自定义属性管理方案将需要使用此方法来建立由 SQLAlchemy 理解的属性状态。

function sqlalchemy.orm.attributes.get_attribute(instance: object, key: str) → Any

获取属性的值，触发任何所需的可调用对象。

无论直接应用于类的仪器是什么，都可以使用此函数，即不需要描述符。自定义属性管理方案将需要使用此方法来使用 SQLAlchemy 理解的属性状态。

function sqlalchemy.orm.attributes.get_history(obj: object, key: str, passive: PassiveFlag = symbol('PASSIVE_OFF')) → History

返回给定对象和属性键的History记录。

这是给定属性的预刷新历史记录，每次Session刷新对当前数据库事务进行更改时都会重置。

注意

优先使用AttributeState.history和AttributeState.load_history()访问器来检索实例属性的History。

参数：

• obj - 其类由属性包装的对象。
  
• key - 字符串属性名称。
  
• passive - 如果值尚不存在，则指示属性的加载行为。这是一个比特标志属性，默认为符号PASSIVE_OFF，表示应发出所有必要的 SQL。
  

另请参阅

AttributeState.history

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

function sqlalchemy.orm.attributes.init_collection(obj: object, key: str) → CollectionAdapter

初始化集合属性并返回集合适配器。

此函数用于为先前未加载的属性提供直接访问集合内部。例如：

collection_adapter = init_collection(someobject, 'elements')
for elem in values:
    collection_adapter.append_without_event(elem)

要更轻松地执行上述操作，请参见set_committed_value()。

参数：

• obj - 一个映射对象
  
• key - 集合所在的字符串属性名称。
  

function sqlalchemy.orm.attributes.flag_modified(instance: object, key: str) → None

将实例上的属性标记为“修改”。

这将在实例上设置“修改”标志，并为给定属性建立一个无条件的更改事件。属性必须有一个值存在，否则会引发InvalidRequestError。

要将对象标记为“脏”，而不引用任何特定属性，以便在刷新时将其视为“脏”，请使用flag_dirty()调用。

另请参阅

flag_dirty()

function sqlalchemy.orm.attributes.flag_dirty(instance: object) → None

将实例标记为“脏”，而不提及任何特定属性。

这是一个特殊操作，将允许对象通过刷新过程，以便被SessionEvents.before_flush()等事件拦截。请注意，对于没有更改的对象，在刷新过程中不会发出任何 SQL，即使通过此方法标记为脏。但是，SessionEvents.before_flush()处理程序将能够在Session.dirty集合中看到对象，并可能对其进行更改，然后将其包含在发出的 SQL 中。

版本 1.2 中的新功能。

另请参阅

flag_modified()

function sqlalchemy.orm.attributes.instance_state()

返回给定映射对象的InstanceState。

此函数是object_state()的内部版本。在这里，建议使用object_state()和/或inspect()函数，因为它们会在给定对象未映射时分别发出信息性异常。

function sqlalchemy.orm.instrumentation.is_instrumented(instance, key)

如果给定实例上的给定属性由属性包进行了仪器化，则返回 True。

无论直接应用于类的仪器化如何，都可以使用此函数，即不需要描述符。

function sqlalchemy.orm.attributes.set_attribute(instance: object, key: str, value: Any, initiator: AttributeEventToken | None = None) → None

设置属性的值，触发历史事件。

无论直接应用于类的仪器化如何，都可以使用此函数，即不需要描述符。自定义属性管理方案将需要使用此方法来建立 SQLAlchemy 理解的属性状态。

参数：

• instance – 将被修改的对象
  
• key – 属性的字符串名称
  
• value – 要分配的值
  
• initiator –
  一个Event的实例，可能已从先前的事件侦听器传播。当在现有事件侦听函数中使用set_attribute()函数时，会使用此参数；该对象可用于跟踪事件链的起源。
  版本 1.2.3 中的新功能。
  

function sqlalchemy.orm.attributes.set_committed_value(instance, key, value)

设置没有历史事件的属性的值。

取消任何先前存在的历史。对于持有标量属性的属性，值应为标量值，对于任何持有集合属性的属性，值应为可迭代对象。

当惰性加载程序触发并从数据库加载附加数据时，使用的是相同的基础方法。特别是，此方法可被应用代码使用，通过单独的查询加载了额外的属性或集合，然后将其附加到实例，就好像它是其原始加载状态的一部分。

class sqlalchemy.orm.attributes.History

一个由添加、未更改和删除值组成的 3 元组，表示在受监控属性上发生的更改。

获取对象上特定属性的History对象的最简单方法是使用inspect()函数：

from sqlalchemy import inspect
hist = inspect(myobject).attrs.myattribute.history

每个元组成员都是一个可迭代序列：

• added - 添加到属性中的项目集合（第一个元组元素）。
  
• unchanged - 未更改属性上的项目集合（第二个元组元素）。
  
• deleted - 从属性中删除的项目集合（第三个元组元素）。
  

成员

added, deleted, empty(), has_changes(), non_added(), non_deleted(), sum(), unchanged

类签名

类sqlalchemy.orm.History（builtins.tuple）

attribute added: Tuple[()] | List[Any]

字段 0 的别名

attribute deleted: Tuple[()] | List[Any]

字段 2 的别名

method empty() → bool

如果此History没有更改和现有的未更改状态，则返回 True。

method has_changes() → bool

如果此History有更改，则返回 True。

method non_added() → Sequence[Any]

返回一个未更改+删除的集合。

method non_deleted() → Sequence[Any]

返回一个添加+未更改的集合。

method sum() → Sequence[Any]

返回一个添加+未更改+删除的集合。

attribute unchanged: Tuple[()] | List[Any]

字段 1 的别名

SqlAlchemy 2.0 中文文档（二十五）（5）https://developer.aliyun.com/article/1560604