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

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

上下文会话 API

class sqlalchemy.orm.scoped_session

提供对 Session 对象的作用域管理。

请查看上下文/线程本地会话以获取教程。

注意

当使用异步 I/O (asyncio)时，应该使用与 scoped_session 替代的异步兼容 async_scoped_session 类。

成员

call(), init(), add(), add_all(),  autoflush, begin(), begin_nested(), bind, bulk_insert_mappings(),  bulk_save_objects(), bulk_update_mappings(), close(), close_all(),  commit(), configure(), connection(), delete(), deleted, dirty,  execute(), expire(), expire_all(), expunge(), expunge_all(), flush(),  get(), get_bind(), get_one(), identity_key(), identity_map, info,  is_active, is_modified(), merge(), new, no_autoflush, object_session(),  query(), query_property(), refresh(), remove(), reset(), rollback(),  scalar(), scalars(), session_factory

类签名

类sqlalchemy.orm.scoped_session (typing.Generic)

method __call__(**kw: Any) → _S

如果不存在，使用scoped_session.session_factory创建当前Session。

参数：

**kw – 如果不存在现有的 Session，则将关键字参数传递给 scoped_session.session_factory 可调用对象。如果存在 Session 并且传递了关键字参数，则会引发 InvalidRequestError。

method __init__(session_factory: sessionmaker[_S], scopefunc: Callable[[], Any] | None = None)

构建一个新的 scoped_session。

参数：

• session_factory – 用于创建新的 Session 实例的工厂。通常情况下，但并非一定如此，它是 sessionmaker 的实例。
  
• scopefunc – 定义当前范围的可选函数。如果未传递，则 scoped_session 对象假定“线程本地”范围，并将使用 Python 的 threading.local() 来维护当前 Session。如果传递，则该函数应返回可哈希的标记；此标记将用作字典中的键，以便存储和检索当前 Session。
  

method add(instance: object, _warn: bool = True) → None

将对象放入此 Session 中。

代表 scoped_session 类的 Session 类的代理。

当传递给 Session.add() 方法时处于 transient 状态的对象将移至 pending 状态，直到下一次刷新，此时它们将移至 persistent 状态。

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

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

另请参见

Session.add_all()

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

method add_all(instances: Iterable[object]) → None

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

代理Session类，代表scoped_session类。

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

另请参阅

Session.add()

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

attribute autoflush

代表scoped_session类的Session.autoflush属性的代理。

method begin(nested: bool = False) → SessionTransaction

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

代理Session类，代表scoped_session类。

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

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

参数：

nested – 如果为 True，则开始一个 SAVEPOINT 事务，并等同于调用Session.begin_nested()。有关 SAVEPOINT 事务的文档，请参阅使用 SAVEPOINT。

返回：

SessionTransaction对象。请注意，SessionTransaction充当 Python 上下文管理器，允许在“with”块中使用Session.begin()。有关示例，请参阅显式开始。

另请参阅

自动开始

管理事务

Session.begin_nested()

method begin_nested() → SessionTransaction

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

代理scoped_session类的Session类。

目标数据库及其关联的驱动程序必须支持 SQL SAVEPOINT 才能使该方法正常运行。

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

返回：

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

另请参阅

使用 SAVEPOINT

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

attribute bind

代理scoped_session类的Session.bind属性。

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

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

代理scoped_session类的Session类。

旧特性

此方法是 SQLAlchemy 2.0 系列的旧特性。对于现代批量 INSERT 和 UPDATE，请参阅 ORM 批量 INSERT 语句和 ORM 按主键批量 UPDATE 部分。2.0 API 与此方法共享实现细节，并添加了新功能。

参数：

• mapper – 一个映射类，或者实际的Mapper对象，代表映射列表中表示的对象类型。
  
• mappings – 一系列字典，每个字典包含要插入的映射行的状态，以映射类上的属性名称表示。如果映射涉及多个表，例如联接继承映射，则每个字典必须包含要填充到所有表中的所有键。
  
• return_defaults –
  当为 True 时，插入过程将被改变，以确保新生成的主键值将被获取。通常，此参数的理由是为了使联接表继承映射能够被批量插入。
  注意
  对于不支持 RETURNING 的后端，Session.bulk_insert_mappings.return_defaults 参数可能会显著降低性能，因为 INSERT 语句无法再批量处理。请参阅“插入多个值”行为的 INSERT 语句以了解受影响的后端的背景信息。
  
