会话 API¶

Session 和 sessionmaker（）¶

对象名称	描述
ORMExecuteState	表示对 `Session.execute（）` 方法的调用，传递给 `SessionEvents.do_orm_execute()` 事件钩子。
会期	管理 ORM 映射对象的持久性作。
会话生成器	可配置的 `Session` 工厂。
会话事务	`会话`级事务。
SessionTransactionOrigin	指示 `SessionTransaction` 的来源。

类 sqlalchemy.orm 中。会话管理器¶

可配置的 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 来生成一个 Session，该 Session 绑定到从该 engine 购买的特定 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 Factory 之前：

# 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

另请参阅

Opening and Closing a Session - 有关使用 sessionmaker 创建会话的介绍性文本。

成员

__call__（）、__init__（）、begin（）、close_all（）、configure（）、identity_key（）、object_session（）

类签名

类 sqlalchemy.orm.sessionmaker （ sqlalchemy.orm.session._SessionClassMethods ， typing.通用）

方法 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：可选[_SessionBind] = 无， *， 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 对象。

另请参阅

刷新 - 自动刷新的其他背景
expire_on_commit=True¶ – 该 Session.expire_on_commit用于新创建的 Session 对象的设置。
info¶—— 可选的信息字典，可通过 Session.info 获得。请注意，当 info 参数被指定给特定的 会话构建作。
**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（）→ 无¶: 继承自 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）→ 无¶

（重新）配置此 sessionmaker 的参数。

例如：

Session = sessionmaker()

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

类方法 sqlalchemy.orm.sessionmaker 中。identity_key（class_：Type[Any]None=None， ident：AnyTuple[Any,...]=None， *， instance：AnyNone=None， row：Row[Any]RowMappingNone=None， identity_token：AnyNone=None）→ _IdentityKeyType[Any]¶

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

返回身份密钥。

这是 identity_key（） 的别名。

类方法 sqlalchemy.orm.sessionmaker 中。object_session（instance： object）→SessionNone¶

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

返回对象所属的 Session。

这是 object_session（） 的别名。

类 sqlalchemy.orm 中。ORMExecuteState¶

表示对 Session.execute（） 方法的调用，传递给 SessionEvents.do_orm_execute() 事件钩子。

在 1.4 版本加入.

另请参阅

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

类签名

类 sqlalchemy.orm.ORMExecuteState （ sqlalchemy.util.langhelpers.MemoizedSlots ）

method sqlalchemy.orm.ORMExecuteState. __init__（session：会话， statement：可执行， parameters：_CoreAnyExecuteParamsNone， execution_options： _ExecuteOptions， bind_arguments： _BindArguments， compile_state_cls：Type[ORMCompileState]None， events_todo： List[_InstanceLevelDispatch[Session]]）¶

构造一个新的 ORMExecuteState。

此对象是在内部构造的。

属性 sqlalchemy.orm.ORMExecuteState. all_mappers¶

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

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

1.4.0b2 版本的新Function。

另请参阅

ORMExecuteState.bind_mapper

属性 sqlalchemy.orm.ORMExecuteState. bind_arguments： _BindArguments¶

作为 Session.execute.bind_arguments 字典。

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

属性 sqlalchemy.orm.ORMExecuteState. bind_mapper¶

返回作为主 “bind” 映射器的 Mapper。

对于调用 ORM 语句的 ORMExecuteState 对象，即 ORMExecuteState.is_orm_statement attribute 为 True，则此 attribute 将返回 Mapper 的 Mapper，该映射器被视为语句的 “primary” 映射器。术语 “bind mapper” 指的是一个 Session 对象可以 “绑定” 到多个 Engine 对象与映射类的键控，“bind mapper” 确定将选择哪些 Engine 对象。

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

1.4.0b2 版本的新Function。

另请参阅

ORMExecuteState.all_mappers

属性 sqlalchemy.orm.ORMExecuteState. execution_options：_ExecuteOptions¶

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

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

另请参阅

ORMExecuteState.local_execution_options

Executable.execution_options()

ORM 执行选项

方法 sqlalchemy.orm.ORMExecuteState. invoke_statement（statement：ExecutableNone=None， params：_CoreAnyExecuteParamsNone=None， execution_options：OrmExecuteOptionsParameterNone=None， bind_arguments：_BindArgumentsNone=None）→ 结果[Any]¶

执行 this 表示的语句 ORMExecuteState，而无需重新调用已发生的事件。

此方法实质上执行 SessionEvents.do_orm_execute() 事件所在的当前语句的重入执行当前正在调用。这种情况的用例是事件处理程序想要覆盖终极 Result 对象，例如，对于从离线缓存中检索结果或连接来自多个执行的结果的方案。

当 Result 对象由实际处理程序函数在 SessionEvents.do_orm_execute() 和传播到调用 Session.execute（） 方法，则 Session.execute（） 方法被抢占，并且 Result 对象返回给 Session.execute（） 立即执行。

参数

statement¶- 要调用的可选语句，代替当前由 ORMExecuteState.statement 表示的语句。
参数¶ –

可选的参数字典或参数列表，该 API 将合并到现有的 ORMExecuteState.parameters 的 ORMExecuteState。

在 2.0 版更改： executemany executions接受参数字典列表。
execution_options¶ – 可选的执行选项字典将合并到现有的 ORMExecuteState.execution_options 的 ORMExecuteState.
bind_arguments¶ – 可选的 bind_arguments 字典它将在当前的 ORMExecuteState.bind_arguments 这个 ORMExecuteState 的。

结果

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

另请参阅

重新执行语句 - 有关正确使用 . ORMExecuteState.invoke_statement()

属性 sqlalchemy.orm.ORMExecuteState. is_column_load¶

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

这发生在 Session.refresh（） 等作期间，以及加载由 defer（） 延迟的属性，或者加载由 Session.expire（） 直接或通过提交作过期的属性时。

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

1.4.0b2 版本的新Function。

另请参阅

ORMExecuteState.is_relationship_load

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

在 2.0.30 版本发生更改： - 对于 Select.from_statement（） 结构，该结构本身针对 Delete 结构，例如 select(Entity).from_statement(delete(..))

属性 sqlalchemy.orm.ORMExecuteState. is_executemany¶: 如果参数是具有多个词典的词典的多元素列表，则返回 True。

2.0 版的新Function。

属性 sqlalchemy.orm.ORMExecuteState. is_from_statement¶

如果此作是 Select.from_statement（）作。

这与 ORMExecuteState.is_select 无关，因为 select（）.from_statement（） 结构可以与 INSERT/UPDATE/DELETE RETURNING 类型的语句。 ORMExecuteState.is_select仅当 Select.from_statement（） 本身就是针对 选择 construct （构造）。

2.0.30 版本的新Function。

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

在 2.0.30 版本发生更改： - 对于 Select.from_statement（） 结构，该结构本身针对 Insert 结构，例如 select(Entity).from_statement(insert(..))

属性 sqlalchemy.orm.ORMExecuteState. is_orm_statement¶

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

