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 ABC。这可以用于检查上下文。

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])

请注意，所有 Mapping 方法，包括Context.__getitem__和Context.get，都忽略上下文变量的默认值（即ContextVar.default）。这意味着对于使用默认值创建并在上下文中未设置的变量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兼容，以防需要在生成器和异步生成器中支持上下文变量。

Token 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对象的直接pickle变得不可能。这可以通过修改API来解决，方法是自动检测定义上下文变量的模块，或者向ContextVar构造函数添加新的关键字参数“module”。
2. 并非所有上下文变量都引用可pickle的对象。使ContextVar可pickle必须是选择加入的。

鉴于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 之外，根本没有合理的“初始值”。例如，考虑一个 Web 框架，它在上下文变量中存储当前的 HTTP 请求对象。使用当前的语义，可以创建一个没有默认值的上下文变量

# 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)