会话 API¶

会话和 sessionmaker()¶

对象名称	描述
ORMExecuteState	表示对 `Session.execute()` 方法的调用，作为传递给 `SessionEvents.do_orm_execute()` 事件挂钩的。
会话	管理 ORM 映射对象的持久化操作。
sessionmaker	可配置的 `Session` 工厂。
SessionTransaction	一个 `Session` 级别的交易。
SessionTransactionOrigin	指示 `SessionTransaction` 的来源。

class sqlalchemy.orm.sessionmaker¶

可配置的 Session 工厂。

sessionmaker 工厂在被调用时生成新的 Session 对象，根据此处建立的配置参数创建它们。

例如

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

# an Engine, which the Session will use for connection
# resources
engine = create_engine('postgresql+psycopg2://scott:tiger@localhost/')

Session = sessionmaker(engine)

with Session() as session:
    session.add(some_object)
    session.add(some_other_object)
    session.commit()

上下文管理器使用是可选的；否则，返回的 Session 对象可以通过 Session.close() 方法显式关闭。使用 try:/finally: 块是可选的，但是它将确保即使出现数据库错误，关闭也会发生。

session = Session()
try:
    session.add(some_object)
    session.add(some_other_object)
    session.commit()
finally:
    session.close()

sessionmaker 充当 Session 对象的工厂，就像 Engine 充当 Connection 对象的工厂一样。因此，它还包含一个 sessionmaker.begin() 方法，该方法提供了一个上下文管理器，既可以开始又可以提交交易，以及在完成时关闭 Session，如果出现任何错误，则回滚交易。

Session = sessionmaker(engine)

with Session.begin() as session:
    session.add(some_object)
    session.add(some_other_object)
# commits transaction, closes session

版本 1.4 中的新增功能。

当调用 sessionmaker 来构造 Session 时，也可以将关键字参数传递给该方法；这些参数将覆盖全局配置参数。

Session = sessionmaker(engine)

# bind an individual session to a connection

with engine.connect() as connection:
    with Session(bind=connection) as session:
        # work with session

该类还包含一个方法 sessionmaker.configure()，它可用于为工厂指定其他关键字参数，这些参数将对随后生成的 Session 对象生效。这通常用于在首次使用之前将一个或多个 Engine 对象与现有的 sessionmaker 工厂关联。

# application starts, sessionmaker does not have
# an engine bound yet
Session = sessionmaker()

# ... later, when an engine URL is read from a configuration
# file or other events allow the engine to be created
engine = create_engine('sqlite:///foo.db')
Session.configure(bind=engine)

sess = Session()
# work with session

另请参阅

打开和关闭会话 - 关于使用 sessionmaker 创建会话的介绍性文本。

成员

__call__(), __init__(), begin(), close_all(), configure(), identity_key(), object_session()

类签名

class sqlalchemy.orm.sessionmaker (sqlalchemy.orm.session._SessionClassMethods, typing.Generic)

方法 sqlalchemy.orm.sessionmaker.__call__(**local_kw: Any) → _S¶

使用此 sessionmaker 中建立的配置，生成一个新的 Session 对象。

在 Python 中，__call__ 方法在对象被“调用”时被调用，就像调用函数一样。

Session = sessionmaker(some_engine)
session = Session()  # invokes sessionmaker.__call__()

方法 sqlalchemy.orm.sessionmaker.__init__(bind: Optional[_SessionBind] = None, *, class_: Type[_S] = <class 'sqlalchemy.orm.session.Session'>, autoflush: bool = True, expire_on_commit: bool = True, info: Optional[_InfoType] = None, **kw: Any)¶

构造一个新的 sessionmaker。

除了 class_ 之外的所有参数都对应于 Session 直接接受的参数。有关参数的更多详细信息，请参阅 Session.__init__() 文档字符串。

参数:

bind¶ – 一个 Engine 或其他 Connectable，新创建的 Session 对象将与其相关联。
class_¶ – 用于创建新的 Session 对象的类。默认值为 Session。
autoflush¶ –
与新创建的 Session 对象一起使用的 autoflush 设置。

另请参阅

刷新 - 关于 autoflush 的更多背景信息
expire_on_commit=True¶ – 与新创建的 Session 对象一起使用的 Session.expire_on_commit 设置。
info¶ – 可选的字典信息，可通过 Session.info 获得。请注意，当 info 参数指定给特定的 Session 构造操作时，此字典会更新，而不是替换。
**kw¶ – 所有其他关键字参数都会传递给新创建的 Session 对象的构造函数。

方法 sqlalchemy.orm.sessionmaker.begin() → AbstractContextManager[_S]¶

生成一个上下文管理器，它既提供一个新的 Session，也提供一个会提交的事务。

例如

Session = sessionmaker(some_engine)

with Session.begin() as session:
    session.add(some_object)

# commits transaction, closes session

版本 1.4 中的新增功能。

类方法 sqlalchemy.orm.sessionmaker.close_all() → None¶: 继承自 sqlalchemy.orm.session._SessionClassMethods.close_all 方法的 sqlalchemy.orm.session._SessionClassMethods

关闭内存中的所有会话。

从版本 1.3 开始弃用: Session.close_all() 方法已弃用，将在未来版本中删除。请参考 close_all_sessions()。

方法 sqlalchemy.orm.sessionmaker.configure(**new_kw: Any) → None¶

(重新)配置此 sessionmaker 的参数。

例如

Session = sessionmaker()

Session.configure(bind=create_engine('sqlite://'))

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

返回一个标识键。

这是 identity_key() 的别名。

classmethod sqlalchemy.orm.sessionmaker.object_session(instance: object) → Session | None¶

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

返回对象所属的 Session。

这是 object_session() 的别名。

class sqlalchemy.orm.ORMExecuteState¶

表示对 Session.execute() 方法的调用，作为传递给 SessionEvents.do_orm_execute() 事件挂钩的。

版本 1.4 中的新增功能。

另请参阅

执行事件 - 有关如何使用 SessionEvents.do_orm_execute() 的顶级文档

类签名

class sqlalchemy.orm.ORMExecuteState (sqlalchemy.util.langhelpers.MemoizedSlots)

method sqlalchemy.orm.ORMExecuteState.__init__(session: Session, statement: Executable, parameters: _CoreAnyExecuteParams | None, execution_options: _ExecuteOptions, bind_arguments: _BindArguments, compile_state_cls: Type[ORMCompileState] | None, events_todo: List[_InstanceLevelDispatch[Session]])¶

构造一个新的 ORMExecuteState。

此对象在内部构造。

attribute sqlalchemy.orm.ORMExecuteState.all_mappers¶

返回此语句顶级涉及的所有 Mapper 对象的序列。

所谓“顶级”，指的是在 select() 查询的结果集行中，或对于 update() 或 delete() 查询，作为 UPDATE 或 DELETE 主要对象的那些 Mapper 对象。

版本 1.4.0b2 中新增。

另请参阅

ORMExecuteState.bind_mapper

attribute sqlalchemy.orm.ORMExecuteState.bind_arguments: _BindArguments¶

作为 Session.execute.bind_arguments 字典传递的字典。

此字典可由 Session 的扩展使用，以传递参数，这些参数将有助于确定一组数据库连接中应使用哪一个来调用此语句。

