Предупреждения — Управление предупреждениями

Категории предупреждений

Существует ряд встроенных исключений, которые представляют категории предупреждений. Эта категоризация полезна для фильтрации групп предупреждений.

Хотя технически это встроенные исключения, они документированы здесь, потому что концептуально они относятся к механизму предупреждений.

Пользовательский код может определить дополнительные категории предупреждений, наследуя одну из стандартных категорий предупреждений. Категория предупреждений всегда должна быть подклассом класса Warning.

В настоящее время определены следующие классы категорий предупреждений:

Фильтр Предупреждений

Фильтр предупреждений управляет тем, игнорируются ли предупреждения, отображаются или превращаются в ошибки (вызывая исключение).

По концепции, фильтр предупреждений поддерживает упорядоченный список спецификаций фильтра; каждое конкретное предупреждение сравнивается с каждой спецификацией фильтра в списке по очереди до тех пор, пока не будет найдено соответствие; фильтр определяет реакцию на соответствие. Каждый элемент — это кортеж вида (действие, сообщение, категория, модуль, номер_строки), где:

• действие — одна из следующих строк:

  Значение	Реакция
  "default"	вывести первое вхождение совпадающих предупреждений для каждого местоположения (модуль + номер строки), где выдаётся предупреждение
  "error"	превратить совпадающие предупреждения в исключения
  "ignore"	никогда не выводить совпадающие предупреждения
  "always"	всегда выводить совпадающие предупреждения
  "module"	выводить первое вхождение совпадающих предупреждений для каждого модуля, где выдаётся предупреждение (независимо от номера строки)
  "once"	выводить только первое вхождение совпадающих предупреждений, независимо от местоположения

• сообщение — строка, содержащая регулярное выражение, которому должно соответствовать начало сообщения о предупреждении, без учёта регистра. В -W и PYTHONWARNINGS, сообщение — это буквальная строка, которой должно соответствовать начало сообщения о предупреждении (без учёта регистра), игнорируя пробелы в начале и конце сообщения.
• категория — класс (подкласс Warning), подклассом которого должна быть категория предупреждения для соответствия.
• модуль — строка, содержащая регулярное выражение, которому должно соответствовать начало полного имени модуля, с учётом регистра. В -W и PYTHONWARNINGS, модуль — это буквальная строка, которой должно быть равно полное имя модуля (с учётом регистра), игнорируя пробелы в начале и конце модуля.
• номер_строки — целое число, которому должен соответствовать номер строки, где возникло предупреждение, или 0 для соответствия всем номерам строк.

Поскольку класс Warning унаследован от встроенного класса Exception, для превращения предупреждения в ошибку достаточно просто вызвать category(message).

Если предупреждение сообщается и не соответствует ни одному зарегистрированному фильтру, то применяется «стандартное» действие (отсюда и его название).

action:message:category:module:line

default                      # Show all warnings (even those ignored by default)
ignore                       # Ignore all warnings
error                        # Convert all warnings to errors
error::ResourceWarning       # Treat ResourceWarning messages as errors
default::DeprecationWarning  # Show DeprecationWarning messages
ignore,default:::mymodule    # Only report warnings triggered by "mymodule"
error:::mymodule             # Convert warnings to errors in "mymodule"

default::DeprecationWarning:__main__
ignore::DeprecationWarning
ignore::PendingDeprecationWarning
ignore::ImportWarning
ignore::ResourceWarning

import sys

if not sys.warnoptions:
    import warnings
    warnings.simplefilter("ignore")

import sys

if not sys.warnoptions:
    import os, warnings
    warnings.simplefilter("default") # Change the filter in this process
    os.environ["PYTHONWARNINGS"] = "default" # Also affect subprocesses

import warnings
warnings.filterwarnings("default", category=DeprecationWarning,
                                   module=user_ns.get("__name__"))

Временное подавление предупреждений

Если вы используете код, который, как известно, вызывает предупреждение, например устаревшую функцию, но не хотите видеть это предупреждение (даже если предупреждения явно сконфигурированы через командную строку), можно подавить предупреждение, используя менеджер контекста catch_warnings:

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    fxn()

