contextvars.ContextVar

ContextVar 类具有以下构造函数签名：ContextVar(name, *, default=_NO_DEFAULT)。 name 参数用于自省和调试目的，并作为只读的 ContextVar.name 属性公开。 default 参数是可选的。例如

# Declare a context variable 'var' with the default value 42.
var = ContextVar('var', default=42)

（_NO_DEFAULT 是一个内部哨兵对象，用于检测是否提供了默认值。）

ContextVar.get(default=_NO_DEFAULT) 返回当前 Context 的上下文变量的值

# Get the value of `var`.
var.get()

如果当前上下文中没有变量的值，ContextVar.get() 将

• 如果提供了，返回 get() 方法的 default 参数的值；或
• 如果提供了，返回上下文变量的默认值；或
• 引发 LookupError。

ContextVar.set(value) -> Token 用于在当前 Context 中为上下文变量设置新值

# Set the variable 'var' to 1 in the current context.
var.set(1)

ContextVar.reset(token) 用于将当前上下文中的变量重置为创建 token 的 set() 操作之前的值（或者如果变量未设置，则将其删除）

# Assume: var.get(None) is None

# Set 'var' to 1:
token = var.set(1)
try:
    # var.get() == 1
finally:
    var.reset(token)

# After reset: var.get(None) is None,
# i.e. 'var' was removed from the current context.

ContextVar.reset() 方法引发

• 如果使用由另一个变量创建的令牌对象调用，则引发 ValueError；
• 如果当前 Context 对象与创建令牌对象的上下文不匹配，则引发 ValueError；
• 如果令牌对象已被使用一次来重置变量，则引发 RuntimeError。

contextvars.Token

contextvars.Token 是一个不透明对象，应使用它将 ContextVar 恢复到其先前的值，或者如果变量之前未设置，则将其从上下文中删除。它只能通过调用 ContextVar.set() 创建。

出于调试和自省目的，它具有

• 指向创建令牌的变量的只读属性 Token.var；
• 在 set() 调用之前，变量的值的只读属性 Token.old_value，如果变量之前未设置，则设置为 Token.MISSING。

contextvars.Context

Context 对象是上下文变量到值的映射。

Context() 创建一个空上下文。要获取当前操作系统线程的当前 Context 的副本，请使用 contextvars.copy_context() 方法。

ctx = contextvars.copy_context()

要在某个 Context 中运行 Python 代码，请使用 Context.run() 方法。

ctx.run(function)

function 引起的任何上下文变量更改都将包含在 ctx 上下文中。

var = ContextVar('var')
var.set('spam')

def main():
    # 'var' was set to 'spam' before
    # calling 'copy_context()' and 'ctx.run(main)', so:
    # var.get() == ctx[var] == 'spam'

    var.set('ham')

    # Now, after setting 'var' to 'ham':
    # var.get() == ctx[var] == 'ham'

ctx = copy_context()

# Any changes that the 'main' function makes to 'var'
# will be contained in 'ctx'.
ctx.run(main)

# The 'main()' function was run in the 'ctx' context,
# so changes to 'var' are contained in it:
# ctx[var] == 'ham'

# However, outside of 'ctx', 'var' is still set to 'spam':
# var.get() == 'spam'

当从多个操作系统线程对同一个上下文对象调用 Context.run()，或者递归调用时，会引发 RuntimeError。

Context.copy() 返回上下文对象的浅拷贝。

Context 对象实现了 collections.abc.Mapping 抽象基类。这可以用于自省上下文。

ctx = contextvars.copy_context()

# Print all context variables and their values in 'ctx':
print(ctx.items())

# Print the value of 'some_variable' in context 'ctx':
print(ctx[some_variable])

请注意，所有映射方法，包括 Context.__getitem__ 和 Context.get，都忽略上下文变量的默认值（即 ContextVar.default）。这意味着对于一个用默认值创建但在 context 中未设置的变量 var：

• context[var] 引发 KeyError，
• var in context 返回 False，
• 该变量不包含在 context.items() 等中。

asyncio

asyncio 使用 Loop.call_soon()、Loop.call_later() 和 Loop.call_at() 来调度函数的异步执行。asyncio.Task 使用 call_soon() 来运行包装的协程。

