`contextvars` — 上下文变量¶

此模块提供用于管理、存储和访问上下文局部状态的 API。ContextVar 类用于声明和使用上下文变量。copy_context() 函数和 Context 类应用于异步框架中管理当前上下文。

具有状态的上下文管理器应使用上下文变量而不是 threading.local()，以防止其状态在并发代码中使用时意外地泄露到其他代码中。

另请参阅 PEP 567 以了解更多详细信息。

3.7 版本中新增。

上下文变量¶

class contextvars.ContextVar(name[, *, default])¶

此类用于声明新的上下文变量，例如：

var: ContextVar[int] = ContextVar('var', default=42)

必需的 *name* 参数用于自省和调试目的。

可选的仅限关键字的 *default* 参数在当前上下文中未找到变量的值时，由 ContextVar.get() 返回。

重要提示：上下文变量应在顶层模块级别创建，而永远不要在闭包中创建。Context 对象持有对上下文变量的强引用，这会阻止上下文变量被正确地垃圾回收。

name¶: 变量的名称。这是一个只读属性。

在 3.7.1 版本中新增。

get([default])¶

返回当前上下文中上下文变量的值。

如果当前上下文中没有该变量的值，则此方法将

返回方法的 *default* 参数的值（如果提供）；或者
返回上下文变量的默认值（如果创建时指定了默认值）；或者
引发 LookupError。

set(value)¶

调用此方法以设置当前上下文中上下文变量的新值。

必需的 *value* 参数是上下文变量的新值。

返回一个 Token 对象，该对象可用于通过 ContextVar.reset() 方法将变量还原为其先前的值。

reset(token)¶

将上下文变量重置为其在创建 *token* 的 ContextVar.set() 使用之前的值。

例如：

var = ContextVar('var')

token = var.set('new value')
# code that uses 'var'; var.get() returns 'new value'.
var.reset(token)

# After the reset call the var has no value again, so
# var.get() would raise a LookupError.

class contextvars.Token¶

Token 对象由 ContextVar.set() 方法返回。可以将它们传递给 ContextVar.reset() 方法，以将变量的值恢复到相应 *set* 之前的值。

var¶: 只读属性。指向创建此 token 的 ContextVar 对象。

old_value¶: 只读属性。设置为在创建 token 的 ContextVar.set() 方法调用之前，变量具有的值。如果该变量在调用之前未设置，则它指向 Token.MISSING。

MISSING¶: Token.old_value 使用的标记对象。

手动上下文管理¶

contextvars.copy_context()¶

返回当前 Context 对象的副本。

以下代码片段获取当前上下文的副本，并打印其中设置的所有变量及其值

ctx: Context = copy_context()
print(list(ctx.items()))

此函数的时间复杂度为 O(1)，即对于具有少量上下文变量的上下文和具有大量上下文变量的上下文，它的运行速度一样快。

class contextvars.Context¶

ContextVars 到其值的映射。

Context() 创建一个不包含任何值的空上下文。要获取当前上下文的副本，请使用 copy_context() 函数。

每个线程都有自己的有效 Context 对象堆栈。当前上下文是当前线程堆栈顶部的 Context 对象。堆栈中的所有 Context 对象都被认为是已进入的。

进入上下文，可以通过调用其 run() 方法来完成，它通过将上下文推到当前线程的上下文堆栈顶部，使其成为当前上下文。

退出当前上下文，可以通过从传递给 run() 方法的回调函数中返回来实现。这会将当前上下文恢复到进入上下文之前的状态，方法是将上下文从上下文堆栈的顶部弹出。

由于每个线程都有自己的上下文堆栈，因此当在不同的线程中分配值时，ContextVar 对象的行为类似于 threading.local()。

尝试进入一个已经进入的上下文（包括在其他线程中进入的上下文）会引发 RuntimeError 异常。

退出上下文后，可以稍后重新进入（从任何线程）。

通过 ContextVar.set() 方法对 ContextVar 值所做的任何更改都会记录在当前上下文中。 ContextVar.get() 方法返回与当前上下文关联的值。退出上下文实际上会还原在进入上下文时对上下文变量所做的任何更改（如果需要，可以通过重新进入上下文来恢复值）。

Context 实现了 collections.abc.Mapping 接口。

run(callable, *args, **kwargs)¶

进入 Context，执行 callable(*args, **kwargs)，然后退出 Context。返回 callable 的返回值，如果发生异常则传播该异常。

示例

import contextvars

var = contextvars.ContextVar('var')
var.set('spam')
print(var.get())  # 'spam'

ctx = contextvars.copy_context()

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

    var.set('ham')

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

# 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:
print(ctx[var])  # 'ham'

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

copy()¶: 返回上下文对象的浅拷贝。

var in context: 如果 context 设置了 var 的值，则返回 True；否则返回 False。

context[var]: 返回 var ContextVar 变量的值。如果该变量在上下文对象中未设置，则会引发 KeyError 异常。

get(var[, default])¶: 如果 var 在上下文对象中有值，则返回 var 的值。否则返回 default。如果未给出 default，则返回 None。

iter(context): 返回一个迭代器，用于迭代上下文中存储的变量。

len(proxy): 返回在上下文对象中设置的变量数量。

keys()¶: 返回上下文中所有变量的列表。

values()¶: 返回上下文对象中所有变量值的列表。

items()¶: 返回一个包含上下文对象中所有变量及其值的 2 元组列表。

asyncio 支持¶

上下文变量在 asyncio 中得到原生支持，无需任何额外配置即可使用。例如，这是一个简单的回显服务器，它使用上下文变量使远程客户端的地址在处理该客户端的 Task 中可用。

import asyncio
import contextvars

client_addr_var = contextvars.ContextVar('client_addr')

def render_goodbye():
    # The address of the currently handled client can be accessed
    # without passing it explicitly to this function.

    client_addr = client_addr_var.get()
    return f'Good bye, client @ {client_addr}\r\n'.encode()

async def handle_request(reader, writer):
    addr = writer.transport.get_extra_info('socket').getpeername()
    client_addr_var.set(addr)

    # In any code that we call is now possible to get
    # client's address by calling 'client_addr_var.get()'.

    while True:
        line = await reader.readline()
        print(line)
        if not line.strip():
            break

    writer.write(b'HTTP/1.1 200 OK\r\n')  # status line
    writer.write(b'\r\n')  # headers
    writer.write(render_goodbye())  # body
    writer.close()

async def main():
    srv = await asyncio.start_server(
        handle_request, '127.0.0.1', 8081)

    async with srv:
        await srv.serve_forever()

asyncio.run(main())

# To test it you can use telnet or curl:
#     telnet 127.0.0.1 8081
#     curl 127.0.0.1:8081

`contextvars` — 上下文变量¶

上下文变量¶

手动上下文管理¶

asyncio 支持¶

目录

上一主题

下一主题

本页

contextvars — 上下文变量¶

上下文变量¶

手动上下文管理¶

asyncio 支持¶

`contextvars` — 上下文变量¶