Внутри менеджера контекста все предупреждения будут просто игнорироваться. Это позволяет вам использовать известный устаревший код, не видя предупреждение, не подавляя при этом предупреждения для других кодов, которые могут не знать о его использовании устаревшего кода. Примечание: это гарантировано только в однопоточных приложениях. Если два или более потока используют менеджер контекста catch_warnings одновременно, поведение не определено.

Предупреждения при тестировании

Для тестирования предупреждений, генерируемых кодом, используйте контекстный менеджер catch_warnings. С его помощью можно временно изменить фильтр предупреждений, чтобы упростить тестирование. Например, выполните следующее, чтобы захватить все генерируемые предупреждения для проверки:

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings(record=True) as w:
    # Cause all warnings to always be triggered.
    warnings.simplefilter("always")
    # Trigger a warning.
    fxn()
    # Verify some things
    assert len(w) == 1
    assert issubclass(w[-1].category, DeprecationWarning)
    assert "deprecated" in str(w[-1].message)

Также можно сделать так, чтобы все предупреждения стали исключениями, используя error вместо always. Следует учитывать, что если предупреждение уже было сгенерировано из-за правила once/default, то независимо от настроек фильтров предупреждение больше не будет отображаться, пока не будет очищен регистр предупреждений, связанный с этим предупреждением.

После выхода из контекстного менеджера фильтр предупреждений восстанавливается в состояние, в котором он был при входе в контекст. Это предотвращает изменение фильтров предупреждений тестами неожиданным образом между тестами, что может привести к неопределённым результатам тестов. Функция showwarning() модуля также восстанавливается до своего исходного значения. Примечание: это гарантируется только в однопоточном приложении. Если два или более потоков одновременно используют контекстный менеджер catch_warnings, поведение не определено.

При тестировании нескольких операций, генерирующих предупреждения одного типа, важно тестировать их таким образом, чтобы убедиться, что каждая операция генерирует новое предупреждение (например, установите предупреждения, чтобы они генерировались как исключения, и проверьте, что операции генерируют исключения, проверьте, что длина списка предупреждений продолжает увеличиваться после каждой операции, или же удалите предыдущие записи из списка предупреждений перед каждой новой операцией).

Обновление кода для новых версий зависимостей

Категории предупреждений, которые в первую очередь интересны разработчикам Python (а не конечным пользователям приложений, написанных на Python), по умолчанию игнорируются.

В частности, в этот список «игнорируемых по умолчанию» входит DeprecationWarning (для каждого модуля, кроме __main__), что означает, что разработчики должны убедиться в тестировании своего кода с обычно игнорируемыми предупреждениями, чтобы получать своевременные уведомления о будущих изменениях API, нарушающих совместимость (как в стандартной библиотеке, так и в пакетах сторонних разработчиков).

В идеальном случае код будет иметь подходящий набор тестов, и система выполнения тестов будет позаботиться о неявном включении всех предупреждений при выполнении тестов (система выполнения тестов, предоставляемая модулем unittest, делает это).

В менее идеальных случаях приложения могут проверяться на использование устаревших интерфейсов путём передачи параметра -Wd интерпретатору Python (это сокращение для -W default) или установки параметра PYTHONWARNINGS=default в среде. Это включает обработку по умолчанию для всех предупреждений, включая те, которые игнорируются по умолчанию. Чтобы изменить действия при возникновении предупреждений, можно изменить аргумент, передаваемый в -W (например, -W error). Подробнее о возможностях см. флаг -W.

Доступные функции

warnings.warn(message, category=None, stacklevel=1, source=None)

Выдать предупреждение, или возможно проигнорировать его или вызвать исключение. Аргумент category, если указан, должен быть классом категории предупреждений; по умолчанию он равен UserWarning. В качестве альтернативы, message может быть экземпляром Warning, в этом случае category будет проигнорирован, и будет использоваться message.__class__. В этом случае текст сообщения будет str(message). Эта функция вызывает исключение, если конкретное выдаваемое предупреждение изменяется на ошибку фильтром предупреждений warnings filter. Аргумент stacklevel может использоваться функциями-обёртками, написанными на Python, например:

def deprecation(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)

Это делает так, что предупреждение относится к вызывающей функции deprecation(), а не к источнику deprecation() самого (поскольку последнее бы лишило смысла сообщение о предупреждении).