我们修改 Loop.call_{at,later,soon} 和 Future.add_done_callback() 以接受新的可选 context 仅限关键字参数，该参数默认为当前上下文。

def call_soon(self, callback, *args, context=None):
    if context is None:
        context = contextvars.copy_context()

    # ... some time later
    context.run(callback, *args)

asyncio 中的任务需要维护它们从创建点继承的自己的上下文。asyncio.Task 进行了如下修改：

class Task:
    def __init__(self, coro):
        ...
        # Get the current context snapshot.
        self._context = contextvars.copy_context()
        self._loop.call_soon(self._step, context=self._context)

    def _step(self, exc=None):
        ...
        # Every advance of the wrapped coroutine is done in
        # the task's context.
        self._loop.call_soon(self._step, context=self._context)
        ...

Python API

1. 一个新的 contextvars 模块，包含 ContextVar、Context 和 Token 类，以及一个 copy_context() 函数。
2. asyncio.Loop.call_at()、asyncio.Loop.call_later()、asyncio.Loop.call_soon() 和 asyncio.Future.add_done_callback() 在其被调用的上下文中运行回调函数。可以使用新的 context 仅限关键字参数来指定自定义上下文。
3. asyncio.Task 在内部进行了修改，以维护其自己的上下文。

C API

1. PyObject * PyContextVar_New(char *name, PyObject *default)：创建 ContextVar 对象。default 参数可以是 NULL，这意味着该变量没有默认值。
2. int PyContextVar_Get(PyObject *, PyObject *default_value, PyObject **value)：如果在查找过程中发生错误，则返回 -1，否则返回 0。如果找到了上下文变量的值，它将被设置为 value 指针。否则，当 default_value 不为 NULL 时，value 将被设置为 default_value。如果 default_value 为 NULL，value 将被设置为变量的默认值，该值也可以是 NULL。 value 始终是新引用。
3. PyObject * PyContextVar_Set(PyObject *, PyObject *)：设置当前上下文中变量的值。
4. PyContextVar_Reset(PyObject *, PyObject *)：重置上下文变量的值。
5. PyObject * PyContext_New()：创建一个新的空上下文。
6. PyObject * PyContext_Copy(PyObject *)：返回传入上下文对象的浅拷贝。
7. PyObject * PyContext_CopyCurrent()：获取当前上下文的副本。
8. int PyContext_Enter(PyObject *) 和 int PyContext_Exit(PyObject *) 允许为当前操作系统线程设置和恢复上下文。始终需要恢复先前的上下文。

   PyObject *old_ctx = PyContext_Copy();
   if (old_ctx == NULL) goto error;
   
   if (PyContext_Enter(new_ctx)) goto error;
   
   // run some code
   
   if (PyContext_Exit(old_ctx)) goto error;
   

复制 threading.local() 接口

请参阅 PEP 550，其中详细介绍了此主题：[2]。

用 ContextVar.unset() 替换 Token

Token API 避免了 ContextVar.unset() 方法，该方法与 PEP 550 的链式上下文设计不兼容。如果将来需要支持生成器和异步生成器中的上下文变量，则希望与 PEP 550 保持兼容性。

令牌 API 还提供了更好的可用性：用户不必特殊处理值的缺失。比较

token = cv.set(new_value)
try:
    # cv.get() is new_value
finally:
    cv.reset(token)

与

_deleted = object()
old = cv.get(default=_deleted)
try:
    cv.set(blah)
    # code
finally:
    if old is _deleted:
        cv.unset()
    else:
        cv.set(old)

使用 Token.reset() 而非 ContextVar.reset()

Nathaniel Smith 建议直接在 Token 类上实现 ContextVar.reset() 方法，因此不是

token = var.set(value)
# ...
var.reset(token)

我们应该写

token = var.set(value)
# ...
token.reset()

拥有 Token.reset() 将使用户不可能尝试使用由另一个变量创建的令牌对象重置变量。

此提议被拒绝的原因是 ContextVar.reset() 对于代码的人类读者来说更清楚正在重置哪个变量。

使 Context 对象可序列化

由 Antoine Pitrou 提出，这可以实现 Context 对象的透明跨进程使用，因此 将执行分流到其他线程 示例也可以与 ProcessPoolExecutor 一起工作。

启用此功能存在问题，原因如下：

