logging — Система ведения журнала для Python

Исходный код: Lib/logging/__init__.py

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

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

Вот простой пример типичного использования:

# myapp.py
import logging
import mylib
logger = logging.getLogger(__name__)

def main():
    logging.basicConfig(filename='myapp.log', level=logging.INFO)
    logger.info('Started')
    mylib.do_something()
    logger.info('Finished')

if __name__ == '__main__':
    main()

# mylib.py
import logging
logger = logging.getLogger(__name__)

def do_something():
    logger.info('Doing something')

Если вы запустите myapp.py, вы увидите это в myapp.log:

INFO:__main__:Started
INFO:mylib:Doing something
INFO:__main__:Finished

Ключевой особенностью этого типичного использования является то, что большая часть кода просто создает логгер уровня модуля с getLogger(__name__), и использует этот логгер для выполнения всех необходимых операций ведения журнала. Это лаконично, при этом позволяя коду ниже по иерархии тонкую настройку при необходимости. Сообщения, записанные в логгер уровня модуля, передаются обработчикам логгеров в модулях более высокого уровня, вплоть до логгера самого высокого уровня, известного как корневой логгер; этот подход известен как иерархическое ведение журнала.

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

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

Основные классы, определенные модулем, вместе с их атрибутами и методами, перечислены в разделах ниже.

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

Объекты логгеров

Логгеры имеют следующие атрибуты и методы. Обратите внимание, что логгеры никогда не должны создаваться напрямую, а всегда через функцию модульного уровня logging.getLogger(name). Несколько вызовов getLogger() с одинаковым именем всегда будут возвращать ссылку на один и тот же объект логгера.

name потенциально является значением иерархической структуры, разделённой точками, например foo.bar.baz (хотя оно также может быть просто foo, например). Логгеры, которые находятся дальше в иерархическом списке, являются дочерними по отношению к логгерам, расположенным выше в списке. Например, если есть логгер с именем foo, логгеры с именами foo.bar, foo.bar.baz, и foo.bam являются потомками foo. Кроме того, все логгеры являются потомками корневого логгера. Иерархия имён логгеров аналогична иерархии пакетов Python и идентична ей, если вы организуете свои логгеры на основе модулей, используя рекомендуемую конструкцию logging.getLogger(__name__). Это связано с тем, что в модуле __name__ — это имя модуля в пространстве имён пакета Python.

class logging.Logger

name: Это имя логгера и значение, которое было передано в getLogger() для получения логгера.

Примечание

К этому атрибуту следует относиться как к только для чтения.

level: Пороговое значение этого логгера, установленное методом setLevel().

Примечание

Не устанавливайте этот атрибут напрямую — всегда используйте setLevel(), который проверяет уровень, передаваемый ему.

parent: Родительский логгер этого логгера. Он может изменяться в зависимости от последующего создания логгеров, которые находятся выше в иерархии пространства имён.

Примечание

Это значение следует рассматривать как только для чтения.

propagate

Если этот атрибут равен true, события, записанные в этот логгер, будут переданы обработчикам логгеров более высокого уровня (предкам), помимо любых обработчиков, присоединённых к этому логгеру. Сообщения передаются непосредственно обработчикам логгеров предков — не учитываются ни уровень, ни фильтры предков.

Если этот атрибут равен false, сообщения об ошибках не передаются обработчикам предковых логгеров.

Пример: Если атрибут propagate логгера с именем A.B.C равен true, любое событие, записанное в A.B.C с помощью вызова метода, например, logging.getLogger('A.B.C').error(...), будет [при условии, что оно пройдёт проверку уровня и фильтров логгера] передано в свою очередь любым обработчикам, присоединённым к логгерам с именами A.B, A и корневому логгеру, после чего оно будет передано любым обработчикам, присоединённым к A.B.C . Если любой логгер в цепочке A.B.C, A.B, A имеет свой атрибут propagate установлен в false, то это последний логгер, чей обработчик получит событие для обработки, и распространение прекращается на этом этапе.

Конструктор устанавливает этот атрибут в True.

Примечание

Если вы присоединяете обработчик к логгеру и одному или нескольким его предкам, он может выводить одну и ту же запись несколько раз. Как правило, вам не нужно присоединять обработчик к более чем одному логгеру — если вы присоедините его только к соответствующему логгеру, который находится выше в иерархии логгеров, он получит все события, записанные всеми дочерними логгерами при условии, что их атрибут propagate оставлен равным True . Общий сценарий заключается в присоединении обработчиков только к корневому логгеру и делегировании распространения остальным логгерам.

handlers: Список обработчиков, непосредственно присоединённых к экземпляру этого логгера.

Примечание

К этому атрибуту следует относиться как к только для чтения; он обычно изменяется с помощью методов addHandler() и removeHandler(), которые используют блокировки для обеспечения потокобезопасности.

disabled: Этот атрибут отключает обработку любых событий. Он устанавливается в False в инициализаторе и изменяется только кодом конфигурации логгирования.

Примечание

К этому атрибуту следует относиться как к только для чтения.

setLevel(level)

Устанавливает порог для этого логгера в level. Сообщения об ошибках, которые менее серьезны, чем level, будут игнорироваться; сообщения об ошибках, у которых уровень серьезности level или выше, будут выводиться любым обработчиком, обслуживающим этот логгер, если уровень обработки не установлен выше, чем level.

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

Термин «делегирование родительскому» означает, что если у логгера установлен уровень NOTSET, иерархия предковых логгеров просматривается до тех пор, пока не будет найден предок с уровнем, отличным от NOTSET, или пока не будет достигнут корень.

Если найден предок с уровнем, отличным от NOTSET, уровень этого предка рассматривается как эффективный уровень логгера, с которого начался поиск предка, и используется для определения того, как обрабатывается событие логгирования.

