情境變數物件（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(