Session API¶

Session 和 sessionmaker()¶

对象名称	描述
ORMExecuteState	表示对 `Session.execute()` 方法的调用，传递给 `SessionEvents.do_orm_execute()` 事件钩子。
Session	管理 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 时，关键字参数也可以传递给该方法；这些参数将覆盖全局配置的参数。下面我们使用绑定到特定 Engine 的 sessionmaker 来生成一个 Session，该 Session 而是绑定到从该引擎获取的特定 Connection

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

另请参阅

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

成员

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

类签名

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

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

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

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

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

method 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 设置。

另请参阅

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

method 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 版本新增。

classmethod sqlalchemy.orm.sessionmaker.close_all() → None¶: 继承自 sqlalchemy.orm.session._SessionClassMethods.close_all 方法，来自 sqlalchemy.orm.session._SessionClassMethods

关闭内存中所有 session。

Deprecated since version 1.3: Session.close_all() 方法已弃用，将在未来的版本中删除。请参考 close_all_sessions()。

method 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 对象的序列。

“顶层”指的是那些 Mapper 对象，它们将表示在 select() 查询的结果集行中，或者对于 update() 或 delete() 查询，作为 UPDATE 或 DELETE 主要对象的映射器。

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 中。

Changed in version 2.0: 版本 2.0 中的更改：参数字典列表被接受用于 executemany 执行。
execution_options¶ – 可选的执行选项字典将合并到此 ORMExecuteState 的现有 ORMExecuteState.execution_options 中。
bind_arguments¶ – 可选的 bind_arguments 字典，它将合并到此 ORMExecuteState 的当前 ORMExecuteState.bind_arguments 中。

Returns:

带有 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。

Changed in version 2.0.30: 版本 2.0.30 中的更改：- 对于 Select.from_statement() 构造，如果它本身针对 Delete 构造，例如 select(Entity).from_statement(delete(..))，此属性也为 True

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 类型的语句一起使用。只有当 Select.from_statement() 本身针对 Select 构造时，才会设置 ORMExecuteState.is_select。

2.0.30 版本新增。

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

Changed in version 2.0.30: 版本 2.0.30 中的更改：- 对于 Select.from_statement() 构造，如果它本身针对 Insert 构造，例如 select(Entity).from_statement(insert(..))，此属性也为 True

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。

Changed in version 2.0.30: 版本 2.0.30 中的更改：- 对于 Select.from_statement() 构造，如果它本身针对 Select 构造，例如 select(Entity).from_statement(select(..))，此属性也为 True

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

Changed in version 2.0.30: 版本 2.0.30 中的更改：- 对于 Select.from_statement() 构造，如果它本身针对 Update 构造，例如 select(Entity).from_statement(update(..))，此属性也为 True

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

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

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

attribute sqlalchemy.orm.ORMExecuteState.statement: Executable¶

正在调用的 SQL 语句。

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

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

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

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

class sqlalchemy.orm.Session¶

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

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

Session 的使用范例在使用 Session 中描述。

类签名

class 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() 才能使数据库查询检索结果。

另请参阅

Flushing - 有关 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 多个数据库后端）

Session.bind_mapper()

Session.bind_table()

