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

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

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

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

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

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

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

if __name__ == '__main__':
    main()

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

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

Если запустить myapp.py, в файле myapp.log должно появиться следующее:

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

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

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

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

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

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

Объекты регистратора

У регистраторов есть следующие атрибуты и методы. Обратите внимание: регистраторы НИКОГДА не следует создавать напрямую; их всегда нужно создавать с помощью функции уровня модуля logging.getLogger(name). Многократные вызовы getLogger() с одним и тем же именем всегда возвращают ссылку на один и тот же объект 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.

Примечание

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

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

Примечание

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

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

Примечание

Этот атрибут следует считать доступным только для чтения.

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

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

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

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

format(record)

Словарь атрибутов записи используется как операнд операции форматирования строки. Возвращает полученную строку. Перед форматированием словаря выполняется несколько подготовительных действий. Атрибут записи message вычисляется с помощью msg % args. Если строка форматирования содержит '(asctime)', для форматирования времени события вызывается formatTime(). Если имеется информация об исключении, она форматируется с помощью formatException() и добавляется к сообщению. Обратите внимание, что отформатированная информация об исключении кэшируется в атрибуте exc_text. Это полезно, поскольку информацию об исключении можно сериализовать с помощью 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(). Чтобы изменить поведение для всех форматировщиков, например если нужно отображать время всех сообщений журнала в часовом поясе GMT, задайте атрибут 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): Следует ли записывать указанную запись? Возвращает ложное значение, если нет, и истинное, если да. Фильтры могут изменять записи журнала на месте или возвращать совершенно другой экземпляр записи, который заменит исходную запись журнала при дальнейшей обработке события.

Обратите внимание, что фильтры, подключённые к обработчикам, проверяются перед выводом события обработчиком, тогда как фильтры, подключённые к регистраторам, проверяются при каждой записи события (с помощью 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()`).
exc_info	Обычно это не требуется форматировать самостоятельно.	Кортеж исключения (по аналогии с `sys.exc_info`) или `None`, если исключение не возникало.
filename	`%(filename)s`	Имя файла из `pathname`.
funcName	`%(funcName)s`	Имя функции, содержащей вызов журналирования.
levelname	`%(levelname)s`	Текстовое название уровня журналирования для сообщения (`'DEBUG'`, `'INFO'`, `'WARNING'`, `'ERROR'`, `'CRITICAL'`).
levelno	`%(levelno)s`	Числовое значение уровня журналирования для сообщения (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`).
lineno	`%(lineno)d`	Номер строки исходного кода, в которой был вызван механизм журналирования (если доступен).
message	`%(message)s`	Записанное в журнал сообщение, вычисленное как `msg % args`. Это значение устанавливается при вызове `Formatter.format()`.
module	`%(module)s`	Модуль (имя из `filename`).
msecs	`%(msecs)d`	Миллисекундная часть времени создания `LogRecord`.
msg	Обычно это не требуется форматировать самостоятельно.	Строка формата, переданная в исходный вызов журналирования. Объединяется с `args` для получения `message` либо представляет собой произвольный объект (см. раздел Использование произвольных объектов в качестве сообщений).
name	`%(name)s`	Имя регистратора, использованного для журналирования вызова.
pathname	`%(pathname)s`	Полный путь к исходному файлу, в котором был вызван механизм журналирования (если доступен).
process	`%(process)d`	Идентификатор процесса (если доступен).
processName	`%(processName)s`	Имя процесса (если доступно).
relativeCreated	`%(relativeCreated)d`	Время в миллисекундах с момента создания LogRecord относительно момента загрузки модуля журналирования.
stack_info	Обычно это не требуется форматировать самостоятельно.	Информация о кадрах стека (если доступна), начиная с нижней части стека в текущем потоке и до кадра стека включительно, в котором был вызван механизм журналирования, приведший к созданию этой записи.
thread	`%(thread)d`	Идентификатор потока (если доступен).
threadName	`%(threadName)s`	Имя потока (если доступно).
taskName	`%(taskName)s`	Имя `asyncio.Task` (если доступно).

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

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

Объекты LoggerAdapter

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

class logging.LoggerAdapter(logger, extra)

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

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

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

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

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

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

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

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

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

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

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

При импорте модуля logging эта функция регистрируется как обработчик выхода (см. 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.