• render_nulls –
  当为 True 时，None 的值将导致 NULL 值被包含在 INSERT 语句中，而不是从 INSERT  中省略该列。这允许所有要插入的行具有相同的列集，从而允许将完整的行集批量到 DBAPI。通常，每个包含与上一行不同组合的 NULL  值的列集必须从呈现的 INSERT  语句中省略一个不同的系列列，这意味着它必须作为一个单独的语句发出。通过传递此标志，保证了整个行集将被批处理到一个批次中；但代价是，由省略列调用的服务器端默认值将被跳过，因此必须小心确保这些值不是必需的。
  警告
  当设置此标志时，不会调用服务器端默认的 SQL 值用于那些以 NULL 插入的列；NULL 值将显式发送。必须小心确保整个操作不需要调用任何服务器端默认函数。
  

另请参阅

ORM-启用的 INSERT、UPDATE 和 DELETE 语句

Session.bulk_save_objects()

Session.bulk_update_mappings()

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

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

代理 Session 类，代表 scoped_session 类。

遗留特性

该方法是 SQLAlchemy 2.0 系列的传统功能。对于现代批量插入和更新，请参阅 ORM 批量插入语句和 ORM 按主键批量更新部分。

对于一般的 ORM 映射对象的 INSERT 和 UPDATE，请优先使用标准的 unit of work 数据管理模式，介绍在  SQLAlchemy 统一教程的 ORM 数据操作部分。SQLAlchemy 2.0 现在使用现代方言的“插入多个值”的行为用于 INSERT  语句，解决了以前的批量插入缓慢的问题。

参数：

• objects –
  一系列映射对象实例。映射对象按原样保留，并且之后不与Session关联。
  对于每个对象，对象是作为 INSERT 还是 UPDATE 发送取决于Session在传统操作中使用的相同规则；如果对象具有InstanceState.key属性设置，则假定对象是“分离的”，将导致 UPDATE。否则，将使用 INSERT。
  在 UPDATE 的情况下，语句根据已更改的属性分组，并且因此将成为每个 SET 子句的主题。如果 update_changed_only 设置为 False，则每个对象中存在的所有属性都将应用于 UPDATE 语句，这可能有助于将语句组合成更大的 executemany()，还将减少检查属性历史的开销。
  
• return_defaults – 当设置为 True 时，缺少生成默认值的值的行，即整数主键默认值和序列，将逐个插入，以便主键值可用。特别是这将允许加入继承和其他多表映射正确插入，无需提前提供主键值；然而，Session.bulk_save_objects.return_defaults 极大地降低了该方法的整体性能。强烈建议请使用标准的Session.add_all()方法。
  
• update_changed_only – 当设置为 True 时，UPDATE 语句基于每个状态中已记录更改的属性。当设置为 False 时，所有存在的属性（主键属性除外）都将进入 SET 子句。
  
• preserve_order – 当为 True 时，插入和更新的顺序与对象给出的顺序完全匹配。当为 False 时，常见类型的对象被分组为插入和更新，以便更多批处理机会。
  

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

Session.bulk_insert_mappings()

Session.bulk_update_mappings()

method bulk_update_mappings(mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]]) → None

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

代表 scoped_session 类的 Session 类的代理。

遗留特性

此方法是 SQLAlchemy 2.0 系列的遗留特性。对于现代批量插入和更新，请参阅 ORM 批量插入语句 和 ORM 通过主键批量更新 部分。2.0 API 共享此方法的实现细节，并添加了新功能。

参数：

• mapper – 一个映射类，或者实际的 Mapper 对象，代表映射列表中表示的单个对象类型。
  
• mappings –  一个字典序列，每个字典包含要更新的映射行的状态，以映射类上的属性名称表示。如果映射涉及多个表，例如连接继承映射，则每个字典可能包含对应于所有表的键。所有那些出现且不是主键的键都应用于  UPDATE 语句的 SET 子句；必需的主键值应用于 WHERE 子句。
  

另请参阅

启用 ORM 的 INSERT、UPDATE 和 DELETE 语句

Session.bulk_insert_mappings()

Session.bulk_save_objects()

method close() → None

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

代表 scoped_session 类的 Session 类的代理。

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

提示

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

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

从版本 1.4 开始：Session.close()方法不会立即创建新的SessionTransaction对象； 只有在再次为数据库操作使用Session时，才会创建新的SessionTransaction。

请参阅

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

Session.reset() - 一种行为类似于带有参数Session.close_resets_only设置为True的close()的方法。

classmethod close_all() → None

关闭所有内存中的会话。

代表scoped_session类为Session类进行了代理。