这表示 select（）、insert（）、update（）或 delete（）被调用的 ORM 实体作为主题。对于声明它没有 ORM 实体，而是仅引用 Table 元数据，它作为 Core SQL 语句调用，并且不会发生 ORM 级别的自动化。

属性 sqlalchemy.orm.ORMExecuteState. is_relationship_load¶

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

这意味着，实际上的加载程序是 LazyLoader、SelectInLoader、SubqueryLoader 或类似程序，并且发出的整个 SELECT 语句代表关系加载。

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

另请参阅

ORMExecuteState.is_column_load

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

在 2.0.30 版本发生更改： - 对于 Select.from_statement（） 结构，它本身是针对 Select 结构的，例如 select(Entity).from_statement(select(..))

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

在 2.0.30 版本发生更改： - 对于 Select.from_statement（） 结构，该结构本身针对 Update 结构，例如 select(Entity).from_statement(update(..))

属性 sqlalchemy.orm.ORMExecuteState. lazy_loaded_from¶

使用此语句执行延迟加载作的 InstanceState。

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

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

属性 sqlalchemy.orm.ORMExecuteState. loader_strategy_path¶

返回当前加载路径的 PathRegistry。

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

属性 sqlalchemy.orm.ORMExecuteState. local_execution_options： _ExecuteOptions¶

传递给 Session.execute（） 方法。

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

另请参阅

ORMExecuteState.execution_options

属性 sqlalchemy.orm.ORMExecuteState. 参数：_CoreAnyExecuteParamsNone¶: 传递给 Session.execute（）的 Session.execute（） 中。

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

attribute sqlalchemy.orm.ORMExecuteState. 语句：可执行文件¶

正在调用的 SQL 语句。

对于从 Query 中检索的 ORM 选择，这是 select 的 SELECT 查询。

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

method sqlalchemy.orm.ORMExecuteState. update_execution_options（**opts： Any）→ 无¶: 使用新值更新本地执行选项。

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

类 sqlalchemy.orm 中。会话¶

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

会话在并发线程中使用不安全..请参阅 Session 线程安全吗？在并发任务中共享 AsyncSession 是否安全？作为背景。

Session 的使用范例在使用 Session 中进行了描述。

成员

__init__（）， add（）， add_all（）， begin（）， begin_nested（）， bind_mapper（）， bind_table（）， bulk_insert_mappings（）， bulk_save_objects（）， bulk_update_mappings（）， close（）， close_all（）， commit（）， connection（）、delete（）、deleted、dirty、enable_relationship_loading（）、execute（）、expire（）、expire_all（）、expunge（）、expunge_all（）、flush（）、get（）、get_bind（）get_nested_transaction（）， get_one（）， get_transaction（）， identity_key（）， identity_map， in_nested_transaction（）， in_transaction（）， info， invalidate（）， is_active， is_modified（）， merge（），新的， no_autoflush、object_session（）、prepare（）、query（）、refresh（）、reset（）、rollback（）、scalar（）、scalars （）

类签名

类 sqlalchemy.orm.Session （ sqlalchemy.orm.session._SessionClassMethods ， sqlalchemy.event.registry.EventTarget ）

方法 sqlalchemy.orm.Session 中。__init__（bind：_SessionBindNone=None， *， autoflush： bool = True， future： Literal[True] = True， expire_on_commit： bool = True， autobegin： bool = True， twophase： bool = False， binds：Dict[_SessionBindKey，_SessionBind]None=无， enable_baked_queries： bool = True， info：_InfoTypeNone=None， query_cls：Type[Query[Any]]None=无，自动提交：Literal[False] = False， join_transaction_mode： JoinTransactionMode = 'conditional_savepoint'， close_resets_only：bool_NoArg=_NoArg.NO_ARG）¶

构造一个新的 Session。

另请参阅 sessionmaker 函数，该函数用于生成具有给定参数集的 Session 生成可调用对象。

参数

自动刷新¶ –

如果为 True，则所有查询作都将发出 Session.flush（） 调用此 Session。这是一个方便的功能，因此不需要重复调用 Session.flush（） 即可让数据库查询检索结果。

另请参阅

刷新 - 自动刷新的其他背景
自动开始¶ –

当作请求数据库访问时，自动启动事务（即等效于调用 Session.begin（））。默认为 True。设置为 如果为 False，则可以防止 Session 在构造后以及在任何 Session.rollback（）、Session.commit（） 或 Session.close（） 方法被调用后隐式地开始事务。

2.0 版的新Function。

另请参阅

禁用 Autostart 以防止隐式事务
bind¶—— 一个可选的 Engine 或此 Session 应绑定到的 Connection。指定后，此会话执行的所有 SQL作都将通过此 connectable 执行。
绑定¶–

一个字典，可以指定任意数量的 发动机或连接 对象作为基于每个实体的 SQL作的连接。键由任意系列的映射类组成，作为映射类的基础的任意 Python 类， Table 对象和 Mapper 对象。这的值是 发动机 或不太常见的 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 应由 returned 类。这是 sessionmaker 函数，并且不会直接发送到 Session 的构造函数。
enable_baked_queries¶ –

遗产;默认为 True。sqlalchemy.ext.baked 扩展使用的参数，用于确定是否应缓存 “烘焙查询” ，这是此扩展的正常作。当设置为 False 时，将禁用此特定扩展使用的缓存。

在 1.4 版本发生变更： sqlalchemy.ext.baked 扩展是遗留的，不被任何 SQLAlchemy 的内部使用。因此，此标志仅影响在其自己的代码中显式使用此扩展的应用程序。
expire_on_commit¶ –

默认为 True。如果为 True，则所有实例将在每次 commit（） 后完全过期，因此完成事务之后的所有属性/对象访问都将从最新的数据库状态加载。

另请参阅

犯
未来¶ –

荒废的;此标志始终为 True。

另请参阅

SQLAlchemy 2.0 - 主要迁移指南
info¶ – 与此 Session 关联的任意数据的可选字典。可通过 Session.info 属性。请注意，词典复制位于施工时间，以便对每个 会话字典将是该 会话。
query_cls¶ – 应该用于创建新的 Query 对象的类，由 Session.query（） 方法返回。默认为 Query。
twophase¶– 当 True 时，所有交易都将以 “两阶段”交易，即使用“两阶段”语义以及 XID。在 commit（）中，在对所有连接的数据库发出 flush（） 后，TwoPhaseTransaction.prepare（） 方法将调用每个数据库的 TwoPhaseTransaction 的 TwoPhaseTransaction 方法。这允许每个数据库在提交每个事务之前回滚整个事务。
autocommit¶– 存在 “autocommit” 关键字是为了向后兼容，但必须保持其默认值 False。
join_transaction_mode¶ –

描述当给定绑定是 Connection 时要采取的事务行为已经开始了超出此范围的交易 会话;换句话说， Connection.in_transaction（） 方法返回 True。

