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

Источник: Lib/logging/__init__.py

Important

Эта страница содержит справочную информацию по API. Для получения учебной информации и обсуждения более сложных тем см.

• Basic Tutorial

• Advanced Tutorial

• Logging Cookbook

---

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

Основное преимущество того, что 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

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

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

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

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

Примечание

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

handlers

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

Примечание

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

disabled

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

Примечание

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

setLevel(level)

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

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

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

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

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

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

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

isEnabledFor(level)

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

getEffectiveLevel()

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

getChild(suffix)

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

Added in version 3.2.

getChildren()

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

Added in version 3.12.

debug(msg, *args, **kwargs)

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

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

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

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

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

Stack (most recent call last):

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

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

Четвертый ключевой аргумент - extra, который можно использовать для передачи словаря, используемого для заполнения __диктанта__ 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. Если они отсутствуют, сообщение не будет зарегистрировано, поскольку произойдет исключение форматирования строки. Поэтому в этом случае всегда нужно передавать дополнительный словарь с этими ключами.

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

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

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

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

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

Изменено в версии 3.13: Удалите недокументированный метод warn(), который был псевдонимом метода warning().

info(msg, *args, **kwargs)

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

warning(msg, *args, **kwargs)

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

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 - это будет последний логгер, который проверяется на наличие обработчиков.

Added in version 3.2.

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

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

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

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

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

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

class logging.Handler

__init__(level=NOTSET)

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

createLock()

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

acquire()

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

release()

Снимает блокировку потока, установленную с помощью acquire().

setLevel(level)

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

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

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

setFormatter(fmt)

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

addFilter(filter)

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

removeFilter(filter)

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

filter(record)

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

flush()

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

close()

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

handle(record)

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

handleError(record)

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

format(record)

Выполнить форматирование записи - если установлен форматтер, используйте его. В противном случае используется форматер по умолчанию для модуля.

emit(record)

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

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

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

• API конфигурации протоколирования получают блокировку на уровне модуля, а затем блокировки на уровне отдельных обработчиков по мере их конфигурирования.

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

Список обработчиков, входящих в стандартную поставку, см. в разделе logging.handlers.

Объекты форматера

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

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

Параметры:

• fmt (str) – Строка формата в заданном стиле для вывода журнала в целом. Возможные ключи отображения берутся из LogRecord объекта Атрибуты LogRecord. Если ключ не указан, используется '%(message)s', который представляет собой просто сообщение в журнале.

• datefmt (str) – Строка формата в заданном стиле для части даты/времени в журнале. Если не указано, используется значение по умолчанию, описанное в formatTime().

• style (str) – Может быть одним из '%', '{' или '$' и определяет, как строка формата будет объединена с данными: с помощью одного из Форматирование строк в стиле printf (%), str.format() ({) или string.Template ($). Это относится только к fmt и datefmt (например, '%(message)s' против '{message}'), а не к фактическим сообщениям журнала, передаваемым методам логирования. Однако есть other ways для использования {- и $-форматирования сообщений журнала.

• validate (bool) – Если True (по умолчанию), то неправильные или несовпадающие fmt и style вызовут ошибку ValueError; например, logging.Formatter('%(asctime)s - %(message)s', style='{').

• defaults (dict[str, Any]) – Словарь со значениями по умолчанию для использования в пользовательских полях. Например, logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})

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

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

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

format(record)

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

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

formatTime(record, datefmt=None)

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

Эта функция использует настраиваемую пользователем функцию для преобразования времени создания в кортеж. По умолчанию используется time.localtime(); чтобы изменить это для конкретного экземпляра форматера, установите атрибут converter в функцию с той же сигнатурой, что и time.localtime() или time.gmtime(). Чтобы изменить этот параметр для всех форматеров, например, если вы хотите, чтобы все время регистрации отображалось в 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)

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

formatFooter(records)

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