Session.get_bind()
class_¶ – 指定除 sqlalchemy.orm.session.Session 之外的备用类，该类应由返回的类使用。这是 sessionmaker 函数的唯一本地参数，并且不直接发送到 Session 的构造函数。
enable_baked_queries¶ –
遗留；默认为 True。sqlalchemy.ext.baked 扩展使用的一个参数，用于确定是否应缓存 “baked queries”，正如该扩展的正常操作一样。当设置为 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 上的 TwoPhaseTransaction.prepare() 方法。这允许每个数据库在提交每个事务之前回滚整个事务。
autocommit¶ – “autocommit” 关键字是为了向后兼容而存在的，但必须保持其默认值 False。
join_transaction_mode¶ –
描述当给定的 bind 是一个 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 有足够的支持，因为此功能的可用性各不相同。"conditional_savepoint" 还试图与以前的 Session 行为建立近似的向后兼容性，对于未设置特定模式的应用程序。建议使用显式设置之一。
- "create_savepoint" - Session 将在所有情况下使用 Connection.begin_nested() 来创建自己的事务。本质上，此事务 “位于” 给定 Connection 上已打开的任何现有事务的 “顶部”；如果底层数据库和正在使用的驱动程序对 SAVEPOINT 具有完整、未损坏的支持，则外部事务将在整个 Session 的生命周期内保持不受影响。
  
  "create_savepoint" 模式最适用于将 Session 集成到测试套件中，其中外部启动的事务应保持不受影响；但是，它依赖于底层驱动程序和数据库的正确 SAVEPOINT 支持。
  
  提示
  
  当使用 SQLite 时，Python 3.11 中包含的 SQLite 驱动程序并非在所有情况下都能正确处理 SAVEPOINT，而无需解决方法。有关当前解决方法的详细信息，请参阅可序列化隔离/保存点/事务性 DDL 和可序列化隔离/保存点/事务性 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（即 Connection.begin()）；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() 方法时，处于 transient 状态的对象将移动到 pending 状态，直到下一次 flush，届时它们将移动到 persistent 状态。

当传递给 Session.add() 方法时，处于 detached 状态的对象将直接移动到 persistent 状态。

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

另请参阅

Session.add_all()

添加新的或现有项 - 在使用 Session 的基础知识中

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

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

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

另请参阅

Session.add()

添加新的或现有项 - 在使用 Session 的基础知识中

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

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

Session 对象具有 autobegin 行为，因此通常无需显式调用 Session.begin() 方法。但是，可以使用它来控制事务状态何时开始的范围。

当用于开始最外层事务时，如果此 Session 已经在一个事务内部，则会引发错误。

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

另请参阅

自动开始

管理事务

Session.begin_nested()

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

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

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

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

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

另请参阅

使用 SAVEPOINT

可序列化隔离/保存点/事务性 DDL - 使用 SQLite 驱动程序需要特殊的解决方法，以使 SAVEPOINT 正常工作。对于 asyncio 用例，请参阅可序列化隔离/保存点/事务性 DDL（asyncio 版本）部分。

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

将 Mapper 或任意 Python 类与 “bind” 关联，例如 Engine 或 Connection。

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

参数:

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

另请参阅

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

Session.binds

Session.bind_table()

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

将 Table 与 “bind” 关联，例如 Engine 或 Connection。

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

参数:

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

另请参阅

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

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 值将导致在 INSERT 语句中包含 NULL 值，而不是从 INSERT 中省略该列。这允许所有要 INSERT 的行都具有相同的列集，从而允许将全套行批处理到 DBAPI。通常，每个列集包含与上一行不同的 NULL 值组合，都必须从呈现的 INSERT 语句中省略一系列不同的列，这意味着必须将其作为单独的语句发出。通过传递此标志，可以保证将全套行批处理到一个批次中。然而，代价是会跳过由省略列调用的服务器端默认值，因此必须注意确保这些值不是必需的。

警告

设置此标志后，对于那些作为 NULL 插入的列，将不会调用服务器端默认 SQL 值； 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 属性，则假定该对象为 “detached”，并将导致 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 本身实际上没有明显的 “closed” 状态；它仅仅意味着 Session 将释放所有数据库连接和 ORM 对象。

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

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

另请参阅

关闭 (Closing) - 详细介绍 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

关闭内存中所有 session。

Deprecated since version 1.3: Session.close_all() 方法已弃用，将在未来的版本中删除。请参考 close_all_sessions()。

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

刷新待定更改并提交当前事务。

当 COMMIT 操作完成时，所有对象都完全过期 (expired)，清除其内部内容，这些内容将在下次访问对象时自动重新加载。在此期间，这些对象处于过期状态，如果它们从 Session 中分离 (detached)，则无法正常工作。此外，当使用面向 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¶

返回与此 Session 对象的事务状态对应的 Connection 对象。

返回与当前事务对应的 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¶

将实例标记为已删除。

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

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

另请参阅