attribute sqlalchemy.orm.ORMExecuteState.bind_mapper¶

返回作为主要“绑定”映射器的 Mapper。

对于调用 ORM 语句的 ORMExecuteState 对象，即 ORMExecuteState.is_orm_statement 属性为 True，此属性将返回被认为是语句的“主要”映射器的 Mapper。术语“绑定映射器”是指 Session 对象可以“绑定”到多个 Engine 对象（这些对象与映射的类相关联），而“绑定映射器”则确定将选择哪些 Engine 对象。

对于针对单个映射类调用的语句，ORMExecuteState.bind_mapper 旨在成为获取此映射器的可靠方法。

版本 1.4.0b2 中新增。

另请参阅

ORMExecuteState.all_mappers

attribute sqlalchemy.orm.ORMExecuteState.execution_options: _ExecuteOptions¶

当前执行选项的完整字典。

这是语句级别选项与本地传递的执行选项的合并。

另请参阅

ORMExecuteState.local_execution_options

Executable.execution_options()

ORM 执行选项

method sqlalchemy.orm.ORMExecuteState.invoke_statement(statement: Executable | None = None, params: _CoreAnyExecuteParams | None = None, execution_options: OrmExecuteOptionsParameter | None = None, bind_arguments: _BindArguments | None = None) → Result[Any]¶

执行此 ORMExecuteState 所表示的语句，而无需重新调用已经执行的事件。

此方法实质上执行了当前语句的重新进入执行，对于该语句，SessionEvents.do_orm_execute() 事件正在被调用。此方法的用例是针对希望覆盖最终 Result 对象返回方式的事件处理程序，例如，对于从脱机缓存检索结果或将多个执行的结果连接起来的方案。

当 Result 对象由 SessionEvents.do_orm_execute() 中的实际处理程序函数返回并传播到调用 Session.execute() 方法时，Session.execute() 方法的其余部分将被抢占，并且 Result 对象将立即返回给 Session.execute() 的调用者。

参数:

statement¶ – 要调用的可选语句，代替当前由 ORMExecuteState.statement 表示的语句。
params¶ –
可选的参数字典或参数列表，它将与此 ORMExecuteState 的现有 ORMExecuteState.parameters 合并。

在版本 2.0 中更改: 接受参数字典列表以进行 executemany 执行。
execution_options¶ – 可选的执行选项字典将与此 ORMExecuteState 的现有 ORMExecuteState.execution_options 合并。
bind_arguments¶ – 可选的 bind_arguments 字典将与此 ORMExecuteState 的当前 ORMExecuteState.bind_arguments 合并。

返回值:

具有 ORM 级别的结果的 Result 对象。

另请参阅

重新执行语句 - 有关 ORMExecuteState.invoke_statement() 的适当用法背景和示例。

attribute sqlalchemy.orm.ORMExecuteState.is_column_load¶

如果操作是在刷新现有 ORM 对象上的面向列的属性，则返回 True。

这发生在诸如 Session.refresh() 这样的操作期间，以及当通过 defer() 推迟的属性被加载时，或者通过 Session.expire() 或提交操作直接过期并被加载的属性时。

当发生此类操作时，处理程序很可能不想向查询添加任何选项，因为查询应该是直接主键提取，不应该有任何额外的 WHERE 条件，并且与实例一起传播的加载器选项已经添加到查询中。

版本 1.4.0b2 中新增。

另请参阅

ORMExecuteState.is_relationship_load

attribute sqlalchemy.orm.ORMExecuteState.is_delete¶: 如果这是 DELETE 操作，则返回 True。

版本 2.0.30 中的变化: - 该属性对于针对 Select.from_statement() 构造本身针对 Delete 构造的构造也为 True，例如 select(Entity).from_statement(delete(..))

attribute sqlalchemy.orm.ORMExecuteState.is_executemany¶: 如果参数是包含多个字典的多元素字典列表，则返回 True。

版本 2.0 中的新功能。

attribute sqlalchemy.orm.ORMExecuteState.is_from_statement¶

如果此操作是 Select.from_statement() 操作，则返回 True。

这独立于 ORMExecuteState.is_select，因为 select().from_statement() 构造可以与 INSERT/UPDATE/DELETE RETURNING 类型语句一起使用。 ORMExecuteState.is_select 仅在 Select.from_statement() 本身针对 Select 构造时才会设置。

版本 2.0.30 中的新功能。

attribute sqlalchemy.orm.ORMExecuteState.is_insert¶: 如果这是 INSERT 操作，则返回 True。

版本 2.0.30 中的变化: - 该属性对于针对 Select.from_statement() 构造本身针对 Insert 构造的构造也为 True，例如 select(Entity).from_statement(insert(..))

attribute sqlalchemy.orm.ORMExecuteState.is_orm_statement¶

如果操作是 ORM 语句，则返回 True。

这表明被调用的 select()、insert()、update() 或 delete() 包含 ORM 实体作为主体。对于没有 ORM 实体而是只引用 Table 元数据的语句，它被调用为 Core SQL 语句，不会发生 ORM 级别的自动化。

attribute sqlalchemy.orm.ORMExecuteState.is_relationship_load¶

如果此加载是代表关系加载对象，则返回 True。

这意味着，有效的加载器是 LazyLoader、SelectInLoader、SubqueryLoader 或类似加载器，并且正在发出的整个 SELECT 语句是代表关系加载。

当发生此类操作时，处理程序很可能不想向查询添加任何选项，因为加载器选项已经能够传播到关系加载器，并且应该已经存在。

另请参阅

ORMExecuteState.is_column_load

attribute sqlalchemy.orm.ORMExecuteState.is_select¶: 如果这是 SELECT 操作，则返回 True。

版本 2.0.30 中的变化: - 该属性对于针对 Select.from_statement() 构造本身针对 Select 构造的构造也为 True，例如 select(Entity).from_statement(select(..))

attribute sqlalchemy.orm.ORMExecuteState.is_update¶: 如果这是 UPDATE 操作，则返回 True。

版本 2.0.30 中的变化: - 该属性对于针对 Select.from_statement() 构造本身针对 Update 构造的构造也为 True，例如 select(Entity).from_statement(update(..))

attribute sqlalchemy.orm.ORMExecuteState.lazy_loaded_from¶

一个 InstanceState，它正在使用此语句执行进行延迟加载操作。

此属性的主要原理是支持水平分片扩展，它在由该扩展创建的特定查询执行时间挂钩内可用。为此，该属性仅在 **查询执行时** 有意义，重要的是，在查询执行时间之前，包括查询编译时间，该属性没有任何意义。

attribute sqlalchemy.orm.ORMExecuteState.load_options¶: 返回将用于此执行的 load_options。

attribute sqlalchemy.orm.ORMExecuteState.loader_strategy_path¶

返回当前加载路径的 PathRegistry。

此对象表示当加载特定对象或集合时，通过关系的查询中的“路径”。

attribute sqlalchemy.orm.ORMExecuteState.local_execution_options: _ExecuteOptions¶

传递给 Session.execute() 方法的执行选项的字典视图。

这并不包括可能与正在调用的语句关联的选项。

另请参阅

ORMExecuteState.execution_options

