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

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

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

Рассмотрим пример. Если значение атрибута propagate логгера с именем A.B.C истинно, любое событие, записанное в 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(): Показывает эффективный уровень этого логгера. Если с помощью 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)

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

Параметр stacklevel передаётся из вызывающего кода методов debug() и других API. Если его значение больше 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: Логгеры теперь можно сериализовать и десериализовать с помощью pickle.

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

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

Уровень	Числовое значение	Значение / когда использовать
`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. Это полезно, поскольку сведения об исключении можно сериализовать с помощью pickle и передать по сети, но следует соблюдать осторожность, если у вас есть несколько подклассов 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) – Текстовое описание события: строка формата %-style с заполнителями для переменных данных или произвольный объект (см. раздел Использование произвольных объектов в качестве сообщений).
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`, если исключение не возникло.
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, merge_extra=False)

Возвращает экземпляр LoggerAdapter, инициализированный базовым экземпляром Logger, объектом, подобным словарю (extra), и логическим значением (merge_extra), указывающим, нужно ли объединять аргумент extra отдельных вызовов журналирования с атрибутом extra экземпляра LoggerAdapter. По умолчанию аргумент 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.13: Добавлен аргумент merge_extra.

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

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

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

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

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

logging.getLogger(name=None)

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

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

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

Предписывает системе журналирования выполнить корректное завершение работы, сбросив буферы и закрыв все обработчики. Эту функцию следует вызывать при завершении приложения; после её вызова систему журналирования больше нельзя использовать.

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

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». Если по какой-либо причине требуется прежнее поведение, можно присвоить None значение lastResort.

Добавлено в версии 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.