1. ContextVar 对象没有 __module__ 和 __qualname__ 属性，使得 Context 对象的直接序列化不可能。这可以通过修改 API 来解决，方法是自动检测上下文变量定义的模块，或者向 ContextVar 构造函数添加新的仅限关键字参数“module”。
2. 并非所有上下文变量都引用可序列化对象。使 ContextVar 可序列化必须是选择加入的。

考虑到 Python 3.7 发布计划的时间框架，决定将此提案推迟到 Python 3.8。

使 Context 成为 MutableMapping

使 Context 类实现 abc.MutableMapping 接口将意味着可以使用 Context[var] = value 和 del Context[var] 操作来设置和取消设置变量。

此提案因以下原因推迟到 Python 3.8+：

1. 如果在 Python 3.8 中决定生成器应该支持上下文变量（参见 PEP 550 和 PEP 568），那么 Context 将被转换为上下文变量映射的链式映射（因为每个生成器都将拥有自己的映射）。这将使诸如 Context.__delitem__ 之类的变异操作变得令人困惑，因为它们只对链中的最顶层映射进行操作。
2. 只有一种方式来修改上下文（ContextVar.set() 和 ContextVar.reset() 方法）使得 API 更直接。

   例如，下面的代码片段为何不能按预期工作将不言而喻：

   var = ContextVar('var')
   
   ctx = copy_context()
   ctx[var] = 'value'
   print(ctx[var])  # Prints 'value'
   
   print(var.get())  # Raises a LookupError
   

   而下面的代码会起作用

   ctx = copy_context()
   
   def func():
       ctx[var] = 'value'
   
       # Contrary to the previous example, this would work
       # because 'func()' is running within 'ctx'.
       print(ctx[var])
       print(var.get())
   
   ctx.run(func)
   

3. 如果 Context 是可变的，则意味着上下文变量可以独立于（或并发地）在上下文中运行的代码进行修改。这类似于获取对正在运行的 Python 帧对象的引用并从另一个操作系统线程修改其 f_locals。采用单一方式将值分配给上下文变量使上下文在概念上更简单、更可预测，同时为未来的性能优化留下了可能性。

为 ContextVars 设置初始值

Nathaniel Smith 建议为 ContextVar 构造函数提供一个必需的 initial_value 仅限关键字参数。

反对该提案的主要论点是，对于某些类型，除了 None 之外，根本没有合理的“初始值”。例如，考虑一个将当前 HTTP 请求对象存储在上下文变量中的 Web 框架。在当前的语义下，可以创建一个没有默认值的上下文变量：

# Framework:
current_request: ContextVar[Request] = \
    ContextVar('current_request')


# Later, while handling an HTTP request:
request: Request = current_request.get()

# Work with the 'request' object:
return request.method

注意，在上面的例子中，不需要检查 request 是否为 None。它只是期望框架总是设置 current_request 变量，否则就是错误（在这种情况下，current_request.get() 将引发 LookupError）。

然而，如果我们需要一个必需的初始值，我们将不得不明确地防止 None 值。

# Framework:
current_request: ContextVar[Optional[Request]] = \
    ContextVar('current_request', initial_value=None)


# Later, while handling an HTTP request:
request: Optional[Request] = current_request.get()

# Check if the current request object was set:
if request is None:
    raise RuntimeError

# Work with the 'request' object:
return request.method

此外，我们可以粗略地将上下文变量与常规 Python 变量和 threading.local() 对象进行比较。它们都在查找失败时引发错误（分别为 NameError 和 AttributeError）。

转换使用 threading.local() 的代码

使用 threading.local() 的典型代码片段通常如下所示：

class PrecisionStorage(threading.local):
    # Subclass threading.local to specify a default value.
    value = 0.0

precision = PrecisionStorage()

# To set a new precision:
precision.value = 0.5

# To read the current precision:
print(precision.value)

此类代码可以转换为使用 contextvars 模块。

precision = contextvars.ContextVar('precision', default=0.0)

# To set a new precision:
precision.set(0.5)

# To read the current precision:
print(precision.get())

将执行分流到其他线程

可以使用当前线程上下文的副本在单独的操作系统线程中运行代码。

executor = ThreadPoolExecutor()
current_context = contextvars.copy_context()

executor.submit(current_context.run, some_function)