warnings.md
1> **Источник:** https://python-all.ru/3.13/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.13/Lib/warnings.py)1011---1213Предупреждения обычно выводятся в ситуациях, когда полезно предупредить пользователя о некотором условии в программе, когда это условие (обычно) не требует возбуждения исключения и завершения программы. Например, может потребоваться выдать предупреждение, если программа использует устаревший модуль.1415Разработчики на Python выводят предупреждения, вызывая функцию [`warn()`](https://python-all.ru/3.13/library/warnings.html#warnings.warn), определённую в этом модуле. (Разработчики на C используют [`PyErr_WarnEx()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_WarnEx); см. [Обработка исключений](https://python-all.ru/3.13/c-api/exceptions.html#exceptionhandling) для подробностей).1617Предупреждения обычно записываются в [`sys.stderr`](https://python-all.ru/3.13/library/sys.html#sys.stderr), но их обработку можно гибко изменять: от игнорирования всех предупреждений до превращения их в исключения. Обработка предупреждений может зависеть от [категории предупреждения](https://python-all.ru/3.13/library/warnings.html#warning-categories), текста предупреждающего сообщения и места в исходном коде, где оно выдается. Повторные предупреждения для одного и того же места в исходном коде обычно подавляются.1819Управление предупреждениями состоит из двух этапов: сначала каждый раз при выдаче предупреждения определяется, должно ли сообщение быть выдано; затем, если сообщение должно быть выдано, оно форматируется и выводится с помощью настраиваемого пользователем перехватчика.2021Решение о том, выдавать ли предупреждающее сообщение, управляется [фильтром предупреждений](https://python-all.ru/3.13/library/warnings.html#warning-filter), который представляет собой последовательность правил сопоставления и действий. Правила можно добавлять в фильтр, вызывая [`filterwarnings()`](https://python-all.ru/3.13/library/warnings.html#warnings.filterwarnings), и сбрасывать в состояние по умолчанию, вызывая [`resetwarnings()`](https://python-all.ru/3.13/library/warnings.html#warnings.resetwarnings).2223Вывод предупреждающих сообщений выполняется вызовом [`showwarning()`](https://python-all.ru/3.13/library/warnings.html#warnings.showwarning), который может быть переопределён; реализация по умолчанию этой функции форматирует сообщение вызовом [`formatwarning()`](https://python-all.ru/3.13/library/warnings.html#warnings.formatwarning), который также доступен для использования в пользовательских реализациях.2425> **См. также**26>27> [`logging.captureWarnings()`](https://python-all.ru/3.13/library/logging.html#logging.captureWarnings) позволяет обрабатывать все предупреждения с помощью стандартной инфраструктуры журналирования.2829## Категории предупреждений3031Существует ряд встроенных исключений, представляющих категории предупреждений. Такая категоризация полезна для фильтрации групп предупреждений.3233Хотя технически это [встроенные исключения](https://python-all.ru/3.13/library/exceptions.html#warning-categories-as-exceptions), они documented here, потому что концептуально относятся к механизму предупреждений.3435Пользовательский код может определять дополнительные категории предупреждений, создавая подкласс одной из стандартных категорий предупреждений. Категория предупреждения всегда должна быть подклассом класса [`Warning`](https://python-all.ru/3.13/library/exceptions.html#Warning).3637В настоящее время определены следующие классы категорий предупреждений:3839| Класс | Описание |40| --- | --- |41| [`Warning`](https://python-all.ru/3.13/library/exceptions.html#Warning) | Это базовый класс всех классов категорий предупреждений. Он является подклассом [`Exception`](https://python-all.ru/3.13/library/exceptions.html#Exception). |42| [`UserWarning`](https://python-all.ru/3.13/library/exceptions.html#UserWarning) | Категория по умолчанию для [`warn()`](https://python-all.ru/3.13/library/warnings.html#warnings.warn). |43| [`DeprecationWarning`](https://python-all.ru/3.13/library/exceptions.html#DeprecationWarning) | Базовая категория для предупреждений об устаревших возможностях, если эти предупреждения предназначены для других разработчиков Python (игнорируется по умолчанию, если не вызвано кодом в `__main__`). |44| [`SyntaxWarning`](https://python-all.ru/3.13/library/exceptions.html#SyntaxWarning) | Базовая категория для предупреждений о сомнительных синтаксических возможностях (обычно выдаются при компиляции исходного кода Python и поэтому могут не подавляться фильтрами времени выполнения). |45| [`RuntimeWarning`](https://python-all.ru/3.13/library/exceptions.html#RuntimeWarning) | Базовая категория для предупреждений о сомнительных возможностях времени выполнения. |46| [`FutureWarning`](https://python-all.ru/3.13/library/exceptions.html#FutureWarning) | Базовая категория для предупреждений об устаревших возможностях, если эти предупреждения предназначены для конечных пользователей приложений, написанных на Python. |47| [`PendingDeprecationWarning`](https://python-all.ru/3.13/library/exceptions.html#PendingDeprecationWarning) | Базовая категория для предупреждений о возможностях, которые будут объявлены устаревшими в будущем (игнорируется по умолчанию). |48| [`ImportWarning`](https://python-all.ru/3.13/library/exceptions.html#ImportWarning) | Базовая категория для предупреждений, возникающих в процессе импорта модуля (игнорируется по умолчанию). |49| [`UnicodeWarning`](https://python-all.ru/3.13/library/exceptions.html#UnicodeWarning) | Базовая категория для предупреждений, связанных с Юникодом. |50| [`BytesWarning`](https://python-all.ru/3.13/library/exceptions.html#BytesWarning) | Базовая категория для предупреждений, связанных с [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) и [`bytearray`](https://python-all.ru/3.13/library/stdtypes.html#bytearray). |51| [`ResourceWarning`](https://python-all.ru/3.13/library/exceptions.html#ResourceWarning) | Базовая категория для предупреждений, связанных с использованием ресурсов (игнорируется по умолчанию). |5253Изменено в версии 3.7: Ранее [`DeprecationWarning`](https://python-all.ru/3.13/library/exceptions.html#DeprecationWarning) и [`FutureWarning`](https://python-all.ru/3.13/library/exceptions.html#FutureWarning) различались по тому, удалялась ли возможность полностью или меняла своё поведение. Теперь они различаются по целевой аудитории и способу обработки фильтрами предупреждений по умолчанию.5455## Фильтр предупреждений5657Фильтр предупреждений управляет тем, игнорируются ли предупреждения, выводятся на экран или превращаются в ошибки (вызывают исключение).5859Концептуально фильтр предупреждений поддерживает упорядоченный список спецификаций фильтра; любое конкретное предупреждение последовательно сопоставляется с каждой спецификацией фильтра из списка, пока не будет найдено совпадение; фильтр определяет обработку совпадения. Каждая запись представляет собой кортеж вида (*действие*, *сообщение*, *категория*, *модуль*, *номер\_строки*), где:6061- *Действие* – одна из следующих строк:6263 | Значение | Действие |64 | --- | --- |65 | `"default"` | выводить первое вхождение подходящих предупреждений для каждого местоположения (модуль + номер строки), где выдано предупреждение |66 | `"error"` | превращать подходящие предупреждения в исключения |67 | `"ignore"` | никогда не выводить подходящие предупреждения |68 | `"always"` | всегда выводить подходящие предупреждения |69 | `"module"` | выводить первое вхождение подходящих предупреждений для каждого модуля, где выдано предупреждение (независимо от номера строки) |70 | `"once"` | выводить только первое вхождение подходящих предупреждений, независимо от местоположения |71- *message* – это строка, содержащая регулярное выражение, которому должно соответствовать начало сообщения предупреждения (без учёта регистра). В [`-W`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-W) и [`PYTHONWARNINGS`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONWARNINGS) параметр *message* – это литеральная строка, которую должно содержать начало сообщения предупреждения (без учёта регистра), при этом игнорируются любые пробельные символы в начале и конце *message*.72- *category* – это класс (подкласс [`Warning`](https://python-all.ru/3.13/library/exceptions.html#Warning)), подклассом которого должна быть категория предупреждения для совпадения.73- *module* – это строка, содержащая регулярное выражение, которому должно соответствовать начало полного имени модуля (с учётом регистра). В [`-W`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-W) и [`PYTHONWARNINGS`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONWARNINGS) параметр *module* – это литеральная строка, которой должно быть равно полное имя модуля (с учётом регистра), при этом игнорируются любые пробельные символы в начале и конце *module*.74- *lineno* – это целое число, которому должен соответствовать номер строки, где произошло предупреждение, или `0` для соответствия всем номерам строк.7576Поскольку класс [`Warning`](https://python-all.ru/3.13/library/exceptions.html#Warning) является наследником встроенного класса [`Exception`](https://python-all.ru/3.13/library/exceptions.html#Exception), чтобы превратить предупреждение в ошибку, мы просто возбуждаем `category(message)`.7778Если предупреждение зарегистрировано и не соответствует ни одному из установленных фильтров, то применяется действие «default» (отсюда и его название).7980### Критерии подавления повторяющихся предупреждений8182Фильтры, подавляющие повторяющиеся предупреждения, используют следующие критерии для определения, считается ли предупреждение повторным:8384- `"default"`: предупреждение считается повторным только в том случае, если все значения (*message*, *category*, *module*, *lineno*) одинаковы.85- `"module"`: предупреждение считается повторным, если (*message*, *category*, *module*) одинаковы, независимо от номера строки.86- `"once"`: предупреждение считается повторным, если (*message*, *category*) одинаковы, независимо от модуля и номера строки.8788### Описание фильтров предупреждений8990Фильтр предупреждений инициализируется опциями [`-W`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-W), переданными в командной строке интерпретатора Python, и переменной окружения [`PYTHONWARNINGS`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONWARNINGS). Интерпретатор сохраняет аргументы для всех предоставленных записей без интерпретации в [`sys.warnoptions`](https://python-all.ru/3.13/library/sys.html#sys.warnoptions); модуль `warnings` анализирует их при первом импорте (недопустимые опции игнорируются после вывода сообщения в [`sys.stderr`](https://python-all.ru/3.13/library/sys.html#sys.stderr)).9192Отдельные фильтры предупреждений задаются в виде последовательности полей, разделённых двоеточиями:9394```python95action:message:category:module:line96```9798Значение каждого из этих полей описано в разделе [Фильтр предупреждений](https://python-all.ru/3.13/library/warnings.html#warning-filter). При перечислении нескольких фильтров в одной строке (как для [`PYTHONWARNINGS`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONWARNINGS)) отдельные фильтры разделяются запятыми, и фильтры, указанные позже, имеют приоритет над теми, что указаны раньше (поскольку они применяются слева направо, и последние применённые фильтры имеют преимущество перед более ранними).99100Обычно используемые фильтры предупреждений применяются либо ко всем предупреждениям, либо к предупреждениям определённой категории, либо к предупреждениям, вызванным определёнными модулями или пакетами. Несколько примеров:101102```python103default # Показывать все предупреждения (даже те, что игнорируются по умолчанию)104ignore # Игнорировать все предупреждения105error # Преобразовать все предупреждения в ошибки106error::ResourceWarning # Обрабатывать сообщения ResourceWarning как ошибки107default::DeprecationWarning # Показывать сообщения DeprecationWarning108ignore,default:::mymodule # Сообщать только о предупреждениях, вызванных "mymodule"109error:::mymodule # Преобразовывать предупреждения в ошибки в "mymodule"110```111112### Фильтр предупреждений по умолчанию113114По умолчанию Python устанавливает несколько фильтров предупреждений, которые можно переопределить с помощью параметра командной строки [`-W`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-W), переменной окружения [`PYTHONWARNINGS`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONWARNINGS) и вызовов [`filterwarnings()`](https://python-all.ru/3.13/library/warnings.html#warnings.filterwarnings).115116В обычных сборках релиза фильтр предупреждений по умолчанию имеет следующие записи (в порядке приоритета):117118```python119default::DeprecationWarning:__main__120ignore::DeprecationWarning121ignore::PendingDeprecationWarning122ignore::ImportWarning123ignore::ResourceWarning124```125126В [отладочной сборке](https://python-all.ru/3.13/using/configure.html#debug-build) список фильтров предупреждений по умолчанию пуст.127128Изменено в версии 3.2: [`DeprecationWarning`](https://python-all.ru/3.13/library/exceptions.html#DeprecationWarning) теперь по умолчанию игнорируется в дополнение к [`PendingDeprecationWarning`](https://python-all.ru/3.13/library/exceptions.html#PendingDeprecationWarning).129130Изменено в версии 3.7: [`DeprecationWarning`](https://python-all.ru/3.13/library/exceptions.html#DeprecationWarning) снова отображается по умолчанию при непосредственном вызове кодом в `__main__`.131132Изменено в версии 3.7: [`BytesWarning`](https://python-all.ru/3.13/library/exceptions.html#BytesWarning) больше не появляется в списке фильтров по умолчанию и вместо этого настраивается через [`sys.warnoptions`](https://python-all.ru/3.13/library/sys.html#sys.warnoptions), когда [`-b`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-b) указан дважды.133134### Переопределение фильтра по умолчанию135136Разработчики приложений на Python могут захотеть скрыть *все* предупреждения уровня Python от пользователей по умолчанию и показывать их только во время тестирования или другой работы над приложением. Атрибут [`sys.warnoptions`](https://python-all.ru/3.13/library/sys.html#sys.warnoptions), используемый для передачи конфигураций фильтра интерпретатору, может служить маркером, указывающим, следует ли отключить предупреждения:137138```python139import sys140141if not sys.warnoptions:142 import warnings143 warnings.simplefilter("ignore")144```145146Разработчикам средств запуска тестов для кода Python рекомендуется вместо этого обеспечить, чтобы *все* предупреждения отображались по умолчанию для тестируемого кода, используя код наподобие:147148```python149import sys150151if not sys.warnoptions:152 import os, warnings153 warnings.simplefilter("default") # Изменить фильтр в этом процессе154 os.environ["PYTHONWARNINGS"] = "default" # Также действовать на подпроцессы155```156157Наконец, разработчикам интерактивных оболочек, выполняющих пользовательский код в пространстве имён, отличном от `__main__`, рекомендуется обеспечить, чтобы сообщения [`DeprecationWarning`](https://python-all.ru/3.13/library/exceptions.html#DeprecationWarning) были видны по умолчанию, используя код наподобие следующего (где `user_ns` – это модуль, используемый для выполнения вводимого интерактивно кода):158159```python160import warnings161warnings.filterwarnings("default", category=DeprecationWarning,162 module=user_ns.get("__name__"))163```164165## Временное подавление предупреждений166167Если вы используете код, который, как известно, вызовет предупреждение (например, устаревшую функцию), но не хотите видеть это предупреждение (даже если предупреждения были явно настроены через командную строку), то предупреждение можно подавить с помощью контекстного менеджера [`catch_warnings`](https://python-all.ru/3.13/library/warnings.html#warnings.catch_warnings):168169```python170import warnings171172def fxn():173 warnings.warn("deprecated", DeprecationWarning)174175with warnings.catch_warnings():176 warnings.simplefilter("ignore")177 fxn()178```179180Пока менеджер контекста активен, все предупреждения просто игнорируются. Это позволяет использовать заведомо устаревший код, не видя предупреждения, при этом не подавляя предупреждения для другого кода, который может не знать об использовании устаревших функций. Примечание: это гарантируется только в однопоточном приложении. Если два или более потока одновременно используют менеджер контекста [`catch_warnings`](https://python-all.ru/3.13/library/warnings.html#warnings.catch_warnings), поведение не определено.181182## Тестирование предупреждений183184Для тестирования предупреждений, вызываемых кодом, используйте контекстный менеджер [`catch_warnings`](https://python-all.ru/3.13/library/warnings.html#warnings.catch_warnings). С его помощью можно временно изменить фильтр предупреждений, чтобы упростить тестирование. Например, сделайте следующее, чтобы перехватить все возникающие предупреждения для проверки:185186```python187import warnings188189def fxn():190 warnings.warn("deprecated", DeprecationWarning)191192with warnings.catch_warnings(record=True) as w:193 # Привести к тому, что все предупреждения всегда будут срабатывать.194 warnings.simplefilter("always")195 # Вызвать предупреждение.196 fxn()197 # Проверить некоторые вещи198 assert len(w) == 1199 assert issubclass(w[-1].category, DeprecationWarning)200 assert "deprecated" in str(w[-1].message)201```202203Также можно сделать все предупреждения исключениями, используя `error` вместо `always`. Следует учитывать, что если предупреждение уже было вызвано из-за правила `once`/`default`, то, независимо от установленных фильтров, оно не будет показано снова, пока не будет очищен реестр предупреждений, связанный с этим предупреждением.204205После выхода из менеджера контекста фильтр предупреждений восстанавливается до состояния на момент входа. Это предотвращает непреднамеренное изменение фильтра предупреждений между тестами и получение неопределённых результатов. Функция [`showwarning()`](https://python-all.ru/3.13/library/warnings.html#warnings.showwarning) в модуле также восстанавливается до исходного значения. Примечание: это гарантируется только в однопоточном приложении. Если два или более потока одновременно используют менеджер контекста [`catch_warnings`](https://python-all.ru/3.13/library/warnings.html#warnings.catch_warnings), поведение не определено.206207При тестировании нескольких операций, вызывающих один и тот же тип предупреждения, важно тестировать их так, чтобы подтвердить, что каждая операция вызывает новое предупреждение (например, настроить предупреждения как исключения и проверить, что операции вызывают исключения, проверить, что длина списка предупреждений увеличивается после каждой операции, или удалять предыдущие записи из списка предупреждений перед каждой новой операцией).208209## Обновление кода для новых версий зависимостей210211Категории предупреждений, представляющие интерес в первую очередь для разработчиков Python (а не для конечных пользователей приложений на Python), по умолчанию игнорируются.212213Примечательно, что этот список «игнорируемых по умолчанию» включает [`DeprecationWarning`](https://python-all.ru/3.13/library/exceptions.html#DeprecationWarning) (для каждого модуля, кроме `__main__`), что означает, что разработчики должны обязательно тестировать свой код с видимыми предупреждениями, которые обычно игнорируются, чтобы своевременно получать уведомления о будущих ломающих изменениях API (как в стандартной библиотеке, так и в сторонних пакетах).214215В идеале код будет иметь подходящий набор тестов, а средство запуска тестов позаботится о неявном включении всех предупреждений при выполнении тестов (средство запуска тестов, предоставляемое модулем [`unittest`](https://python-all.ru/3.13/library/unittest.html#module-unittest), делает это).216217В менее идеальных случаях приложения можно проверить на использование устаревших интерфейсов, передав [`-Wd`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-W) интерпретатору Python (это сокращение для `-W default`) или установив `PYTHONWARNINGS=default` в окружении. Это включает обработку по умолчанию для всех предупреждений, включая те, которые игнорируются по умолчанию. Чтобы изменить действие для встреченных предупреждений, можно изменить аргумент, передаваемый `-W` (например, `-W error`). См. флаг `-W` для подробностей о возможностях.218219## Доступные функции220221#### `warnings.warn(message, category=None, stacklevel=1, source=None, *, skip_file_prefixes=())`222223Выдаёт предупреждение, или же игнорирует его, или вызывает исключение. Аргумент *category*, если указан, должен быть [классом категории предупреждения](https://python-all.ru/3.13/library/warnings.html#warning-categories); по умолчанию он равен [`UserWarning`](https://python-all.ru/3.13/library/exceptions.html#UserWarning). В качестве альтернативы *message* может быть экземпляром [`Warning`](https://python-all.ru/3.13/library/exceptions.html#Warning), и в этом случае *category* игнорируется, а используется `message.__class__`. В этом случае текст сообщения будет `str(message)`. Эта функция вызывает исключение, если конкретное выданное предупреждение превращается в ошибку [фильтром предупреждений](https://python-all.ru/3.13/library/warnings.html#warning-filter). Аргумент *stacklevel* может использоваться функциями-обёртками, написанными на Python, например:224225```python226def deprecated_api(message):227 warnings.warn(message, DeprecationWarning, stacklevel=2)228```229230Это заставляет предупреждение ссылаться на вызывающий объект `deprecated_api`, а не на источник самого `deprecated_api` (поскольку последнее противоречило бы цели сообщения предупреждения).231232Именованный аргумент *skip\_file\_prefixes* можно использовать для указания, какие кадры стека игнорируются при подсчёте уровней стека. Это может быть полезно, когда нужно, чтобы предупреждение всегда появлялось в местах вызова за пределами пакета, когда постоянное значение *stacklevel* не подходит для всех путей вызова или его сложно поддерживать. Если указан, он должен быть кортежем строк. При указании префиксов значение stacklevel неявно переопределяется в `max(2, stacklevel)`. Чтобы предупреждение приписывалось вызывающему коду за пределами текущего пакета, можно написать:233234```python235# example/lower.py236_warn_skips = (os.path.dirname(__file__),)237238def one_way(r_luxury_yacht=None, t_wobbler_mangrove=None):239 if r_luxury_yacht:240 warnings.warn("Please migrate to t_wobbler_mangrove=.",241 skip_file_prefixes=_warn_skips)242243# example/higher.py244from . import lower245246def another_way(**kw):247 lower.one_way(**kw)248```249250Это заставляет предупреждение ссылаться на точки вызова как `example.lower.one_way()`, так и `example.higher.another_way()`, только из вызывающего кода, находящегося за пределами пакета `example`.251252Если указан, *source* – это уничтоженный объект, который породил [`ResourceWarning`](https://python-all.ru/3.13/library/exceptions.html#ResourceWarning).253254Изменено в версии 3.6: Добавлен параметр *source*.255256Изменено в версии 3.12: Добавлено *skip\_file\_prefixes*.257258#### `warnings.warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)`259260Это низкоуровневый интерфейс к функциональности [`warn()`](https://python-all.ru/3.13/library/warnings.html#warnings.warn), который явно принимает сообщение, категорию, имя файла и номер строки, а также опционально другие аргументы. *message* должен быть строкой, а *category* – подклассом [`Warning`](https://python-all.ru/3.13/library/exceptions.html#Warning), или *message* может быть экземпляром `Warning`, и в этом случае *category* игнорируется.261262*module*, если указан, должен быть именем модуля. Если модуль не передан, используется имя файла с удалённым `.py`.263264*registry*, если указан, должен быть словарём `__warningregistry__` модуля. Если реестр не передан, каждое предупреждение рассматривается как первое появление, то есть действия фильтра `"default"`, `"module"` и `"once"` обрабатываются как `"always"`.265266*module\_globals*, если указан, должно быть глобальным пространством имён, используемым кодом, для которого выдаётся предупреждение. (Этот аргумент используется для поддержки отображения исходного кода для модулей, найденных в zip-файлах или других источниках импорта, не основанных на файловой системе).267268Если указан, *source* – это уничтоженный объект, который породил [`ResourceWarning`](https://python-all.ru/3.13/library/exceptions.html#ResourceWarning).269270Изменено в версии 3.6: Добавлен параметр *source*.271272#### `warnings.showwarning(message, category, filename, lineno, file=None, line=None)`273274Записывает предупреждение в файл. Реализация по умолчанию вызывает `formatwarning(message, category, filename, lineno, line)` и записывает результирующую строку в *file*, который по умолчанию равен [`sys.stderr`](https://python-all.ru/3.13/library/sys.html#sys.stderr). Эту функцию можно заменить любой вызываемой, присвоив её `warnings.showwarning`. *line* – это строка исходного кода, которая должна быть включена в сообщение предупреждения; если *line* не указана, `showwarning()` попытается прочитать строку, заданную *filename* и *lineno*.275276#### `warnings.formatwarning(message, category, filename, lineno, line=None)`277278Форматирует предупреждение стандартным способом. Возвращает строку, которая может содержать встроенные символы новой строки и заканчивается символом новой строки. *line* – это строка исходного кода, которая должна быть включена в сообщение предупреждения; если *line* не указана, `formatwarning()` попытается прочитать строку, заданную *filename* и *lineno*.279280#### `warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)`281282Вставляет запись в список [спецификаций фильтра предупреждений](https://python-all.ru/3.13/library/warnings.html#warning-filter). По умолчанию запись вставляется в начало; если *append* равен истине, она вставляется в конец. Эта функция проверяет типы аргументов, компилирует регулярные выражения *message* и *module* и вставляет их в виде кортежа в список фильтров предупреждений. Записи, находящиеся ближе к началу списка, имеют приоритет над записями, находящимися ближе к концу, если обе соответствуют конкретному предупреждению. Опущенные аргументы по умолчанию принимают значение, которое соответствует всему.283284#### `warnings.simplefilter(action, category=Warning, lineno=0, append=False)`285286Вставляет простую запись в список [спецификаций фильтра предупреждений](https://python-all.ru/3.13/library/warnings.html#warning-filter). Смысл параметров функции такой же, как у [`filterwarnings()`](https://python-all.ru/3.13/library/warnings.html#warnings.filterwarnings), но регулярные выражения не нужны, так как вставленный фильтр всегда соответствует любому сообщению в любом модуле, если совпадают категория и номер строки.287288#### `warnings.resetwarnings()`289290Сбрасывает фильтр предупреждений. Это отменяет действие всех предыдущих вызовов [`filterwarnings()`](https://python-all.ru/3.13/library/warnings.html#warnings.filterwarnings), включая вызовы, сделанные с помощью параметров командной строки [`-W`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-W) и вызовы [`simplefilter()`](https://python-all.ru/3.13/library/warnings.html#warnings.simplefilter).291292#### `@warnings.deprecated(msg, *, category=DeprecationWarning, stacklevel=1)`293294Декоратор для указания, что класс, функция или перегрузка устарели.295296Когда этот декоратор применяется к объекту, во время выполнения при использовании объекта могут возникать предупреждения об устаревании. [Статические анализаторы типов](https://python-all.ru/3.13/glossary.html#term-static-type-checker) также будут генерировать диагностику при использовании устаревшего объекта.297298Использование:299300```python301from warnings import deprecated302from typing import overload303304@deprecated("Use B instead")305class A:306 pass307308@deprecated("Use g instead")309def f():310 pass311312@overload313@deprecated("int support is deprecated")314def g(x: int) -> int: ...315@overload316def g(x: str) -> int: ...317```318319Предупреждение, заданное с помощью *category*, будет выдаваться во время выполнения при использовании устаревших объектов. Для функций это происходит при вызовах; для классов – при создании экземпляров и создании подклассов. Если *category* равно `None`, предупреждение во время выполнения не выдается. *stacklevel* определяет, где выдается предупреждение. Если он равен `1` (по умолчанию), предупреждение выдается непосредственно тому, кто вызвал устаревший объект; если значение больше, то выше по стеку. Поведение статических анализаторов типов не зависит от аргументов *category* и *stacklevel*.320321Сообщение об устаревании, переданное декоратору, сохраняется в атрибуте `__deprecated__` декорированного объекта. Если применяется к перегрузке, декоратор должен располагаться после декоратора [`@~typing.overload`](https://python-all.ru/3.13/library/typing.html#typing.overload), чтобы атрибут существовал в перегрузке, возвращаемой [`typing.get_overloads()`](https://python-all.ru/3.13/library/typing.html#typing.get_overloads).322323Добавлено в версии 3.13: См. [**PEP 702**](https://python-all.ru/3.13/library/warnings.html).324325## Доступные контекстные менеджеры326327#### `class warnings.catch_warnings(*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)`328329Контекстный менеджер, который копирует и при выходе восстанавливает фильтр предупреждений и функцию [`showwarning()`](https://python-all.ru/3.13/library/warnings.html#warnings.showwarning). Если аргумент *record* равен [`False`](https://python-all.ru/3.13/library/constants.html#False) (по умолчанию), контекстный менеджер при входе возвращает [`None`](https://python-all.ru/3.13/library/constants.html#None). Если *record* равен [`True`](https://python-all.ru/3.13/library/constants.html#True), возвращается список, который постепенно заполняется объектами, видимыми пользовательской функцией `showwarning()` (которая также подавляет вывод в `sys.stderr`). Для каждого объекта в списке гарантировано наличие следующих атрибутов:330331> - `message`: сообщение предупреждения (экземпляр [`Warning`](https://python-all.ru/3.13/library/exceptions.html#Warning))332> - `category`: категория предупреждения (подкласс [`Warning`](https://python-all.ru/3.13/library/exceptions.html#Warning))333> - `filename`: имя файла, где произошло предупреждение ([`str`](https://python-all.ru/3.13/library/stdtypes.html#str))334> - `lineno`: номер строки в файле ([`int`](https://python-all.ru/3.13/library/functions.html#int))335> - `file`: файловый объект, используемый для вывода (если есть), или `None`336> - `line`: строка исходного кода (если доступна), или `None`337> - `source`: исходный объект, который сгенерировал предупреждение (если доступен), или `None`338339Изменено в версии 3.6: Был добавлен атрибут `source`.340341Тип этих объектов не определён и может измениться; гарантируется только наличие этих атрибутов.342343Аргумент *module* принимает модуль, который будет использоваться вместо модуля, возвращаемого при импорте `warnings`, фильтр которого будет защищён. Этот аргумент существует в основном для тестирования самого модуля `warnings`.344345Если аргумент *action* не равен `None`, остальные аргументы передаются в [`simplefilter()`](https://python-all.ru/3.13/library/warnings.html#warnings.simplefilter), как если бы она была вызвана сразу при входе в контекст.346347Смотрите [Фильтр предупреждений](https://python-all.ru/3.13/library/warnings.html#warning-filter) для пояснения параметров *category* и *lineno* .348349> **Примечание**350>351> Менеджер `catch_warnings` работает путём замены, а затем восстановления функции [`showwarning()`](https://python-all.ru/3.13/library/warnings.html#warnings.showwarning) модуля и внутреннего списка спецификаций фильтров. Это означает, что менеджер контекста изменяет глобальное состояние и поэтому не является потокобезопасным.352353Изменено в версии 3.11: Добавлены параметры *action*, *category*, *lineno* и *append*.354