以下行为仅在 Session实际使用给定的连接时生效;也就是说，实际上调用了 Session.execute（）、Session.connection（） 等方法：
- “conditional_savepoint” - 这是默认值。如果给定的 Connection 在事务中开始，但没有 SAVEPOINT，则使用 “rollback_only”。如果连接还位于换句话说，一个 SAVEPOINT Connection.in_nested_transaction() method 返回 True，则使用 “create_savepoint”。
  
  “conditional_savepoint” 行为尝试利用 savepoints 来保持现有事务的状态保持不变，但前提是已经有一个 savepoint 正在进行中; 否则，不会假定正在使用的后端具有足够的支持 SAVEPOINT，因为此功能的可用性各不相同。 “conditional_savepoint” 还寻求建立与上一个 Session 的近似向后兼容性行为，适用于未设置特定模式的应用程序。它建议使用显式设置之一。
- “create_savepoint” - 会话将使用 Connection.begin_nested（） 创建它自己的交易。这种交易本质上是乘风破浪的 “on” 在给定 连接;如果底层数据库和正在使用的驱动程序对 SAVEPOINT 具有完全、不间断的支持，则外部事务将在 Session 的整个生命周期内保持不变。
  
  “create_savepoint” 模式对于将 Session 集成到测试套件中最有用，其中外部发起的事务应该不受影响;但是，它依赖于底层驱动程序和数据库的适当 SAVEPOINT 支持。
  
  提示
  
  使用 SQLite 时，通过 Python 3.11 并非在所有情况下都能正确处理 SAVEPOINT 没有解决方法。查看各部分可序列化隔离 / 保存点 / 事务性 DDL 和可序列化隔离 / 保存点 / 事务性 DDL（asyncio 版本）了解有关当前解决方法的详细信息。
- “control_fully” - 会话将采用将给定交易的控制权视为自己的交易; Session.commit（） 将在事务上调用 .commit（），Session.rollback（） 将调用 .rollback（） 时，Session.close（） 将对事务调用 .rollback。
  
  提示
  
  这种使用模式相当于 SQLAlchemy 1.4 如何处理使用现有 SAVEPOINT（即 Connection.begin_nested（））给定的 Connection;这 Session 将完全控制现有的 SAVEPOINT。
- “rollback_only” - Session 将仅控制给定的 .rollback（） 调用事务; .commit（） 调用不会传播到给定的事务。.close（） 调用对给定的事务没有影响。
  
  提示
  
  这种使用模式相当于 SQLAlchemy 1.4 如何处理给定的 Connection 常规数据库事务（即 Connection.begin（））;会话 会将 Session.rollback（） 调用传播到底层事务，但不会将 Session.commit（） 或 Session.close（） 调用。
2.0.0rc1 版本的新Function。
close_resets_only¶ –

默认为 True。确定会话是否应在调用 .close（） 后重置自身或者应该以不再可用的状态传递，从而禁用重用。

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

另请参阅

结束语 - 有关语义的详细信息 Session.close（） 和 Session.reset（）的 Session.reset（） 来获取。

方法 sqlalchemy.orm.Session 中。add（instance： object， _warn： bool = True）→ 无¶

将对象放入此 Session 中。

在传递给 Session.add（） 方法将移动到 pending 状态，直到下一次 flush，此时它们将进入 persistent 状态。

在传递给 Session.add（） 方法将移动到持久化 state 直接。

如果 Session 使用的事务回滚，对象，这些对象在传递给 Session.add（） 将移回 transient 状态，并且将不再存在于此 会话。

另请参阅

Session.add_all（）

添加新项或现有项 - 使用会话的基础知识

方法 sqlalchemy.orm.Session 中。add_all（instances： Iterable[object]）→ 无¶

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

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

另请参阅

Session.add（）

添加新项或现有项 - 使用会话的基础知识

方法 sqlalchemy.orm.Session 中。begin（嵌套： bool = False）→ SessionTransaction¶

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

Session 对象具有 autostart 行为、因此，通常不需要调用 会话.begin（） 方法。但是，它可以用于控制事务状态开始的时间范围。

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

参数: nested¶ – 如果为 True，则开始 SAVEPOINT 事务，等效于调用 Session.begin_nested（）。为有关 SAVEPOINT 事务的文档，请参阅使用 SAVEPOINT。
结果: SessionTransaction 对象。请注意， 会话事务 充当 Python 上下文管理器，允许 Session.begin（） 用于 “with” 块。有关示例，请参阅 Explicit Begin 。

另请参阅

自动开始

管理事务

Session.begin_nested（）

方法 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 版本）。

方法 sqlalchemy.orm.Session 中。bind_mapper（mapper： _EntityBindKey[_O]， bind： _SessionBind）→ 无¶

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

给定的实体被添加到 Session.get_bind（） 方法。

参数

mapper¶—— 一个 Mapper 对象，或一个 mapped 类的实例，或任何作为一组 mapped 类的基础的 Python 类。
bind¶ —— 引擎或连接 对象。

另请参阅

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

Session.binds

Session.bind_table（）

方法 sqlalchemy.orm.Session 中。bind_table（table： TableClause， bind：EngineConnection）→ 无¶

将 Table 与 “bind” 关联，例如 发动机 或 Connection （连接）。

给定的 Table 被添加到 Session.get_bind（） 方法。

参数

table¶—— 一个 Table 对象，通常是 ORM 映射的目标，或者存在于被映射的 selectable 中。
bind¶ —— 引擎或连接 对象。

另请参阅

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

Session.binds

Session.bind_mapper（）

方法 sqlalchemy.orm.Session 中。bulk_insert_mappings（mapper： Mapper[Any]， mappings： Iterable[Dict[str， Any]]， return_defaults： bool = False， render_nulls： bool = False）→ 无¶

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

旧版功能

此方法是 SQLAlchemy 2.0 系列的遗留功能。有关现代批量 INSERT 和 UPDATE，请参阅 ORM 批量 INSERT 语句和按主键的 ORM 批量更新。2.0 API 与此方法共享实现细节，并添加了新功能。

参数

mapper¶—— 一个映射的类，或者实际的 Mapper 对象表示映射中表示的单一对象列表。
mappings¶—— 一系列字典，每个字典都包含要插入的映射行的状态，根据 mapped 类上的属性名称。如果映射引用多个表，例如联接继承映射，则每个字典必须包含要填充到所有表中的所有键。
return_defaults¶ –

当 True 时，INSERT 进程将被更改以确保将获取新生成的主键值。此参数的基本原理通常是启用要批量插入的联接表继承映射。

注意

对于不支持 RETURNING 的后端， Session.bulk_insert_mappings.return_defaults 参数会显著降低性能，因为 INSERT 语句不能再进行批处理。看 INSERT 语句的 “Insert Many Values” 行为了解哪些后端受到影响的背景信息。
render_nulls¶ –

