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

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

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

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

Пользовательский код может определить дополнительные категории предупреждений, наследуя одну из стандартных категорий предупреждений. Категория предупреждений всегда должна быть подклассом класса 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, *, skip_file_prefixes=())

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

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

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

Ключевой аргумент skip_file_prefixes может использоваться для указания, какие кадровые кадры игнорируются при подсчёте уровней стека. Это может быть полезно, когда вы хотите, чтобы предупреждение всегда появлялось в местах вызова вне пакета, когда постоянный stacklevel не подходит для всех путей вызова или иначе сложно поддерживать. Если он предоставлен, он должен быть кортежем строк. При предоставлении префиксов, stacklevel неявно переопределяется в max(2, stacklevel). Чтобы вызвать предупреждение, которое будет приписываться вызывающей функции извне текущего пакета, вы можете написать:

# example/lower.py
_warn_skips = (os.path.dirname(__file__),)

def one_way(r_luxury_yacht=None, t_wobbler_mangrove=None):
    if r_luxury_yacht:
        warnings.warn("Please migrate to t_wobbler_mangrove=.",
                      skip_file_prefixes=_warn_skips)

# example/higher.py
from . import lower

def another_way(**kw):
    lower.one_way(**kw)

Это заставляет предупреждение относиться как к example.lower.one_way() , так и к package.higher.another_way() местам вызова, только для вызывающего кода, находящегося вне пакета example.

source, если задан, является уничтоженным объектом, который выдал ResourceWarning.

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

Изменено в версии 3.12: Добавлен skip_file_prefixes.

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().

@warnings.deprecated(msg, *, category=DeprecationWarning, stacklevel=1)

Декоратор, указывающий, что класс, функция или перегрузка устарели.

При применении этого декоратора к объекту, во время выполнения могут быть выведены предупреждения об устарелости при использовании объекта. Статические анализаторы типов также будут генерировать диагностику при использовании устаревшего объекта.

Использование:

from warnings import deprecated
from typing import overload

@deprecated("Use B instead")
class A:
    pass

@deprecated("Use g instead")
def f():
    pass

@overload
@deprecated("int support is deprecated")
def g(x: int) -> int: ...
@overload
def g(x: str) -> int: ...

Определённое предупреждение, указанное в category, будет выведено при использовании устаревших объектов во время выполнения. Для функций, это происходит при вызовах; для классов — при создании экземпляров и создании подклассов. Если category это None, предупреждение не выводится во время выполнения. stacklevel определяет, где выводится предупреждение. Если это 1 (по умолчанию), предупреждение выводится в вызывающей функции устаревшего объекта; если значение выше, оно выводится дальше вверх по стеку. Поведение статического анализатора типов не зависит от аргументов category и stacklevel.

Сообщение об устарелости, переданное декоратору, сохраняется в атрибуте __deprecated__ на декорируемом объекте. При применении к перегрузке, декоратор должен быть после декоратора @overload для того, чтобы атрибут существовал на перегрузке, возвращаемой typing.get_overloads().

Добавлен в версии 3.13: См. PEP 702.

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

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(), как если бы он был вызван немедленно при входе в контекст.

См. Фильтр предупреждений для значения параметров category и lineno.

Примечание

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

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