自版本 1.3 起不推荐使用：Session.close_all()方法已弃用，并将在将来的版本中删除。请参阅close_all_sessions()。

method commit() → None

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

代表scoped_session类的Session类的代理。

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

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

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

另请参见

提交

事务管理

在使用 AsyncSession 时防止隐式 IO

method configure(**kwargs: Any) → None

重新配置由此scoped_session使用的sessionmaker。

参见 sessionmaker.configure()。

method connection(bind_arguments: _BindArguments | None = None, execution_options: CoreExecuteOptionsParameter | None = None) → Connection

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

代表scoped_session类的Session类的代理。

返回当前事务对应的Connection，或者如果没有进行事务，则开始新事务并返回Connection（请注意，在发出第一条 SQL 语句之前，与 DBAPI 之间不会建立事务状态）。

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

参数：

• bind_arguments – 绑定参数字典。可能包括“mapper”，“bind”，“clause”，其他传递给Session.get_bind()的自定义参数。
  
• execution_options –
  执行选项字典，将在首次获得连接时传递给Connection.execution_options()，仅在首次获得连接时。如果连接已经存在于Session中，则发出警告并忽略参数。
  另请参阅
  设置事务隔离级别/DBAPI AUTOCOMMIT
  

method delete(instance: object) → None

将实例标记为已删除。

代表scoped_session类的Session类的代理。

当传递时，假定对象为持久或分离状态；在调用该方法之后，对象将保持持久状态，直到下一个刷新发生。在此期间，对象还将是Session.deleted集合的成员。

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

另请参阅

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

attribute deleted

在此Session中标记为“已删除”的所有实例的集合

代理了scoped_session类，代表Session类。

attribute dirty

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

代理了scoped_session类，代表Session类。

例如：

some_mapped_object in session.dirty

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

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

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

method 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 表达式构造。

代理了scoped_session类，代表Session类。

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

例如：

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

Session.execute()的 API 合同与Connection.execute()类似，是Connection的 2.0 风格版本。

从版本 1.4 开始：当使用 2.0 风格 ORM 使用时，Session.execute()方法现在是 ORM 语句执行的主要点。

参数：

• statement – 可执行的语句（即Executable表达式，如select()）。
  
• params – 可选的字典，或包含绑定参数值的字典列表。如果是单个字典，则执行单行；如果是字典列表，则会触发“executemany”。每个字典中的键必须与语句中存在的参数名相对应。
  
• execution_options –
  可选的执行选项字典，将与语句执行关联。该字典可以提供 Connection.execution_options() 接受的选项子集，并且还可以提供仅在 ORM 上下文中理解的其他选项。
  另请参阅
  ORM 执行选项 - ORM 特定的执行选项
  
• bind_arguments – 用于确定绑定的其他参数字典。可能包括“mapper”、“bind”或其他自定义参数。此字典的内容将传递给 Session.get_bind() 方法。
  

返回：

一个 Result 对象。

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

使实例上的属性过期。

代表 scoped_session 类，代理 Session 类。

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

同时使Session中的所有对象过期，可使用 Session.expire_all() 方法。

当调用 Session.rollback() 或 Session.commit() 方法时，Session 对象的默认行为是使所有状态过期，以便为新事务加载新状态。因此，仅在当前事务中发出了非 ORM SQL 语句的情况下调用 Session.expire() 才有意义。

参数：

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

另请参阅

刷新 / 过期 - 入门材料

Session.expire()

Session.refresh()

Query.populate_existing()

method expire_all() → None

使本 Session 中的所有持久化实例过期。

代理了 scoped_session 类的代表 Session 类。

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

要使单个对象以及这些对象上的单个属性过期，请使用 Session.expire()。

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

另请参阅

刷新 / 过期 - 入门材料

Session.expire()

Session.refresh()

Query.populate_existing()

method expunge(instance: object) → None

从此 Session 中删除实例。

代理了 scoped_session 类的代表 Session 类。

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

method expunge_all() → None

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

代理了 scoped_session 类的代表 Session 类。

这相当于在此 Session 中的所有对象上调用 expunge(obj)。

method flush(objects: Sequence[Any] | None = None) → None

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

代表 scoped_session 类，为 Session 类代理。

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

数据库操作将在当前事务上下文中发出，并且不会影响事务的状态，除非发生错误，此时整个事务将回滚。您可以在事务中随意刷新（flush()）以将更改从 Python 移动到数据库的事务缓冲区。

参数：

对象 -

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

此功能仅适用于极少数情况，特定对象可能需要在完全执行 flush() 之前进行操作。不适用于一般用途。

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

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