当 True 时，值 None 将导致 NULL 值包含在 INSERT 语句中，而不是从 INSERT 中省略该列。这允许所有被 INSERT 的行具有相同的列集，从而允许将完整的行集批处理到 DBAPI。通常，包含与前一行不同的 NULL 值组合的每个列集必须省略呈现的 INSERT 语句中的不同列系列，这意味着它必须作为单独的语句发出。通过传递此标志，可以保证整组行可批处理为一个批处理;但是，代价是将被跳过由省略的列调用的服务器端默认值，因此必须注意确保这些不是必需的。

警告

设置此标志后，服务器端默认 SQL 值将不会为作为 NULL 插入的列调用 ;NULL 值将被显式发送。必须注意确保不需要为整个作调用服务器端默认函数。

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

Session.bulk_save_objects（）

Session.bulk_update_mappings()

方法 sqlalchemy.orm.Session 中。bulk_save_objects（objects： Iterable[object]， return_defaults： bool = False， update_changed_only： bool = True， preserve_order： bool = True）→ 无¶

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

旧版功能

此方法是 SQLAlchemy 2.0 系列的遗留功能。有关现代批量 INSERT 和 UPDATE，请参阅 ORM 批量 INSERT 语句和按主键的 ORM 批量更新。

对于现有 ORM 映射对象的常规 INSERT 和 UPDATE，首选标准工作单元数据管理模式，在 SQLAlchemy Unified Tutorial 中介绍，网址为使用 ORM 进行数据作。SQLAlchemy 2.0 现在对具有现代方言的 INSERT 语句使用“插入许多值”行为，这解决了以前批量 INSERT 缓慢的问题。

参数

对象¶ –

映射的对象实例序列。映射的对象按原样保留，并且不与 会议之后。

对于每个对象，对象是作为 INSERT 还是 UPDATE 发送，取决于 Session 使用的相同规则在传统作中;如果对象具有 InstanceState.key 属性集，则假定对象为 “detached” 并且将导致 UPDATE。否则，使用 INSERT。

在 UPDATE 的情况下，语句根据已更改的属性进行分组，因此将成为每个 SET 子句的主题。如果 update_changed_only 为 False，则每个对象中存在的所有属性都将应用于 UPDATE 语句，这可能有助于将语句分组到更大的 executemany（）中，并且还将减少检查属性历史记录的开销。
return_defaults¶ – 当 True 时，将一次插入一个缺少生成默认值的值的行，即整数主键默认值和序列，以便主键值可用。特别是，这将允许 joined-inheritance 等多表映射，无需正确插入提前提供主键值;然而 Session.bulk_save_objects.return_defaults 大大降低方法的整体性能增益。强烈建议使用标准 Session.add_all（） 方法。
update_changed_only¶– 当 True 时，UPDATE 语句根据每个状态中已记录更改的属性呈现。当 False 时，除主键属性外，存在的所有属性都将呈现到 SET 子句中。
preserve_order¶ – 当为 True 时，插入和更新的顺序与对象的给定顺序完全匹配。当 False 时，常见类型的对象将分为 inserts 和 updates，以允许更多的批处理机会。

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

Session.bulk_insert_mappings()

Session.bulk_update_mappings()

方法 sqlalchemy.orm.Session 中。bulk_update_mappings（mapper： Mapper[Any]， mappings： Iterable[Dict[str， Any]]）→ 无¶

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

旧版功能

此方法是 SQLAlchemy 2.0 系列的遗留功能。有关现代批量 INSERT 和 UPDATE，请参阅 ORM 批量 INSERT 语句和按主键的 ORM 批量更新。2.0 API 与此方法共享实现细节，并添加了新功能。

参数

mapper¶—— 一个映射的类，或者实际的 Mapper 对象表示映射中表示的单一对象列表。
mappings¶—— 一系列字典，每个字典都包含要更新的映射行的状态，根据 mapped 类上的属性名称。如果映射引用多个表，例如联接继承映射，则每个字典可能包含所有表对应的键。所有存在但不属于主键的键都应用于 UPDATE 语句的 SET 子句;主键值是必需的，应用于 WHERE 子句。

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

Session.bulk_insert_mappings()

Session.bulk_save_objects（）

方法 sqlalchemy.orm.Session 中。close（）→ 无¶

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

这将清除与此关联的所有 ORM 对象 Session 结束任何正在进行的事务，并且释放此 会话本身已从关联的 Engine 对象。然后，该作会离开 Session 处于可以再次使用的状态。

提示

在默认运行模式下，Session.close（） 方法不会阻止 Session 再次被使用。Session 本身实际上并没有明显的 “closed” 状态;它仅仅意味着 Session 将释放所有数据库连接和 ORM 对象。

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

在 1.4 版本发生变更： Session.close（） 方法不会立即创建新的 SessionTransaction 对象;相反，只有当 Session 再次用于数据库作时，才会创建新的 SessionTransaction。

另请参阅

结束语 - 有关语义的详细信息 Session.close（） 和 Session.reset（）的 Session.reset（） 来获取。

Session.reset（） - 一个类似的方法，其行为类似于 close（） 替换为参数 Session.close_resets_only设置为 True。

类方法 sqlalchemy.orm.Session 中。close_all（）→ 无¶: 继承自 sqlalchemy.orm.session._SessionClassMethods.close_all sqlalchemy.orm.session._SessionClassMethods

关闭内存中的所有会话。

1.3 版后已移除： Session.close_all（） 方法已弃用，并将在未来发行版中删除。请参阅 close_all_sessions（）。

方法 sqlalchemy.orm.Session 中。commit（）→ 无¶

刷新待处理的更改并提交当前事务。

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

当 Session 没有事务时，表示未在此 Session 上调用任何作自上次调用 Session.commit（） 以来，该方法将开始并提交一个仅限内部的“逻辑”事务，除非检测到待处理的刷新更改，否则该事务通常不会影响数据库，但仍将调用事件处理程序和对象过期规则。

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

另请参阅

犯

管理事务

使用 AsyncSession 时防止隐式 IO

方法 sqlalchemy.orm.Session 中。connection（bind_arguments：_BindArgumentsNone=None， execution_options：CoreExecuteOptionsParameterNone=None）→ 连接¶

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

返回与当前事务对应的 Connection，或者如果没有事务正在进行，则开始一个新的事务，并将 Connection 返回（请注意，没有事务状态是使用 DBAPI 建立的，直到第一个 SQL 语句）。

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

参数

bind_arguments¶ —— 绑定参数字典。可能包括 “mapper”、“bind”、“clause” 和其他传递给 Session.get_bind（） 的自定义参数。
execution_options¶ –

将传递给 Connection.execution_options() 的执行选项字典，当仅首先获得连接。如果 Session 中已存在该连接，则会发出警告并忽略参数。

另请参阅

设置事务隔离级别 / DBAPI AUTOCOMMIT

方法 sqlalchemy.orm.Session 中。delete（instance： object）→ 无¶

将实例标记为已删除。

假定对象为 persistent 或通过时分离;调用该方法后，对象将保持持久状态，直到下一次刷新继续。在此期间，该对象也将是 Session.deleted 集合的成员。

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

