`contextvars.md`

154 строк · 10.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3/c-api/contextvars.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты контекстных переменных89Добавлено в версии 3.7.1011Изменено в версии 3.7.1:1213> **Примечание**14>15> В Python 3.7.1 сигнатуры всех C API контекстных переменных были **изменены**, чтобы использовать указатели [`PyObject`](https://python-all.ru/3/c-api/structures.html#c.PyObject) вместо [`PyContext`](https://python-all.ru/3/c-api/contextvars.html#c.PyContext), [`PyContextVar`](https://python-all.ru/3/c-api/contextvars.html#c.PyContextVar) и [`PyContextToken`](https://python-all.ru/3/c-api/contextvars.html#c.PyContextToken), например:16>17> ```c18> // в 3.7.0:19> PyContext *PyContext_New(void);20>21> // в 3.7.1+:22> PyObject *PyContext_New(void);23> ```24>25> См. [bpo-34762](https://python-all.ru/3/c-api/contextvars.html) для подробностей.2627В этом разделе описывается публичный C API для модуля [`contextvars`](https://python-all.ru/3/library/contextvars.html#module-contextvars).2829#### `type PyContext`3031Структура C, используемая для представления объекта [`contextvars.Context`](https://python-all.ru/3/library/contextvars.html#contextvars.Context).3233#### `type PyContextVar`3435Структура C, используемая для представления объекта [`contextvars.ContextVar`](https://python-all.ru/3/library/contextvars.html#contextvars.ContextVar).3637#### `type PyContextToken`3839Структура C, используемая для представления объекта [`contextvars.Token`](https://python-all.ru/3/library/contextvars.html#contextvars.Token).4041#### `PyTypeObject PyContext_Type`4243Объект типа, представляющий тип *контекст*.4445#### `PyTypeObject PyContextVar_Type`4647Объект типа, представляющий тип *контекстной переменной*.4849#### `PyTypeObject PyContextToken_Type`5051Объект типа, представляющий тип *токена контекстной переменной*.5253Макросы проверки типа:5455#### `int PyContext_CheckExact(PyObject *o)`5657Возвращает true, если *o* имеет тип [`PyContext_Type`](https://python-all.ru/3/c-api/contextvars.html#c.PyContext_Type). *o* не должно быть `NULL`. Эта функция всегда завершается успешно.5859#### `int PyContextVar_CheckExact(PyObject *o)`6061Возвращает true, если *o* имеет тип [`PyContextVar_Type`](https://python-all.ru/3/c-api/contextvars.html#c.PyContextVar_Type). *o* не должно быть `NULL`. Эта функция всегда завершается успешно.6263#### `int PyContextToken_CheckExact(PyObject *o)`6465Возвращает true, если *o* имеет тип [`PyContextToken_Type`](https://python-all.ru/3/c-api/contextvars.html#c.PyContextToken_Type). *o* не должно быть `NULL`. Эта функция всегда завершается успешно.6667Функции управления объектами контекста:6869#### `PyObject *PyContext_New(void)`7071*Возвращаемое значение: новая ссылка.*7273Создаёт новый пустой объект контекста. Возвращает `NULL`, если произошла ошибка.7475#### `PyObject *PyContext_Copy(PyObject *ctx)`7677*Возвращаемое значение: новая ссылка.*7879Создаёт поверхностную копию переданного объекта контекста *ctx*. Возвращает `NULL`, если произошла ошибка.8081#### `PyObject *PyContext_CopyCurrent(void)`8283*Возвращаемое значение: новая ссылка.*8485Создаёт поверхностную копию контекста текущего потока. Возвращает `NULL`, если произошла ошибка.8687#### `int PyContext_Enter(PyObject *ctx)`8889Устанавливает *ctx* в качестве текущего контекста для текущего потока. Возвращает `0` в случае успеха и `-1` в случае ошибки.9091#### `int PyContext_Exit(PyObject *ctx)`9293Деактивирует контекст *ctx* и восстанавливает предыдущий контекст как текущий для текущего потока. Возвращает `0` в случае успеха и `-1` в случае ошибки.9495#### `int PyContext_AddWatcher(PyContext_WatchCallback callback)`9697Регистрирует *колбэк* как наблюдатель за объектами контекста для текущего интерпретатора. Возвращает идентификатор, который может быть передан в [`PyContext_ClearWatcher()`](https://python-all.ru/3/c-api/contextvars.html#c.PyContext_ClearWatcher). В случае ошибки (например, если нет доступных идентификаторов наблюдателей) возвращает `-1` и устанавливает исключение.9899Добавлено в версии 3.14.100101#### `int PyContext_ClearWatcher(int watcher_id)`102103Удаляет наблюдатель, заданный идентификатором *watcher\_id*, ранее полученным от [`PyContext_AddWatcher()`](https://python-all.ru/3/c-api/contextvars.html#c.PyContext_AddWatcher) для текущего интерпретатора. Возвращает `0` при успехе или `-1` с установкой исключения при ошибке (например, если указанный *watcher\_id* никогда не был зарегистрирован).104105Добавлено в версии 3.14.106107#### `type PyContextEvent`108109Перечисление возможных событий наблюдателя за объектами контекста:110111- `Py_CONTEXT_SWITCHED`: [текущий контекст](https://python-all.ru/3/glossary.html#term-current-context) переключился на другой контекст. Объект, передаваемый в колбэк-наблюдатель, – это текущий объект [`contextvars.Context`](https://python-all.ru/3/library/contextvars.html#contextvars.Context) или None, если контекст не установлен.112113Добавлено в версии 3.14.114115#### `typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)`116117Функция колбэка-наблюдателя за объектами контекста. Объект, передаваемый в колбэк, зависит от события; подробности см. в [`PyContextEvent`](https://python-all.ru/3/c-api/contextvars.html#c.PyContextEvent).118119Если колбэк возвращает значение с установленным исключением, он должен вернуть `-1`; это исключение будет выведено как "неподавляемое исключение" с помощью [`PyErr_FormatUnraisable()`](https://python-all.ru/3/c-api/exceptions.html#c.PyErr_FormatUnraisable). В противном случае он должен вернуть `0`.120121На момент входа в обратный вызов уже может быть установлено отложенное исключение. В этом случае обратный вызов должен вернуть `0`, оставив то же исключение установленным. Это означает, что обратный вызов не может вызывать никакой другой API, который может установить исключение, если только он сначала не сохранит и не очистит состояние исключения, а затем не восстановит его перед возвратом.122123Добавлено в версии 3.14.124125Функции контекстных переменных:126127#### `PyObject *PyContextVar_New(const char *name, PyObject *def)`128129*Возвращаемое значение: новая ссылка.*130131Создаёт новый объект `ContextVar`. Параметр *name* используется для интроспекции и отладки. Параметр *def* задаёт значение по умолчанию для контекстной переменной или `NULL`, если значение не требуется. Если произошла ошибка, эта функция возвращает `NULL`.132133#### `int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)`134135Получает значение контекстной переменной. Возвращает `-1`, если при поиске произошла ошибка, и `0`, если ошибки не было, независимо от того, было ли найдено значение.136137Если контекстная переменная найдена, *value* будет указателем на неё. Если контекстная переменная *не* найдена, *value* будет указывать на:138139- *default\_value*, если не `NULL`;140- значение по умолчанию *var*, если не `NULL`;141- `NULL`142143За исключением `NULL`, функция возвращает новую ссылку.144145#### `PyObject *PyContextVar_Set(PyObject *var, PyObject *value)`146147*Возвращаемое значение: новая ссылка.*148149Устанавливает значение *var* равным *value* в текущем контексте. Возвращает новый объект токена для этого изменения или `NULL`, если произошла ошибка.150151#### `int PyContextVar_Reset(PyObject *var, PyObject *token)`152153Сбрасывает состояние контекстной переменной *var* к тому, в котором она была до вызова [`PyContextVar_Set()`](https://python-all.ru/3/c-api/contextvars.html#c.PyContextVar_Set), вернувшего *token*. Эта функция возвращает `0` в случае успеха и `-1` в случае ошибки.154