# 情境變數物件（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`。

情境變數函式：

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`。