属性 sqlalchemy.orm.ORMExecuteState.parameters: _CoreAnyExecuteParams | None¶: 传递给 Session.execute() 的参数字典。

属性 sqlalchemy.orm.ORMExecuteState.session: Session¶: 正在使用的 Session。

属性 sqlalchemy.orm.ORMExecuteState.statement: Executable¶

正在调用的 SQL 语句。

对于从 Query 中检索到的 ORM 选择，这是一个从 ORM 查询生成的 select 实例。

属性 sqlalchemy.orm.ORMExecuteState.update_delete_options¶: 返回将用于此执行的 update_delete_options。

方法 sqlalchemy.orm.ORMExecuteState.update_execution_options(**opts: Any) → None¶: 使用新值更新本地执行选项。

属性 sqlalchemy.orm.ORMExecuteState.user_defined_options¶: 已与正在调用的语句关联的 UserDefinedOptions 序列。

类 sqlalchemy.orm.Session¶

管理 ORM 映射对象的持久化操作。

Session 不适合在并发线程中使用。有关背景信息，请参见 Session 是线程安全的吗？AsyncSession 在并发任务中共享安全吗？。

使用 Session 中描述了 Session 的使用模式。

类签名

类 sqlalchemy.orm.Session (sqlalchemy.orm.session._SessionClassMethods, sqlalchemy.event.registry.EventTarget)

method sqlalchemy.orm.Session.__init__(bind: _SessionBind | None = None, *, autoflush: bool = True, future: Literal[True] = True, expire_on_commit: bool = True, autobegin: bool = True, twophase: bool = False, binds: Dict[_SessionBindKey, _SessionBind] | None = None, enable_baked_queries: bool = True, info: _InfoType | None = None, query_cls: Type[Query[Any]] | None = None, autocommit: Literal[False] = False, join_transaction_mode: JoinTransactionMode = 'conditional_savepoint', close_resets_only: bool | _NoArg = _NoArg.NO_ARG)¶

构造一个新的 Session。

另请参见 sessionmaker 函数，该函数用于生成一个使用给定参数集产生 Session 的可调用对象。

参数:

autoflush¶ –
当为 True 时，所有查询操作将在继续之前向此 Session 发出 Session.flush() 调用。这是一个便利的功能，因此不必重复调用 Session.flush() 才能使数据库查询检索结果。

另请参阅

刷新 - 关于 autoflush 的更多背景信息
autobegin¶ –
在请求数据库访问的操作时自动开始事务（即等效于调用 Session.begin()）。默认值为 True。设置为 False 以防止 Session 在构造后以及在调用任何 Session.rollback()、Session.commit() 或 Session.close() 方法后隐式开始事务。

版本 2.0 中的新功能。

另请参阅

禁用 Autobegin 以防止隐式事务
bind¶ – 一个可选的 Engine 或 Connection，此 Session 应该绑定到该对象。当指定此参数时，此会话执行的所有 SQL 操作都将通过此连接对象执行。
binds¶ –
一个字典，可以按实体指定任意数量的 Engine 或 Connection 对象作为 SQL 操作的连接源。字典的键由任何一系列映射类、作为映射类基类的任意 Python 类、Table 对象和 Mapper 对象组成。然后，字典的值是 Engine 的实例，或者不太常见的是 Connection 对象。相对于特定映射类进行的操作将查询此字典以查找最匹配的实体，以确定应使用哪个 Engine 用于特定 SQL 操作。在 Session.get_bind() 中描述了用于解析的完整启发式方法。用法如下
```
Session = sessionmaker(binds={
    SomeMappedClass: create_engine('postgresql+psycopg2://engine1'),
    SomeDeclarativeBase: create_engine('postgresql+psycopg2://engine2'),
    some_mapper: create_engine('postgresql+psycopg2://engine3'),
    some_table: create_engine('postgresql+psycopg2://engine4'),
    })
```
另请参阅

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

Session.bind_mapper()

Session.bind_table()

Session.get_bind()
class_¶ – 指定除了 sqlalchemy.orm.session.Session 之外的其他类，该类应由返回的类使用。这是 sessionmaker 函数特有的唯一参数，不会直接发送到 Session 的构造函数。
enable_baked_queries¶ –
遗留参数；默认为 True。由 sqlalchemy.ext.baked 扩展使用的参数，以确定是否应缓存“烘焙查询”，这与此扩展的正常操作一致。当设置为 False 时，将禁用此特定扩展使用的缓存。

版本 1.4 中的变更: sqlalchemy.ext.baked 扩展已过时，SQLAlchemy 的任何内部机制都不再使用它。因此，此标志仅影响在其自身代码中显式使用此扩展的应用程序。
expire_on_commit¶ –
默认值为 True。当为 True 时，在每次 commit() 之后，所有实例将完全过期，因此，在完成事务后对所有属性/对象访问都将从最新的数据库状态加载。

另请参阅

提交
future¶ –
已弃用；此标志始终为 True。

另请参阅

SQLAlchemy 2.0 - 主要迁移指南
info¶ – 与此 Session 关联的任意数据的可选字典。可通过 Session.info 属性访问。请注意，字典在构造时被复制，因此对每个 Session 字典的修改将是针对该 Session 本地的。
query_cls¶ – 用于创建新 Query 对象的类，由 Session.query() 方法返回。默认为 Query.
twophase¶ – 当 True 时，所有事务都将启动为“两阶段”事务，即使用所用数据库的“两阶段”语义以及 XID。在 commit() 期间，在对所有附加的数据库发出 flush() 之后，将调用每个数据库的 TwoPhaseTransaction.prepare() 方法上的 TwoPhaseTransaction。这使每个数据库都能回滚整个事务，然后再提交每个事务。
autocommit¶ – “autocommit” 关键字是为了向后兼容而存在的，但必须保持其默认值 False。
join_transaction_mode¶ –
描述当给定绑定为 Connection 时要采取的事务行为，该连接已在此 Session 的范围之外开始事务；换句话说，Connection.in_transaction() 方法返回 True。

以下行为仅在给定连接实际被 Session 使用时才会生效；也就是说，当实际调用 Session.execute()、Session.connection() 等方法时。
- "conditional_savepoint" - 这是默认值。如果给定的 Connection 在事务内启动，但没有 SAVEPOINT，则使用 "rollback_only"。如果 Connection 还在 SAVEPOINT 内，换句话说，Connection.in_nested_transaction() 方法返回 True，则使用 "create_savepoint"。
  
  "conditional_savepoint" 行为尝试利用 savepoint 来保持现有事务的状态不变，但前提是已经有一个 savepoint 在进行中；否则，不认为所用的后端对 SAVEPOINT 提供了充分的支持，因为此功能的可用性各不相同。 "conditional_savepoint" 还试图为不设置特定模式的应用程序建立与以前 Session 行为的近似向后兼容性。建议使用显式设置之一。
