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

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

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

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

Объекты Logger

Логгеры имеют следующие атрибуты и методы. Обратите внимание: объекты Logger НИКОГДА не следует создавать напрямую; для этого всегда нужно использовать функцию уровня модуля logging.getLogger(name). Многократные вызовы getLogger() с одним и тем же именем всегда возвращают ссылку на один и тот же объект Logger.

Значение 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.

Примечание

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

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(): Возвращает эффективный уровень этого логгера. Если с помощью setLevel() было задано значение, отличное от NOTSET, возвращается это значение. В противном случае выполняется обход иерархии в направлении корневого логгера, пока не будет найдено значение, отличное от 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.

debug(msg, *args, **kwargs)

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

Из 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)

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

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

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

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	Серьёзная ошибка, указывающая на то, что программа может оказаться неспособной продолжить работу.

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

Обработчики имеют следующие атрибуты и методы. Обратите внимание, что 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): Задаёт для этого обработчика форматировщик fmt. Аргумент fmt должен быть экземпляром Formatter или None.

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

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

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

flush(): Гарантирует сброс всех выходных данных журналирования. Эта версия ничего не делает и предназначена для реализации в подклассах.

close()

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

Подклассы должны обеспечить вызов этого метода из переопределённых методов 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) – Строка формата для всего выводимого журнала в заданном стиле style. Возможные ключи соответствия берутся из атрибутов объекта LogRecord Атрибуты LogRecord. Если параметр не указан, используется '%(message)s' — это просто сообщение журнала.
datefmt (str) – Строка формата для даты и времени в выводимом журнале. Если параметр не указан, используется значение по умолчанию, описанное в formatTime().
style (str) – Может принимать одно из значений '%', '{' или '$' и определяет, как строка формата будет объединена с данными: с использованием форматирования строк в стиле printf (%), str.format() ({) или string.Template ($). Это относится только к fmt (например, '%(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 нужно осторожно, но это позволяет добавлять в журналы контекстную информацию (см. раздел Использование фильтров для добавления контекстной информации).

Объекты 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 и т. д.). Обратите внимание, что это значение преобразуется в два атрибута LogRecord: 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_ns()` / 1e9).
exc_info	Вам не должно понадобиться форматировать это самостоятельно.	Кортеж исключения (в духе `sys.exc_info`) или `None`, если исключение не произошло.
exc_text	Вам не должно понадобиться форматировать это самостоятельно.	Информация об исключении в виде строки. Она задаётся при вызове `Formatter.format()` или принимает значение `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=None, merge_extra=False)

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

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: В LoggerAdapter добавлены методы isEnabledFor(), getEffectiveLevel(), setLevel() и hasHandlers(). Эти методы делегируют вызовы базовому регистратору.

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

Изменено в версии 3.10: Аргумент extra теперь необязательный.

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

Потокобезопасность

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

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

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

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

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() для корневого регистратора. Обработка аргументов полностью совпадает с описанной для этого метода.

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

Для очень коротких скриптов или быстрых демонстраций возможностей 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.

logging.getLevelName(level)

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

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

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

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

Примечание

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

Изменено в версии 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 в формате pickle, отправленного через сокет, и его восстановления на принимающей стороне в экземпляр LogRecord.

logging.basicConfig(**kwargs)

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

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

Примечание

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

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

Формат	Описание
filename	Указывает, что вместо `StreamHandler` следует создать `FileHandler`, используя указанное имя файла.
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	Если этому ключевому аргументу задано значение true, все существующие обработчики корневого регистратора удаляются и закрываются перед выполнением настройки, определяемой остальными аргументами.
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), поэтому обычно вызывать её вручную не нужно.

logging.setLoggerClass(klass): Указывает системе ведения журнала использовать класс klass при создании регистратора. Класс должен определять __init__() таким образом, чтобы требовался только аргумент name, а __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. Версия пакета, доступная на этом сайте, предназначена для Python 1.5.2, 2.1.x и 2.2.x, в стандартную библиотеку которых пакет logging не входит.