Если достигнут корень, и у него установлен уровень NOTSET, все сообщения будут обработаны. В противном случае будет использован уровень корневого логгера.

См. Уровни логгирования для списка уровней.

Изменено в версии 3.2: Параметр level теперь принимает строковое представление уровня, например «INFO», в качестве альтернативы целочисленным константам, например INFO. Однако следует отметить, что уровни хранятся в виде целых чисел, и методы, такие как, например, getEffectiveLevel() и isEnabledFor(), будут возвращать/ожидать целые числа.

isEnabledFor(level): Указывает, будет ли сообщение уровня level обработано этим логгером. Этот метод сначала проверяет уровень модуля, установленный logging.disable(level), а затем эффективный уровень логгера, определённый методом getEffectiveLevel().

getEffectiveLevel(): Указывает эффективный уровень для этого логгера. Если значение, отличное от NOTSET, было установлено с помощью setLevel(), оно возвращается. В противном случае иерархия просматривается в сторону корня, пока не будет найдено значение, отличное от NOTSET, и это значение возвращается. Возвращаемое значение — целое число, обычно одно из logging.DEBUG, logging.INFO и т. д.

getChild(suffix): Возвращает логгер, являющийся потомком этого логгера, как определяется суффиксом. Таким образом, logging.getLogger('abc').getChild('def.ghi') вернёт тот же логгер, что и logging.getLogger('abc.def.ghi'). Это удобный метод, полезный, когда имя родительского логгера задаётся, например, __name__ вместо строковой константы.

Добавлен в версии 3.2.

getChildren(): Возвращает множество логгеров, которые являются непосредственными дочерними элементами этого логгера. Например, logging.getLogger().getChildren() может вернуть множество, содержащее логгеры с именами foo и bar, но логгер с именем foo.bar не будет включён в множество. Аналогично, logging.getLogger('foo').getChildren() может вернуть множество, включающее логгер с именем foo.bar, но не включающее логгер с именем foo.bar.baz.

Добавлен в версии 3.12.

END_OF_DOCUMENT_MARKER

debug(msg, *args, **kwargs)

Записывает сообщение с уровнем DEBUG в этот логгер. Строка msg — это формат сообщения, а args — аргументы, которые подставляются в msg с помощью оператора форматирования строк. (Обратите внимание, что это означает, что вы можете использовать ключевые слова в строке формата вместе с единственным аргументом словаря.) Операция форматирования % над msg не выполняется, если args не заданы.

В kwargs проверяются четыре ключевых аргумента: exc_info, stack_info, stacklevel и extra.

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

Второй необязательный ключевой аргумент — stack_info, по умолчанию False. Если он имеет значение истина, в сообщение об ошибке добавляется информация о стеке вызовов, включая сам вызов логгирования. Обратите внимание, что эта информация о стеке отличается от информации, отображаемой при указании exc_info: первая представляет собой кадры стека снизу до вызова логгирования в текущем потоке, а вторая — информацию о кадрах стека, которые были развёрнуты после возникновения исключения при поиске обработчиков исключений.

Вы можете указать stack_info независимо от exc_info, например, чтобы просто показать, как вы попали в определённую точку кода, даже если исключения не возникло. Кадры стека выводятся после заголовка, который гласит:

Stack (most recent call last):

Это имитирует Traceback (most recent call last): используемое при отображении кадров стека исключений.

Третий необязательный ключевой аргумент — stacklevel, по умолчанию 1. Если он больше 1, пропускается соответствующее количество кадров стека при вычислении номера строки и имени функции, заданных в LogRecord, созданном для события логгирования. Это можно использовать в вспомогательных функциях логгирования, чтобы имя функции, имя файла и номер строки, записанные, не были информацией для вспомогательной функции/метода, а скорее для её вызывающей функции. Название этого параметра соответствует аналогичному параметру в модуле warnings.

Четвёртый ключевой аргумент — extra, который может быть использован для передачи словаря, используемого для заполнения __dict__ объекта LogRecord, созданного для события логгирования, пользовательскими атрибутами. Эти пользовательские атрибуты затем могут быть использованы по вашему усмотрению. Например, они могут быть включены в записанные сообщения. Например:

FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)

будет выводить что-то вроде

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

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

Если вы решите использовать эти атрибуты в записанных сообщениях, вам нужно проявить осторожность. Например, в приведенном выше примере Formatter настроен с строкой формата, которая ожидает ‘clientip’ и ‘user’ в словаре атрибутов LogRecord. Если их нет, сообщение не будет записано, потому что произойдёт исключение при форматировании строки. Таким образом, в данном случае вам всегда необходимо передать словарь extra с этими ключами.

Хотя это может быть немного неудобно, эта функция предназначена для использования в специальных случаях, таких как многопотоковые серверы, где один и тот же код выполняется во многих контекстах, и интересные условия зависят от этого контекста (например, IP-адрес удалённого клиента и имя аутентифицированного пользователя в приведённом выше примере). В таких ситуациях, скорее всего, будут использоваться специализированные Formatter с конкретными Handler.

Если к этому логгеру (или любому из его предков, с учётом соответствующих атрибутов Logger.propagate) не прикреплён ни один обработчик, сообщение будет отправлено обработчику, заданному в lastResort.

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

Изменено в версии 3.5: Параметр exc_info теперь может принимать экземпляры исключений.

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

info(msg, *args, **kwargs): Записывает сообщение с уровнем INFO в этот логгер. Аргументы интерпретируются так же, как для debug().

warning(msg, *args, **kwargs): Записывает сообщение с уровнем WARNING в этот логгер. Аргументы интерпретируются так же, как для debug().

Примечание

Существует устаревший метод warn который функционально идентичен warning. Так как warn устарел, не используйте его — используйте warning вместо этого.

error(msg, *args, **kwargs): Записывает сообщение с уровнем ERROR в этот логгер. Аргументы интерпретируются так же, как для debug().