另请参阅

删除 - 使用会话的基础知识

属性 sqlalchemy.orm.Session 的 Session。已删除¶: 此 Session 中标记为 'deleted' 的所有实例的集合

属性 sqlalchemy.orm.Session 的 Session。脏的¶

被视为 dirty 的所有持久性实例的集合。

例如：

some_mapped_object in session.dirty

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

请注意，这种 “肮脏 ”的计算是 “乐观的”;大多数属性设置或集合修改作会将实例标记为 'dirty' 并将其放置在此集中，即使属性的值没有净变化。在 flush 时，将每个属性的值与其之前保存的值进行比较，如果没有净变化，则不会发生 SQL作（这是一个成本更高的作，因此仅在 flush 时完成）。

要检查实例是否对其属性进行了可作的净更改，请使用 Session.is_modified（） 方法。

方法 sqlalchemy.orm.Session 中。enable_relationship_loading（obj： object）→ 无¶

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

警告

enable_relationship_loading（） 的存在是为了服务于特殊用例，不建议用于一般用途。

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

该对象将附加到此会话，但会不参与任何持久化作;对于几乎所有目的，它的状态都将保持 “transient” 或 “detached”，但 relationship loading 的情况除外。

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

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

使瞬态对象与 Session 关联通过 Session.enable_relationship_loading() pending，正常使用 Session.add（） 将其添加到 Session 中。如果该对象表示数据库中的现有身份，则应使用 Session.merge（） 将其合并。

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

另请参阅

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

make_transient_to_detached（） - 允许将对象添加到不发出 SQL 的 Session 中，然后 SQL 将在访问时取消过期属性。

方法 sqlalchemy.orm.Session 中。execute（statement：可执行文件， params：_CoreAnyExecuteParamsNone=None， *， execution_options： OrmExecuteOptionsParameter = {}， bind_arguments：_BindArgumentsNone=无， _parent_execute_state：AnyNone=无， _add_event：AnyNone=无）→ 结果[Any]¶

执行 SQL 表达式构造。

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

例如：

from sqlalchemy import select

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

Session.execute（） 的 API 协定类似于 Connection 的 2.0 样式版本 Connection.execute（） 的 API 协定。

在 1.4 版本发生变更： Session.execute（） 方法是现在是 ORM 语句执行的主要点，当使用 2.0 样式ORM 用法。

参数

statement¶– 一个可执行语句（即一个 Executable 表达式，例如 select（））。
params¶– 包含绑定参数值的可选字典或字典列表。如果是单个字典，则执行单行;如果是字典列表，则将调用 “executeMany”。每个字典中的键必须与语句中存在的参数名称相对应。
execution_options¶ –

可选的 Dictionary of execution options，将与语句 execution 关联。此字典可以提供 Connection.execution_options() 接受的选项的子集，还可以提供仅在 ORM 上下文中理解的其他选项。

另请参阅

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

结果

Result 对象。

方法 sqlalchemy.orm.Session 中。expire（instance： object， attribute_names：Iterable[str]None=None）→ 无¶

使实例上的属性过期。

将实例的属性标记为过期。当过期的属性，则会向 Session 对象的当前事务上下文，以便加载给定实例的所有过期属性。请注意，高度隔离的事务将返回与之前在同一事务中读取的值相同的值，而不管该事务之外的数据库状态如何变化。

要同时使 Session 中的所有对象过期，请使用 Session.expire_all（）。

Session 对象的默认行为是每当 Session.rollback（） 或 Session.commit（） 方法，以便可以为新事务加载新状态。因此，调用 Session.expire（） 仅对当前事务中发出非 ORM SQL 语句的特定情况有意义。

参数

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

另请参阅

刷新 / 过期 - 介绍性材料

会话.expire（）

Session.refresh（）

Query.populate_existing（）

方法 sqlalchemy.orm.Session 中。expire_all（）→ 无¶

使此 Session 中的所有持久性实例过期。

下次访问持久化实例上的任何属性时，将使用 Session 对象的当前事务上下文，以便加载给定实例的所有过期属性。请注意，高度隔离的事务将返回与之前在同一事务中读取的值相同的值，而不管该事务之外的数据库状态如何变化。

要使单个对象和这些对象上的各个属性过期，请使用 Session.expire（）。

Session 对象的默认行为是每当 Session.rollback（） 或 Session.commit（） 方法，以便可以为新事务加载新状态。因此，假设事务是隔离的，通常不需要调用 Session.expire_all（） 。

另请参阅

刷新 / 过期 - 介绍性材料

会话.expire（）

Session.refresh（）

Query.populate_existing（）

方法 sqlalchemy.orm.Session 中。expunge（instance： object）→ 无¶

从此 Session 中删除实例。

这将释放对实例的所有内部引用。将根据 Expunge Cascade 规则应用 Cascading。

方法 sqlalchemy.orm.Session 中。expunge_all（）→ 无¶

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

这相当于对 this 中的所有对象调用 expunge（obj） 会话。

方法 sqlalchemy.orm.Session 中。flush（objects：Sequence[Any]None=None）→ 无¶

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

将所有待处理的对象创建、删除和修改作为 INSERT、DELETE、UPDATE 等写出到数据库中。作由 Session 的工作单元依存关系求解器自动排序。

数据库作将在当前事务上下文中发出，并且不会影响事务的状态，除非发生错误，在这种情况下，整个事务都会回滚。您可以在事务中随心所欲地 flush（）将更改从 Python 移动到数据库的事务缓冲区。

参数

对象¶ –

自选;将 flush作限制为仅对给定集合中的元素进行作。

此功能适用于一组极其狭窄的用例，在这些用例中，可能需要在完全 flush（）发生之前对特定对象进行作。它不用于一般用途。

方法 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：AnyNone=None， execution_options： OrmExecuteOptionsParameter = {}， bind_arguments：_BindArgumentsNone=None）→_ONone¶

根据给定的主键标识符返回实例，如果未找到，则返回 None。

例如：

my_user = session.get(User, 5)

some_object = session.get(VersionedFoo, (5, 10))

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

1.4 版本中的新功能：添加了 Session.get（），它是从现在遗留的 Query.get（） 方法移动而来的。

Session.get（） 很特殊，因为它提供了对 Session 的身份映射的直接访问。如果本地身份映射中存在给定的主键标识符，则直接从此集合返回该对象，并且不会发出 SQL，除非该对象已标记为完全过期。如果不存在，则执行 SELECT 以查找对象。

Session.get（） 还将执行检查对象是否存在于身份映射中并标记为过期 - 发出 SELECT 以刷新对象并确保该行仍然存在。否则，将引发 ObjectDeletedError。

参数

entity¶—— 一个映射的类或 Mapper，指示要加载的实体类型。
识别¶ –

表示主键的标量、元组或字典。对于复合（例如多列）主键，应传递 Tuples 或 Dictionary。