代表 scoped_session 类，为 Session 类代理。

例如：

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

版本 1.4 中新增：新增 Session.get()，它从现在遗留的 Query.get() 方法中移动而来。

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

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

参数：

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

my_object = session.get(SomeClass, 5)

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

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

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

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

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

返回：

对象实例，或None。

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

返回此Session绑定的“bind”。

代理给scoped_session类的Session类。

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

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

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

解析顺序为：

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

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

参数：

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

另请参见

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

Session.binds

Session.bind_mapper()

Session.bind_table()

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

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

代理为scoped_session类代表Session类。

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

要详细了解参数的文档，请参阅方法Session.get()。

版本 2.0.22 中的新功能。

返回：

对象实例。

另请参见

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

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

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

返回一个身份键。

代理为scoped_session类代表Session类。

这是identity_key()的别名。

attribute identity_map

代理scoped_session类的Session.identity_map属性。

attribute info

用户可修改的字典。

代理scoped_session类的Session类。

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

attribute is_active

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

代理scoped_session类的Session类。

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

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

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

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

另请参阅

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

Session.in_transaction()

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

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

代表scoped_session类的Session类的代理。

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

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

例如：

return session.is_modified(someobject)

此方法有一些注意事项：

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

参数：

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

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

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

代理Session类，代表scoped_session类。

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

如果关联映射了cascade="merge"，此操作会级联到关联的实例。

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

参数：

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

另请参阅

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

attribute new

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

代表 scoped_session 类而为 Session 类代理。

attribute no_autoflush

返回一个上下文管理器，用于禁用自动提交。

代表 scoped_session 类而为 Session 类代理。

例如：

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

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

classmethod object_session(instance: object) → Session | None

返回对象所属的 Session。

代表 scoped_session 类而为 Session 类代理。

这是 object_session() 的别名。

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

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

代表 scoped_session 类而为 Session 类代理。

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

另请参阅

SQLAlchemy 统一教程

ORM 查询指南

遗留查询 API - 遗留 API 文档

method query_property(query_cls: Type[Query[_T]] | None = None) → QueryPropertyDescriptor

返回一个类属性，当调用时，该属性会针对类和当前 Session 生成一个遗留 Query 对象。

遗留特性

scoped_session.query_property() 访问器是特定于传统的 Query 对象的，不被视为 2.0 风格 ORM 使用的一部分。

例如：

from sqlalchemy.orm import QueryPropertyDescriptor
from sqlalchemy.orm import scoped_session
from sqlalchemy.orm import sessionmaker
Session = scoped_session(sessionmaker())
class MyClass:
    query: QueryPropertyDescriptor = Session.query_property()
# after mappers are defined
result = MyClass.query.filter(MyClass.name=='foo').all()

默认情况下，生成会话配置的查询类的实例。要覆盖并使用自定义实现，请提供一个 query_cls 可调用对象。将以类的映射器作为位置参数和一个会话关键字参数调用该可调用对象。

类上放置的查询属性数量没有限制。

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

在给定实例上过期并刷新属性。

代理scoped_session 类的 Session 类。

选定的属性将首先过期，就像使用 Session.expire() 时一样；然后将向数据库发出 SELECT 语句，以使用当前事务中可用的当前值刷新列导向属性。

relationship() 导向属性如果已经在对象上急切加载，将立即被加载，使用与最初加载时相同的急切加载策略。

自 1.4 版开始：- Session.refresh() 方法也可以刷新急切加载的属性。

如果通常使用select（或“延迟”）加载器策略加载的 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 参数。
  

另请参阅

刷新 / 过期 - 入门材料

Session.expire()

Session.expire_all()

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

method remove() → None

丢弃当前Session（如果存在）。

这将首先在当前Session上调用Session.close()方法，释放仍在保持的任何现有事务/连接资源；具体来说，事务将被回滚。然后丢弃Session。在同一范围内的下一次使用时，scoped_session将生成一个新的Session对象。

method reset() → None

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

代理scoped_session类代表Session类。

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

版本 2.0.22 中的新功能。

另请参见

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

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

method rollback() → None

回滚当前进行中的事务。

代理scoped_session类代表Session类。

如果没有进行中的事务，则此方���是一个透传。

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

另请参见

回滚

管理事务

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

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

代理scoped_session类代表Session类。

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

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

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

代理scoped_session类代表Session类。

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

返回：

一个ScalarResult对象

新版本 1.4.24 中新增：Session.scalars()

新版本 1.4.26 中新增：scoped_session.scalars()

