# コンテキスト変数オブジェクト

Added in version 3.7.

バージョン 3.7.1 で変更:

注釈

Python 3.7.1 で全てのコンテキスト変数の C API のシグネチャは、 `PyContext`, `PyContextVar`, `PyContextToken` の代わりに `PyObject` ポインタを使うように 変更 されました。例えば:

    // in 3.7.0:
    PyContext *PyContext_New(void);

    // in 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

  コンテキスト 型を表現する型オブジェクト。

PyTypeObject PyContextVar_Type

  コンテキスト変数 型を表現する型オブジェクト。

PyTypeObject PyContextToken_Type

  コンテキスト変数トークン 型を表現する型オブジェクト。

型チェックマクロ:

int PyContext_CheckExact(PyObject *o)

  o が `PyContext_Type` の場合に真を返します。 o は `NULL` であってはなりません。 この関数は常に成功します。

int PyContextVar_CheckExact(PyObject *o)

  o が `PyContextVar_Type` の場合に真を返します。 o は `NULL` であってはなりません。 この関数は常に成功します。

int PyContextToken_CheckExact(PyObject *o)

  o が `PyContextToken_Type` の場合に真を返します。 o は `NULL` であってはなりません。 この関数は常に成功します。

コンテキストオブジェクトを取り扱う関数:

PyObject *PyContext_New(void)
  戻り値: 新しい参照。

  新しい空のコンテキストオブジェクトを作成します。 エラーが起きた場合は `NULL` を返します。

PyObject *PyContext_Copy(PyObject *ctx)
  戻り値: 新しい参照。

  渡された ctx コンテキストオブジェクトの浅いコピーを作成します。 エラーが起きた場合は `NULL` を返します。

PyObject *PyContext_CopyCurrent(void)
  戻り値: 新しい参照。

  現在のコンテキストオブジェクトの浅いコピーを作成します。 エラーが起きた場合は `NULL` を返します。

int PyContext_Enter(PyObject *ctx)

  ctx を現在のスレッドの現在のコンテキストに設定します。 成功したら `0` を、失敗したら `-1` を返します。

int PyContext_Exit(PyObject *ctx)

  ctx コンテキストを無効にし、1 つ前のコンテキストを現在のスレッドの現在のコンテキストに復元します。 成功したら `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.

  Added in version 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.)

  Added in version 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.

  Added in version 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.

  Added in version 3.14.

コンテキスト変数の関数:

PyObject *PyContextVar_New(const char *name, PyObject *def)
  戻り値: 新しい参照。

  新しい `ContextVar` オブジェクトを作成します。name 引数は内部走査とデバッグの目的で使われます。def 引数はコンテキスト変数のデフォルト値を指定するか、デフォルトがない場合は `NULL` です。エラーが起きた場合は、関数は `NULL` を返します。

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

  コンテキスト変数の値を取得します。 取得中にエラーが起きた場合は `-1` を、値が見付かっても見付からなくてもエラーが起きなかった場合は `0` を返します。

  コンテキスト変数が見付かった場合、 value はそれを指すポインタになっています。 コンテキスト変数が見付から なかった 場合は、 value が指すものは次のようになっています:

  - (`NULL` でなければ) default_value

  - (`NULL` でなければ) var のデフォルト値

  - `NULL`

  `NULL` を除けば、この関数は新しい参照を返します。

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
  戻り値: 新しい参照。

  現在のコンテキストにおいて var の値を value にセットします。この変更による新しいトークンオブジェクトか、エラーが起こった場合は``NULL``を返します。

int PyContextVar_Reset(PyObject *var, PyObject *token)

  var コンテキスト変数の状態をリセットし、 token を返した `PyContextVar_Set()` が呼ばれる前の状態に戻します。 この関数は成功したら `0` 、失敗したら `-1` を返します。