删除 (Deleting) - 在 Session 的基本用法 (Basics of Using a 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 作为连接源从数据库加载值。这些值将根据此对象上存在的外键和主键值加载 - 如果不存在，则这些关系将不可用。

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

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

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

要使通过 Session.enable_relationship_loading() 与 Session 关联的瞬态对象处于待定状态，请使用 Session.add() 正常将其添加到 Session。如果对象反而表示数据库中的现有标识，则应使用 Session.merge() 合并它。

当正常使用 ORM 时，Session.enable_relationship_loading() 不会改善行为 - 对象引用应在对象级别而不是外键级别构建，以便它们在 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))

Session.execute() 的 API 约定与 Connection.execute() 的 API 约定类似，后者是 Connection 的 2.0 风格 (2.0 style) 版本。

在 1.4 版本中更改: 当使用 2.0 风格 (2.0 style) ORM 用法时，Session.execute() 方法现在是 ORM 语句执行的主要入口点。

参数:

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

另请参阅

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

Returns:

一个 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() 方法时使所有状态过期，以便可以为新事务加载新状态。因此，仅当在当前事务中发出了非 ORM SQL 语句时，调用 Session.expire() 才合理。

参数:

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

另请参阅

刷新 / 过期 (Refreshing / Expiring) - 介绍性材料

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()。

另请参阅

刷新 / 过期 (Refreshing / Expiring) - 介绍性材料

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})

在 1.4 版本中新增: 添加了 Session.get()，它从现在已过时的 Query.get() 方法移动而来。

Session.get() 方法的特殊之处在于，它提供了对 Session 的身份映射的直接访问。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，或者可以是包含标志的字典，以指示更具体的 FOR UPDATE 标志集用于 SELECT；标志应与 Query.with_for_update() 的参数匹配。取代了 Session.refresh.lockmode 参数。
execution_options¶ –
执行选项的可选字典，如果发出查询，则将与查询执行关联。该字典可以提供 Connection.execution_options() 接受的选项的子集，并且还可以提供仅在 ORM 上下文中理解的其他选项。

1.4.29 版本新增。

另请参阅

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

Returns:

对象实例，或 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 绑定的 “bind”。

“bind” 通常是 Engine 的实例，除非 Session 已显式直接绑定到 Connection。

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

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

解析顺序如下

如果给定 mapper 且存在 Session.binds，则首先根据正在使用的 mapper，然后根据正在使用的映射类，然后根据映射类的 __mro__ 中存在的任何基类（从更具体的超类到更一般的超类）来查找绑定。
如果给定 clause 且存在 Session.binds，则根据 Table 对象在给定的 clause 中查找绑定，这些对象存在于 Session.binds 中。
如果 Session.binds 存在，则返回该绑定。
如果给定 clause，则尝试返回链接到最终与 clause 关联的 MetaData 的绑定。
如果给定 mapper，则尝试返回链接到最终与 Table 或 mapper 映射到的其他 selectable 关联的 MetaData 的绑定。
如果找不到绑定，则会引发 UnboundExecutionError 异常。

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

参数:

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

另请参阅

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

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 版本新增。

Returns:: 对象实例。

另请参阅

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¶

用户可修改的字典。

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

method sqlalchemy.orm.Session.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 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.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 调用的开销，因为假设通常需要更新标量值，并且在少数不需要更新的情况下，平均而言，它的成本低于发出防御性 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() 检查源实例的主键属性，并尝试将其与会话中具有相同主键的实例进行协调。如果本地找不到，它会尝试根据主键从数据库加载对象，如果找不到任何对象，则创建一个新实例。然后，源实例上每个属性的状态都会被复制到目标实例。然后，该方法返回结果目标实例；原始源实例保持不变，如果尚未与 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 中标记为“new”的所有实例的集合。

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 对象。

请注意，Query 对象在 SQLAlchemy 2.0 中已过时；现在使用 select() 构造 ORM 查询。

另请参阅

SQLAlchemy 统一教程

ORM 查询指南

旧版查询 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() 方法还可以刷新急切加载的属性。

通常使用 select（或“lazy”）加载器策略加载的 relationship() 面向的属性，如果它们在 attribute_names 集合中被显式命名，也会加载，使用 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 参数。

另请参阅

刷新 / 过期 (Refreshing / Expiring) - 介绍性材料

Session.expire()

Session.expire_all()

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

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

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

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

2.0.22 版本新增。

