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