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

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

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

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

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

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

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

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

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

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

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

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

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

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

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, делает именно это).

В менее идеальных случаях приложения можно проверить на использование устаревших интерфейсов, передав интерпретатору Python параметр -Wd (это сокращённая запись для -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().

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

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.