warnings.md
1> **Источник:** https://python-all.ru/3.14/library/warnings.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `warnings` – Управление предупреждениями89**Исходный код:** [Lib/warnings.py](https://python-all.ru/src/3.14/Lib/warnings.py)1011---1213Предупреждения обычно выводятся в ситуациях, когда полезно предупредить пользователя о некотором условии в программе, когда это условие (обычно) не требует возбуждения исключения и завершения программы. Например, может потребоваться выдать предупреждение, если программа использует устаревший модуль.1415Разработчики на Python выводят предупреждения, вызывая функцию [`warn()`](https://python-all.ru/3.14/library/warnings.html#warnings.warn), определённую в этом модуле. (Разработчики на C используют [`PyErr_WarnEx()`](https://python-all.ru/3.14/c-api/exceptions.html#c.PyErr_WarnEx); см. [Обработка исключений](https://python-all.ru/3.14/c-api/exceptions.html#exceptionhandling) для подробностей).1617Предупреждения обычно записываются в [`sys.stderr`](https://python-all.ru/3.14/library/sys.html#sys.stderr), но их обработку можно гибко изменять: от игнорирования всех предупреждений до превращения их в исключения. Обработка предупреждений может зависеть от [категории предупреждения](https://python-all.ru/3.14/library/warnings.html#warning-categories), текста предупреждающего сообщения и места в исходном коде, где оно выдается. Повторные предупреждения для одного и того же места в исходном коде обычно подавляются.1819Управление предупреждениями состоит из двух этапов: сначала каждый раз при выдаче предупреждения определяется, должно ли сообщение быть выдано; затем, если сообщение должно быть выдано, оно форматируется и выводится с помощью настраиваемого пользователем перехватчика.2021Решение о том, выдавать ли предупреждающее сообщение, управляется [фильтром предупреждений](https://python-all.ru/3.14/library/warnings.html#warning-filter), который представляет собой последовательность правил сопоставления и действий. Правила можно добавлять в фильтр, вызывая [`filterwarnings()`](https://python-all.ru/3.14/library/warnings.html#warnings.filterwarnings), и сбрасывать в состояние по умолчанию, вызывая [`resetwarnings()`](https://python-all.ru/3.14/library/warnings.html#warnings.resetwarnings).2223Вывод предупреждающих сообщений выполняется вызовом [`showwarning()`](https://python-all.ru/3.14/library/warnings.html#warnings.showwarning), который может быть переопределён; реализация по умолчанию этой функции форматирует сообщение вызовом [`formatwarning()`](https://python-all.ru/3.14/library/warnings.html#warnings.formatwarning), который также доступен для использования в пользовательских реализациях.2425> **См. также**26>27> [`logging.captureWarnings()`](https://python-all.ru/3.14/library/logging.html#logging.captureWarnings) позволяет обрабатывать все предупреждения с помощью стандартной инфраструктуры журналирования.2829## Категории предупреждений3031Существует ряд встроенных исключений, представляющих категории предупреждений. Такая категоризация полезна для фильтрации групп предупреждений.3233Хотя технически это [встроенные исключения](https://python-all.ru/3.14/library/exceptions.html#warning-categories-as-exceptions), они documented here, потому что концептуально относятся к механизму предупреждений.3435Пользовательский код может определять дополнительные категории предупреждений, создавая подкласс одной из стандартных категорий предупреждений. Категория предупреждения всегда должна быть подклассом класса [`Warning`](https://python-all.ru/3.14/library/exceptions.html#Warning).3637В настоящее время определены следующие классы категорий предупреждений:3839| Класс | Описание |40| --- | --- |41| [`Warning`](https://python-all.ru/3.14/library/exceptions.html#Warning) | Это базовый класс всех классов категорий предупреждений. Он является подклассом [`Exception`](https://python-all.ru/3.14/library/exceptions.html#Exception). |42| [`UserWarning`](https://python-all.ru/3.14/library/exceptions.html#UserWarning) | Категория по умолчанию для [`warn()`](https://python-all.ru/3.14/library/warnings.html#warnings.warn). |43| [`DeprecationWarning`](https://python-all.ru/3.14/library/exceptions.html#DeprecationWarning) | Базовая категория для предупреждений об устаревших возможностях, если эти предупреждения предназначены для других разработчиков Python (игнорируется по умолчанию, если не вызвано кодом в `__main__`). |44| [`SyntaxWarning`](https://python-all.ru/3.14/library/exceptions.html#SyntaxWarning) | Базовая категория для предупреждений о сомнительных синтаксических возможностях (обычно выдаются при компиляции исходного кода Python и поэтому могут не подавляться фильтрами времени выполнения). |45| [`RuntimeWarning`](https://python-all.ru/3.14/library/exceptions.html#RuntimeWarning) | Базовая категория для предупреждений о сомнительных возможностях времени выполнения. |46| [`FutureWarning`](https://python-all.ru/3.14/library/exceptions.html#FutureWarning) | Базовая категория для предупреждений об устаревших возможностях, если эти предупреждения предназначены для конечных пользователей приложений, написанных на Python. |47| [`PendingDeprecationWarning`](https://python-all.ru/3.14/library/exceptions.html#PendingDeprecationWarning) | Базовая категория для предупреждений о возможностях, которые будут объявлены устаревшими в будущем (игнорируется по умолчанию). |48| [`ImportWarning`](https://python-all.ru/3.14/library/exceptions.html#ImportWarning) | Базовая категория для предупреждений, возникающих в процессе импорта модуля (игнорируется по умолчанию). |49| [`UnicodeWarning`](https://python-all.ru/3.14/library/exceptions.html#UnicodeWarning) | Базовая категория для предупреждений, связанных с Юникодом. |50| [`BytesWarning`](https://python-all.ru/3.14/library/exceptions.html#BytesWarning) | Базовая категория для предупреждений, связанных с [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes) и [`bytearray`](https://python-all.ru/3.14/library/stdtypes.html#bytearray). |51| [`ResourceWarning`](https://python-all.ru/3.14/library/exceptions.html#ResourceWarning) | Базовая категория для предупреждений, связанных с использованием ресурсов (игнорируется по умолчанию). |5253Изменено в версии 3.7: Ранее [`DeprecationWarning`](https://python-all.ru/3.14/library/exceptions.html#DeprecationWarning) и [`FutureWarning`](https://python-all.ru/3.14/library/exceptions.html#FutureWarning) различались по тому, удалялась ли возможность полностью или меняла своё поведение. Теперь они различаются по целевой аудитории и способу обработки фильтрами предупреждений по умолчанию.5455## Фильтр предупреждений5657Фильтр предупреждений управляет тем, игнорируются ли предупреждения, выводятся на экран или превращаются в ошибки (вызывают исключение).5859Концептуально фильтр предупреждений поддерживает упорядоченный список спецификаций фильтра; любое конкретное предупреждение последовательно сопоставляется с каждой спецификацией фильтра из списка, пока не будет найдено совпадение; фильтр определяет обработку совпадения. Каждая запись представляет собой кортеж вида (*действие*, *сообщение*, *категория*, *модуль*, *номер\_строки*), где:6061- *Действие* – одна из следующих строк:6263 | Значение | Действие |64 | --- | --- |65 | `"default"` | выводить первое вхождение подходящих предупреждений для каждого местоположения (модуль + номер строки), где выдано предупреждение |66 | `"error"` | превращать подходящие предупреждения в исключения |67 | `"ignore"` | никогда не выводить подходящие предупреждения |68 | `"always"` | всегда выводить подходящие предупреждения |69 | `"all"` | псевдоним для “always” |70 | `"module"` | выводить первое вхождение подходящих предупреждений для каждого модуля, где выдано предупреждение (независимо от номера строки) |71 | `"once"` | выводить только первое вхождение подходящих предупреждений, независимо от местоположения |72- *message* – это строка, содержащая регулярное выражение, которому должно соответствовать начало сообщения предупреждения (без учёта регистра). В [`-W`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-W) и [`PYTHONWARNINGS`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONWARNINGS) параметр *message* – это литеральная строка, которую должно содержать начало сообщения предупреждения (без учёта регистра), при этом игнорируются любые пробельные символы в начале и конце *message*.73- *category* – это класс (подкласс [`Warning`](https://python-all.ru/3.14/library/exceptions.html#Warning)), подклассом которого должна быть категория предупреждения для совпадения.74- *module* – это строка, содержащая регулярное выражение, которому должно соответствовать начало полного имени модуля (с учётом регистра). В [`-W`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-W) и [`PYTHONWARNINGS`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONWARNINGS) параметр *module* – это литеральная строка, которой должно быть равно полное имя модуля (с учётом регистра), при этом игнорируются любые пробельные символы в начале и конце *module*.75- *lineno* – это целое число, которому должен соответствовать номер строки, где произошло предупреждение, или `0` для соответствия всем номерам строк.7677Поскольку класс [`Warning`](https://python-all.ru/3.14/library/exceptions.html#Warning) является наследником встроенного класса [`Exception`](https://python-all.ru/3.14/library/exceptions.html#Exception), чтобы превратить предупреждение в ошибку, мы просто возбуждаем `category(message)`.7879Если предупреждение зарегистрировано и не соответствует ни одному из установленных фильтров, то применяется действие «default» (отсюда и его название).8081### Критерии подавления повторяющихся предупреждений8283Фильтры, подавляющие повторяющиеся предупреждения, используют следующие критерии для определения, считается ли предупреждение повторным:8485- `"default"`: предупреждение считается повторным только в том случае, если все значения (*message*, *category*, *module*, *lineno*) одинаковы.86- `"module"`: предупреждение считается повторным, если (*message*, *category*, *module*) одинаковы, независимо от номера строки.87- `"once"`: предупреждение считается повторным, если (*message*, *category*) одинаковы, независимо от модуля и номера строки.8889### Описание фильтров предупреждений9091Фильтр предупреждений инициализируется опциями [`-W`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-W), переданными в командной строке интерпретатора Python, и переменной окружения [`PYTHONWARNINGS`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONWARNINGS). Интерпретатор сохраняет аргументы для всех предоставленных записей без интерпретации в [`sys.warnoptions`](https://python-all.ru/3.14/library/sys.html#sys.warnoptions); модуль `warnings` анализирует их при первом импорте (недопустимые опции игнорируются после вывода сообщения в [`sys.stderr`](https://python-all.ru/3.14/library/sys.html#sys.stderr)).9293Отдельные фильтры предупреждений задаются в виде последовательности полей, разделённых двоеточиями:9495```python96action:message:category:module:line97```9899Значение каждого из этих полей описано в разделе [Фильтр предупреждений](https://python-all.ru/3.14/library/warnings.html#warning-filter). При перечислении нескольких фильтров в одной строке (как для [`PYTHONWARNINGS`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONWARNINGS)) отдельные фильтры разделяются запятыми, и фильтры, указанные позже, имеют приоритет над теми, что указаны раньше (поскольку они применяются слева направо, и последние применённые фильтры имеют преимущество перед более ранними).100101Обычно используемые фильтры предупреждений применяются либо ко всем предупреждениям, либо к предупреждениям определённой категории, либо к предупреждениям, вызванным определёнными модулями или пакетами. Несколько примеров:102103```python104default # Показывать все предупреждения (даже те, что игнорируются по умолчанию)105ignore # Игнорировать все предупреждения106error # Преобразовать все предупреждения в ошибки107error::ResourceWarning # Обрабатывать сообщения ResourceWarning как ошибки108default::DeprecationWarning # Показывать сообщения DeprecationWarning109ignore,default:::mymodule # Сообщать только о предупреждениях, вызванных "mymodule"110error:::mymodule # Преобразовывать предупреждения в ошибки в "mymodule"111```112113### Фильтр предупреждений по умолчанию114115По умолчанию Python устанавливает несколько фильтров предупреждений, которые можно переопределить с помощью параметра командной строки [`-W`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-W), переменной окружения [`PYTHONWARNINGS`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONWARNINGS) и вызовов [`filterwarnings()`](https://python-all.ru/3.14/library/warnings.html#warnings.filterwarnings).116117В обычных сборках релиза фильтр предупреждений по умолчанию имеет следующие записи (в порядке приоритета):118119```python120default::DeprecationWarning:__main__121ignore::DeprecationWarning122ignore::PendingDeprecationWarning123ignore::ImportWarning124ignore::ResourceWarning125```126127В [отладочной сборке](https://python-all.ru/3.14/using/configure.html#debug-build) список фильтров предупреждений по умолчанию пуст.128129Изменено в версии 3.2: [`DeprecationWarning`](https://python-all.ru/3.14/library/exceptions.html#DeprecationWarning) теперь по умолчанию игнорируется в дополнение к [`PendingDeprecationWarning`](https://python-all.ru/3.14/library/exceptions.html#PendingDeprecationWarning).130131Изменено в версии 3.7: [`DeprecationWarning`](https://python-all.ru/3.14/library/exceptions.html#DeprecationWarning) снова отображается по умолчанию при непосредственном вызове кодом в `__main__`.132133Изменено в версии 3.7: [`BytesWarning`](https://python-all.ru/3.14/library/exceptions.html#BytesWarning) больше не появляется в списке фильтров по умолчанию и вместо этого настраивается через [`sys.warnoptions`](https://python-all.ru/3.14/library/sys.html#sys.warnoptions), когда [`-b`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-b) указан дважды.134135### Переопределение фильтра по умолчанию136137Разработчики приложений на Python могут захотеть скрыть *все* предупреждения уровня Python от пользователей по умолчанию и показывать их только во время тестирования или другой работы над приложением. Атрибут [`sys.warnoptions`](https://python-all.ru/3.14/library/sys.html#sys.warnoptions), используемый для передачи конфигураций фильтра интерпретатору, может служить маркером, указывающим, следует ли отключить предупреждения:138139```python140import sys141142if not sys.warnoptions:143 import warnings144 warnings.simplefilter("ignore")145```146147Разработчикам средств запуска тестов для кода Python рекомендуется вместо этого обеспечить, чтобы *все* предупреждения отображались по умолчанию для тестируемого кода, используя код наподобие:148149```python150import sys151152if not sys.warnoptions:153 import os, warnings154 warnings.simplefilter("default") # Изменить фильтр в этом процессе155 os.environ["PYTHONWARNINGS"] = "default" # Также действовать на подпроцессы156```157158Наконец, разработчикам интерактивных оболочек, выполняющих пользовательский код в пространстве имён, отличном от `__main__`, рекомендуется обеспечить, чтобы сообщения [`DeprecationWarning`](https://python-all.ru/3.14/library/exceptions.html#DeprecationWarning) были видны по умолчанию, используя код наподобие следующего (где `user_ns` – это модуль, используемый для выполнения вводимого интерактивно кода):159160```python161import warnings162warnings.filterwarnings("default", category=DeprecationWarning,163 module=user_ns.get("__name__"))164```165166## Временное подавление предупреждений167168Если вы используете код, который, как известно, вызовет предупреждение (например, устаревшую функцию), но не хотите видеть это предупреждение (даже если предупреждения были явно настроены через командную строку), то предупреждение можно подавить с помощью контекстного менеджера [`catch_warnings`](https://python-all.ru/3.14/library/warnings.html#warnings.catch_warnings):169170```python171import warnings172173def fxn():174 warnings.warn("deprecated", DeprecationWarning)175176with warnings.catch_warnings():177 warnings.simplefilter("ignore")178 fxn()179```180181Внутри контекстного менеджера все предупреждения просто игнорируются. Это позволяет использовать заведомо устаревший код, не видя предупреждения, при этом не подавляя предупреждения для другого кода, который может не знать об использовании устаревшего кода.182183> > **Примечание**184> >185> > Смотрите [Безопасность менеджеров контекста при параллельном выполнении](https://python-all.ru/3.14/library/warnings.html#warning-concurrent-safe) для подробностей о потокобезопасности менеджера контекста [`catch_warnings`](https://python-all.ru/3.14/library/warnings.html#warnings.catch_warnings) при использовании в программах с несколькими потоками или асинхронными функциями.186187## Тестирование предупреждений188189Для тестирования предупреждений, вызываемых кодом, используйте контекстный менеджер [`catch_warnings`](https://python-all.ru/3.14/library/warnings.html#warnings.catch_warnings). С его помощью можно временно изменить фильтр предупреждений, чтобы упростить тестирование. Например, сделайте следующее, чтобы перехватить все возникающие предупреждения для проверки:190191```python192import warnings193194def fxn():195 warnings.warn("deprecated", DeprecationWarning)196197with warnings.catch_warnings(record=True) as w:198 # Привести к тому, что все предупреждения всегда будут срабатывать.199 warnings.simplefilter("always")200 # Вызвать предупреждение.201 fxn()202 # Проверить некоторые вещи203 assert len(w) == 1204 assert issubclass(w[-1].category, DeprecationWarning)205 assert "deprecated" in str(w[-1].message)206```207208Также можно сделать все предупреждения исключениями, используя `error` вместо `always`. Следует учитывать, что если предупреждение уже было вызвано из-за правила `once`/`default`, то, независимо от установленных фильтров, оно не будет показано снова, пока не будет очищен реестр предупреждений, связанный с этим предупреждением.209210После выхода из контекстного менеджера фильтр предупреждений восстанавливается в состояние, которое было при входе в контекст. Это предотвращает непреднамеренное изменение фильтра предупреждений между тестами и получение неопределённых результатов тестирования.211212> > **Примечание**213> >214> > Смотрите [Безопасность менеджеров контекста при параллельном выполнении](https://python-all.ru/3.14/library/warnings.html#warning-concurrent-safe) для подробностей о потокобезопасности менеджера контекста [`catch_warnings`](https://python-all.ru/3.14/library/warnings.html#warnings.catch_warnings) при использовании в программах с несколькими потоками или асинхронными функциями.215216При тестировании нескольких операций, вызывающих один и тот же тип предупреждения, важно тестировать их так, чтобы подтвердить, что каждая операция вызывает новое предупреждение (например, настроить предупреждения как исключения и проверить, что операции вызывают исключения, проверить, что длина списка предупреждений увеличивается после каждой операции, или удалять предыдущие записи из списка предупреждений перед каждой новой операцией).217218## Обновление кода для новых версий зависимостей219220Категории предупреждений, представляющие интерес в первую очередь для разработчиков Python (а не для конечных пользователей приложений на Python), по умолчанию игнорируются.221222Примечательно, что этот список «игнорируемых по умолчанию» включает [`DeprecationWarning`](https://python-all.ru/3.14/library/exceptions.html#DeprecationWarning) (для каждого модуля, кроме `__main__`), что означает, что разработчики должны обязательно тестировать свой код с видимыми предупреждениями, которые обычно игнорируются, чтобы своевременно получать уведомления о будущих ломающих изменениях API (как в стандартной библиотеке, так и в сторонних пакетах).223224В идеале код будет иметь подходящий набор тестов, а средство запуска тестов позаботится о неявном включении всех предупреждений при выполнении тестов (средство запуска тестов, предоставляемое модулем [`unittest`](https://python-all.ru/3.14/library/unittest.html#module-unittest), делает это).225226В менее идеальных случаях приложения можно проверить на использование устаревших интерфейсов, передав [`-Wd`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-W) интерпретатору Python (это сокращение для `-W default`) или установив `PYTHONWARNINGS=default` в окружении. Это включает обработку по умолчанию для всех предупреждений, включая те, которые игнорируются по умолчанию. Чтобы изменить действие для встреченных предупреждений, можно изменить аргумент, передаваемый `-W` (например, `-W error`). См. флаг `-W` для подробностей о возможностях.227228## Доступные функции229230#### `warnings.warn(message, category=None, stacklevel=1, source=None, *, skip_file_prefixes=())`231232Выдаёт предупреждение, или же игнорирует его, или вызывает исключение. Аргумент *category*, если указан, должен быть [классом категории предупреждения](https://python-all.ru/3.14/library/warnings.html#warning-categories); по умолчанию он равен [`UserWarning`](https://python-all.ru/3.14/library/exceptions.html#UserWarning). В качестве альтернативы *message* может быть экземпляром [`Warning`](https://python-all.ru/3.14/library/exceptions.html#Warning), и в этом случае *category* игнорируется, а используется `message.__class__`. В этом случае текст сообщения будет `str(message)`. Эта функция вызывает исключение, если конкретное выданное предупреждение превращается в ошибку [фильтром предупреждений](https://python-all.ru/3.14/library/warnings.html#warning-filter). Аргумент *stacklevel* может использоваться функциями-обёртками, написанными на Python, например:233234```python235def deprecated_api(message):236 warnings.warn(message, DeprecationWarning, stacklevel=2)237```238239Это заставляет предупреждение ссылаться на вызывающий объект `deprecated_api`, а не на источник самого `deprecated_api` (поскольку последнее противоречило бы цели сообщения предупреждения).240241Именованный аргумент *skip\_file\_prefixes* можно использовать для указания, какие кадры стека игнорируются при подсчёте уровней стека. Это может быть полезно, когда нужно, чтобы предупреждение всегда появлялось в местах вызова за пределами пакета, когда постоянное значение *stacklevel* не подходит для всех путей вызова или его сложно поддерживать. Если указан, он должен быть кортежем строк. При указании префиксов значение stacklevel неявно переопределяется в `max(2, stacklevel)`. Чтобы предупреждение приписывалось вызывающему коду за пределами текущего пакета, можно написать:242243```python244# example/lower.py245_warn_skips = (os.path.dirname(__file__),)246247def one_way(r_luxury_yacht=None, t_wobbler_mangrove=None):248 if r_luxury_yacht:249 warnings.warn("Please migrate to t_wobbler_mangrove=.",250 skip_file_prefixes=_warn_skips)251252# example/higher.py253from . import lower254255def another_way(**kw):256 lower.one_way(**kw)257```258259Это заставляет предупреждение ссылаться на точки вызова как `example.lower.one_way()`, так и `example.higher.another_way()`, только из вызывающего кода, находящегося за пределами пакета `example`.260261Если указан, *source* – это уничтоженный объект, который породил [`ResourceWarning`](https://python-all.ru/3.14/library/exceptions.html#ResourceWarning).262263Изменено в версии 3.6: Добавлен параметр *source*.264265Изменено в версии 3.12: Добавлено *skip\_file\_prefixes*.266267#### `warnings.warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)`268269Это низкоуровневый интерфейс к функциональности [`warn()`](https://python-all.ru/3.14/library/warnings.html#warnings.warn), который явно принимает сообщение, категорию, имя файла и номер строки, а также опционально другие аргументы. *message* должен быть строкой, а *category* – подклассом [`Warning`](https://python-all.ru/3.14/library/exceptions.html#Warning), или *message* может быть экземпляром `Warning`, и в этом случае *category* игнорируется.270271*module*, если указан, должен быть именем модуля. Если модуль не передан, используется имя файла с удалённым `.py`.272273*registry*, если указан, должен быть словарём `__warningregistry__` модуля. Если реестр не передан, каждое предупреждение рассматривается как первое появление, то есть действия фильтра `"default"`, `"module"` и `"once"` обрабатываются как `"always"`.274275*module\_globals*, если указан, должно быть глобальным пространством имён, используемым кодом, для которого выдаётся предупреждение. (Этот аргумент используется для поддержки отображения исходного кода для модулей, найденных в zip-файлах или других источниках импорта, не основанных на файловой системе).276277Если указан, *source* – это уничтоженный объект, который породил [`ResourceWarning`](https://python-all.ru/3.14/library/exceptions.html#ResourceWarning).278279Изменено в версии 3.6: Добавлен параметр *source*.280281#### `warnings.showwarning(message, category, filename, lineno, file=None, line=None)`282283Записывает предупреждение в файл. Реализация по умолчанию вызывает `formatwarning(message, category, filename, lineno, line)` и записывает результирующую строку в *file*, который по умолчанию равен [`sys.stderr`](https://python-all.ru/3.14/library/sys.html#sys.stderr). Эту функцию можно заменить любой вызываемой, присвоив её `warnings.showwarning`. *line* – это строка исходного кода, которая должна быть включена в сообщение предупреждения; если *line* не указана, `showwarning()` попытается прочитать строку, заданную *filename* и *lineno*.284285#### `warnings.formatwarning(message, category, filename, lineno, line=None)`286287Форматирует предупреждение стандартным способом. Возвращает строку, которая может содержать встроенные символы новой строки и заканчивается символом новой строки. *line* – это строка исходного кода, которая должна быть включена в сообщение предупреждения; если *line* не указана, `formatwarning()` попытается прочитать строку, заданную *filename* и *lineno*.288289#### `warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)`290291Вставляет запись в список [спецификаций фильтра предупреждений](https://python-all.ru/3.14/library/warnings.html#warning-filter). По умолчанию запись вставляется в начало; если *append* равен истине, она вставляется в конец. Эта функция проверяет типы аргументов, компилирует регулярные выражения *message* и *module* и вставляет их в виде кортежа в список фильтров предупреждений. Записи, находящиеся ближе к началу списка, имеют приоритет над записями, находящимися ближе к концу, если обе соответствуют конкретному предупреждению. Опущенные аргументы по умолчанию принимают значение, которое соответствует всему.292293#### `warnings.simplefilter(action, category=Warning, lineno=0, append=False)`294295Вставляет простую запись в список [спецификаций фильтра предупреждений](https://python-all.ru/3.14/library/warnings.html#warning-filter). Смысл параметров функции такой же, как у [`filterwarnings()`](https://python-all.ru/3.14/library/warnings.html#warnings.filterwarnings), но регулярные выражения не нужны, так как вставленный фильтр всегда соответствует любому сообщению в любом модуле, если совпадают категория и номер строки.296297#### `warnings.resetwarnings()`298299Сбрасывает фильтр предупреждений. Это отменяет действие всех предыдущих вызовов [`filterwarnings()`](https://python-all.ru/3.14/library/warnings.html#warnings.filterwarnings), включая вызовы, сделанные с помощью параметров командной строки [`-W`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-W) и вызовы [`simplefilter()`](https://python-all.ru/3.14/library/warnings.html#warnings.simplefilter).300301#### `@warnings.deprecated(msg, *, category=DeprecationWarning, stacklevel=1)`302303Декоратор для указания, что класс, функция или перегрузка устарели.304305Когда этот декоратор применяется к объекту, во время выполнения при использовании объекта могут возникать предупреждения об устаревании. [Статические анализаторы типов](https://python-all.ru/3.14/glossary.html#term-static-type-checker) также будут генерировать диагностику при использовании устаревшего объекта.306307Использование:308309```python310from warnings import deprecated311from typing import overload312313@deprecated("Use B instead")314class A:315 pass316317@deprecated("Use g instead")318def f():319 pass320321@overload322@deprecated("int support is deprecated")323def g(x: int) -> int: ...324@overload325def g(x: str) -> int: ...326```327328Предупреждение, заданное с помощью *category*, будет выдаваться во время выполнения при использовании устаревших объектов. Для функций это происходит при вызовах; для классов – при создании экземпляров и создании подклассов. Если *category* равно `None`, предупреждение во время выполнения не выдается. *stacklevel* определяет, где выдается предупреждение. Если он равен `1` (по умолчанию), предупреждение выдается непосредственно тому, кто вызвал устаревший объект; если значение больше, то выше по стеку. Поведение статических анализаторов типов не зависит от аргументов *category* и *stacklevel*.329330Сообщение об устаревании, переданное декоратору, сохраняется в атрибуте `__deprecated__` декорированного объекта. Если применяется к перегрузке, декоратор должен располагаться после декоратора [`@~typing.overload`](https://python-all.ru/3.14/library/typing.html#typing.overload), чтобы атрибут существовал в перегрузке, возвращаемой [`typing.get_overloads()`](https://python-all.ru/3.14/library/typing.html#typing.get_overloads).331332Добавлено в версии 3.13: См. [**PEP 702**](https://python-all.ru/3.14/library/warnings.html).333334## Доступные контекстные менеджеры335336#### `class warnings.catch_warnings(*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)`337338Контекстный менеджер, который копирует и при выходе восстанавливает фильтр предупреждений и функцию [`showwarning()`](https://python-all.ru/3.14/library/warnings.html#warnings.showwarning). Если аргумент *record* равен [`False`](https://python-all.ru/3.14/library/constants.html#False) (по умолчанию), контекстный менеджер при входе возвращает [`None`](https://python-all.ru/3.14/library/constants.html#None). Если *record* равен [`True`](https://python-all.ru/3.14/library/constants.html#True), возвращается список, который постепенно заполняется объектами, видимыми пользовательской функцией `showwarning()` (которая также подавляет вывод в `sys.stderr`). Для каждого объекта в списке гарантировано наличие следующих атрибутов:339340> - `message`: сообщение предупреждения (экземпляр [`Warning`](https://python-all.ru/3.14/library/exceptions.html#Warning))341> - `category`: категория предупреждения (подкласс [`Warning`](https://python-all.ru/3.14/library/exceptions.html#Warning))342> - `filename`: имя файла, где произошло предупреждение ([`str`](https://python-all.ru/3.14/library/stdtypes.html#str))343> - `lineno`: номер строки в файле ([`int`](https://python-all.ru/3.14/library/functions.html#int))344> - `file`: файловый объект, используемый для вывода (если есть), или `None`345> - `line`: строка исходного кода (если доступна), или `None`346> - `source`: исходный объект, который сгенерировал предупреждение (если доступен), или `None`347348Изменено в версии 3.6: Был добавлен атрибут `source`.349350Тип этих объектов не определён и может измениться; гарантируется только наличие этих атрибутов.351352Аргумент *module* принимает модуль, который будет использоваться вместо модуля, возвращаемого при импорте `warnings`, фильтр которого будет защищён. Этот аргумент существует в основном для тестирования самого модуля `warnings`.353354Если аргумент *action* не равен `None`, остальные аргументы передаются в [`simplefilter()`](https://python-all.ru/3.14/library/warnings.html#warnings.simplefilter), как если бы она была вызвана сразу при входе в контекст.355356Смотрите [Фильтр предупреждений](https://python-all.ru/3.14/library/warnings.html#warning-filter) для пояснения параметров *category* и *lineno* .357358> **Примечание**359>360> Смотрите [Безопасность менеджеров контекста при параллельном выполнении](https://python-all.ru/3.14/library/warnings.html#warning-concurrent-safe) для подробностей о потокобезопасности менеджера контекста `catch_warnings` при использовании в программах с несколькими потоками или асинхронными функциями.361362Изменено в версии 3.11: Добавлены параметры *action*, *category*, *lineno* и *append*.363364## Безопасность менеджеров контекста при параллельном выполнении365366Поведение менеджера контекста [`catch_warnings`](https://python-all.ru/3.14/library/warnings.html#warnings.catch_warnings) зависит от флага [`sys.flags.context_aware_warnings`](https://python-all.ru/3.14/library/sys.html#sys.flags.context_aware_warnings). Если флаг истинен, менеджер контекста ведет себя безопасно при параллельном выполнении, в противном случае – нет. Безопасность при параллельном выполнении означает, что он одновременно потокобезопасен и безопасен для использования внутри [корутин asyncio](https://python-all.ru/3.14/library/asyncio-task.html#coroutine) и задач. Потокобезопасность означает, что поведение предсказуемо в многопоточной программе. По умолчанию флаг имеет значение true для free-threaded сборок и false в остальных случаях.367368Если флаг [`context_aware_warnings`](https://python-all.ru/3.14/library/sys.html#sys.flags.context_aware_warnings) ложен, то [`catch_warnings`](https://python-all.ru/3.14/library/warnings.html#warnings.catch_warnings) изменяет глобальные атрибуты модуля `warnings`. Это небезопасно при использовании в параллельной программе (с несколькими потоками или корутинами asyncio). Например, если два или более потоков одновременно используют класс `catch_warnings`, поведение становится неопределённым.369370Если флаг истинен, [`catch_warnings`](https://python-all.ru/3.14/library/warnings.html#warnings.catch_warnings) не изменяет глобальные атрибуты, а вместо этого использует [`ContextVar`](https://python-all.ru/3.14/library/contextvars.html#contextvars.ContextVar) для хранения только что установленного состояния фильтрации предупреждений. Переменная контекста обеспечивает локальное хранилище для потока и делает использование `catch_warnings` потокобезопасным.371372Параметр *record* контекстного обработчика также ведёт себя по-разному в зависимости от значения флага. Когда *record* истинен, а флаг ложен, менеджер контекста работает путём замены, а затем восстановления функции [`showwarning()`](https://python-all.ru/3.14/library/warnings.html#warnings.showwarning) модуля. Это небезопасно при параллельном выполнении.373374Когда *record* истинен и флаг истинен, функция [`showwarning()`](https://python-all.ru/3.14/library/warnings.html#warnings.showwarning) не заменяется. Вместо этого статус записи указывается внутренним свойством в переменной контекста. В этом случае функция `showwarning()` не будет восстановлена при выходе из контекстного обработчика.375376Флаг [`context_aware_warnings`](https://python-all.ru/3.14/library/sys.html#sys.flags.context_aware_warnings) можно установить с помощью параметра командной строки [`-X context_aware_warnings`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-X) или переменной окружения [`PYTHON_CONTEXT_AWARE_WARNINGS`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHON_CONTEXT_AWARE_WARNINGS).377378> > **Примечание**379> >380> > Вероятно, большинство программ, которым требуется потокобезопасное поведение модуля warnings, также захотят установить флаг [`thread_inherit_context`](https://python-all.ru/3.14/library/sys.html#sys.flags.thread_inherit_context) в true. Этот флаг заставляет потоки, созданные с помощью [`threading.Thread`](https://python-all.ru/3.14/library/threading.html#threading.Thread), запускаться с копией переменных контекста из потока, который их запускает. Если true, контекст, установленный [`catch_warnings`](https://python-all.ru/3.14/library/warnings.html#warnings.catch_warnings) в одном потоке, также будет применяться к новым потокам, запущенным из него. Если false, новые потоки запускаются с пустой переменной контекста предупреждений, что означает, что любая фильтрация, установленная менеджером контекста `catch_warnings`, больше не будет активна.381382Изменено в версии 3.14: Добавлены флаг [`sys.flags.context_aware_warnings`](https://python-all.ru/3.14/library/sys.html#sys.flags.context_aware_warnings) и использование переменной контекста для [`catch_warnings`](https://python-all.ru/3.14/library/warnings.html#warnings.catch_warnings), если флаг истинен. Предыдущие версии Python вели себя так, как если бы флаг всегда был установлен в false.383