- "create_savepoint" - Session 将在所有情况下使用 Connection.begin_nested() 来创建自己的事务。这种事务本质上位于给定的 Connection 上打开的任何现有事务之上；如果所用驱动程序和底层数据库对 SAVEPOINT 提供了完整的、无故障的支持，则外部事务将在 Session 的整个生命周期内保持不受影响。
  
  当将 Session 集成到测试套件中，其中外部启动的事务应保持不受影响时，"create_savepoint" 模式非常有用；但是，它依赖于底层驱动程序和数据库对 SAVEPOINT 的适当支持。
  
  提示
  
  当使用 SQLite 时，通过 Python 3.11 包含的 SQLite 驱动程序在没有解决方法的情况下，在所有情况下都无法正确处理 SAVEPOINT。有关当前解决方法的详细信息，请参阅部分可序列化隔离/Savepoints/事务性 DDL 和可序列化隔离/Savepoints/事务性 DDL (asyncio 版本)。
- "control_fully" - Session 将完全控制给定事务；Session.commit() 将在事务上调用 .commit()，Session.rollback() 将在事务上调用 .rollback()，Session.close() 将在事务上调用 .rollback。
  
  提示
  
  这种使用方法等同于 SQLAlchemy 1.4 处理给定具有现有 SAVEPOINT 的 Connection 的方式（即 Connection.begin_nested()）；Session 将完全控制现有 SAVEPOINT。
- "rollback_only" - Session 将控制给定事务以进行 .rollback() 调用；.commit() 调用将不会传播到给定事务。 .close() 调用将不会对给定事务产生任何影响。
  
  提示
  
  这种使用模式等同于 SQLAlchemy 1.4 如何处理使用现有常规数据库事务（即 Connection.begin()）提供的 Connection；Session 将把 Session.rollback() 调用传播到底层事务，但不会传播 Session.commit() 或 Session.close() 调用。
2.0.0rc1 版本新增。
close_resets_only¶ –
默认值为 True。确定会话在调用 .close() 后是否应该重置自身，或者应该进入不可用状态，禁用重复使用。

2.0.22 版本新增：添加了标志 close_resets_only。未来的 SQLAlchemy 版本可能会将此标志的默认值更改为 False。

另请参阅

关闭 - 关于 Session.close() 和 Session.reset() 语义的详细信息。

method sqlalchemy.orm.Session.add(instance: object, _warn: bool = True) → None¶

将一个对象放入此 Session 中。

传递给 Session.add() 方法时处于瞬态状态的对象将移至待定状态，直到下一次刷新，此时它们将移至持久状态。

传递给 Session.add() 方法时处于分离状态的对象将直接移至持久状态。

如果 Session 使用的事务回滚，则传递给 Session.add() 时处于瞬态的对象将移回瞬态状态，并且将不再存在于此 Session 中。

另请参阅

Session.add_all()

添加新项目或现有项目 - 在使用会话的基础

method sqlalchemy.orm.Session.add_all(instances: Iterable[object]) → None¶

将给定的实例集合添加到此 Session 中。

有关一般行为描述，请参阅 Session.add() 的文档。

另请参阅

Session.add()

添加新项目或现有项目 - 在使用会话的基础

method sqlalchemy.orm.Session.begin(nested: bool = False) → SessionTransaction¶

在该 Session 上开始一个事务或嵌套事务（如果尚未开始）。

Session 对象具有 **自动开始** 行为，因此通常不必显式调用 Session.begin() 方法。但是，它可以用于控制事务状态何时开始。

当用于开始最外层事务时，如果该 Session 已经在事务中，则会引发错误。

参数:: nested¶ – 如果为 True，则开始一个 SAVEPOINT 事务，等同于调用 Session.begin_nested()。有关 SAVEPOINT 事务的文档，请参阅使用 SAVEPOINT。
返回值:: SessionTransaction 对象。请注意，SessionTransaction 充当 Python 上下文管理器，允许 Session.begin() 在“with”块中使用。有关示例，请参阅显式开始。

另请参阅

自动开始

管理事务

Session.begin_nested()

method sqlalchemy.orm.Session.begin_nested() → SessionTransaction¶

在该 Session 上开始一个“嵌套”事务，例如 SAVEPOINT。

目标数据库及其关联的驱动程序必须支持 SQL SAVEPOINT，此方法才能正常工作。

有关 SAVEPOINT 事务的文档，请参阅使用 SAVEPOINT。

返回值:: SessionTransaction 对象。请注意，SessionTransaction 充当上下文管理器，允许 Session.begin_nested() 在“with”块中使用。有关使用示例，请参阅使用 SAVEPOINT。

另请参阅

使用 SAVEPOINT

可序列化隔离/保存点/事务性 DDL - SQLite 驱动程序需要特殊的解决方法才能使 SAVEPOINT 正确工作。对于 asyncio 使用情况，请参阅部分可序列化隔离/保存点/事务性 DDL (asyncio 版本)。

method sqlalchemy.orm.Session.bind_mapper(mapper: _EntityBindKey[_O], bind: _SessionBind) → None¶

将一个 Mapper 或任意 Python 类与一个“绑定”关联，例如一个 Engine 或 Connection.

给定的实体将被添加到 Session.get_bind() 方法使用的查找中。

参数:

mapper¶ – 一个 Mapper 对象，或一个映射类实例，或任何作为一组映射类的基类的 Python 类。
bind¶ – 一个 Engine 或 Connection 对象。

另请参阅

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

Session.binds

Session.bind_table()

method sqlalchemy.orm.Session.bind_table(table: TableClause, bind: Engine | Connection) → None¶

将一个 Table 与一个“绑定”关联，例如一个 Engine 或 Connection.

给定的 Table 将被添加到 Session.get_bind() 方法使用的查找中。

参数:

table¶ – 一个 Table 对象，它通常是 ORM 映射的目标，或者存在于映射的可选对象中。
bind¶ – 一个 Engine 或 Connection 对象。

另请参阅

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

Session.binds

Session.bind_mapper()

method sqlalchemy.orm.Session.bulk_insert_mappings(mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]], return_defaults: bool = False, render_nulls: bool = False) → None¶

对给定的映射字典列表执行批量插入。

遗留功能

从 SQLAlchemy 2.0 版本开始，此方法是一个遗留功能。对于现代批量 INSERT 和 UPDATE，请参见部分 ORM 批量 INSERT 语句和 ORM 按主键批量 UPDATE。2.0 API 与此方法共享实现细节，并添加了新功能。

参数:

mapper¶ – 一个映射类，或实际的 Mapper 对象，表示映射列表中表示的单一对象类型。
mappings¶ – 一系列字典，每个字典包含要插入的映射行的状态，以映射类上的属性名称表示。如果映射引用多个表，例如联接继承映射，则每个字典必须包含填充所有表的所有键。
return_defaults¶ –
当为 True 时，INSERT 过程将被修改以确保获取新生成的主键值。此参数的理由通常是使联接表继承映射能够批量插入。

注意

对于不支持 RETURNING 的后端， Session.bulk_insert_mappings.return_defaults 参数会显著降低性能，因为 INSERT 语句无法再进行批处理。有关受影响后端的信息，请参见 INSERT 语句的“插入多个值”行为。
render_nulls¶ –
当为 True 时，None 值将导致 NULL 值被包含在 INSERT 语句中，而不是从 INSERT 中省略该列。这使所有要插入的行具有相同的列集，从而使所有行的完整集能够批处理到 DBAPI。通常，每个包含与前一行不同的 NULL 值组合的列集必须从渲染的 INSERT 语句中省略不同的列序列，这意味着它必须作为单独的语句发出。通过传递此标志，可以保证所有行的完整集能够批处理到一个批次中；然而，代价是会跳过通过省略列调用的服务器端默认值，因此必须注意确保这些默认值不是必要的。

