> **Источник:** https://python-all.ru/3.16/c-api/contextvars.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # Объекты контекстных переменных Добавлено в версии 3.7. Изменено в версии 3.7.1: > **Примечание** > > В Python 3.7.1 сигнатуры всех C API контекстных переменных были **изменены**, чтобы использовать указатели [`PyObject`](https://python-all.ru/3.16/c-api/structures.html#c.PyObject) вместо [`PyContext`](https://python-all.ru/3.16/c-api/contextvars.html#c.PyContext), [`PyContextVar`](https://python-all.ru/3.16/c-api/contextvars.html#c.PyContextVar) и [`PyContextToken`](https://python-all.ru/3.16/c-api/contextvars.html#c.PyContextToken), например: > > ```c > // в 3.7.0: > PyContext *PyContext_New(void); > > // в 3.7.1+: > PyObject *PyContext_New(void); > ``` > > См. [bpo-34762](https://python-all.ru/3.16/c-api/contextvars.html) для подробностей. В этом разделе описывается публичный C API для модуля [`contextvars`](https://python-all.ru/3.16/library/contextvars.html#module-contextvars). #### `type PyContext` Структура C, используемая для представления объекта [`contextvars.Context`](https://python-all.ru/3.16/library/contextvars.html#contextvars.Context). #### `type PyContextVar` Структура C, используемая для представления объекта [`contextvars.ContextVar`](https://python-all.ru/3.16/library/contextvars.html#contextvars.ContextVar). #### `type PyContextToken` Структура C, используемая для представления объекта [`contextvars.Token`](https://python-all.ru/3.16/library/contextvars.html#contextvars.Token). #### `PyTypeObject PyContext_Type` Объект типа, представляющий тип *контекст*. #### `PyTypeObject PyContextVar_Type` Объект типа, представляющий тип *контекстной переменной*. #### `PyTypeObject PyContextToken_Type` Объект типа, представляющий тип *токена контекстной переменной*. Макросы проверки типа: #### `int PyContext_CheckExact(PyObject *o)` Возвращает true, если *o* имеет тип [`PyContext_Type`](https://python-all.ru/3.16/c-api/contextvars.html#c.PyContext_Type). *o* не должно быть `NULL`. Эта функция всегда завершается успешно. #### `int PyContextVar_CheckExact(PyObject *o)` Возвращает true, если *o* имеет тип [`PyContextVar_Type`](https://python-all.ru/3.16/c-api/contextvars.html#c.PyContextVar_Type). *o* не должно быть `NULL`. Эта функция всегда завершается успешно. #### `int PyContextToken_CheckExact(PyObject *o)` Возвращает true, если *o* имеет тип [`PyContextToken_Type`](https://python-all.ru/3.16/c-api/contextvars.html#c.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()`](https://python-all.ru/3.16/c-api/contextvars.html#c.PyContext_ClearWatcher). В случае ошибки (например, если нет доступных идентификаторов наблюдателей) возвращает `-1` и устанавливает исключение. Добавлено в версии 3.14. #### `int PyContext_ClearWatcher(int watcher_id)` Удаляет наблюдатель, заданный идентификатором *watcher\_id*, ранее полученным от [`PyContext_AddWatcher()`](https://python-all.ru/3.16/c-api/contextvars.html#c.PyContext_AddWatcher) для текущего интерпретатора. Возвращает `0` при успехе или `-1` с установкой исключения при ошибке (например, если указанный *watcher\_id* никогда не был зарегистрирован). Добавлено в версии 3.14. #### `type PyContextEvent` Перечисление возможных событий наблюдателя за объектами контекста: - `Py_CONTEXT_SWITCHED`: [текущий контекст](https://python-all.ru/3.16/glossary.html#term-current-context) переключился на другой контекст. Объект, передаваемый в колбэк-наблюдатель, – это текущий объект [`contextvars.Context`](https://python-all.ru/3.16/library/contextvars.html#contextvars.Context) или None, если контекст не установлен. Добавлено в версии 3.14. #### `typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)` Функция колбэка-наблюдателя за объектами контекста. Объект, передаваемый в колбэк, зависит от события; подробности см. в [`PyContextEvent`](https://python-all.ru/3.16/c-api/contextvars.html#c.PyContextEvent). Если колбэк возвращает значение с установленным исключением, он должен вернуть `-1`; это исключение будет выведено как "неподавляемое исключение" с помощью [`PyErr_FormatUnraisable()`](https://python-all.ru/3.16/c-api/exceptions.html#c.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()`](https://python-all.ru/3.16/c-api/contextvars.html#c.PyContextVar_Set), вернувшего *token*. Эта функция возвращает `0` в случае успеха и `-1` в случае ошибки.