上下文/线程本地会话¶

回想一下何时构造 Session，何时提交它，何时关闭它？一节中，引入了“会话范围”的概念，强调 Web 应用程序以及将 Session 范围与 Web 请求的范围联系起来的实践。大多数现代 Web 框架都包含集成工具，以便可以自动管理 Session 的范围，并且应该在这些工具可用时使用它们。

SQLAlchemy 包含它自己的帮助程序对象，这有助于建立用户定义的 Session 范围。第三方集成系统也使用它来帮助构建其集成方案。

该对象是 scoped_session 对象，它表示一个 Session 对象的注册表。如果您不熟悉注册表模式，可以在 Patterns of Enterprise 中找到一个很好的介绍。架构。

警告

默认情况下，scoped_session 注册表使用 Python 线程.local（） 来跟踪 Session 实例。这不是必须与所有应用程序服务器兼容，尤其是那些使用 Greenlet 或其他替代形式的并发控制的应用程序服务器，这在中高并发场景中使用时可能会导致争用条件（例如随机发生的故障）。请阅读线程局部范围和下面的 Using Thread-Local Scope with Web Applications，以更全面地理解使用 threading.local（） 跟踪 Session 对象的含义，并考虑在使用不基于传统线程的应用程序服务器时更明确的范围界定方法。

注意

scoped_session 对象是许多 SQLAlchemy 应用程序使用的非常流行且有用的对象。然而，重要的是要注意，它只提出了一种解决 Session 问题的方法管理。如果您不熟悉 SQLAlchemy，尤其是术语 “thread-local variable” 对您来说似乎很陌生，我们建议如果可能，您首先要熟悉现成的集成 Flask-SQLAlchemy 等系统或 zope.sqlalchemy 的 Kubernetes Halchemy。

scoped_session是通过调用它来构造的，并向其传递一个 factory，它可以创建新的 Session 对象。工厂只是在调用时产生新对象的东西，在 Session 的情况下，最常见的工厂是本节前面介绍的 sessionmaker。下面我们说明这种用法：

>>> from sqlalchemy.orm import scoped_session
>>> from sqlalchemy.orm import sessionmaker

>>> session_factory = sessionmaker(bind=some_engine)
>>> Session = scoped_session(session_factory)

我们创建的 scoped_session 对象现在将调用 sessionMaker：

>>> some_session = Session()

上面，some_session 是 Session 的一个实例，我们现在可以使用它与数据库通信。这个相同的 Session 也存在于我们创建的 scoped_session 注册表中。如果我们第二次调用注册表，我们会得到相同的Session：

>>> some_other_session = Session()
>>> some_session is some_other_session
True

此模式允许应用程序的不同部分调用全局 scoped_session，以便所有这些区域可以共享同一会话，而无需显式传递它。我们在注册表中建立的 Session 将保留，直到我们通过调用 scoped_session.remove（） 明确告诉我们的注册表处理它：

>>> Session.remove()

scoped_session.remove（） 方法首先在当前 Session 上调用 Session.close（），其效果是先释放 Session 拥有的所有连接/事务资源，然后丢弃 Session 本身。这里的 “释放” 意味着连接将返回到其连接池，并且任何事务状态都会回滚，最终使用底层 DBAPI 连接的 rollback（） 方法。

此时，scoped_session 对象是 “空的”，并且会在再次调用时创建一个新的Session。如下图所示，这与我们之前的 Session 不同：

>>> new_session = Session()
>>> new_session is some_session
False

以上一系列步骤简要说明了 “registry” 模式的概念。有了这个基本概念，我们可以讨论这个模式如何进行的一些细节。

隐式方法访问¶

scoped_session的工作很简单;hold on a Session （保留会话）为所有要求它的人。作为产生更透明访问的一种手段 Session 中，scoped_session还包括代理行为，这意味着注册表本身可以像 Session 一样处理径直;当在此对象上调用方法时，它们将被代理到由 Registry 维护的基础 Session：

