# 情境變數物件（Context Variables Objects）

在 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

  代表 情境變數 型別的型別物件。

PyTypeObject PyContextToken_Type

  代表 情境變數 token 型別的型別物件。

型別檢查巨集：

int PyContext_CheckExact(PyObject *o)

  如果 o 的型別為 `PyContext_Type` 則回傳 true。o 不得為 `NULL`。此函式一定會成功回傳。

int PyContextVar_CheckExact(PyObject *o)

  如果 o 的類型為 `PyContextVar_Type` 則回傳 true。o 不得為 `NULL`。此函式一定會成功回傳。

int PyContextToken_CheckExact(PyObject *o)

  如果 o 的類型為 `PyContextToken_Type` 則回傳 true。 o 不得為 `NULL`。此函式一定會成功回傳。

情境物件管理函式：

PyObject *PyContext_New(void)
  回傳值：新的參照。

  建立一個新的空的情境物件。 如果發生錯誤，則回傳 `NULL`。

PyObject *PyContext_Copy(PyObject *ctx)
  回傳值：新的參照。

  建立傳入的 ctx 情境物件的淺層複製 (shallow copy)。如果發生錯誤，則回傳 `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)

  Register callback as a context object watcher for the current interpreter. Return an ID which may be passed to `PyContext_ClearWatcher()`. In case of error (e.g. no more watcher IDs available), return `-1` and set an exception.

  在 3.14 版被加入.

int PyContext_ClearWatcher(int watcher_id)

  Clear watcher identified by watcher_id previously returned from `PyContext_AddWatcher()` for the current interpreter. Return `0` on success, or `-1` and set an exception on error (e.g. if the given watcher_id was never registered.)

  在 3.14 版被加入.

type PyContextEvent

  Enumeration of possible context object watcher events:

  - `Py_CONTEXT_SWITCHED`: The current context has switched to a different context. The object passed to the watch callback is the now-current `contextvars.Context` object, or None if no context is current.

  在 3.14 版被加入.

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

  Context object watcher callback function. The object passed to the callback is event-specific; see `PyContextEvent` for details.

  If the callback returns with an exception set, it must return `-1`; this exception will be printed as an unraisable exception using `PyErr_FormatUnraisable()`. Otherwise it should return `0`.

  There may already be a pending exception set on entry to the callback. In this case, the callback should return `0` with the same exception still set. This means the callback may not call any other API that can set an exception unless it saves and clears the exception state first, and restores it before returning.

  在 3.14 版被加入.

情境變數函式：

PyObject *PyContextVar_New(const char *name, PyObject *def)
  回傳值：新的參照。

  建立一個新的 `ContextVar` 物件。name 參數用於自我檢查（introspection）和除錯目的。def 參數指定情境變數的預設值，亦可用 `NULL` 表示沒有預設值。 如果發生錯誤，此函式會回傳 `NULL`。

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

  取得情境變數的值。如果在查找過程中發生錯誤則回傳 `-1`，如果沒有發生錯誤則無論是否找到值都會回傳 `0`。

  如果找到情境變數，value 將會是指向它的指標。如果 沒有 找到情境變數，value 將會指到：

  - default_value 預設值，但前提是預設值不是 `NULL`；

  - var 的預設值，但前提是預設值不是 `NULL`；

  - `NULL`

  除了 `NULL` 之外，此函式會回傳一個新的參照（reference）。

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
  回傳值：新的參照。

  在目前的情境中將 var 的值設為 value。會回傳一個用來代表此變更的新 token 物件，如果發生錯誤則回傳 `NULL`。

int PyContextVar_Reset(PyObject *var, PyObject *token)

  將 var 情境變數的狀態設回之前的狀態，亦即上一次回傳 token 的 `PyContextVar_Set()` 被呼叫前的狀態。此函式在成功時回傳 `0`，錯誤時回傳 `-1`。