source, если предоставлен, — это уничтоженный объект, который выдал ResourceWarning.

Изменено в версии 3.6: Добавлен параметр source.

warnings.warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)

Это низкоуровневый интерфейс к функциональности warn(), позволяющий явно указать сообщение, категорию, имя файла и номер строки, а также необязательно имя модуля и регистр (который должен быть словарем __warningregistry__ модуля). Имя модуля по умолчанию — имя файла без .py; если регистр не указан, предупреждение никогда не подавляется. message должен быть строкой, а category — подклассом Warning или message может быть экземпляром Warning, в этом случае category будет проигнорирован.

module_globals, если предоставлен, должен быть глобальным пространством имён, используемым кодом, для которого выводится предупреждение. (Этот аргумент используется для поддержки отображения исходного кода модулей, найденных в zip-файлах или других источниках импорта, не являющихся файловой системой).

source, если предоставлен, — это уничтоженный объект, который выдал ResourceWarning.

Изменено в версии 3.6: Добавлен параметр source.

warnings.showwarning(message, category, filename, lineno, file=None, line=None)

Записать предупреждение в файл. По умолчанию реализация вызывает formatwarning(message, category, filename, lineno, line) и записывает полученную строку в file, по умолчанию sys.stderr. Вы можете заменить эту функцию любым вызываемым объектом, присвоив значение warnings.showwarning. line — строка исходного кода, которая должна быть включена в сообщение о предупреждении; если line не указан, showwarning() попытается прочитать строку, указанную filename и lineno.

warnings.formatwarning(message, category, filename, lineno, line=None)

Форматировать предупреждение стандартным способом. Возвращает строку, которая может содержать встроенные переводы строк и заканчивается переводом строки. line — строка исходного кода, которая должна быть включена в сообщение о предупреждении; если line не указан, formatwarning() попытается прочитать строку, указанную filename и lineno.

warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)

Вставить запись в список спецификаций фильтра предупреждений warnings filter specifications. По умолчанию запись вставляется в начало; если append равно true, она вставляется в конец. Проверяет типы аргументов, компилирует регулярные выражения message и module и вставляет их как кортеж в список фильтров предупреждений. Записи, расположенные ближе к началу списка, переопределяют записи, расположенные позже в списке, если обе соответствуют определённому предупреждению. Пропущенные аргументы по умолчанию соответствуют всему.

warnings.simplefilter(action, category=Warning, lineno=0, append=False)

Вставить простую запись в список спецификаций фильтра предупреждений warnings filter specifications. Значение параметров функции аналогично параметрам filterwarnings(), но регулярные выражения не требуются, так как вставляемый фильтр всегда соответствует любому сообщению в любом модуле, если категория и номер строки совпадают.

warnings.resetwarnings()

Сбросить фильтр предупреждений. Это отбрасывает эффект всех предыдущих вызовов filterwarnings(), включая опции командной строки -W и вызовы simplefilter().

Доступные менеджеры контекста

class warnings.catch_warnings(*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)

Менеджер контекста, который копирует и, при выходе, восстанавливает фильтр предупреждений и функцию showwarning(). Если аргумент record имеет значение False (по умолчанию), менеджер контекста возвращает None при входе. Если record имеет значение True, возвращается список, который постепенно заполняется объектами, как их видит пользовательская функция showwarning() (которая также подавляет вывод в sys.stdout). Каждый объект в списке имеет атрибуты с теми же именами, что и аргументы функции showwarning().

Аргумент module принимает модуль, который будет использоваться вместо модуля, возвращаемого при импорте warnings, фильтр которого будет защищён. Этот аргумент существует в основном для тестирования самого модуля warnings.

Если аргумент action не None, оставшиеся аргументы передаются в функцию simplefilter(), как если бы она была вызвана сразу при входе в контекст.

Примечание

Менеджер catch_warnings работает путём замены и последующего восстановления функции модуля showwarning() и внутреннего списка спецификаций фильтра. Это означает, что менеджер контекста изменяет глобальное состояние, и поэтому не является потокобезопасным.

Изменено в версии 3.11: Добавлены параметры action, category, lineno и append.