Session = scoped_session(some_factory)

# equivalent to:
#
# session = Session()
# print(session.scalars(select(MyClass)).all())
#
print(Session.scalars(select(MyClass)).all())

上面的代码完成的任务与获取电流 Session，然后使用该 Session。

线程局部范围¶

熟悉多线程编程的用户会注意到，将任何内容表示为全局变量通常是一个坏主意，因为这意味着全局对象将由多个线程并发访问。会议 Object 完全设计为以非并发方式使用，在多线程方面，这意味着“一次只能在一个线程中”。所以我们上面的 scoped_session 用法示例，其中相同的 Session object 在多个调用中维护，这表明某些进程需要到位，以便跨多个线程的多个调用实际上不会得到同一会话的句柄。我们将这个概念称为线程本地存储 这意味着，使用一个特殊的对象来维护一个不同的对象每个应用程序线程。 Python 通过线程.local（）构建。默认情况下，scoped_session 对象使用此对象作为存储，以便为调用 scoped_session 注册表的所有用户维护单个 Session，但仅限于单个线。在不同线程中调用注册表的调用方将获得 Session 实例。

使用这种技术，scoped_session提供了一种快速且相对简单的（如果熟悉线程本地存储）的方法，可以在应用程序中安全地从多个线程调用单个全局对象。

scoped_session.remove（） 方法一如既往地删除当前的与线程关联的会话（如果有）。但是， threading.local（） 对象，如果应用程序线程本身结束，则该线程的 “存储” 也会被垃圾回收。因此，实际上，在生成和关闭线程的应用程序中使用线程局部范围是“安全的”，而无需调用 scoped_session.remove（）。但是，事务本身的范围，即通过 Session.commit（） 或 Session.rollback（） 通常仍然必须在适当的时间明确安排，除非应用程序实际上将线程的生命周期与事务的生命周期相关联。

在 Web 应用程序中使用线程局部范围¶

正如何时构造 Session、何时提交以及何时关闭一节中所讨论的，Web 应用程序是围绕 Web 请求的概念构建的，将此类应用程序与 Session 集成通常意味着 Session 将与该请求相关联。事实证明，大多数 Python Web 框架但有明显的例外，例如异步框架 Twisted 和 Tornado，以简单的方式使用线程，以便接收到特定的 Web 请求，在单个工作线程的范围内处理和完成。当请求结束时，worker 线程被释放到一个 worker 池中，在那里它可以处理另一个请求。

Web 请求和线程的这种简单对应意味着要关联带有线程的 Session 意味着它也与在该线程中运行的 Web 请求相关联，反之亦然，前提是 Session 仅在 Web 请求开始后创建，并在 Web 请求结束之前拆除。因此，通常的做法是使用 scoped_session 作为将 Session 与 Web 应用程序集成的快速方法。下面的序列图说明了此流程：

Web Server          Web Framework        SQLAlchemy ORM Code
--------------      --------------       ------------------------------
startup        ->   Web framework        # Session registry is established
                    initializes          Session = scoped_session(sessionmaker())

incoming
web request    ->   web request     ->   # The registry is *optionally*
                    starts               # called upon explicitly to create
                                         # a Session local to the thread and/or request
                                         Session()

                                         # the Session registry can otherwise
                                         # be used at any time, creating the
                                         # request-local Session() if not present,
                                         # or returning the existing one
                                         Session.execute(select(MyClass)) # ...

                                         Session.add(some_object) # ...

                                         # if data was modified, commit the
                                         # transaction
                                         Session.commit()

                    web request ends  -> # the registry is instructed to
                                         # remove the Session
                                         Session.remove()

                    sends output      <-
outgoing web    <-
response

使用上述流程，将 Session 与 Web 应用程序集成的过程恰好有两个要求：