对于单列主键，标量调用形式通常是最方便的。如果一行的主键是值 “5”，则调用如下所示：
```
my_object = session.get(SomeClass, 5)
```
元组形式包含主键值，通常位于它们与映射的 桌子 Object 的主键列，或者如果 Mapper.primary_key配置参数的 Sequences 中使用该参数。例如，如果一行的主键由整数数字 “5， 10” 表示，则调用将如下所示：
```
my_object = session.get(SomeClass, (5, 10))
```
字典形式应包括与主键的每个元素对应的映射属性名称作为键。如果映射的类具有 attributes id， version_id 作为存储对象主键值的属性，则调用将如下所示：
```
my_object = session.get(SomeClass, {"id": 5, "version_id": 10})
```
options¶– 可选的 loader 选项序列，如果发出一个选项，将应用于查询。
populate_existing¶– 使该方法无条件地发出 SQL 查询并使用新加载的数据刷新对象，无论该对象是否已经存在。
with_for_update¶ – 可选布尔值 True，表示 FOR UPDATE 应该使用，或者可以是包含标志的字典，以便指示 SELECT 的更具体的 FOR UPDATE 标志集; flags 应与 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。

方法 sqlalchemy.orm.Session 中。get_bind（mapper：_EntityBindKey[_O]None=None， *， clause：ClauseElementNone=None， bind：_SessionBindNone=None， _sa_skip_events：boolNone=None， _sa_skip_for_implicit_returning： bool = False， **kw： Any）→EngineConnection¶

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

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

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

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

解决顺序为：

如果存在 mapper given 和 Session.binds，则首先根据正在使用的 mapper 找到一个 bind，然后是正在使用的 Map 类，然后是 Map 类的__mro__中存在的任何基类，从更具体的超类到更通用的超类。
if 子句给定且 Session.binds 存在，则根据 Session.binds 中存在的给定子句中找到的 Table 对象找到绑定。
如果存在 Session.binds，则返回该 Session.binds。
if 子句，尝试返回链接到最终与子句关联的 MetaData 的 bind。
如果给定 mapper，则尝试返回链接到 MetaData 的绑定，该 MetaData 最终与 Table 或 mapper 映射到的其他可选内容相关联。
找不到 bind，UnboundExecutionError 被提升。

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

参数

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

另请参阅

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

Session.binds

Session.bind_mapper（）

Session.bind_table（）

方法 sqlalchemy.orm.Session 中。get_nested_transaction（）→SessionTransactionNone¶: 返回当前正在进行的嵌套事务（如果有）。

在 1.4 版本加入.

方法 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：AnyNone=None， execution_options： OrmExecuteOptionsParameter = {}， bind_arguments：_BindArgumentsNone=None）→ _O¶

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

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

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

2.0.22 新版功能.

结果: 对象实例。

另请参阅

Session.get（） - 等效方法: 如果未找到具有提供的主键的行，则返回 None

方法 sqlalchemy.orm.Session 中。get_transaction（）→SessionTransactionNone¶: 返回当前正在进行的根事务（如果有）。

在 1.4 版本加入.

类方法 sqlalchemy.orm.Session 中。identity_key（class_：Type[Any]None=None， ident：AnyTuple[Any,...]=None， *， instance：AnyNone=None， row：Row[Any]RowMappingNone=None， identity_token：AnyNone=None）→ _IdentityKeyType[Any]¶

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

返回身份密钥。

这是 identity_key（） 的别名。

属性 sqlalchemy.orm.Session 的 Session。identity_map： IdentityMap¶

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

迭代 Session.identity_map.values（） 可以访问当前 session 中的完整持久对象集（即具有行标识的对象）。

另请参阅

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

方法 sqlalchemy.orm.Session 中。in_nested_transaction（）→ bool¶: 如果此 Session 已经开始一个嵌套事务，例如 SAVEPOINT，则返回 True。

在 1.4 版本加入.

方法 sqlalchemy.orm.Session 中。in_transaction（）→ bool¶: 如果此 Session 已开始事务，则返回 True。

在 1.4 版本加入.

另请参阅

Session.is_active

属性 sqlalchemy.orm.Session 的 Session。信息¶

用户可修改的字典。

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

方法 sqlalchemy.orm.Session 中。invalidate（）→ 无¶

使用连接失效关闭此 Session。

这是 Session.close（） 的一个变体，它将额外确保 Connection.invalidate（） method 将在当前用于事务的每个 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 对象都被删除。

属性 sqlalchemy.orm.Session 的 Session。is_active¶

如果此 Session 未处于 “partial rollback” 状态，则为 True。

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

“partial rollback” 状态通常表示 Session 的 flush 过程失败，并且 Session.rollback（） 方法才能完全回滚事务。

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

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

另请参阅

“由于刷新期间的上一个异常，此 Session 的事务已回滚。”（或类似名称）

Session.in_transaction（）

方法 sqlalchemy.orm.Session 中。is_modified（instance： object， include_collections： bool = True）→ bool¶

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

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

它实际上是更昂贵和准确的版本。 Session.dirty 集合;对每个属性的 Net “dirty” 状态执行完整测试。

例如：

return session.is_modified(someobject)

此方法需要注意以下几点：

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

仅当属性容器的 active_history 标志设置为 True 时，才会在设置时无条件地获取 “old” 值。此标志通常用于主键属性和标量对象引用，它们不是简单的多对一。要为任何任意映射列设置此标志，请使用 active_history 参数替换为 column_property（） 的

参数

instance¶—— 要测试待处理更改的映射实例。
include_collections¶– 指示作中是否应包含多值集合。将此设置为 False 是一种仅检测基于局部列的属性（即标量列或多对一外键）的方法，这些属性在刷新时会导致此实例发生 UPDATE。

方法 sqlalchemy.orm.Session 中。merge（instance： _O， *， load： bool = True， options：Sequence[ORMOption]None=None）→ _O¶

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

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

如果关联使用 cascade=“merge” 映射，则此作将级联到关联的实例。

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

参数

instance¶- 要合并的实例。
加载¶ –

Boolean，当 False 时，merge（） 切换到“高性能”模式，这会导致它放弃发出历史事件以及所有数据库访问。此标志用于将对象图传输到 Session 中从二级缓存，或传输刚刚加载的对象放入 worker 线程或进程拥有的 Session 中，而无需重新查询数据库。

load=False 用例添加了一个警告，即给定的对象必须处于 “干净” 状态，即没有待处理的更改 to be flushed - 即使传入对象与任何 会话。这样，当 merge作填充本地属性并级联到相关对象和集合时，这些值可以按原样“标记”到目标对象上，而无需生成任何历史记录或属性事件，也无需将传入数据与任何可能未加载的现有相关对象或集合进行协调。从 load=False 生成的对象总是被生成为 “clean”，因此给定的对象也应该是 “clean” 的，否则这表明该方法被误用。
选项¶ –

可选的 loader 选项序列，当 merge作从数据库中加载对象的现有版本时，这些选项将应用于 Session.get（） 方法。

在 1.4.24 版本加入.

另请参阅