警告

当设置此标志时，服务器端默认 SQL 值不会被调用，对于那些插入为 NULL 的列；NULL 值将被显式发送。必须注意确保整个操作不需要调用任何服务器端默认函数。

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

Session.bulk_save_objects()

Session.bulk_update_mappings()

method sqlalchemy.orm.Session.bulk_save_objects(objects: Iterable[object], return_defaults: bool = False, update_changed_only: bool = True, preserve_order: bool = True) → None¶

对给定的对象列表执行批量保存。

遗留功能

此方法是 SQLAlchemy 2.0 系列中的遗留功能。有关现代的批量 INSERT 和 UPDATE，请参阅以下部分：ORM 批量 INSERT 语句和 ORM 通过主键进行批量 UPDATE.

对于现有 ORM 映射对象的常规 INSERT 和 UPDATE，建议使用标准的工作单元数据管理模式，这些模式在 SQLAlchemy 统一教程中的使用 ORM 进行数据操作中介绍。SQLAlchemy 2.0 现在使用 INSERT 语句的“插入多个值”行为，该行为适用于现代方言，解决了以前批量 INSERT 速度慢的问题。

参数:

objects¶ –
一个映射对象实例的序列。映射对象将按原样持久化，并且不会与 Session 相关联。

对于每个对象，对象是作为 INSERT 还是 UPDATE 发送取决于 Session 在传统操作中使用的相同规则；如果对象具有 InstanceState.key 属性集，则该对象被认为是“分离”的，并将导致 UPDATE。否则，将使用 INSERT。

在 UPDATE 的情况下，语句将根据哪些属性已更改进行分组，因此成为每个 SET 子句的主题。如果 update_changed_only 为 False，则每个对象中存在的全部属性将应用于 UPDATE 语句，这可能有助于将语句分组到更大的 executemany() 中，并且还会减少检查属性历史记录的开销。
return_defaults¶ – 当为 True 时，缺少生成默认值的行的行，即整数主键默认值和序列，将一次插入一行，以便主键值可用。尤其是这将允许连接继承和其他多表映射在没有提前提供主键值的情况下正确插入；但是，Session.bulk_save_objects.return_defaults 极大地降低了该方法的整体性能优势。强烈建议您使用标准的 Session.add_all() 方法。
update_changed_only¶ – 当为 True 时，UPDATE 语句将根据每个状态中记录更改的那些属性呈现。当为 False 时，所有存在的属性将呈现到 SET 子句中，主键属性除外。
preserve_order¶ – 当为 True 时，插入和更新的顺序与提供对象的顺序完全匹配。当为 False 时，通用类型的对象将分组到插入和更新中，以允许更多的批处理机会。

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

Session.bulk_insert_mappings()

Session.bulk_update_mappings()

method sqlalchemy.orm.Session.bulk_update_mappings(mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]]) → None¶

对给定的映射字典列表执行批量更新。

遗留功能

从 SQLAlchemy 2.0 版本开始，此方法是一个遗留功能。对于现代批量 INSERT 和 UPDATE，请参见部分 ORM 批量 INSERT 语句和 ORM 按主键批量 UPDATE。2.0 API 与此方法共享实现细节，并添加了新功能。

参数:

mapper¶ – 一个映射类或实际的 Mapper 对象，表示映射列表中表示的单个对象类型。
mappings¶ – 一个字典序列，每个字典包含要更新的映射行的状态，以映射类上的属性名称表示。如果映射引用多个表，例如连接继承映射，则每个字典可能包含对应于所有表的键。所有存在的键，只要不是主键的一部分，就会应用于 UPDATE 语句的 SET 子句；主键值是必需的，将应用于 WHERE 子句。

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

Session.bulk_insert_mappings()

Session.bulk_save_objects()

method sqlalchemy.orm.Session.close() → None¶

关闭此 Session 使用的事务资源和 ORM 对象。

这将删除与此 Session 相关联的所有 ORM 对象，结束正在进行的任何事务，并释放此 Session 本身从关联的 Engine 对象中签出的任何 Connection 对象。然后，此操作将使 Session 处于可以再次使用的状态。

提示

在默认运行模式下，Session.close() 方法不会阻止 Session 再次使用。Session 本身实际上没有不同的“关闭”状态；它只是意味着 Session 将释放所有数据库连接和 ORM 对象。

将参数 Session.close_resets_only 设置为 False 将使 close 最终，这意味着禁止对会话执行任何进一步的操作。

在 1.4 版中更改: Session.close() 方法不会立即创建一个新的 SessionTransaction 对象；相反，只有在 Session 再次用于数据库操作时，才会创建新的 SessionTransaction 对象。

另请参阅

关闭 - 关于 Session.close() 和 Session.reset() 语义的详细信息。

Session.reset() - 一个类似的方法，其行为类似于 close()，其中参数 Session.close_resets_only 设置为 True。

classmethod sqlalchemy.orm.Session.close_all() → None¶: 继承自 sqlalchemy.orm.session._SessionClassMethods.close_all 方法的 sqlalchemy.orm.session._SessionClassMethods

关闭内存中的所有会话。

从版本 1.3 开始弃用: Session.close_all() 方法已弃用，将在未来版本中删除。请参考 close_all_sessions()。

method sqlalchemy.orm.Session.commit() → None¶

刷新挂起的更改并提交当前事务。

当 COMMIT 操作完成时，所有对象将完全过期，擦除其内部内容，这些内容将在下次访问对象时自动重新加载。在此期间，这些对象处于过期状态，如果它们分离自Session，则无法正常工作。此外，在使用面向 asyncio 的 API 时，不支持此重新加载操作。该Session.expire_on_commit参数可用于禁用此行为。

当Session中没有事务，这表明自上次调用Session.commit()以来，没有对该Session执行任何操作，该方法将开始并提交一个仅用于内部的“逻辑”事务，该事务通常不会影响数据库，除非检测到挂起的刷新更改，但仍将调用事件处理程序和对象过期规则。

最外层的数据库事务将无条件提交，自动释放生效的任何 SAVEPOINT。

另请参阅

提交

管理事务

使用 AsyncSession 时阻止隐式 IO

method sqlalchemy.orm.Session.connection(bind_arguments: _BindArguments | None = None, execution_options: CoreExecuteOptionsParameter | None = None) → Connection¶

返回一个Connection对象，对应于此Session对象的交易状态。

要么返回对应于当前事务的Connection，要么如果当前没有事务，则开始一个新事务并返回Connection（注意，直到发出第一个 SQL 语句，DBAPI 才与数据库建立交易状态）。

多绑定或未绑定Session对象中的歧义可以通过任何可选的关键字参数来解决。这最终使得使用该get_bind()方法进行解析。

参数:

bind_arguments¶ – 绑定参数字典。可以包含“mapper”、“bind”、“clause”和其他传递给Session.get_bind()的自定义参数。
execution_options¶ –
传递给Connection.execution_options()的执行选项字典，仅在首次获取连接时。如果连接已存在于Session中，则会发出警告并忽略这些参数。