critical(msg, *args, **kwargs): Записывает сообщение с уровнем CRITICAL в этот логгер. Аргументы интерпретируются так же, как для debug().

log(level, msg, *args, **kwargs): Записывает сообщение с целым уровнем level в этот логгер. Остальные аргументы интерпретируются так же, как для debug().

exception(msg, *args, **kwargs): Записывает сообщение с уровнем ERROR в этот логгер. Аргументы интерпретируются так же, как для debug(). Информация об исключении добавляется в сообщение о логгировании. Этот метод должен вызываться только из обработчика исключений.

addFilter(filter): Добавляет указанный фильтр filter в этот логгер.

removeFilter(filter): Удаляет указанный фильтр filter из этого логгера.

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

addHandler(hdlr): Добавляет указанный обработчик hdlr в этот логгер.

removeHandler(hdlr): Удаляет указанный обработчик hdlr из этого логгера.

findCaller(stack_info=False, stacklevel=1)

Находит имя файла и номер строки вызывающего кода. Возвращает имя файла, номер строки, имя функции и информацию о стеке в виде 4-элементного кортежа. Информация о стеке возвращается как None , если stack_info не True.

Параметр stacklevel передаётся из кода, вызывающего debug() и других API. Если он больше 1, избыток используется для пропуска кадров стека перед определением значений, которые должны быть возвращены. Это обычно полезно при вызове API логгирования из вспомогательного/оберточного кода, чтобы информация в журнале событий относилась не к вспомогательному/оберточному коду, а к коду, который его вызывает.

handle(record): Обрабатывает запись, передавая её всем обработчикам, связанным с этим логгером и его предками (до тех пор, пока не будет найдено ложное значение propagate). Этот метод используется для распакованных записей, полученных из сокета, а также для записей, созданных локально. Фильтрация на уровне логгера выполняется с помощью filter().

END_OF_DOCUMENT_MARKER

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None): Этот фабричный метод можно переопределить в подклассах для создания специализированных экземпляров LogRecord.

hasHandlers(): Проверяет, есть ли у этого логгера какие-либо обработчики. Это делается путём поиска обработчиков в этом логгере и его родительских логгерах в иерархии логгеров. Возвращает True, если обработчик был найден, иначе False. Метод прекращает поиск по иерархии, когда обнаруживает логгер с атрибутом ‘propagate’, установленным в значение false — это последний логгер, в котором проверяется наличие обработчиков.

Добавлен в версии 3.2.

Изменено в версии 3.7: Теперь логгеры можно сериализовать и десериализовать.

Уровни ведения журнала

Числовые значения уровней ведения журнала приведены в следующей таблице. Они в первую очередь интересны, если вы хотите определить свои собственные уровни и им нужно задать конкретные значения относительно предопределённых уровней. Если вы определите уровень с тем же числовым значением, он перезаписывает предопределённое значение; предопределённое имя теряется.

Уровень	Числовое значение	Что это значит / Когда его использовать
`logging.NOTSET`	0	При установке для логгера указывает, что следует обратиться к родительским логгерам, чтобы определить эффективный уровень. Если это всё равно приводит к `NOTSET`, то все события регистрируются. При установке для обработчика все события обрабатываются.
`logging.DEBUG`	10	Подробная информация, как правило, интересна только разработчику, пытающемуся диагностировать проблему.
`logging.INFO`	20	Подтверждение того, что всё работает как ожидается.
`logging.WARNING`	30	Указание на то, что произошло что-то неожиданное, или что проблема может возникнуть в ближайшем будущем (например, «низкий объём диска»). Программное обеспечение всё ещё работает как ожидается.
`logging.ERROR`	40	Из-за более серьёзной проблемы программное обеспечение не смогло выполнить некоторую функцию.
`logging.CRITICAL`	50	Серьёзная ошибка, указывающая на то, что программа, возможно, не сможет продолжить работу.

END_OF_DOCUMENT_MARKER

Объекты обработчиков

Обработчики имеют следующие атрибуты и методы. Обратите внимание, что Handler никогда не создаётся напрямую; этот класс служит базой для более полезных подклассов. Однако метод __init__() в подклассах должен вызывать Handler.__init__().

class logging.Handler

__init__(level=NOTSET): Инициализирует экземпляр Handler, устанавливая его уровень, устанавливая список фильтров в пустой список и создавая блокировку (используя createLock()) для сериализации доступа к механизму ввода-вывода.

createLock(): Инициализирует блокировку потока, которая может использоваться для сериализации доступа к базовой функциональности ввода-вывода, которая может не быть потокобезопасной.

acquire(): Получает блокировку потока, созданную с помощью createLock().

release(): Освобождает блокировку потока, полученную с помощью acquire().

setLevel(level)

Устанавливает порог для этого обработчика на level. Сообщения протоколирования, которые менее серьёзны, чем level, будут проигнорированы. При создании обработчика уровень устанавливается на NOTSET (что приводит к обработке всех сообщений).

Список уровней см. в Уровни протоколирования.

Изменено в версии 3.2: Параметр level теперь принимает строковое представление уровня, например, ‘INFO’, как альтернативу целочисленным константам, таким как INFO.

setFormatter(fmt): Устанавливает Formatter для этого обработчика на fmt.

addFilter(filter): Добавляет указанный фильтр filter к этому обработчику.

removeFilter(filter): Удаляет указанный фильтр filter из этого обработчика.

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

flush(): Обеспечивает, чтобы весь выходной протокол был сброшен. Этот вариант ничего не делает и предназначен для реализации подклассами.

close(): Убирает все используемые обработчиком ресурсы. Этот вариант не производит вывод, но удаляет обработчик из внутреннего списка обработчиков, который закрывается при вызове shutdown(). Подклассы должны гарантировать, что этот вызов происходит из переопределённых методов close().

