上下文变量对象 — Python 3.14.5 文档
Description: 本节深入介绍了 contextvars 模块的公用 C API。 类型检查宏： 上下文对象管理函数： 上下文变量函数：

# 上下文变量对象

Added in version 3.7.

在 3.7.1 版本发生变更:

备注

在 Python 3.7.1 中，所有上下文变量 C API 的签名被 更改 为使用 `PyObject` 指针而不是 `PyContext`, `PyContextVar` 以及 `PyContextToken`，例如:

    // 在 3.7.0：
    PyContext *PyContext_New(void);

    // 在 3.7.1+：
    PyObject *PyContext_New(void);

请参阅 bpo-34762 了解详情。

本节深入介绍了 `contextvars` 模块的公用 C API。

type PyContext

  用于表示 `contextvars.Context` 对象的 C 结构体。

type PyContextVar

  用于表示 `contextvars.ContextVar` 对象的 C 结构体。

type PyContextToken

  用于表示 `contextvars.Token` 对象的 C 结构体。

PyTypeObject PyContext_Type

  表示 context 类型的类型对象。

PyTypeObject PyContextVar_Type

  表示 context variable 类型的类型对象。

PyTypeObject PyContextToken_Type

  表示 context variable token 类型的类型对象。

类型检查宏：

int PyContext_CheckExact(PyObject *o)

  如果 o 的类型为 `PyContext_Type` 则返回真值。 o 必须不为 `NULL`。此函数总是会成功执行。

int PyContextVar_CheckExact(PyObject *o)

  如果 o 的类型为 `PyContextVar_Type` 则返回真值。 o 必须不为 `NULL`。 此函数总是会成功执行。

int PyContextToken_CheckExact(PyObject *o)

  如果 o 的类型为 `PyContextToken_Type` 则返回真值。 o 必须不为 `NULL`。 此函数总是会成功执行。

上下文对象管理函数：

PyObject *PyContext_New(void)
  返回值：新的引用。

  创建一个新的空上下文对象。如果发生错误则返回 `NULL`。

PyObject *PyContext_Copy(PyObject *ctx)
  返回值：新的引用。

  创建所传入的 ctx 上下文对象的浅拷贝。如果发生错误则返回 `NULL`。

PyObject *PyContext_CopyCurrent(void)
  返回值：新的引用。

  创建当前线程上下文的浅拷贝。如果发生错误则返回 `NULL`。

int PyContext_Enter(PyObject *ctx)

  将 ctx 设为当前线程的当前上下文。成功时返回 `0`，出错时返回 `-1`。

int PyContext_Exit(PyObject *ctx)

  取消激活 ctx 上下文并将之前的上下文恢复为当前线程的当前上下文。成功时返回 `0`，出错时返回 `-1`。

int PyContext_AddWatcher(PyContext_WatchCallback callback)

  注册 callback 作为当前解释器的上下文对象监视器。返回一个可被传递给 `PyContext_ClearWatcher()` 的 ID。当出错时（例如没有可用的监视器 ID），则返回 `-1` 并设置一个异常。

  Added in version 3.14.

int PyContext_ClearWatcher(int watcher_id)

  清除之前从 `PyContext_AddWatcher()` 返回的当前解释器中由 watcher_id 所标识的监视器。成功时返回 `0`，或者出错时（例如当给定的 watcher_id 未被注册）返回 `-1` 并设置异常。

  Added in version 3.14.

type PyContextEvent

  由可能的上下文对象监视器事件组成的枚举：

  - `Py_CONTEXT_SWITCHED`: current context 已切换到不同的上下文。 传递给监视回调函数的对象是当前的 `contextvars.Context` 对象，或 None（如果没有当前上下文）。

  Added in version 3.14.

typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)

  上下文对象监视器回调函数。传递给回调函数的对象是特定于事件的；有关详细信息，请参阅 `PyContextEvent`。

  如果回调函数返回时设置了一个异常，则它必须返回 `-1`；此异常将作为不可引发的异常使用 `PyErr_FormatUnraisable()` 打印出来。在其他情况下它应当返回 `0`。

  在进入回调时可能已经设置了尚未处理的异常。在此情况下，回调应当返回 `0` 并仍然设置同样的异常。这意味着该回调可能不会调用任何其他可设置异常的 API 除非它先保存并清空异常状态，并在返回之前恢复它。

  Added in version 3.14.

上下文变量函数：

PyObject *PyContextVar_New(const char *name, PyObject *def)
  返回值：新的引用。

  创建一个新的 `ContextVar` 对象。形参 name 用于内省和调试目的。形参 def 为上下文变量指定默认值，或为 `NULL` 表示无默认值。如果发生错误，这个函数会返回 `NULL`。

int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)

  获取上下文变量的值。如果在查找过程中发生错误，返回 `-1`，如果没有发生错误，无论是否找到值，都返回 `0`。

  如果找到上下文变量，value 将是指向它的指针。如果上下文变量 没有 找到，value 将指向：

  - default_value，如果非 `NULL`;

  - var 的默认值，如果不是 `NULL`；

  - `NULL`

  除了返回 `NULL`，这个函数会返回一个新的引用。

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
  返回值：新的引用。

  在当前上下文中将 var 设为 value。返回针对此修改的新令牌对象，或者如果发生错误则返回 `NULL`。

int PyContextVar_Reset(PyObject *var, PyObject *token)

  将上下文变量 var 的状态重置为它在返回 token 的 `PyContextVar_Set()` 被调用之前的状态。 此函数成功时返回 `0`，出错时返回 `-1`。