另请参阅

设置事务隔离级别/DBAPI AUTOCOMMIT

method sqlalchemy.orm.Session.delete(instance: object) → None¶

将实例标记为已删除。

假定传递的对象是持久化的或分离的；在调用该方法后，该对象将保持在持久化状态，直到下一次刷新完成。在此期间，该对象也将是Session.deleted集合的成员。

当下次刷新进行时，该对象将移动到已删除状态，表示已为其在当前事务中的行发出DELETE语句。当事务成功提交时，已删除的对象将移动到分离状态，并且不再存在于此Session中。

另请参阅

删除 - 在使用 Session 的基础知识

attribute sqlalchemy.orm.Session.deleted¶: 此Session中所有标记为“已删除”的实例的集合

attribute sqlalchemy.orm.Session.dirty¶

所有被视为脏的持久化实例的集合。

例如：

some_mapped_object in session.dirty

当实例被修改但没有被删除时，它们被视为脏的。

请注意，此“脏”计算是“乐观的”；大多数属性设置或集合修改操作将标记实例为“脏”，并将其放入此集合中，即使属性的值没有净变化也是如此。在刷新时，每个属性的值都会与其之前保存的值进行比较，如果没有净变化，则不会发生任何 SQL 操作（这是一个更昂贵的操作，因此只在刷新时执行）。

要检查实例的属性是否具有可操作的净变化，请使用该Session.is_modified()方法。

method sqlalchemy.orm.Session.enable_relationship_loading(obj: object) → None¶

将对象与此Session关联以进行相关对象加载。

警告

enable_relationship_loading()存在于服务特殊用例，不建议在一般情况下使用。

使用relationship()映射的属性的访问将尝试使用此Session作为连接来源从数据库加载值。这些值将根据此对象上存在的外部键和主键值进行加载 - 如果不存在，则这些关系将不可用。

该对象将附加到此会话，但不会参与任何持久化操作；它的状态在几乎所有情况下都将保持“瞬态”或“分离”状态，除了关系加载的情况。

还要注意，反向引用通常不会按预期工作。如果有效值是已从持有外键的值加载的值，则更改目标对象上的关系绑定属性可能不会触发反向引用事件。

方法与 relationship() 上的 load_on_pending 标志类似。与该标志不同，Session.enable_relationship_loading() 允许对象保持瞬态，同时仍然能够加载相关项。

要使瞬态对象与 Session 通过 Session.enable_relationship_loading() 相关联，请使用 Session.add() 将其添加到 Session 中。如果该对象代表数据库中已存在的标识，则应使用 Session.merge() 合并它。

Session.enable_relationship_loading() 在 ORM 正常使用时不会改善行为 - 对象引用应在对象级别构建，而不是在外键级别构建，以便在 flush() 继续之前以普通方式存在。此方法不适用于一般用途。

另请参阅

relationship.load_on_pending - 此标志允许在待处理的项目上对多对一进行逐个关系加载。

make_transient_to_detached() - 允许将对象添加到 Session 而不发出 SQL，然后在访问时会取消属性的过期状态。

method sqlalchemy.orm.Session.execute(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, _parent_execute_state: Any | None = None, _add_event: Any | None = None) → Result[Any]¶

执行 SQL 表达式构造。

返回一个 Result 对象，表示语句执行的结果。

例如：

from sqlalchemy import select
result = session.execute(
    select(User).where(User.id == 5)
)

方法的 API 契约与 Connection.execute() 类似，2.0 风格版本的 Connection。

在版本 1.4 中更改：方法现在是使用 2.0 风格 ORM 使用时 ORM 语句执行的主要方式。

参数:

statement¶ – 可执行语句（即 Executable 表达式，例如 select()）。
params¶ – 可选字典或字典列表，包含绑定参数值。如果是单个字典，则执行单行；如果是字典列表，则将调用“executemany”。每个字典中的键必须与语句中存在的参数名称相对应。
execution_options¶ –
可选的执行选项字典，它将与语句执行相关联。此字典可以提供 Connection.execution_options() 接受的选项的子集，并且还可以提供仅在 ORM 上下文中理解的额外选项。

另请参阅

ORM 执行选项 - ORM 特定的执行选项
bind_arguments¶ – 确定绑定的附加参数字典。可能包括“mapper”、“bind”或其他自定义参数。此字典的内容将传递给 Session.get_bind() 方法。

返回值:

一个 Result 对象。

method sqlalchemy.orm.Session.expire(instance: object, attribute_names: Iterable[str] | None = None) → None¶

使实例上的属性失效。

将实例的属性标记为过期。当下次访问过期的属性时，将向 Session 对象的当前事务上下文发出查询，以便加载给定实例的所有过期属性。请注意，高度隔离的事务将返回与该事务中先前读取的值相同的值，而与该事务之外的数据库状态的变化无关。

要使 Session 中的所有对象同时失效，请使用 Session.expire_all()。

默认情况下，Session 对象在调用 Session.rollback() 或 Session.commit() 方法时会使所有状态失效，以便为新事务加载新状态。因此，调用 Session.expire() 仅适用于在当前事务中发出非 ORM SQL 语句的特定情况。

参数:

instance¶ – 要刷新的实例。
attribute_names¶ – 可选的字符串属性名称列表，指示要失效的属性子集。

另请参阅

刷新/失效 - 概述

Session.expire()

Session.refresh()

Query.populate_existing()

method sqlalchemy.orm.Session.expire_all() → None¶

使此 Session 中的所有持久实例失效。

当下次访问持久实例上的任何属性时，将使用 Session 对象的当前事务上下文发出查询，以加载给定实例的所有失效属性。请注意，高度隔离的事务将返回与在该事务中先前读取的值相同的值，无论该事务之外的数据库状态发生什么变化。

要使单个对象和这些对象上的单个属性失效，请使用 Session.expire()。

默认情况下，Session 对象在调用 Session.rollback() 或 Session.commit() 方法时会使所有状态失效，以便为新事务加载新状态。因此，通常不需要调用 Session.expire_all()，假设事务是隔离的。

另请参阅

刷新/失效 - 概述

Session.expire()

Session.refresh()

Query.populate_existing()

method sqlalchemy.orm.Session.expunge(instance: object) → None¶

从此 Session 中删除 instance。

这将释放对实例的所有内部引用。级联将根据expunge级联规则应用。

method sqlalchemy.orm.Session.expunge_all() → None¶

从此 Session 中删除所有对象实例。

这等效于对 Session 中的所有对象调用 expunge(obj)。

method sqlalchemy.orm.Session.flush(objects: Sequence[Any] | None = None) → None¶

将所有对象更改刷新到数据库中。

将所有待处理的对象创建、删除和修改写入数据库，作为 INSERT、DELETE、UPDATE 等。操作会根据 Session 的工作单元依赖性解析器自动排序。

数据库操作将在当前事务上下文中发出，不会影响事务的状态，除非发生错误，在这种情况下，整个事务将回滚。您可以在事务中多次调用 flush()，以将更改从 Python 移动到数据库的事务缓冲区。

参数:

objects¶ –

可选；将刷新操作限制在给定集合中的元素上。