make_transient_to_detached（） - 提供将单个对象 “合并” 到 Session 中的替代方法

属性 sqlalchemy.orm.Session 的 Session。新¶: 此 Session 中标记为 'new' 的所有实例的集合。

属性 sqlalchemy.orm.Session 的 Session。no_autoflush¶

返回禁用 autoflush 的上下文管理器。

例如：

with session.no_autoflush:

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

在 with： 块中继续的作不会受到查询访问时发生的刷新的影响。这在初始化涉及现有数据库查询的一系列对象时非常有用，其中未完成的对象不应被刷新。

类方法 sqlalchemy.orm.Session 中。object_session（instance： object）→SessionNone¶

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

返回对象所属的 Session。

这是 object_session（） 的别名。

方法 sqlalchemy.orm.Session 中。prepare（）→ 无¶

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

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

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

方法 sqlalchemy.orm.Session 中。query（*entities： _ColumnsClauseArgument[Any]， **kwargs： Any）→ query[Any]¶

返回与此对应的新 Query 对象 会话。

请注意，Query 对象是 SQLAlchemy 2.0 的遗留对象;select（） 结构现在用于构造 ORM 查询。

另请参阅

SQLAlchemy Unified 教程

ORM 查询指南

旧版查询 API - 旧版 API 文档

方法 sqlalchemy.orm.Session 中。refresh（instance： object， attribute_names：Iterable[str]None=None， with_for_update： ForUpdateParameter = None）→ 无¶

Expire 和 refresh 给定实例上的属性。

所选属性将首先过期，就像使用 Session.expire（）;然后，将向数据库发出 SELECT 语句，以使用当前事务中可用的当前值刷新面向列的属性。

如果面向 relationship（） 的属性已经预先加载到对象上，它们也会立即加载，使用与最初加载它们相同的预先加载策略。

在 1.4 版本加入： - Session.refresh（） 方法也可以刷新预先加载的属性。

如果在 attribute_names 中明确命名，则通常使用 SELECT（或 “LAZY”）加载器策略加载的面向 relationship（） 的属性也将加载集合，使用 立即加载器策略。如果未在 Session.refresh.attribute_names 中命名延迟加载的关系，则它们将保留为“延迟加载”属性，并且不会隐式刷新。

在 2.0.4 版本发生变更： Session.refresh（） 方法现在将面向延迟加载的 relationship（） 进行刷新属性 Session.refresh.attribute_names 收集。

提示

虽然 Session.refresh（） 方法能够刷新面向列和关系的属性时，其主要关注点是刷新本地面向列的属性在单个实例上。对于更多开放式 “刷新” 功能，包括刷新一次，同时对 RELATIONSHIP LOADER 具有显式控制权策略，请使用填充现有功能。

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

参数

attribute_names¶ – 可选。字符串属性名称的可迭代集合，指示要刷新的属性子集。
with_for_update¶ – 可选布尔值 True，表示 FOR UPDATE 应该使用，或者可以是包含标志的字典，以便指示 SELECT 的更具体的 FOR UPDATE 标志集; flags 应与 Query.with_for_update（）.取代 Session.refresh.lockmode 参数。

另请参阅

刷新 / 过期 - 介绍性材料

会话.expire（）

Session.expire_all（）

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

方法 sqlalchemy.orm.Session 中。reset（）→ 无¶

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

此方法提供与 Session.close（） 方法历史上提供了 Session 的状态被重置，就好像对象是全新的一样，并准备好再次使用。然后，此方法对于将 Session.close_resets_only 设置为 False 的 Session 对象可能很有用，因此“仅重置”行为仍然可用。

2.0.22 新版功能.

另请参阅

结束语 - 有关语义的详细信息 Session.close（） 和 Session.reset（）的 Session.reset（） 来获取。

Session.close（） - 类似的方法将额外当参数 Session.close_resets_only 设置为 False。

方法 sqlalchemy.orm.Session 中。rollback（）→ 无¶

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

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

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

另请参阅

回滚

管理事务

方法 sqlalchemy.orm.Session 中。scalar（statement：可执行文件， params：_CoreSingleExecuteParamsNone=None， *， execution_options： OrmExecuteOptionsParameter = {}， bind_arguments：_BindArgumentsNone=None， **kw： Any）→ Any¶

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

用法和参数与 Session.execute（）的返回结果为标量 Python 值。

方法 sqlalchemy.orm.Session 中。scalars（statement：可执行， params：_CoreAnyExecuteParamsNone=None， *， execution_options： OrmExecuteOptionsParameter = {}， bind_arguments：_BindArgumentsNone=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（） 的行为进行对比

类 sqlalchemy.orm 中。SessionTransaction 会话事务¶

会话级事务。

SessionTransaction 是从 会话.begin（） 和 Session.begin_nested（） 方法。它主要是一个内部对象，在现代使用中为 session 事务提供了一个上下文管理器。

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

在 1.4 版本发生变更：用于 SessionTransaction 对象。

另请参阅

管理事务

会话.begin（）

Session.begin_nested（）

Session.rollback（）

会话.commit（）

Session.in_transaction（）

Session.in_nested_transaction()

Session.get_transaction（）

Session.get_nested_transaction()

成员

嵌套、原点、父级

类签名

类 sqlalchemy.orm.SessionTransaction （ sqlalchemy.orm.state_changes._StateChange ， sqlalchemy.engine.util.TransactionalContext ）

属性 sqlalchemy.orm.SessionTransaction. 嵌套： bool = False¶

指示这是嵌套事务还是 SAVEPOINT 事务。

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

另请参阅

SessionTransaction.origin

属性 sqlalchemy.orm.SessionTransaction. 来源：SessionTransactionOrigin¶

此 SessionTransaction 的来源。

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

2.0 版的新Function。

attribute parent（属性 sqlalchemy.orm.SessionTransaction. 父级）¶

此 SessionTransaction 的 SessionTransaction 中。

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

类 sqlalchemy.orm 中。SessionTransactionOrigin （会话事务源）¶

指示 SessionTransaction 的来源。

此枚举位于 SessionTransaction.origin 属性 SessionTransaction 对象。

2.0 版的新Function。

成员

AUTOBEGIN、BEGIN、BEGIN_NESTED、SUBTRANSACTION

类签名

class sqlalchemy.orm.SessionTransactionOrigin （enum.枚举）

属性 sqlalchemy.orm.SessionTransactionOrigin. AUTOBEGIN = 0¶: 事务由 AutoStart 启动

属性 sqlalchemy.orm.SessionTransactionOrigin. BEGIN = 1¶: 事务是通过调用 Session.begin（） 来启动的

属性 sqlalchemy.orm.SessionTransactionOrigin. BEGIN_NESTED = 2¶: tranaction 由 Session.begin_nested（） 启动

属性 sqlalchemy.orm.SessionTransactionOrigin. SUBTRANSACTION = 3¶: transaction 是一个内部的 “subtransaction”

Session 工具¶

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

函数 sqlalchemy.orm 中。close_all_sessions（）→ 无¶