handle(record): Условно отправляет указанную запись протоколирования, в зависимости от фильтров, которые могут быть добавлены в обработчик. Оборачивает фактический вывод записи с получением/освобождением блокировки потока ввода-вывода.

handleError(record): Этот метод должен вызываться от обработчиков при возникновении исключения во время вызова emit(). Если модульный атрибут raiseExceptions равен False, исключения игнорируются молча. Это то, что в основном нужно для системы протоколирования – большинство пользователей не будут заботиться об ошибках в системе протоколирования, их больше интересуют ошибки приложения. Однако вы можете заменить это пользовательским обработчиком, если хотите. Указанная запись — это та, которая обрабатывалась при возникновении исключения. (Значение по умолчанию для raiseExceptions равно True, так как это более полезно во время разработки).

format(record): Выполняет форматирование записи — если установлено форматирование, используйте его. В противном случае используйте форматирование по умолчанию для модуля.

emit(record)

Выполните необходимые действия для фактического протоколирования указанной записи протоколирования. Эта версия предназначена для реализации подклассами и поэтому вызывает NotImplementedError.

Предупреждение

Этот метод вызывается после получения блокировки на уровне обработчика, которая освобождается после возвращения этого метода. При переопределении этого метода будьте осторожны при вызове чего-либо, что вызывает другие части API протоколирования, которые могут производить блокировку, так как это может привести к тупику. В частности:

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

Список стандартных обработчиков см. в logging.handlers.

Объекты форматирования

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Отвечает за преобразование LogRecord в строку вывода, предназначенную для интерпретации человеком или внешней системой.

Параметры:

fmt (str) – Строка формата в заданном стиле для всего выводимого лог-сообщения. Возможные ключи сопоставления взяты из объекта LogRecord атрибутов записей логов. Если не указано, используется '%(message)s', представляющая собой просто само записанное сообщение.
datefmt (str) – Строка формата в заданном стиле для части даты/времени в лог-выводе. Если не указано, используется значение по умолчанию, описанное в formatTime().
style (str) – Может быть одним из '%', '{' или '$' и определяет, как строка формата будет объединена с данными: используя один из форматирования строк в стиле printf (%), str.format() ({) или string.Template ($). Это относится только к fmt и datefmt (например, '%(message)s' против '{message}'), а не к самим лог-сообщениям, переданным в методы логирования. Однако есть другие способы использования {- и $-форматирования для лог-сообщений.
validate (bool) – Если True (значение по умолчанию), неверный или несоответствующий fmt и style приведет к ошибке ValueError; например, logging.Formatter('%(asctime)s - %(message)s', style='{').
defaults (dict[str, Any]) – Словарь с значениями по умолчанию, используемыми в пользовательских полях. Например, logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})

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

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

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

format(record)

Словарь атрибутов записи используется как операнд в операции форматирования строк. Возвращает результирующую строку. Перед форматированием словаря выполняется несколько подготовительных шагов. Атрибут message записи вычисляется с помощью msg % args. Если строка форматирования содержит '(asctime)', вызывается formatTime() для форматирования времени события. Если есть информация об исключении, она форматируется с помощью formatException() и добавляется к сообщению. Обратите внимание, что отформатированная информация об исключении кэшируется в атрибуте exc_text. Это полезно, так как информацию об исключении можно сериализовать и передать по каналу связи, но нужно быть осторожным, если у вас более одного подкласса Formatter, который настраивает форматирование информации об исключении. В этом случае вам нужно очистить кэшированное значение (установив атрибут exc_text в None) после того, как форматировщик выполнил форматирование, чтобы следующий форматировщик, обрабатывающий событие, не использовал кэшированное значение, а вычислил его заново.

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

formatTime(record, datefmt=None)

Этот метод должен вызываться из format() форматировщиком, который хочет использовать отформатированное время. Этот метод может быть переопределен в форматировщиках для удовлетворения любых специфических требований, но основное поведение следующее: если datefmt (строка) указано, оно используется с time.strftime() для форматирования времени создания записи. В противном случае используется формат ‘%Y-%m-%d %H:%M:%S,uuu’, где uuu – значение миллисекунд, а остальные буквы соответствуют документации time.strftime(). Пример времени в этом формате: 2003-01-23 00:29:50,411. Возвращается полученная строка.

Эта функция использует настраиваемую пользователем функцию для преобразования времени создания в кортеж. По умолчанию используется time.localtime(); чтобы изменить это для конкретного экземпляра форматировщика, установите атрибут converter в функцию с тем же сигнатурным описанием, что у time.localtime() или time.gmtime(). Чтобы изменить его для всех форматировщиков, например, если вы хотите, чтобы все времена в журналах отображались по Гринвичу, установите атрибут converter в классе Formatter.

Изменено в версии 3.3: Ранее формат по умолчанию был жестко задан, как в этом примере: 2010-09-06 22:38:15,292 где часть до запятой обрабатывается строкой формата strptime ('%Y-%m-%d %H:%M:%S'), а часть после запятой – значение миллисекунд. Так как strptime не имеет места для замены миллисекунд в формате, значение миллисекунд добавляется с помощью другой строки формата '%s,%03d' — обе эти строки формата были жестко закодированы в этом методе. С изменением эти строки определяются как атрибуты класса, которые могут быть переопределены на уровне экземпляра при необходимости. Названия атрибутов: default_time_format (для строки формата strptime) и default_msec_format (для добавления значения миллисекунд).

Изменено в версии 3.9: Значение default_msec_format может быть None.

formatException(exc_info): Форматирует указанную информацию об исключении (стандартный кортеж исключения, возвращаемый sys.exc_info()) в виде строки. Эта реализация по умолчанию просто использует traceback.print_exception(). Возвращается результирующая строка.