format(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) – numeric level события регистрации (например, 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, или dict, значения которого используются для объединения (если аргумент только один, и он является словарем).
asctime	%(asctime)s	Время создания LogRecord в человекочитаемом виде. По умолчанию оно имеет вид „2003-07-08 16:49:45,896“ (цифры после запятой - это миллисекундная часть времени).
создан	%(created)f	Время, когда был создан LogRecord (как возвращается time.time_ns() / 1e9).
exc_info	Вам не придется форматировать его самостоятельно.	Кортеж исключений (а-ля sys.exc_info) или, если исключение не произошло, None.
имя файла	%(filename)s	Часть имени файла pathname.
funcName	%(funcName)s	Имя функции, содержащей вызов регистрации.
имя уровня	%(levelname)s	Уровень регистрации текста сообщения ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
уровень нет	%(levelno)s	Числовой уровень регистрации сообщения (DEBUG, INFO, WARNING, ERROR, CRITICAL).
lineno	%(lineno)d	Номер исходной строки, на которой был сделан вызов регистрации (если доступно).
сообщение	%(message)s	Сообщение в журнале, вычисляемое как msg % args. Это значение устанавливается при вызове Formatter.format().
модуль	%(module)s	Модуль (часть имени из filename).
мсек	%(msecs)d	Миллисекундная часть времени, когда был создан LogRecord.
msg	Вам не придется форматировать его самостоятельно.	Строка формата, переданная в исходном вызове логирования. Объединяется с args для получения message или произвольного объекта (см. Использование произвольных объектов в качестве сообщений).
имя	%(name)s	Имя регистратора, используемого для регистрации вызова.
имя пути	%(pathname)s	Полное имя пути к исходному файлу, в котором был выполнен вызов журнализации (если доступно).
процесс	%(process)d	Идентификатор процесса (если имеется).
processName	%(processName)s	Имя процесса (если доступно).
relativeCreated	%(relativeCreated)d	Время в миллисекундах, когда была создана запись LogRecord, относительно времени загрузки модуля протоколирования.
информация о стеке	Вам не придется форматировать его самостоятельно.	Информация о фрейме стека (если доступна) от нижней части стека в текущем потоке, до фрейма стека вызова регистрации, который привел к созданию этой записи, включительно.
нить	%(thread)d	Идентификатор нити (если имеется).
threadName	%(threadName)s	Название нити (если имеется).
taskName	%(taskName)s	asyncio.Task имя (если доступно).

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

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

Объекты LoggerAdapter

Экземпляры LoggerAdapter используются для удобной передачи контекстной информации в вызовы логирования. Пример использования см. в разделе, посвященном adding contextual information to your logging output.

class logging.LoggerAdapter(logger, extra, merge_extra=False)

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

process(msg, kwargs)

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

manager

Делегирует базовый manager` на logger.

_log

Делегирует базовый метод _log`() на logger.

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

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

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

Изменено в версии 3.13: Удалите недокументированный метод warn`(), который был псевдонимом метода warning().

Изменено в версии 3.13: Был добавлен аргумент merge_extra.

Безопасность нитей

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

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

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

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

logging.getLogger(name=None)

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

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

logging.getLoggerClass()

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

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

logging.getLogRecordFactory()

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

Added in version 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.

Изменено в версии 3.13: Удалите недокументированную функцию 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 для всех логгеров, который имеет приоритет над собственным уровнем логгера. Когда возникает необходимость временно сократить вывод логов во всем приложении, эта функция может оказаться полезной. Ее действие заключается в отключении всех вызовов логирования уровня * и ниже, так что если вы вызовете ее со значением 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. Возвращаемое отображение копируется из внутреннего отображения при каждом вызове этой функции.

Added in version 3.11.

logging.getLevelName(level)

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

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

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

Если не передано ни одного подходящего числового или строкового значения, возвращается строка „Level %s“ % level.

Примечание

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

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

logging.getHandlerByName(name)

Возвращает обработчик с указанным именем, или None, если обработчика с таким именем не существует.

Added in version 3.12.

logging.getHandlerNames()

Возвращает неизменяемый набор всех известных имен обработчиков.

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

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

Формат	Описание
имя файла	Указывает на создание FileHandler с использованием указанного имени файла, а не StreamHandler.
filemode	Если указано filename, откройте файл в этом mode. По умолчанию - 'a'.
формат	Используйте указанную строку формата для обработчика. По умолчанию используются атрибуты levelname, name и message, разделенные двоеточиями.
datefmt	Используйте указанный формат даты/времени, принятый time.strftime().
стиль	Если указан формат, используйте этот стиль для строки формата. Одно из '%', '{' или '$' для printf-style, str.format() или string.Template соответственно. По умолчанию используется значение '%'.
уровень	Установите уровень корневого регистратора на указанное значение level.
поток	Используйте указанный поток для инициализации StreamHandler. Обратите внимание, что этот аргумент несовместим с filename - если присутствуют оба аргумента, возникает ошибка ValueError.
handlers	Если указано, то это должно быть итеративное множество уже созданных обработчиков для добавления в корневой логгер. Все обработчики, у которых еще не установлен формат, получат формат по умолчанию, созданный в этой функции. Обратите внимание, что этот аргумент несовместим с filename или stream - если присутствуют оба аргумента, возникает ошибка ValueError.
силой	Если этот ключевой аргумент указан как true, все существующие обработчики, прикрепленные к корневому регистратору, будут удалены и закрыты, прежде чем будет выполнена настройка, указанная в других аргументах.
кодирование	Если этот ключевой аргумент указан вместе с filename, то его значение используется при создании FileHandler и, соответственно, при открытии выходного файла.
ошибки	Если этот ключевой аргумент указан вместе с filename, то его значение используется при создании FileHandler и, соответственно, при открытии выходного файла. Если он не указан, используется значение „backslashreplace“. Обратите внимание, что если указан None, то он будет передан как таковой в open(), что означает, что это будет рассматриваться так же, как передача „errors“.

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

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

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

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

logging.shutdown()

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

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

logging.setLoggerClass(klass)

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

logging.setLogRecordFactory(factory)

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

Параметры:

factory – Вызываемая фабрика, которая будет использоваться для создания записи журнала.

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

Фабрика имеет следующую подпись:

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

имя:

Имя регистратора.

уровень:

Уровень регистрации (числовой).

fn:

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

lno:

Номер строки в файле, в которой был выполнен вызов журнала.

msg:

Сообщение о регистрации.

args:

Аргументы для сообщения журнализации.

exc_info:

Кортеж исключений, или None.

func:

Имя функции или метода, вызвавшего вызов регистрации.

sinfo:

Отслеживание стека, как это сделано в traceback.print_stack(), показывает иерархию вызовов.

kwargs:

Дополнительные аргументы в виде ключевых слов.

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

logging.lastResort

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

Added in version 3.2.

logging.raiseExceptions

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

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

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

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

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

logging.captureWarnings(capture)

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

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

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

См.также

Модуль logging.config

API конфигурации для модуля протоколирования.

Модуль logging.handlers

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

PEP 282 - Система ведения журнала

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

Original Python logging package

Это оригинальный источник пакета logging. Версия пакета, доступная с этого сайта, подходит для использования с Python 1.5.2, 2.1.x и 2.2.x, которые не включают пакет logging в стандартную библиотеку.