在 Web 应用程序首次启动时创建一个 scoped_session 注册表，确保应用程序的其余部分可以访问此对象。
确保在 Web 请求结束时调用 scoped_session.remove（），通常是通过与 Web 框架的事件系统集成来建立“on request end”事件。

如前所述，上述模式只是集成 Session 的一种潜在方法 使用 Web 框架，它特别做出重要的假设 Web 框架将 Web 请求与应用程序线程相关联。但是，强烈建议使用 Web 框架随附的集成工具如果可用，则使用 its 而不是 scoped_session。

特别是，虽然使用本地线程很方便，但最好将 Session 直接与请求关联，而不是与当前线程关联。下一节关于自定义范围详细介绍了一种更高级的配置，它可以将 scoped_session 的使用与基于直接请求的范围或任何类型的范围相结合。

使用自定义创建的作用域¶

scoped_session 对象的默认行为 “thread local” 范围只是有关如何 “范围” Session 的众多选项之一。自定义范围可以基于任何现有的系统来定义 “我们正在处理的当前事物”。

假设一个 Web 框架定义了一个库函数 get_current_request（）。使用此框架构建的应用程序可以随时调用此函数，结果将是某种 Request 对象，表示当前正在处理的请求。如果 Request 对象是可哈希的，那么这个函数可以很容易地与 scoped_session 将 Session 与请求相关联。下面我们说明一下这与 Web 框架提供的假设事件标记结合使用 on_request_end，它允许在请求结束时调用代码：

from my_web_framework import get_current_request, on_request_end
from sqlalchemy.orm import scoped_session, sessionmaker

Session = scoped_session(sessionmaker(bind=some_engine), scopefunc=get_current_request)


@on_request_end
def remove_session(req):
    Session.remove()

在上面，我们以通常的方式实例化 scoped_session，只是我们将请求返回函数作为 “scopefunc” 传递。这将指示scoped_session 使用此函数在调用注册表时生成字典键返回当前 Session。在这种情况下，我们确保实现可靠的 “remove” 系统尤为重要，因为此字典不是自我管理的。

上下文会话 API¶

对象名称	描述
QueryPropertyDescriptor 查询属性描述符	描述应用于类级别的类型 `scoped_session.query_property()` 属性。
scoped_session	提供 `Session` 对象的范围管理。
ScopedRegistry 注册表	一个 Registry 可以基于“范围”函数存储单个类的一个或多个实例。
ThreadLocalRegistry （线程本地注册表）	使用 `threading.local（）` 的 `ScopedRegistry` 变量进行存储。

类 sqlalchemy.orm 中。scoped_session¶

提供 Session 对象的范围管理。

有关教程，请参阅 Contextual/Thread-local Sessions 。

注意

当使用异步 I/O （asyncio）时，async-compatible 应使用 async_scoped_session 类来代替 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、信息、 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 （键入。通用）

方法 sqlalchemy.orm.scoped_session. __call__（**kw： Any）→ _S¶

返回当前 Session，使用 scoped_session.session_factory if not present 创建它。

参数: kw – 关键字参数将传递给 scoped_session.session_factory callable，如果现有的 会话不存在。如果会话存在和 keyword 参数， InvalidRequestError 引发。

方法 sqlalchemy.orm.scoped_session. __init__（session_factory： sessionmaker[_S]， scopefunc：Callable[[]，Any]None=None）¶

构建新scoped_session。

参数

session_factory¶ – 创建新 Session 的工厂实例。这通常（但不一定）是一个实例 的 sessionmaker。
scopefunc¶ —— 定义当前范围的可选函数。如果未通过，则 scoped_session object 假定 “thread-local” 范围，并将使用一个 Python threading.local（） 来维护当前的 会话。如果传递，该函数应返回一个可哈希的代币;此令牌将用作 dictionary 来存储和检索当前的 会话。

method sqlalchemy.orm.scoped_session. add（instance： object， _warn： bool = True）→ 无¶

将对象放入此 Session 中。

SQLAlchemy 2.0 文档