# Об’єкти змінних контексту

Added in version 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 для отримання додаткової інформації.

У цьому розділі детально описано публічний API C для модуля `contextvar`.

type PyContext

  Структура C, яка використовується для представлення об’єкта `contextvars.Context`.

type PyContextVar

  Структура C, яка використовується для представлення об’єкта `contextvars.ContextVar`.

type PyContextToken

  Структура C, яка використовується для представлення об’єкта `contextvars.Token`.

PyTypeObject PyContext_Type

  Об’єкт типу, що представляє тип context.

PyTypeObject PyContextVar_Type

  Об’єкт типу, що представляє тип контекстної змінної.

PyTypeObject PyContextToken_Type

  Об’єкт типу, що представляє тип токен змінної контексту.

Макроси перевірки типу:

int PyContext_CheckExact(PyObject *o)

  Повертає true, якщо o має тип `PyContext_Type`. o не має бути `NULL`. Ця функція завжди успішна.

int PyContextVar_CheckExact(PyObject *o)

  Повертає true, якщо o має тип `PyContextVar_Type`. o не має бути `NULL`. Ця функція завжди успішна.

int PyContextToken_CheckExact(PyObject *o)

  Повертає true, якщо o має тип `PyContextToken_Type`. o не має бути `NULL`. Ця функція завжди успішна.

Функції керування об’єктами контексту:

PyObject *PyContext_New(void)
  Return value: New reference.

  Створіть новий порожній контекстний об’єкт. Повертає `NULL`, якщо сталася помилка.

PyObject *PyContext_Copy(PyObject *ctx)
  Return value: New reference.

  Створіть поверхневу копію переданого контекстного об’єкта ctx. Повертає `NULL`, якщо сталася помилка.

PyObject *PyContext_CopyCurrent(void)
  Return value: New reference.

  Створіть поверхневу копію контексту поточного потоку. Повертає `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.

  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)
  Return value: New reference.

  Створіть новий об’єкт `ContextVar`. Параметр name використовується для самоаналізу та налагодження. Параметр def визначає значення за замовчуванням для змінної контексту або `NULL` для відсутності замовчування. Якщо сталася помилка, ця функція повертає `NULL`.

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

  Отримати значення контекстної змінної. Повертає `-1`, якщо під час пошуку сталася помилка, і `0`, якщо помилки не сталося, незалежно від того, чи було знайдено значення.

  Якщо контекстну змінну знайдено, value буде вказівником на неї. Якщо контекстну змінну не знайдено, значення вказуватиме на:

  - default_value, якщо не `NULL`;

  - значення за замовчуванням var, якщо не `NULL`;

  - `NULL`

  За винятком `NULL`, функція повертає нове посилання.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
  Return value: New reference.

  Установіть для var значення value у поточному контексті. Повертає новий об’єкт маркера для цієї зміни або `NULL`, якщо сталася помилка.

int PyContextVar_Reset(PyObject *var, PyObject *token)

  Скинути стан контекстної змінної var до того, у якому вона була до виклику `PyContextVar_Set()`, який повернув токен. Ця функція повертає `0` у разі успіху та `-1` у разі помилки.