Объекты контекстных переменных¶Context Variables Objects

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

// в 3.7.1+:
PyObject *PyContext_New(void);

В этом разделе описывается публичный C API для модуля contextvars.

type PyContext¶

Структура C, используемая для представления объекта contextvars.Context.

type PyContextVar¶

Структура C, используемая для представления объекта contextvars.ContextVar.

type PyContextToken¶

Структура C, используемая для представления объекта contextvars.Token.

PyTypeObject PyContext_Type¶

Объект типа, представляющий тип контекст.

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)¶

Возвращаемое значение: новая ссылка.

Создаёт новый пустой объект контекста. Возвращает 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 и восстанавливает предыдущий контекст как текущий для текущего потока. Возвращает 0 в случае успеха и -1 в случае ошибки.

int PyContext_AddWatcher(PyContext_WatchCallback callback)¶

Регистрирует колбэк как наблюдатель за объектами контекста для текущего интерпретатора. Возвращает идентификатор, который может быть передан в PyContext_ClearWatcher(). В случае ошибки (например, если нет доступных идентификаторов наблюдателей) возвращает -1 и устанавливает исключение.

Добавлено в версии 3.14.

int PyContext_ClearWatcher(int watcher_id)¶

Удаляет наблюдатель, заданный идентификатором watcher_id, ранее полученным от PyContext_AddWatcher() для текущего интерпретатора. Возвращает 0 при успехе или -1 с установкой исключения при ошибке (например, если указанный watcher_id никогда не был зарегистрирован).

Добавлено в версии 3.14.

type PyContextEvent¶

Перечисление возможных событий наблюдателя за объектами контекста:

• Py_CONTEXT_SWITCHED: текущий контекст переключился на другой контекст. Объект, передаваемый в колбэк-наблюдатель, – это текущий объект contextvars.Context или None, если контекст не установлен.

Добавлено в версии 3.14.

typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)¶

Функция колбэка-наблюдателя за объектами контекста. Объект, передаваемый в колбэк, зависит от события; подробности см. в PyContextEvent.

Если колбэк возвращает значение с установленным исключением, он должен вернуть -1; это исключение будет выведено как "неподавляемое исключение" с помощью PyErr_FormatUnraisable(). В противном случае он должен вернуть 0.

На момент входа в обратный вызов уже может быть установлено отложенное исключение. В этом случае обратный вызов должен вернуть 0, оставив то же исключение установленным. Это означает, что обратный вызов не может вызывать никакой другой API, который может установить исключение, если только он сначала не сохранит и не очистит состояние исключения, а затем не восстановит его перед возвратом.

Добавлено в версии 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 будет указывать на:

• default_value, если не NULL;

• значение по умолчанию var, если не NULL;

• NULL

За исключением NULL, функция возвращает новую ссылку.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)¶

Возвращаемое значение: новая ссылка.

Устанавливает значение var равным value в текущем контексте. Возвращает новый объект токена для этого изменения или NULL, если произошла ошибка.

int PyContextVar_Reset(PyObject *var, PyObject *token)¶

Сбрасывает состояние контекстной переменной var к тому, в котором она была до вызова PyContextVar_Set(), вернувшего token. Эта функция возвращает 0 в случае успеха и -1 в случае ошибки.