关闭内存中的所有会话。

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

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

在 1.3 版本加入.

函数 sqlalchemy.orm 中。make_transient（instance： object）→ 无¶

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

注意

make_transient（） 是仅适用于高级用例的特殊情况函数。

假定给定的映射实例位于持久或 detached 状态。该函数将删除它与任何 Session 及其 InstanceState.identity 的 InstanceState.identity 中。其效果是，对象的行为就像它是新构造的一样，除了保留在调用时加载的任何属性/集合值。InstanceState.deleted 标志也会重置如果此对象已因使用 Session.delete（） 的

警告

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

通过 Session.expire（） 过期
作为提交 session 事务的自然效果而过期，例如 Session.commit（）
通常延迟加载，但当前未加载
是 “deferred” （请参阅使用 Column Deferral 限制哪些列加载）并且尚未加载
不存在于加载此对象的查询中，例如在联接表继承和其他方案中常见的情况。

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

另请参阅

make_transient_to_detached（）

函数 sqlalchemy.orm 中。make_transient_to_detached（instance： object）→ 无¶

使给定的瞬态实例分离。

注意

make_transient_to_detached（） 是仅适用于高级用例的特殊情况函数。

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

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

这是一个特殊的用例函数，与对 Session.merge（） 的正常调用不同，因为可以在没有任何 SQL 调用的情况下制造给定的持久状态。

另请参阅

make_transient（）

Session.enable_relationship_loading()

函数 sqlalchemy.orm 中。object_session（instance： object）→SessionNone（无会话）¶

返回给定实例所属的 Session。

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

函数 sqlalchemy.orm.util 中。was_deleted（object_： object）→ bool¶

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

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

另请参阅

InstanceState.was_deleted

属性和状态管理工具¶

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

对象名称	描述
del_attribute（实例、密钥）	删除属性的值，触发历史事件。
flag_dirty（实例）	将实例标记为 'dirty' ，而不提及任何特定属性。
flag_modified（实例、键）	将实例上的属性标记为 'modified'。
get_attribute（实例、键）	获取属性的值，触发所需的任何可调用对象。
get_history（obj， key[，被动]）	返回给定对象和属性键的 `History` 记录。
历史	一个 3 元组，由 added、unchanged 和 deleted 值组成，表示对 instrumented 属性发生的更改。
init_collection（obj， key）	初始化 collection 属性并返回 collection 适配器。
instance_state	返回给定映射对象的 `InstanceState`。
is_instrumented（实例、键）	如果给定实例上的给定属性由 attributes 包检测，则返回 True。
object_state（实例）	给定一个对象，返回 `InstanceState` 与对象关联。
set_attribute（实例、键、值 [、发起方]）	设置属性的值，触发历史事件。
set_committed_value（实例、键、值）	设置没有历史事件的属性的值。

函数 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）→ 无¶

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

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

函数 sqlalchemy.orm.attributes 中。get_attribute（instance： object， key： str）→ 任意¶

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

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

函数 sqlalchemy.orm.attributes 中。get_history（obj： object， key： str， passive： PassiveFlag = symbol（'PASSIVE_OFF'））→ 历史¶

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

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

注意

更喜欢使用 AttributeState.history 和 AttributeState.load_history（） 访问器检索 实例属性的历史记录。

参数

obj¶ – 一个对象，其类由 attributes 包进行检测。
key¶ - 字符串属性名称。
passive¶ —— 表示 attribute 的加载行为如果该值尚不存在。这是一个 bitflag 属性，默认为元件 PASSIVE_OFF 指示应发出所有必要的 SQL。

另请参阅

AttributeState.history （属性状态.历史）

AttributeState.load_history（） - 如果值在本地不存在，则使用 loader 可调用对象检索历史记录。

函数 sqlalchemy.orm.attributes 中。init_collection（obj： object， key： str）→ CollectionAdapter¶

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

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

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）→ 无¶

将实例上的属性标记为 'modified'。

这会在实例上设置 'modified' 标志，并且为给定属性建立无条件更改事件。该属性必须具有值，否则 InvalidRequestError 引发。

在不引用任何特定属性的情况下将对象标记为 “dirty” 因此，在 flush 中将其视为 Flush，请使用 flag_dirty（） 调用。

另请参阅

flag_dirty（）

函数 sqlalchemy.orm.attributes 中。flag_dirty（instance： object）→ 无¶

将实例标记为 'dirty' ，而不提及任何特定属性。

这是一个允许对象穿过的特殊作用于 Flush 事件拦截的进程，例如 SessionEvents.before_flush（） 中。请注意，对于没有更改的对象，在 flush 过程中不会发出任何 SQL，即使通过此方法标记为 dirt 也是如此。但是，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）¶

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

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

函数 sqlalchemy.orm.attributes 中。set_attribute（instance： object， key： str， value： Any， initiator：AttributeEventTokenNone=None）→ 无¶

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

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

参数

instance¶ – 将被修改的对象
key¶- 属性的字符串名称
value¶ – 要分配的值
发起方¶ –

一个 Event 实例，该实例将从以前的事件侦听器传播。当 set_attribute（） 函数在提供 Event 对象的现有事件侦听函数中使用时，将使用此参数;该对象可用于跟踪事件链的来源。

在 1.2.3 版本加入.

函数 sqlalchemy.orm.attributes 中。set_committed_value（实例、键、值）¶

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

取消存在的任何先前历史记录。该值应该是标量持有属性的标量值，或者任何集合持有属性的可迭代值。

这与延迟加载程序触发并从数据库加载其他数据时使用的底层方法相同。特别是，此方法可由应用程序代码使用，这些代码通过单独的查询加载了其他属性或集合，然后可以将其附加到实例，就像它是其原始加载状态的一部分一样。

类 sqlalchemy.orm.attributes 中。历史¶

一个 3 元组，由 added、unchanged 和 deleted 值组成，表示对 instrumented 属性发生的更改。

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

from sqlalchemy import inspect

hist = inspect(myobject).attrs.myattribute.history

每个 Tuples 成员都是一个可迭代的序列：

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

成员

added， deleted， empty（）， has_changes（）， non_added（）， non_deleted（）， sum（）， unchanged

类签名

类 sqlalchemy.orm.History （builtins.tuple）

sqlalchemy.orm.attributes.History. 属性添加：Tuple[（）]List[Any]¶: 字段编号 0 的别名

attribute 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（）→ 序列[Any]¶: 返回 unchanged + deleted 的集合。

方法 sqlalchemy.orm.attributes.History. non_deleted（）→ Sequence[Any]¶: 返回 added + unchanged 的集合。

方法 sqlalchemy.orm.attributes.History. sum（）→ 序列[Any]¶: 返回 added + unchanged + deleted 的集合。

attribute sqlalchemy.orm.attributes.History. unchanged：Tuple[（）]List[Any]¶: 字段编号 1 的别名

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy ORM

会话 API¶

Session 和 sessionmaker（）¶

Session 工具¶

属性和状态管理工具¶