formatStack(stack_info): Форматирует указанную информацию о стеке вызовов (строка, возвращаемая traceback.print_stack(), но с удаленной последней новой строкой) в виде строки. Эта реализация по умолчанию просто возвращает входное значение.

class logging.BufferingFormatter(linefmt=None)

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

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

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

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

Объекты фильтрации

Filters могут использоваться Handlers и Loggers для более сложной фильтрации, чем обеспечивается уровнями. Базовый класс фильтра позволяет только событиям, которые находятся ниже определённого уровня в иерархии регистратора. Например, фильтр, инициализированный «A.B», позволит событиям, зарегистрированным регистраторами «A.B», «A.B.C», «A.B.C.D», «A.B.D» и т. д., но не «A.BB», «B.A.B» и т. д. Если инициализирован с пустой строкой, все события пропускаются.

class logging.Filter(name='')

Возвращает экземпляр класса Filter. Если указано name, это имя регистратора, который вместе со своими дочерними элементами будет пропускать свои события через фильтр. Если name пустая строка, пропускает все события.

filter(record): Требуется ли указанная запись для регистрации? Возвращает false для нет, true для да. Фильтры могут либо изменять записи журналов на месте, либо возвращать совершенно другой экземпляр записи, который заменит исходную запись журнала в любом последующем обработке события.

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

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

Изменено в версии 3.2: Вам не нужно создавать специализированные Filter классы или использовать другие классы с методом filter. Вы можете использовать функцию (или другой вызываемый объект) в качестве фильтра. Логика фильтрации проверит, есть ли у объекта фильтра атрибут filter: если он есть, предполагается, что это Filter и вызывается его метод filter(). В противном случае предполагается, что это вызываемый объект, и он вызывается с записью в качестве единственного параметра. Возвращаемое значение должно соответствовать возвращаемому значению filter().

Изменено в версии 3.12: Теперь вы можете возвращать экземпляр LogRecord из фильтров для замены записи журнала вместо изменения её на месте. Это позволяет фильтрам, прикреплённым к Handler, изменять запись журнала до её вывода без побочных эффектов на другие обработчики.

Хотя фильтры используются в основном для фильтрации записей на основе более сложных критериев, чем уровни, они видят каждую запись, обрабатываемую обработчиком или регистратором, к которому они прикреплены: это может быть полезно, если вы хотите, например, подсчитать количество записей, обработанных конкретным регистратором или обработчиком, или добавить, изменить или удалить атрибуты в LogRecord, которые обрабатываются. Очевидно, изменение записи журнала требует осторожности, но это позволяет вводить контекстную информацию в журналы (см. Использование фильтров для передачи контекстной информации).

Объекты записей журнала

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

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)

Содержит всю информацию, относящуюся к регистрируемому событию.

Основная информация передаётся в msg и args, которые объединяются с помощью msg % args для создания атрибута message записи.

Параметры:

name (str) – Имя регистратора, используемого для регистрации события, представленного этим LogRecord. Обратите внимание, что имя регистратора в LogRecord всегда будет иметь это значение, даже если оно может быть выпущено обработчиком, прикреплённым к другому (предковому) регистратору.
level (int) – Числовой уровень события регистрации (например, 10 для DEBUG, 20 для INFO и т. д.). Обратите внимание, что это преобразуется в *два* атрибута записи журнала: levelno для числового значения и levelname для соответствующего имени уровня.
pathname (str) – Полный путь к исходному файлу, в котором был сделан вызов регистрации.
lineno (int) – Номер строки в исходном файле, где был сделан вызов регистрации.
msg (Any) – Сообщение с описанием события, которое может быть строкой с %-форматированием для заменителей данных переменных или произвольным объектом (см. Использование произвольных объектов в качестве сообщений).
args (tuple | dict[str, Any]) – Данные переменных для объединения с аргументом msg, чтобы получить описание события.
exc_info (tuple[type[BaseException], BaseException, types.TracebackType] | None) – Кортеж исключений с текущей информацией об исключении, возвращаемый sys.exc_info(), или None если информация об исключении недоступна.
func (str | None) – Имя функции или метода, из которого был вызван вызов регистрации.
sinfo (str | None) – Строка текста, представляющая информацию о стеке из основания стека в текущем потоке до вызова регистрации.

getMessage(): Возвращает сообщение для этого экземпляра LogRecord после объединения любых предоставленных пользователем аргументов с сообщением. Если аргумент сообщения, предоставленный пользователем для вызова регистрации, не является строкой, на него вызывается str() для преобразования его в строку. Это позволяет использовать пользовательские классы в качестве сообщений, чьи метод __str__ может вернуть фактическую строку форматирования, которая должна использоваться.

Изменено в версии 3.2: Создание LogRecord стало более настраиваемым путём предоставления фабрики, которая используется для создания записи. Фабрику можно установить с помощью getLogRecordFactory() и setLogRecordFactory() (см. эту информацию для сигнатуры фабрики).

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

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

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

Атрибуты LogRecord

LogRecord имеет ряд атрибутов, большинство из которых получены из параметров конструктора. (Обратите внимание, что имена не всегда точно соответствуют параметрам конструктора LogRecord и атрибутам LogRecord.) Эти атрибуты могут использоваться для объединения данных из записи в строку формата. В следующей таблице перечислены (в алфавитном порядке) имена атрибутов, их значения и соответствующие заполнитель в строке формата в стиле «%».

Если вы используете форматирование {} (str.format()), вы можете использовать {attrname} в качестве заполнителя в строке формата. Если вы используете форматирование $ (string.Template), используйте форму ${attrname}. В обоих случаях, конечно, замените attrname фактическим именем атрибута, который вы хотите использовать.

В случае форматирования {}, вы можете указать флаги форматирования, поместив их после имени атрибута, разделив их двоеточием. Например: заполнитель {msecs:03.0f} будет форматировать значение миллисекунд 4 как 004. Обратитесь к документации str.format() для получения полной информации о доступных вам вариантах.

