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

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

Важно

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

• Базовый учебник

• Продвинутый учебник

• Кулинарная книга по журналированию

---

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

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

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

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

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

if __name__ == '__main__':
    main()

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

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

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

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

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

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

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

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

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

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

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

• Форматировщики определяют макет записей журнала в окончательном выводе.

Logger ObjectsОбъекты Logger

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

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

class logging.Logger¶

name¶

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

Примечание

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

level¶

Порог этого логгера, установленный методом setLevel().

Примечание

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

parent¶

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

Примечание

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

propagate¶

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

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

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

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

Примечание

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

handlers¶

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

Примечание

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

disabled¶

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

Примечание

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

setLevel(level)¶

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

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

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

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

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

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

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

isEnabledFor(level)¶

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

getEffectiveLevel()¶

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

getChild(suffix)¶

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

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

getChildren()¶

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

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

debug(msg, *args, **kwargs)¶

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

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

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

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

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

Stack (most recent call last):

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

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

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

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

выведет что-то вроде

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

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

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

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

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

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

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

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

info(msg, *args, **kwargs)¶

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

warning(msg, *args, **kwargs)¶

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

Примечание

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

error(msg, *args, **kwargs)¶

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

critical(msg, *args, **kwargs)¶

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

log(level, msg, *args, **kwargs)¶

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

exception(msg, *args, **kwargs)¶

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

addFilter(filter)¶

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

removeFilter(filter)¶

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

filter(record)¶

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

addHandler(hdlr)¶

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

removeHandler(hdlr)¶

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

findCaller(stack_info=False, stacklevel=1)¶

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

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

handle(record)¶

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

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)¶

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

hasHandlers()¶

Проверяет, настроены ли у этого логгера какие-либо обработчики. Для этого производится поиск обработчиков в этом логгере и его родителях в иерархии логгеров. Возвращает True, если обработчик найден, иначе False. Метод прекращает поиск вверх по иерархии, как только будет найден логгер, у которого атрибут 'propagate' установлен в false – это будет последний логгер, проверяемый на наличие обработчиков.

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

Изменено в версии 3.7: Логгеры теперь можно сериализовать и десериализовать с помощью модуля pickle.

Logging LevelsУровни логирования

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

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

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

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

class logging.Handler¶

__init__(level=NOTSET)¶

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

createLock()¶

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

acquire()¶

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

release()¶

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

setLevel(level)¶

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

Список уровней приведён в разделе Logging Levels.

Изменено в версии 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.

Formatter ObjectsОбъекты Formatter

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

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

Параметры:

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

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

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

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

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

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

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

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

format(record)¶

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

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

formatTime(record, datefmt=None)¶

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

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

Filter ObjectsОбъекты фильтров

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 ObjectsОбъекты 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 attributesАтрибуты LogRecord

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

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

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

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

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

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

LoggerAdapter ObjectsОбъекты LoggerAdapter

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

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

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

process(msg, kwargs)¶

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

manager¶

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

_log¶

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

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

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

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

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

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

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

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

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

Module-Level FunctionsФункции уровня модуля

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

logging.getLogger(name=None)¶

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

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

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

logging.info(msg, *args, **kwargs)¶

Записывает сообщение с уровнем INFO в корневой регистратор. В остальном аргументы и поведение такие же, как для debug().

logging.warning(msg, *args, **kwargs)¶

Записывает сообщение с уровнем WARNING в корневой регистратор. В остальном аргументы и поведение такие же, как для debug().

Примечание

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

logging.error(msg, *args, **kwargs)¶

Записывает сообщение с уровнем ERROR в корневой регистратор. В остальном аргументы и поведение такие же, как для debug().

logging.critical(msg, *args, **kwargs)¶

Записывает сообщение с уровнем CRITICAL в корневой регистратор. В остальном аргументы и поведение такие же, как для debug().

logging.exception(msg, *args, **kwargs)¶

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

logging.log(level, msg, *args, **kwargs)¶

Записывает сообщение с уровнем level в корневой регистратор. В остальном аргументы и поведение такие же, как для debug().

logging.disable(level=CRITICAL)¶

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

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

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

logging.addLevelName(level, levelName)¶

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

Примечание

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

logging.getLevelNamesMapping()¶

Возвращает отображение имён уровней на соответствующие уровни логирования. Например, строка «CRITICAL» соответствует CRITICAL. Возвращаемое отображение копируется из внутреннего отображения при каждом вызове этой функции.

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

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

logging.basicConfig(**kwargs)¶

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

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

Примечание

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

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

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

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

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

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

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

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

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:

Дополнительные именованные аргументы.

Module-Level AttributesАтрибуты уровня модуля

logging.lastResort¶

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

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

logging.raiseExceptions¶

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

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

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

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

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

logging.captureWarnings(capture)¶

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

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

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

Смотрите также

Модуль logging.config

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

Модуль logging.handlers

Полезные обработчики, включённые в модуль логирования.

PEP 282 – Система логирования

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

Оригинальный пакет логирования Python

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