另请参阅

关闭 (Closing) - 详细介绍 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 对象。

Returns:: 一个 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¶

指示这是否是嵌套事务或保存点事务。

当 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，则这要么是 “子事务”（flush 进程使用的内部标记对象），要么是 “嵌套” / 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¶: 事务是一个内部的 “子事务”

Session 实用工具¶

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

function sqlalchemy.orm.close_all_sessions() → None¶

关闭内存中的所有 session。

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

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

1.3 版本新增。

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

更改给定实例的状态，使其变为 transient（瞬态）。

注意

make_transient() 是一个特殊情况函数，仅适用于高级用例。

假定给定的映射实例处于 persistent（持久态）或 detached（游离态）状态。此函数将删除其与任何 Session 的关联以及其 InstanceState.identity。效果是该对象将表现得好像是新构建的一样，但会保留调用时加载的任何属性/集合值。如果此对象由于使用 Session.delete() 而被删除，则 InstanceState.deleted 标志也会被重置。

警告

make_transient() **不会** “取消过期” 或以其他方式急切加载在调用函数时未加载的 ORM 映射属性。这包括以下属性：

通过 Session.expire() 过期
由于提交 session 事务的自然影响而过期，例如 Session.commit()
通常是 lazy loaded（懒加载）但当前未加载
是 “deferred”（延迟加载）（请参阅 Limiting which Columns Load with Column Deferral）且尚未加载
未出现在加载此对象的查询中，例如在连接表继承和其他场景中常见的情况。

在调用 make_transient() 后，未加载的属性（如上述属性）在访问时通常会解析为值 None，或者对于面向集合的属性，则解析为空集合。由于对象是瞬态的并且未与任何数据库标识关联，因此它将不再检索这些值。

另请参阅

make_transient_to_detached()

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

使给定的瞬态实例变为 detached（游离态）。

注意

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

给定实例上的所有属性历史记录都将被重置，就好像该实例是从查询中新加载的一样。缺失的属性将被标记为已过期。对象的主键属性（必需的）将变为实例的 “key”。

然后可以将该对象添加到 session 中，或者可以与 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¶

如果给定对象在 session flush 中被删除，则返回 True。

这与对象是持久态还是游离态无关。

另请参阅

InstanceState.was_deleted

属性和状态管理实用工具¶

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

对象名称	描述
del_attribute(instance, key)	删除属性的值，触发历史记录事件。
flag_dirty(instance)	将实例标记为 “dirty”（脏），而无需提及任何特定属性。
flag_modified(instance, key)	将实例上的属性标记为 “modified”（已修改）。
get_attribute(instance, key)	获取属性的值，触发任何所需的可调用对象。
get_history(obj, key[, passive])	返回给定对象和属性键的 `History` 记录。
History	一个包含添加、未更改和删除值的 3 元组，表示在检测属性上发生的更改。
init_collection(obj, key)	初始化集合属性并返回集合适配器。
instance_state	返回给定映射对象的 `InstanceState`。
is_instrumented(instance, key)	如果给定实例上的给定属性由 attributes 包检测，则返回 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 异常。

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 记录。

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

注意

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

参数:

obj¶ – 其类由 attributes 包检测的对象。
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¶

将实例上的属性标记为 “modified”（已修改）。

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

要将对象标记为 “dirty”（脏），而无需引用任何特定属性，以便在 flush 过程中考虑它，请使用 flag_dirty() 调用。

另请参阅

flag_dirty()

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

将实例标记为 “dirty”（脏），而无需提及任何特定属性。

这是一个特殊操作，它将允许对象在 flush 过程中传递，以便被诸如 SessionEvents.before_flush() 之类的事件拦截。请注意，即使通过此方法标记为 dirty，对于没有更改的对象，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)¶

如果给定实例上的给定属性由 attributes 包检测，则返回 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() 函数时，将使用此参数，其中提供了 Event 对象；该对象可用于跟踪事件链的来源。

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

类签名

class sqlalchemy.orm.History (builtins.tuple)

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

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

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

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

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

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

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

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

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy ORM

项目版本

Session API¶

Session 和 sessionmaker()¶

Session 实用工具¶

属性和状态管理实用工具¶