此功能适用于极少数用例，在这些用例中，可能需要在完整 flush() 发生之前对特定对象进行操作。它不适合一般用途。

method sqlalchemy.orm.Session.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}
)

New in version 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 sqlalchemy.orm.Session.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 绑定的“绑定”。

“绑定”通常是 Engine 的实例，但如果 Session 已明确直接绑定到 Connection，则情况并非如此。

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

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

解析顺序为

如果给定了 mapper 且 Session.binds 存在，则首先根据正在使用的 mapper、然后根据正在使用的映射类、然后根据映射类 __mro__ 中存在的任何基类（从更具体的超类到更通用的超类）查找绑定。
如果给定了 clause 且 Session.binds 存在，则根据给定 clause 中找到的 Table 对象（存在于 Session.binds 中）查找绑定。
如果 Session.binds 存在，则返回它。
如果给定了 clause，则尝试返回链接到与 clause 最终关联的 MetaData 的绑定。
如果给定了 mapper，则尝试返回链接到与 Table 或其他可选映射相关联的 MetaData 的绑定。
找不到绑定，将引发 UnboundExecutionError。

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

参数:

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

另请参阅

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

Session.binds

Session.bind_mapper()

Session.bind_table()

method sqlalchemy.orm.Session.get_nested_transaction() → SessionTransaction | None¶: 返回当前正在进行的嵌套事务（如果有）。

版本 1.4 中的新增功能。

method sqlalchemy.orm.Session.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 sqlalchemy.orm.Session.get_transaction() → SessionTransaction | None¶: 返回当前正在进行的根事务（如果有）。

版本 1.4 中的新增功能。

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

返回一个标识键。

这是 identity_key() 的别名。

attribute sqlalchemy.orm.Session.identity_map: IdentityMap¶

对象标识与其自身对象的映射。

遍历 Session.identity_map.values() 可以访问会话中当前的所有持久对象（即具有行标识的那些对象）。

另请参阅

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

method sqlalchemy.orm.Session.in_nested_transaction() → bool¶: 如果此 Session 已经开始嵌套事务（例如 SAVEPOINT），则返回 True。

版本 1.4 中的新增功能。

method sqlalchemy.orm.Session.in_transaction() → bool¶: 如果此 Session 已经开始事务，则返回 True。

版本 1.4 中的新增功能。

另请参阅

Session.is_active

attribute sqlalchemy.orm.Session.info¶

用户可修改的字典。

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

method sqlalchemy.orm.Session.invalidate() → None¶

使用连接失效来关闭此 Session。

这是 Session.close() 的一个变体，它还会额外确保 Connection.invalidate() 方法将被调用在当前用于事务的每个 Connection 对象上（通常只有一个连接，除非 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 sqlalchemy.orm.Session.is_active¶

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

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

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

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

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

另请参阅

“此 Session 的事务已回滚，因为之前刷新期间发生了异常。”（或类似的）

Session.in_transaction()

method sqlalchemy.orm.Session.is_modified(instance: object, include_collections: bool = True) → bool¶

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

此方法检索实例上每个被检测属性的历史记录，并比较当前值与其之前刷新或提交的值（如果有）。

它实际上是检查给定实例是否在 Session.dirty 集合中的更昂贵且更准确的版本；对每个属性的净“脏”状态执行完整测试。

例如：

return session.is_modified(someobject)

此方法有一些注意事项

存在于 Session.dirty 集合中的实例在使用此方法测试时可能报告 False。这是因为对象可能已通过属性变异接收更改事件，从而将其置于 Session.dirty 中，但最终状态与从数据库加载的状态相同，因此这里没有净变化。
如果在接收新值时未加载标量属性，或者已过期，则标量属性可能不会记录之前设置的值，在这种情况下，假设该属性发生了更改，即使最终相对于其数据库值没有净更改。在大多数情况下，SQLAlchemy 不需要“旧”值，因此如果旧值不存在，它会跳过执行 SQL 调用的开销，这是基于以下假设：通常需要对标量值进行 UPDATE，在少数不需要的情况下，平均而言，这比发出防御性 SELECT 便宜。

只有当属性容器的 active_history 标志设置为 True 时，才会在设置时无条件地获取“旧”值。此标志通常用于主键属性和不是简单多对一的标量对象引用。要为任何任意映射的列设置此标志，请将 active_history 参数与 column_property() 一起使用。

参数:

instance¶ – 要测试是否存在未决更改的映射实例。
include_collections¶ – 指示是否应在操作中包含多值集合。将其设置为 False 是一种方法来检测仅会导致在刷新时对该实例进行 UPDATE 的基于本地列的属性（即标量列或多对一外键）。

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

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

Session.merge() 检查源实例的主键属性，并尝试将其与会话中具有相同主键的实例协调。如果本地未找到，它将尝试根据主键从数据库中加载对象，如果找不到，则创建一个新实例。然后，源实例上的每个属性的状态将被复制到目标实例。然后，方法将返回生成的 target 实例；原始 source 实例保持不变，并且如果尚未与 Session 关联，则与 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 sqlalchemy.orm.Session.new¶: 此 Session 中标记为“新”的所有实例的集合。

attribute sqlalchemy.orm.Session.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 sqlalchemy.orm.Session.object_session(instance: object) → Session | None¶

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

返回对象所属的 Session。

这是 object_session() 的别名。

method sqlalchemy.orm.Session.prepare() → None¶

为当前正在进行的事务准备两阶段提交。

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

只有两阶段会话的根事务才能准备。如果当前事务不是这样的，则会引发 InvalidRequestError。

method sqlalchemy.orm.Session.query(*entities: _ColumnsClauseArgument[Any], **kwargs: Any) → Query[Any]¶

返回对应于此 Session 的新的 Query 对象。

请注意，从 SQLAlchemy 2.0 开始，Query 对象是遗留的；select() 构造现在用于构建 ORM 查询。

另请参阅

SQLAlchemy 统一教程

ORM 查询指南

Legacy Query API - 遗留 API 文档

method sqlalchemy.orm.Session.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（或“延迟”）加载器策略加载，也会加载 **如果它们在属性名称集合中被明确命名**，则使用 immediate 加载器策略为属性发出 SELECT 语句。如果延迟加载的关系未在 Session.refresh.attribute_names 中命名，则它们保持为“延迟加载”属性，并且不会被隐式刷新。

版本 2.0.4 中的更改： Session.refresh() 方法现在将刷新延迟加载的 relationship() 面向的属性，这些属性在 Session.refresh.attribute_names 集合中被明确命名。

提示

尽管 Session.refresh() 方法能够刷新列和关系导向的属性，但其主要重点是刷新单个实例上的本地列导向属性。对于更开放的“刷新”功能，包括能够一次刷新多个对象上的属性，同时对关系加载器策略有明确的控制，请使用填充现有功能。

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

参数:

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 sqlalchemy.orm.Session.reset() → None¶

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

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

版本 2.0.22 中的新增功能。

另请参阅

关闭 - 关于 Session.close() 和 Session.reset() 语义的详细信息。

Session.close() - 当参数 Session.close_resets_only 设置为 False 时，类似的方法将另外阻止对 Session 的重新使用。

method sqlalchemy.orm.Session.rollback() → None¶

