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

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

本節詳述contextvars 模組的公開 C API。

typePyContext¶

用來代表contextvars.Context 物件的 C 結構。

typePyContextVar¶

用來代表contextvars.ContextVar 物件的 C 結構。

typePyContextToken¶

用來代表contextvars.Token 物件的 C 結構。

PyTypeObjectPyContext_Type¶

代表context 型別的型別物件。

PyTypeObjectPyContextVar_Type¶

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

PyTypeObjectPyContextToken_Type¶

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

型別檢查巨集：

intPyContext_CheckExact(PyObject*o)¶

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

intPyContextVar_CheckExact(PyObject*o)¶

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

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

intPyContext_Enter(PyObject*ctx)¶

設定ctx 為目前執行緒上的目前情境。成功時回傳0，錯誤時回傳-1。

intPyContext_Exit(PyObject*ctx)¶

關閉ctx 情境，並將目前執行緒的目前情境設回之前的情境。 成功時回傳0，錯誤時回傳-1。

intPyContext_AddWatcher(PyContext_WatchCallbackcallback)¶

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

在 3.14 版被加入.

intPyContext_ClearWatcher(intwatcher_id)¶

Clear watcher identified bywatcher_id previously returned fromPyContext_AddWatcher() for the current interpreter.Return0 on success, or-1 and set an exception on error(e.g. if the givenwatcher_id was never registered.)

在 3.14 版被加入.

typePyContextEvent¶

Enumeration of possible context object watcher events:

• Py_CONTEXT_SWITCHED: Thecurrent context has switched to adifferent context. The object passed to the watch callback is thenow-currentcontextvars.Context object, or None if no context iscurrent.

在 3.14 版被加入.

typedefint(*PyContext_WatchCallback)(PyContextEventevent,PyObject*obj)¶

Context object watcher callback function. The object passed to the callbackis event-specific; seePyContextEvent for details.

If the callback returns with an exception set, it must return-1; thisexception will be printed as an unraisable exception usingPyErr_FormatUnraisable(). Otherwise it should return0.

There may already be a pending exception set on entry to the callback. Inthis case, the callback should return0 with the same exception stillset. This means the callback may not call any other API that can set anexception unless it saves and clears the exception state first, and restoresit before returning.

在 3.14 版被加入.

情境變數函式：

PyObject*PyContextVar_New(constchar*name,PyObject*def)¶

回傳值：新的參照。

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

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

intPyContextVar_Reset(PyObject*var,PyObject*token)¶

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