上下文/线程局部会话¶

回想一下我应该何时构造会话、何时提交会话以及何时关闭会话？部分，其中介绍了“会话作用域”的概念，重点是 Web 应用程序以及将 Session 的作用域与 Web 请求的作用域链接的做法。大多数现代 Web 框架都包含集成工具，以便可以自动管理 Session 的作用域，并且应尽可能使用这些工具。

SQLAlchemy 包含其自身的辅助对象，该对象有助于建立用户定义的 Session 作用域。第三方集成系统也使用它来帮助构建其集成方案。

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

警告

scoped_session 注册表默认使用 Python threading.local() 来跟踪 Session 实例。这不一定与所有应用程序服务器兼容，特别是那些使用 greenlet 或其他形式的并发控制的服务器，当在中高并发场景中使用时，可能会导致竞争条件（例如，随机发生的故障）。请阅读下面的线程局部作用域和在 Web 应用程序中使用线程局部作用域，以更全面地了解使用 threading.local() 跟踪 Session 对象的含义，并在使用不基于传统线程的应用程序服务器时考虑更明确的作用域划分方式。

注意

scoped_session 对象是一个非常流行且有用的对象，被许多 SQLAlchemy 应用程序使用。但是，重要的是要注意，它仅代表解决 Session 管理问题的一种方法。如果您是 SQLAlchemy 的新手，尤其是当“线程局部变量”这个术语对您来说很陌生时，我们建议您尽可能先熟悉现成的集成系统，例如 Flask-SQLAlchemy 或 zope.sqlalchemy。

scoped_session 通过调用它来构造，并传递一个工厂，该工厂可以创建新的 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

上述一系列步骤说明了“注册表”模式的要点。掌握了这个基本概念后，我们可以讨论这种模式如何进行的一些细节。

隐式方法访问¶

scoped_session 的工作很简单；为所有需要它的人保留一个 Session。作为更透明地访问此 Session 的一种方法，scoped_session 还包括代理行为，这意味着注册表本身可以像 Session 一样直接处理；当在此对象上调用方法时，它们会代理到注册表维护的底层 Session

Session = scoped_session(some_factory)

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

上面的代码完成的任务与获取当前 Session 的任务相同，通过调用注册表，然后使用该 Session。

线程局部作用域¶

熟悉多线程编程的用户会注意到，将任何东西表示为全局变量通常不是一个好主意，因为它意味着全局对象将由多个线程并发访问。Session 对象完全设计为以非并发方式使用，就多线程而言，这意味着“一次只能在一个线程中使用”。因此，我们上面 scoped_session 用法的示例，其中同一个 Session 对象在多次调用中保持不变，表明需要某种过程来确保跨多个线程的多次调用实际上不会获得对同一个会话的句柄。我们将此概念称为线程局部存储，这意味着，使用一个特殊的对象，它将为每个应用程序线程维护一个不同的对象。Python 通过 threading.local() 构造提供此功能。scoped_session 对象默认使用此对象作为存储，以便为所有调用 scoped_session 注册表的人员维护一个 Session，但仅在单个线程的作用域内。在不同线程中调用注册表的调用者会获得一个 Session 实例，该实例是该其他线程本地的。

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

与往常一样，scoped_session.remove() 方法删除与线程关联的当前 Session（如果有）。但是，threading.local() 对象的一个优点是，如果应用程序线程本身结束，则该线程的“存储”也会被垃圾回收。因此，在生成和销毁线程的应用程序中使用线程局部作用域实际上是“安全的”，而无需调用 scoped_session.remove()。但是，事务本身的作用域，即通过 Session.commit() 或 Session.rollback() 结束事务，通常仍然是必须在适当的时间显式安排的事情，除非应用程序实际上将线程的生命周期与事务的生命周期联系起来。

在 Web 应用程序中使用线程局部作用域¶

如我应该何时构造会话、何时提交会话以及何时关闭会话？部分所述，Web 应用程序围绕Web 请求的概念构建，将此类应用程序与 Session 集成通常意味着 Session 将与该请求关联。事实证明，大多数 Python Web 框架（值得注意的例外是异步框架 Twisted 和 Tornado）以一种简单的方式使用线程，即在一个特定的 工作线程 的作用域内接收、处理和完成一个特定的 Web 请求。当请求结束时，工作线程被释放到工作线程池，在那里它可以处理另一个请求。

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 框架的事件系统集成来建立“请求结束时”事件。

如前所述，上述模式只是一种潜在的方式，用于将 Session 与 Web 框架集成，特别是假设 Web 框架将 Web 请求与应用程序线程关联。但是，强烈建议使用 Web 框架本身提供的集成工具（如果可用），而不是 scoped_session。

特别是，虽然使用线程局部变量可能很方便，但最好将 Session 直接与请求 而不是与当前线程关联。下一节关于自定义作用域的详细信息介绍了更高级的配置，该配置可以将 scoped_session 的用法与基于直接请求的作用域或任何类型的作用域结合起来。

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

scoped_session 对象的“线程局部”作用域的默认行为只是如何“作用域” 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 时，使用此函数生成字典键。在这种情况下，尤其重要的是我们要确保实现可靠的“删除”系统，因为此字典没有其他自管理功能。

上下文会话 API¶

对象名称	描述
QueryPropertyDescriptor	描述应用于类级别 `scoped_session.query_property()` 属性的类型。
scoped_session	提供 `Session` 对象的范围管理。
ScopedRegistry	一个注册表，可以根据“作用域”函数存储单个类的一个或多个实例。
ThreadLocalRegistry	一个 `ScopedRegistry`，它使用 `threading.local()` 变量进行存储。

class sqlalchemy.orm.scoped_session¶

提供 Session 对象的范围管理。

有关教程，请参见上下文/线程局部会话。

注意

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

类签名

class sqlalchemy.orm.scoped_session (typing.Generic)

method sqlalchemy.orm.scoped_session.__call__(**kw: Any) → _S¶

返回当前的 Session，如果不存在则使用 scoped_session.session_factory 创建它。

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

method sqlalchemy.orm.scoped_session.__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 sqlalchemy.orm.scoped_session.add(instance: object, _warn: bool = True) → None¶

将对象放入此 Session 中。

SQLAlchemy 2.0 文档