warnings – Управление предупреждениями¶warnings – Warning control

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

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

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

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

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

Фильтр предупреждений¶The Warnings Filter

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

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

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

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

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

• category – это класс (подкласс Warning), подклассом которого должна быть категория предупреждения для совпадения.

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

• lineno – это целое число, которому должен соответствовать номер строки, где произошло предупреждение, или 0 для соответствия всем номерам строк.

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

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

action:message:category:module:line

default                      # Показывать все предупреждения (даже те, что игнорируются по умолчанию)
ignore                       # Игнорировать все предупреждения
error                        # Преобразовать все предупреждения в ошибки
error::ResourceWarning       # Обрабатывать сообщения ResourceWarning как ошибки
default::DeprecationWarning  # Показывать сообщения DeprecationWarning
ignore,default:::mymodule    # Сообщать только о предупреждениях, вызванных "mymodule"
error:::mymodule             # Преобразовывать предупреждения в ошибки в "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") # Изменить фильтр в этом процессе
    os.environ["PYTHONWARNINGS"] = "default" # Также действовать на подпроцессы

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

Временное подавление предупреждений¶Temporarily Suppressing Warnings

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

import warnings

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

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

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

Примечание

См. Безопасность контекстных менеджеров при параллельном выполнении для подробной информации о безопасности при параллельном выполнении контекстного менеджера catch_warnings при использовании в программах с несколькими потоками или асинхронными функциями.

Тестирование предупреждений¶Testing Warnings

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

import warnings

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

with warnings.catch_warnings(record=True) as w:
    # Привести к тому, что все предупреждения всегда будут срабатывать.
    warnings.simplefilter("always")
    # Вызвать предупреждение.
    fxn()
    # Проверить некоторые вещи
    assert len(w) == 1
    assert issubclass(w[-1].category, DeprecationWarning)
    assert "deprecated" in str(w[-1].message)

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

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

Примечание

См. Безопасность контекстных менеджеров при параллельном выполнении для подробной информации о безопасности при параллельном выполнении контекстного менеджера catch_warnings при использовании в программах с несколькими потоками или асинхронными функциями.

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

Обновление кода для новых версий зависимостей¶Updating Code For New Versions of Dependencies

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

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

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

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

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

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(), так и example.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(), который явно принимает сообщение, категорию, имя файла и номер строки, а также опционально другие аргументы. message должен быть строкой, а category – подклассом Warning, или message может быть экземпляром Warning, и в этом случае category игнорируется.

module, если указан, должен быть именем модуля. Если модуль не передан, используется имя файла с удалённым .py.

registry, если указан, должен быть словарём __warningregistry__ модуля. Если реестр не передан, каждое предупреждение рассматривается как первое появление, то есть действия фильтра "default", "module" и "once" обрабатываются как "always".

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 равен истине, она вставляется в конец. Эта функция проверяет типы аргументов, компилирует регулярные выражения 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__ декорированного объекта. Если применяется к перегрузке, декоратор должен располагаться после декоратора @~typing.overload, чтобы атрибут существовал в перегрузке, возвращаемой typing.get_overloads().

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

Доступные контекстные менеджеры¶Available Context Managers

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

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

• message: сообщение предупреждения (экземпляр Warning)

• category: категория предупреждения (подкласс Warning)

• filename: имя файла, где произошло предупреждение (str)

• lineno: номер строки в файле (int)

• file: файловый объект, используемый для вывода (если есть), или None

• line: строка исходного кода (если доступна), или None

• source: исходный объект, который сгенерировал предупреждение (если доступен), или None

Изменено в версии 3.6: Был добавлен атрибут source.

Тип этих объектов не определён и может измениться; гарантируется только наличие этих атрибутов.

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

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

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

Примечание

Смотрите Безопасность менеджеров контекста при параллельном выполнении для подробностей о потокобезопасности менеджера контекста catch_warnings при использовании в программах с несколькими потоками или асинхронными функциями.

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

Безопасность менеджеров контекста при параллельном выполнении¶Concurrent safety of Context Managers

Поведение менеджера контекста catch_warnings зависит от флага sys.flags.context_aware_warnings. Если флаг истинен, менеджер контекста ведет себя безопасно при параллельном выполнении, в противном случае – нет. Безопасность при параллельном выполнении означает, что он одновременно потокобезопасен и безопасен для использования внутри корутин asyncio и задач. Потокобезопасность означает, что поведение предсказуемо в многопоточной программе. По умолчанию флаг имеет значение true для free-threaded сборок и false в остальных случаях.

Если флаг context_aware_warnings ложен, то catch_warnings изменяет глобальные атрибуты модуля warnings. Это небезопасно при использовании в параллельной программе (с несколькими потоками или корутинами asyncio). Например, если два или более потоков одновременно используют класс catch_warnings, поведение становится неопределённым.

Если флаг истинен, catch_warnings не изменяет глобальные атрибуты, а вместо этого использует ContextVar для хранения только что установленного состояния фильтрации предупреждений. Переменная контекста обеспечивает локальное хранилище для потока и делает использование catch_warnings потокобезопасным.

Параметр record контекстного обработчика также ведёт себя по-разному в зависимости от значения флага. Когда record истинен, а флаг ложен, менеджер контекста работает путём замены, а затем восстановления функции showwarning() модуля. Это небезопасно при параллельном выполнении.

Когда record истинен и флаг истинен, функция showwarning() не заменяется. Вместо этого статус записи указывается внутренним свойством в переменной контекста. В этом случае функция showwarning() не будет восстановлена при выходе из контекстного обработчика.

Флаг context_aware_warnings можно установить с помощью параметра командной строки -X context_aware_warnings или переменной окружения PYTHON_CONTEXT_AWARE_WARNINGS.

Примечание

Вероятно, большинство программ, которым требуется потокобезопасное поведение модуля warnings, также захотят установить флаг thread_inherit_context в true. Этот флаг заставляет потоки, созданные с помощью threading.Thread, запускаться с копией переменных контекста из потока, который их запускает. Если true, контекст, установленный catch_warnings в одном потоке, также будет применяться к новым потокам, запущенным из него. Если false, новые потоки запускаются с пустой переменной контекста предупреждений, что означает, что любая фильтрация, установленная менеджером контекста catch_warnings, больше не будет активна.