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

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

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

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

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

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

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

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

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

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

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

• сообщение — строка, содержащая регулярное выражение, которому должно соответствовать начало сообщения о предупреждении. Выражение компилируется таким образом, чтобы игнорировать регистр.
• категория — класс (подкласс класса Warning), подклассом которого должна быть категория предупреждения для соответствия.
• модуль — строка, содержащая регулярное выражение, которому должно соответствовать имя модуля. Выражение компилируется таким образом, чтобы учитывать регистр.
• номер_строки — целое число, которому должен соответствовать номер строки, где произошло предупреждение, или 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"
                             # and any subpackages of "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). Эта функция вызывает исключение, если конкретное выданное предупреждение преобразуется в ошибку фильтром предупреждений фильтром предупреждений. Аргумент 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)

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

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

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

warnings.resetwarnings()

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

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

class warnings.catch_warnings(*, record=False, module=None)

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

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

Примечание

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