另请参见

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

attribute session_factory: sessionmaker[_S]

提供给 init 的 session_factory 存储在此属性中，可以在以后访问。当需要新的非范围化的Session时，这可能会有用。

class sqlalchemy.util.ScopedRegistry

一个可以根据“scope”函数存储单个类的一个或多个实例的注册表。

此对象实现了__call__作为“getter”，因此通过调用myregistry()将返回当前范围内的包含对象。

参数：

• createfunc – 返回要放置在注册表中的新对象的可调用函数
  
• scopefunc – 一个可调用函数，将返回一个键以存储/检索对象。
  

成员

init(), clear(), has(), set()

类签名

类sqlalchemy.util.ScopedRegistry（typing.Generic）

method __init__(createfunc: Callable[[], _T], scopefunc: Callable[[], Any])

构造一个新的ScopedRegistry。

参数：

• createfunc – 如果当前范围中不存在，则生成新值的创建函数。
  
• scopefunc – 一个返回表示当前范围的可哈希令牌的函数（例如，当前线程标识符）。
  

method clear() → None

清除当前范围（如果有）。

method has() → bool

如果当前范围中存在对象，则返回 True。

method set(obj: _T) → None

设置当前范围的值。

class sqlalchemy.util.ThreadLocalRegistry

使用threading.local()变量进行存储的ScopedRegistry。

类签名

类sqlalchemy.util.ThreadLocalRegistry（sqlalchemy.util.ScopedRegistry）

class sqlalchemy.orm.QueryPropertyDescriptor

描述应用于类级别scoped_session.query_property()属性的类型。

自 2.0.5 版本新增。

类签名

类sqlalchemy.orm.QueryPropertyDescriptor（typing_extensions.Protocol）

方法也可以刷新急切加载的属性。

如果通常使用select（或“延迟”）加载器策略加载的 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 参数。
  

另请参阅

刷新 / 过期 - 入门材料

Session.expire()

Session.expire_all()

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

method remove() → None

丢弃当前Session（如果存在）。

这将首先在当前Session上调用Session.close()方法，释放仍在保持的任何现有事务/连接资源；具体来说，事务将被回滚。然后丢弃Session。在同一范围内的下一次使用时，scoped_session将生成一个新的Session对象。

method reset() → None

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

代理scoped_session类代表Session类。

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

版本 2.0.22 中的新功能。

另请参见

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

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

method rollback() → None

回滚当前进行中的事务。

代理scoped_session类代表Session类。

如果没有进行中的事务，则此方���是一个透传。

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

另请参见

回滚

管理事务

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

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

代理scoped_session类代表Session类。

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

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

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

代理scoped_session类代表Session类。

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

返回：

一个ScalarResult对象

新版本 1.4.24 中新增：Session.scalars()

新版本 1.4.26 中新增：scoped_session.scalars()

另请参见

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

attribute session_factory: sessionmaker[_S]

提供给 init 的 session_factory 存储在此属性中，可以在以后访问。当需要新的非范围化的Session时，这可能会有用。

class sqlalchemy.util.ScopedRegistry

一个可以根据“scope”函数存储单个类的一个或多个实例的注册表。

此对象实现了__call__作为“getter”，因此通过调用myregistry()将返回当前范围内的包含对象。

参数：

• createfunc – 返回要放置在注册表中的新对象的可调用函数
  
• scopefunc – 一个可调用函数，将返回一个键以存储/检索对象。
  

成员

init(), clear(), has(), set()

类签名

类sqlalchemy.util.ScopedRegistry（typing.Generic）

method __init__(createfunc: Callable[[], _T], scopefunc: Callable[[], Any])

构造一个新的ScopedRegistry。

参数：

• createfunc – 如果当前范围中不存在，则生成新值的创建函数。
  
• scopefunc – 一个返回表示当前范围的可哈希令牌的函数（例如，当前线程标识符）。
  

method clear() → None

清除当前范围（如果有）。

method has() → bool

如果当前范围中存在对象，则返回 True。

method set(obj: _T) → None

设置当前范围的值。

class sqlalchemy.util.ThreadLocalRegistry

使用threading.local()变量进行存储的ScopedRegistry。

类签名

类sqlalchemy.util.ThreadLocalRegistry（sqlalchemy.util.ScopedRegistry）

class sqlalchemy.orm.QueryPropertyDescriptor

描述应用于类级别scoped_session.query_property()属性的类型。

自 2.0.5 版本新增。

类签名

类sqlalchemy.orm.QueryPropertyDescriptor（typing_extensions.Protocol）