回滚正在进行的当前事务。

如果没有事务正在进行，则此方法是直通方法。

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

另请参阅

回滚

管理事务

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

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

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

method sqlalchemy.orm.Session.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()

成员

nested, origin, parent

类签名

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

attribute sqlalchemy.orm.SessionTransaction.nested: bool = False¶

指示这是否是一个嵌套的（或 SAVEPOINT）事务。

当 SessionTransaction.nested 为 True 时，预期 SessionTransaction.parent 也会存在，并链接到封闭的 SessionTransaction.

另请参阅

SessionTransaction.origin

attribute sqlalchemy.orm.SessionTransaction.origin: SessionTransactionOrigin¶

此 SessionTransaction 的来源。

引用一个 SessionTransactionOrigin 实例，该实例是一个枚举，表示导致构建此 SessionTransaction 的源事件。

版本 2.0 中的新功能。

attribute sqlalchemy.orm.SessionTransaction.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

类签名

class sqlalchemy.orm.SessionTransactionOrigin (enum.Enum)

attribute sqlalchemy.orm.SessionTransactionOrigin.AUTOBEGIN = 0¶: 事务由 autobegin 启动

attribute sqlalchemy.orm.SessionTransactionOrigin.BEGIN = 1¶: 事务由调用 Session.begin() 启动

attribute sqlalchemy.orm.SessionTransactionOrigin.BEGIN_NESTED = 2¶: 事务由 Session.begin_nested() 启动

attribute sqlalchemy.orm.SessionTransactionOrigin.SUBTRANSACTION = 3¶: 事务是一个内部“子事务”

会话工具¶

对象名称	描述
close_all_sessions()	关闭内存中的所有会话。
make_transient(instance)	更改给定实例的状态，使其变为瞬态。
make_transient_to_detached(instance)	使给定的瞬态实例变为分离状态。
object_session(instance)	返回给定实例所属的 `Session`。
was_deleted(object_)	如果给定对象在会话刷新中被删除，则返回 True。

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 事件中描述的那些函数。

对象名称	描述
del_attribute(instance, key)	删除属性的值，并触发历史记录事件。
flag_dirty(instance)	将实例标记为 “脏”，而不提及任何特定的属性。
flag_modified(instance, key)	将实例上的属性标记为 “修改”。
get_attribute(instance, key)	获取属性的值，并触发任何所需的回调。
get_history(obj, key[, passive])	返回给定对象和属性键的 `History` 记录。
历史	一个 3 元组，包含已添加、未更改和已删除的值，代表已在检测的属性上发生的更改。
init_collection(obj, key)	初始化集合属性并返回集合适配器。
instance_state	返回给定映射对象的 `InstanceState`。
is_instrumented(instance, key)	如果给定实例上的给定属性由属性包检测，则返回 True。
object_state(instance)	给定一个对象，返回与该对象关联的 `InstanceState`。
set_attribute(instance, key, value[, initiator])	设置属性的值，并触发历史记录事件。
set_committed_value(instance, key, value)	设置属性的值，不触发历史记录事件。

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

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

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

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

inspect(instance)

如果实例不是映射的一部分，则使用检查系统会引发 sqlalchemy.exc.NoInspectionAvailable。

函数 sqlalchemy.orm.attributes.del_attribute(instance: object, key: str) → None¶

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

无论直接应用于类的 instrumentation，此函数都可以使用，也就是说，不需要描述符。自定义属性管理方案将需要使用此方法来建立 SQLAlchemy 所理解的属性状态。

函数 sqlalchemy.orm.attributes.get_attribute(instance: object, key: str) → Any¶

获取属性的值，并触发任何所需的回调。

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

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

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

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

注意

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

参数:

obj¶ – 其类由属性包进行 instrumentation 的对象。
key¶ – 字符串属性名称。
passive¶ – 指示如果值不存在，则为属性加载行为。这是一个位标志属性，它默认为符号PASSIVE_OFF，指示应发出所有必要的 SQL。

另请参阅

AttributeState.history

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

函数 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¶ – 集合所在的字符串属性名称。

函数 sqlalchemy.orm.attributes.flag_modified(instance: object, key: str) → None¶

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

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

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

另请参阅

flag_dirty()

函数 sqlalchemy.orm.attributes.flag_dirty(instance: object) → None¶

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

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

版本 1.2 中的新增功能。

另请参阅

flag_modified()

函数 sqlalchemy.orm.attributes.instance_state()¶

返回给定映射对象的 InstanceState。

此函数是object_state()的内部版本。最好在此处使用object_state()和/或inspect()函数，因为它们都将发出一个信息丰富的异常，如果给定的对象未映射。

函数 sqlalchemy.orm.instrumentation.is_instrumented(instance, key)¶

如果给定实例上的给定属性由属性包检测，则返回 True。

无论直接应用于类的 instrumentation，此函数都可以使用，也就是说，不需要描述符。

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

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

无论直接应用于类的 instrumentation，此函数都可以使用，也就是说，不需要描述符。自定义属性管理方案将需要使用此方法来建立 SQLAlchemy 所理解的属性状态。

参数:

instance¶ – 将被修改的对象
key¶ – 属性的字符串名称
value¶ – 要分配的值
initiator¶ –
一个 Event 实例，它应该来自之前的事件监听器。当 set_attribute() 函数在现有事件监听函数中使用，并且提供了一个 Event 对象时，将使用此参数；该对象可用于跟踪事件链的起源。

版本 1.2.3 中的新功能。

函数 sqlalchemy.orm.attributes.set_committed_value(instance, key, value)¶

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

取消任何以前存在的历史记录。对于保存标量的属性，该值应为标量值，对于保存集合的属性，该值应为可迭代对象。

这是延迟加载器触发并从数据库加载额外数据时使用的相同底层方法。特别是，此方法可用于已经通过单独的查询加载了额外属性或集合的应用程序代码，这些属性或集合可以作为其原始加载状态的一部分附加到实例。

类 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

类签名

class sqlalchemy.orm.History (builtins.tuple)

属性 sqlalchemy.orm.attributes.History.added: Tuple[()] | List[Any]¶: 字段编号 0 的别名

属性 sqlalchemy.orm.attributes.History.deleted: Tuple[()] | List[Any]¶: 字段编号 2 的别名

方法 sqlalchemy.orm.attributes.History.empty() → bool¶: 如果此 History 没有更改并且没有现有的、未更改的状态，则返回 True。

方法 sqlalchemy.orm.attributes.History.has_changes() → bool¶: 如果此 History 有更改，则返回 True。

方法 sqlalchemy.orm.attributes.History.non_added() → Sequence[Any]¶: 返回一个未更改 + 已删除的集合。

方法 sqlalchemy.orm.attributes.History.non_deleted() → Sequence[Any]¶: 返回一个已添加 + 未更改的集合。

方法 sqlalchemy.orm.attributes.History.sum() → Sequence[Any]¶: 返回一个已添加 + 未更改 + 已删除的集合。

属性 sqlalchemy.orm.attributes.History.unchanged: Tuple[()] | List[Any]¶: 字段编号 1 的别名

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy ORM

项目版本

会话 API¶

会话和 sessionmaker()¶

会话工具¶

属性和状态管理实用程序¶