Имя атрибута	Формат	Описание
args	Вам, вероятно, не нужно будет форматировать это самостоятельно.	Кортеж аргументов, объединённых в `msg` для получения `message`, или словарь, значения которого используются для объединения (когда есть только один аргумент, и это словарь).
asctime	`%(asctime)s`	Время в удобочитаемом формате, когда был создан `LogRecord`. По умолчанию это имеет вид ‘2003-07-08 16:49:45,896’ (числа после запятой — миллисекундная часть времени).
created	`%(created)f`	Время создания `LogRecord` (как возвращается `time.time()`).
exc_info	Вам, вероятно, не нужно будет форматировать это самостоятельно.	Кортеж исключения (по типу `sys.exc_info`) или, если исключение не произошло, `None`.
filename	`%(filename)s`	Часть имени файла в `pathname`.
funcName	`%(funcName)s`	Имя функции, содержащей вызов логирования.
levelname	`%(levelname)s`	Текстовый уровень логирования сообщения (`'DEBUG'`, `'INFO'`, `'WARNING'`, `'ERROR'`, `'CRITICAL'`).
levelno	`%(levelno)s`	Числовой уровень логирования сообщения (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`).
lineno	`%(lineno)d`	Номер строки источника, где был выдан вызов логирования (если доступен).
message	`%(message)s`	Залогированное сообщение, вычисленное как `msg % args`. Оно устанавливается при вызове `Formatter.format()`.
module	`%(module)s`	Модуль (имя части `filename`).
msecs	`%(msecs)d`	Миллисекундная часть времени создания `LogRecord`.
msg	Вам, вероятно, не нужно будет форматировать это самостоятельно.	Строка формата, переданная в исходном вызове логирования. Объединённая с `args` для получения `message`, или произвольный объект (см. Использование произвольных объектов в качестве сообщений).
name	`%(name)s`	Имя логгера, использовавшегося для логирования вызова.
pathname	`%(pathname)s`	Полный путь к исходному файлу, где был выдан вызов логирования (если доступен).
process	`%(process)d`	Идентификатор процесса (если доступен).
processName	`%(processName)s`	Имя процесса (если доступно).
relativeCreated	`%(relativeCreated)d`	Время в миллисекундах, когда LogRecord был создан, относительно времени загрузки модуля логирования.
stack_info	Вам, вероятно, не нужно будет форматировать это самостоятельно.	Информация о стеке кадров (если доступна) снизу доверху в текущей нити, включая кадр стека вызова логирования, который привёл к созданию этой записи.
thread	`%(thread)d`	Идентификатор потока (если доступен).
threadName	`%(threadName)s`	Имя потока (если доступно).
taskName	`%(taskName)s`	Имя `asyncio.Task` (если доступно).

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

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

Объекты LoggerAdapter

LoggerAdapter используются для удобного передачи контекстной информации в вызовы регистрации. Пример использования см. в разделе добавления контекстной информации в ваш лог-вывод.

class logging.LoggerAdapter(logger, extra)

Возвращает экземпляр LoggerAdapter, инициализированный с базовым экземпляром Logger и объектом, похожим на словарь.

process(msg, kwargs): Изменяет сообщение и/или ключевые аргументы, передаваемые в вызов регистрации, для вставки контекстной информации. Эта реализация принимает объект, переданный как extra в конструктор, и добавляет его в kwargs с ключом ‘extra’. Возвращаемое значение — кортеж (msg, kwargs), содержащий (возможно, изменённые) версии переданных аргументов.

manager: Делегирует обращение к базовому manager` объекта logger.

_log: Делегирует обращение к базовому методу _log`() объекта logger.

Помимо вышеперечисленного, LoggerAdapter поддерживает следующие методы Logger: debug(), info(), warning(), error(), exception(), critical(), log(), isEnabledFor(), getEffectiveLevel(), setLevel() и hasHandlers(). Эти методы имеют те же сигнатуры, что и их аналоги в Logger, поэтому вы можете использовать оба типа экземпляров взаимозаменяемо.

Изменено в версии 3.2: Методы isEnabledFor(), getEffectiveLevel(), setLevel() и hasHandlers() были добавлены в LoggerAdapter. Эти методы делегируют обращение к базовому логгеру.

Изменено в версии 3.6: Атрибут manager и метод _log() были добавлены, которые делегируют обращение к базовому логгеру и позволяют вложенные адаптеры.

Безопасность потоков

Модуль регистрации предполагает безопасность потоков без необходимости каких-либо специальных действий со стороны его клиентов. Это достигается благодаря использованию потоковых блокировок; существует одна блокировка для сериализации доступа к общим данным модуля, а каждый обработчик также создаёт блокировку для сериализации доступа к его базовому вводу/выводу.

Если вы реализуете асинхронные обработчики сигналов, используя модуль signal, вы можете не иметь возможности использовать регистрацию внутри таких обработчиков. Это происходит из-за того, что реализации блокировок в модуле threading не всегда являются рекурсивными и, следовательно, не могут быть вызваны из таких обработчиков сигналов.

END_OF_DOCUMENT_MARKER

Функции уровня модуля

В дополнение к описанным выше классам, существует ряд функций уровня модуля.

logging.getLogger(name=None)

Возвращает логгер с указанным именем или, если имя равно None, возвращает корневой логгер иерархии. Если указано, имя обычно представляет собой иерархическое имя, разделенное точками, например, ‘a’, ‘a.b’ или ‘a.b.c.d’. Выбор этих имён полностью зависит от разработчика, использующего журналирование, хотя рекомендуется использовать __name__, если у вас нет конкретной причины не делать этого, как упоминается в Объекты логгера.

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

logging.getLoggerClass()

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

class MyLogger(logging.getLoggerClass()):
    # ... override behaviour here

logging.getLogRecordFactory()

Возвращает вызываемый объект, используемый для создания LogRecord.

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

См. setLogRecordFactory() для получения дополнительной информации о том, как вызывается фабрика.

logging.debug(msg, *args, **kwargs)

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

Единственное отличие заключается в том, что если у корневого логгера нет обработчиков, то вызывается basicConfig() перед вызовом debug в корневом логгере.

Для очень коротких скриптов или быстрых демонстраций возможностей logging функции debug и другие функции уровня модуля могут быть удобными. Однако большинство программ захотят тщательно и явно контролировать конфигурацию журналирования и поэтому должны предпочесть создание логгера уровня модуля и вызов Logger.debug() (или других методов уровня) в нём, как описано в начале этой документации.

logging.info(msg, *args, **kwargs): Регистрирует сообщение с уровнем INFO в корневом логгере. Аргументы и поведение в остальном такие же, как у debug().

logging.warning(msg, *args, **kwargs): Регистрирует сообщение с уровнем WARNING в корневом логгере. Аргументы и поведение в остальном такие же, как у debug().

Примечание

Существует устаревшая функция warn, которая функционально идентична warning. Поскольку warn устарела, пожалуйста, не используйте её - используйте warning вместо неё.

logging.error(msg, *args, **kwargs): Регистрирует сообщение с уровнем ERROR в корневом логгере. Аргументы и поведение в остальном такие же, как у debug().

logging.critical(msg, *args, **kwargs): Регистрирует сообщение с уровнем CRITICAL в корневом логгере. Аргументы и поведение в остальном такие же, как у debug().

logging.exception(msg, *args, **kwargs): Регистрирует сообщение с уровнем ERROR в корневом логгере. Аргументы и поведение в остальном такие же, как у debug(). Информация об исключении добавляется в сообщение журналирования. Эта функция должна вызываться только из обработчика исключений.

logging.log(level, msg, *args, **kwargs): Регистрирует сообщение с уровнем level в корневом логгере. Аргументы и поведение в остальном такие же, как у debug().

logging.disable(level=CRITICAL)

Предоставляет накладываемый уровень level для всех логгеров, который имеет приоритет над собственным уровнем логгера. Когда возникает необходимость временно ограничить выходные данные журналирования по всему приложению, эта функция может быть полезной. Её действие заключается в отключении всех вызовов журналирования с уровнем level и ниже, так что если вы вызываете её со значением INFO, то все события INFO и DEBUG будут отброшены, в то время как события с уровнем WARNING и выше будут обрабатываться в соответствии с эффективным уровнем логгера. Если logging.disable(logging.NOTSET) вызван, он эффективно удаляет этот накладываемый уровень, так что выходные данные журналирования снова зависят от эффективных уровней отдельных логгеров.

Обратите внимание, что если вы определили какие-либо пользовательские уровни журналирования выше CRITICAL, (это не рекомендуется), вы не сможете положиться на значение по умолчанию параметра level, а должны явно указать подходящее значение.

Изменено в версии 3.7: Параметр level был установлен по умолчанию к уровню CRITICAL. См. bpo-28524 для получения дополнительной информации об этом изменении.

logging.addLevelName(level, levelName): Связывает уровень level с текстом levelName во внутренней таблице, которая используется для сопоставления числовых уровней с текстовым представлением, например, когда Formatter форматирует сообщение. Эта функция также может использоваться для определения собственных уровней. Единственными ограничениями являются то, что все используемые уровни должны быть зарегистрированы с помощью этой функции, уровни должны быть положительными целыми числами и они должны увеличиваться в возрастающем порядке строгости.

Примечание

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

logging.getLevelNamesMapping(): Возвращает сопоставление имён уровней с соответствующими уровнями журналирования. Например, строка “CRITICAL” сопоставляется с CRITICAL. Возвращаемое отображение копируется из внутренней таблицы при каждом вызове этой функции.

Добавлен в версии 3.11.

END_OF_DOCUMENT_MARKER

logging.getLevelName(level)

Возвращает текстовое или числовое представление уровня регистрации level.

Если level является одним из предопределённых уровней CRITICAL, ERROR, WARNING, INFO или DEBUG, то возвращается соответствующая строка. Если вы связали уровни с именами с помощью addLevelName(), то возвращается имя, связанное с level. Если передано числовое значение, соответствующее одному из определённых уровней, возвращается соответствующее строковое представление.

Параметр level также принимает строковое представление уровня, например, ‘INFO’. В таких случаях функция возвращает соответствующее числовое значение уровня.

Если не передано соответствующее числовое или строковое значение, возвращается строка ‘Уровень %s’ % level.

Примечание

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

Изменено в версии 3.4: В версиях Python до 3.4 эта функция также могла принимать текстовый уровень и возвращать соответствующее числовое значение уровня. Это недокументированное поведение считалось ошибкой и было удалено в Python 3.4, но восстановлено в 3.4.2 для сохранения обратной совместимости.

logging.getHandlerByName(name): Возвращает обработчик с указанным именем name или None , если такого обработчика нет.

Добавлен в версии 3.12.

logging.getHandlerNames(): Возвращает неизменяемый набор всех известных имён обработчиков.

Добавлен в версии 3.12.

logging.makeLogRecord(attrdict): Создаёт и возвращает новый экземпляр LogRecord, атрибуты которого определяются attrdict. Эта функция полезна для получения закодированного в виде пикла словаря атрибутов LogRecord, отправленного по сокету, и его реконструирования в экземпляр LogRecord на стороне приёма.

logging.basicConfig(**kwargs)

Выполняет базовую настройку системы регистрации, создавая StreamHandler с помощью значения по умолчанию Formatter и добавляя его к корневому регистратору. Функции debug(), info(), warning(), error() и critical() вызывают basicConfig() автоматически, если для корневого регистратора не определены обработчики.

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

Примечание

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

Поддерживаются следующие ключевые аргументы.

Формат	Описание
filename	Указывает, что должен быть создан `FileHandler`, используя указанное имя файла, а не `StreamHandler`.
filemode	Если указано filename, откройте файл в указанном режиме. Значение по умолчанию `'a'`.
format	Используйте указанную строку формата для обработчика. Значение по умолчанию — атрибуты `levelname`, `name` и `message`, разделенные двоеточиями.
datefmt	Используйте указанный формат даты/времени, как принимается `time.strftime()`.
style	Если указан format, используйте этот стиль для строки формата. Один из `'%'`, `'{'` или `'$'` для форматирования в стиле printf, `str.format()` или `string.Template` соответственно. Значение по умолчанию — `'%'`.
level	Установите уровень корневого регистратора на указанный уровень.
stream	Используйте указанный поток для инициализации `StreamHandler`. Обратите внимание, что этот аргумент несовместим с filename — если оба присутствуют, возникает `ValueError`.
handlers	Если указано, это должен быть итерируемый объект уже созданных обработчиков для добавления в корневой регистрирующий обработчик. Любые обработчики, у которых ещё нет установленного формата, будут назначены формату по умолчанию, созданному в этой функции. Обратите внимание, что этот аргумент несовместим с filename или stream — если оба присутствуют, возникает `ValueError`.
force	Если этот ключевой аргумент задан как истина, все существующие обработчики, присоединённые к корневому регистратору, удаляются и закрываются перед выполнением настройки, заданной другими аргументами.
encoding	Если этот ключевой аргумент задан вместе с filename, его значение используется при создании `FileHandler`, и, следовательно, используется при открытии выходного файла.
errors	Если этот ключевой аргумент задан вместе с filename, его значение используется при создании `FileHandler`, и, следовательно, используется при открытии выходного файла. Если не указано, используется значение ‘backslashreplace’. Обратите внимание, что если `None` указано, оно будет передано как есть в `open()`, что означает, что оно будет обработано так же, как и передача ‘errors’.

Изменено в версии 3.2: Добавлен аргумент style.

Изменено в версии 3.3: Добавлен аргумент handlers. Были добавлены дополнительные проверки для выявления ситуаций, когда указаны несовместимые аргументы (например, handlers вместе с stream или filename, или stream вместе с filename).

Изменено в версии 3.8: Добавлен аргумент force.

Изменено в версии 3.9: Добавлены аргументы encoding и errors.

logging.shutdown()

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

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

END_OF_DOCUMENT_MARKER

logging.setLoggerClass(klass): Указывает системе логирования использовать класс klass при создании логгера. Класс должен определять __init__() таким образом, чтобы требовался только аргумент имени, и __init__() должен вызывать Logger.__init__(). Эта функция обычно вызывается перед созданием логгеров приложениями, которым требуется настройка поведения логгера. После этого вызова, как и в любой другой момент, не создавайте логгеры напрямую с помощью подкласса: продолжайте использовать API logging.getLogger() для получения логгеров.

logging.setLogRecordFactory(factory)

Устанавливает вызываемый объект, используемый для создания LogRecord.

Параметры:: factory – Вызываемый объект-фабрика для создания записи лога.

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

Фабрика имеет следующую сигнатуру:

factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

name:: Имя логгера.
level:: Уровень логирования (числовое значение).
fn:: Полный путь к файлу, в котором был вызван вызов логирования.
lno:: Номер строки в файле, в которой был вызван вызов логирования.
msg:: Сообщение логирования.
args:: Аргументы для сообщения логирования.
exc_info:: Кортеж исключений или None.
func:: Имя функции или метода, вызвавшего вызов логирования.
sinfo:: Стек вызовов, подобный предоставляемому traceback.print_stack(), показывающий иерархию вызовов.
kwargs:: Дополнительные ключевые аргументы.

Атрибуты уровня модуля

logging.lastResort: «Обработчик последней инстанции» доступен через этот атрибут. Это StreamHandler, записывающий в sys.stderr с уровнем WARNING, и используется для обработки событий логирования при отсутствии какой-либо конфигурации логирования. Результатом является просто вывод сообщения в sys.stderr. Это заменяет предыдущее сообщение об ошибке, указывающее, что «не удалось найти обработчики для логгера XYZ». Если по какой-то причине вам нужно поведение более ранних версий, lastResort может быть установлено в None.

Добавлен в версии 3.2.

logging.raiseExceptions

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

По умолчанию: True.

Если raiseExceptions равно False, исключения будут молча игнорироваться. Это то, что обычно требуется для системы логирования - большинство пользователей не будут заботиться об ошибках в системе логирования, их больше интересуют ошибки приложения.

Интеграция с модулем warnings

Функция captureWarnings() может использоваться для интеграции logging с модулем warnings.

logging.captureWarnings(capture)

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

Если capture равно True, предупреждения, выпущенные модулем warnings, будут перенаправлены в систему логирования. Конкретно, предупреждение будет отформатировано с помощью warnings.formatwarning(), а полученная строка будет записана в логгер с именем 'py.warnings' с уровнем критичности WARNING.

Если capture равно False, перенаправление предупреждений в систему логирования прекратится, и предупреждения будут перенаправлены в их исходные места назначения (т.е. те, которые действовали до вызова captureWarnings(True)).

См. также

Module logging.config: API конфигурации для модуля логирования.
Module logging.handlers: Полезные обработчики, включенные в модуль логирования.
PEP 282 - Система логирования: Предложение, которое описывало эту функцию для включения в стандартную библиотеку Python.
Оригинальный пакет Python logging: Это исходный код пакета logging. Версия пакета, доступная с этого сайта, подходит для использования с Python 1.5.2, 2.1.x и 2.2.x, которые не включают пакет logging в стандартной библиотеке.