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

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

Регистраторы имеют следующие атрибуты и методы. Обратите внимание, что экземпляры регистраторов никогда не должны создаваться напрямую, а всегда через функцию уровня модуля logging.getLogger(name). Несколько вызовов getLogger() с одинаковым именем всегда будут возвращать ссылку на один и тот же объект регистратора.

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

class logging.Logger¶

name¶

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

Примечание

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

level¶

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

Примечание

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

parent¶

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

Примечание

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

propagate¶

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

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

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

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

Примечание

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

handlers¶

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

Примечание

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

disabled¶

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

Примечание

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

setLevel(level)¶

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

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

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

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

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

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

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

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

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

В 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, который можно использовать для передачи словаря, который используется для заполнения __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, не должны совпадать с ключами, используемыми системой ведения журнала. (Смотрите раздел Атрибуты записи журнала для получения дополнительной информации о том, какие ключи используются системой ведения журнала.)

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

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

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

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: Теперь лесорубы можно мариновать и не мариновать.

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

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

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

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

class logging.Handler¶

__init__(level=NOTSET)¶

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

createLock()¶

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

acquire()¶

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

release()¶

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

setLevel(level)¶

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

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

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

setFormatter(fmt)¶

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

addFilter(filter)¶

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

removeFilter(filter)¶

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

filter(record)¶

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

flush()¶

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

close()¶

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

handle(record)¶

Автоматически генерирует указанную запись журнала, в зависимости от фильтров, которые, возможно, были добавлены в обработчик. Завершает фактическую передачу записи получением/снятием блокировки потока ввода-вывода.

handleError(record)¶

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

format(record)¶

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

emit(record)¶

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

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

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

• API-интерфейсы настройки ведения журнала получают блокировку на уровне модуля, а затем блокировку на уровне отдельных обработчиков по мере настройки этих обработчиков.

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

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

Объекты средства форматирования¶

Formatter объекты имеют следующие атрибуты и методы. Они отвечают за преобразование LogRecord в (обычно) строку, которая может быть интерпретирована как человеком, так и внешней системой. Базовый параметр Formatter позволяет указать строку форматирования. Если он не указан, используется значение по умолчанию '%(message)s', которое просто включает сообщение в вызов журнала. Чтобы получить дополнительную информацию в отформатированном выводе (например, временную метку), продолжайте чтение.

Средство форматирования может быть инициализировано строкой формата, которая использует знание атрибутов LogRecord, таких как значение по умолчанию, упомянутое выше, используя тот факт, что пользовательское сообщение и аргументы предварительно отформатированы в виде LogRecord. атрибут message. Эта строка формата содержит стандартные ключи сопоставления в стиле Python. Смотрите раздел printf -стиль форматирования строки для получения дополнительной информации о форматировании строк.

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

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

Возвращает новый экземпляр класса Formatter. Экземпляр инициализируется строкой формата для сообщения в целом, а также строкой формата для части сообщения, содержащей дату и время. Если не указан fmt, используется '%(message)s'. Если не указан datefmt, используется формат, описанный в документации formatTime().

Параметр style может быть одним из „%“, „{“ или „$“ и определяет, как строка формата будет объединена с ее данными: с использованием одного из значений %-formatting, str.format() или string.Template. Это относится только к строке формата fmt (например, '%(message)s' или {message}), а не к фактическим сообщениям журнала, передаваемым в Logger.debug и т.д.; см. Использование определенных стилей форматирования в вашем приложении для получения дополнительной информации об использовании {- и $-форматирование сообщений журнала.

Параметр defaults может быть словарем со значениями по умолчанию для использования в пользовательских полях. Например: logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})

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

Изменено в версии 3.8: Был добавлен параметр validate. Неверный или несоответствующий стилю и fmt вызовут значение ValueError. Например: logging.Formatter('%(asctime)s - %(message)s', style='{').

Изменено в версии 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“, где часть uu - это миллисекундное значение, а остальные буквы указаны в соответствии с документацией time.strftime(). Примером времени в этом формате является 2003-01-23 00:29:50,411. Возвращается результирующая строка.

Эта функция использует настраиваемую пользователем функцию для преобразования времени создания в кортеж. По умолчанию используется time.localtime(); чтобы изменить это значение для конкретного экземпляра средства форматирования, присвойте атрибуту converter значение функции с той же сигнатурой, что и time.localtime() или time.gmtime(). Чтобы изменить его для всех форматировщиков, например, если вы хотите, чтобы все время регистрации отображалось по Гринвичу, установите атрибут converter в классе Formatter.

Изменено в версии 3.3: Ранее формат по умолчанию был жестко задан, как в этом примере: 2010-09-06 22:38:15,292, где часть перед запятой обрабатывается строкой формата strptime ('%Y-%m-%d %H:%M:%S'),, а часть после запятой представляет собой миллисекундное значение. Поскольку strptime не имеет форматного заполнителя для миллисекунд, значение миллисекунды добавляется с использованием другой форматной строки, '%s,%03d' — и обе эти форматные строки были жестко запрограммированы в этом методе. С изменением эти строки определяются как атрибуты уровня класса, которые при желании могут быть переопределены на уровне экземпляра. Имена атрибутов следующие: default_time_format (для строки формата strptime) и default_msec_format (для добавления миллисекундного значения).

Изменено в версии 3.9: Значение default_msec_format может быть None.

formatException(exc_info)¶

Форматирует указанную информацию об исключении (стандартный кортеж исключений, возвращаемый с помощью sys.exc_info()) в виде строки. Эта реализация по умолчанию использует только traceback.print_exception(). Возвращается результирующая строка.

formatStack(stack_info)¶

Форматирует указанную информацию о стеке (строку, возвращаемую с помощью traceback.print_stack(), но с удалением последней новой строки) в виде строки. Эта реализация по умолчанию просто возвращает входное значение.

class logging.BufferingFormatter(linefmt=None)¶

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

formatHeader(records)¶

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

formatFooter(records)¶

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

format(records)¶

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

Фильтровать объекты¶

Filters может использоваться Handlers и Loggers для более сложной фильтрации, чем это предусмотрено в levels. Базовый класс filter допускает только те события, которые находятся ниже определенной точки в иерархии регистратора. Например, фильтр, инициализированный «A.B», разрешит события, регистрируемые регистраторами «A.B», «A.B.C», «A.B.C.D», «A.B.D» и т.д., но не «A.BB“, „B.A.B“ и т.д. Если инициализируется пустой строкой, передаются все события.

class logging.Filter(name='')¶

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

filter(record)¶

Требуется ли занести указанную запись в журнал? Возвращает ноль в случае «нет» и ненулевое значение в случае «да». При необходимости запись может быть изменена на месте с помощью этого метода.

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

На самом деле вам не нужно создавать подкласс Filter: вы можете передать любой экземпляр, который имеет метод filter с той же семантикой.

Хотя фильтры используются в основном для фильтрации записей на основе более сложных критериев, чем уровни, они позволяют просматривать каждую запись, обработанную обработчиком или регистратором, к которому они подключены: это может быть полезно, если вы хотите, например, подсчитать, сколько записей было обработано конкретным регистратором или обработчиком, или добавление, изменение или удаление атрибутов в обрабатываемом LogRecord. Очевидно, что изменение записи журнала должно производиться с некоторой осторожностью, но это позволяет вводить контекстную информацию в журналы (см. Использование фильтров для передачи контекстуальной информации).

Объекты записи журнала¶

LogRecord экземпляры создаются автоматически с помощью Logger каждый раз, когда что-либо регистрируется, и могут быть созданы вручную с помощью makeLogRecord() (например, из выбранного события, полученного по проводам).

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)¶

Содержит всю информацию, относящуюся к регистрируемому событию.

Первичная информация передается в msg и args, которые объединяются с помощью msg % args для создания атрибута message записи.

Parameters:

• name (str) – Имя регистратора, используемого для регистрации события, представленного этим LogRecord. Обратите внимание, что имя регистратора в LogRecord всегда будет иметь это значение, даже если оно может быть выдано обработчиком, подключенным к другому (предковому) регистратору.

• level (int) – numeric level события регистрации (например, 10 для DEBUG, 20 для INFO и т.д.). Обратите внимание, что это значение преобразуется в два атрибута записи журнала: 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 после объединения всех предоставленных пользователем аргументов с сообщением. Если предоставленный пользователем аргумент message для вызова logging не является строкой, для его преобразования в строку вызывается 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 не всегда точно совпадают). Эти атрибуты можно использовать для объединения данных из записи в строку формата. В следующей таблице перечислены (в алфавитном порядке) названия атрибутов, их значения и соответствующий заполнитель в строке формата в стиле %.

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

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

Объекты LoggerAdapter¶

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

class logging.LoggerAdapter(logger, extra)¶

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

process(msg, kwargs)¶

Изменяет сообщение и/или аргументы ключевого слова, передаваемые в вызов logging, чтобы вставить контекстную информацию. Эта реализация использует объект, переданный как 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(), которые делегируются базовому регистратору и позволяют использовать вложенные адаптеры.

Безопасность резьбы¶

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

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

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

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

logging.getLogger(name=None)¶

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

Все вызовы этой функции с заданным именем возвращают один и тот же экземпляр logger. Это означает, что экземпляры 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 для всех регистраторов, который имеет приоритет над уровнем самого регистратора. Когда возникает необходимость временно снизить производительность ведения журнала во всем приложении, эта функция может оказаться полезной. Его эффект заключается в отключении всех вызовов протоколирования с уровнем серьезности * и ниже, так что если вы вызовете его со значением INFO, то все информационные и отладочные события будут отброшены, в то время как события с предупреждением о серьезности и выше будут обработаны в соответствии с эффективным уровнем регистратора. Если вызывается logging.disable(logging.NOTSET), это эффективно удаляет этот переопределяющий уровень, так что выходные данные ведения журнала снова зависят от эффективных уровней отдельных регистраторов.

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

Изменено в версии 3.7: Для параметра level по умолчанию было установлено значение 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 (см. Атрибуты записи журнала) и наоборот.

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

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

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

Parameters:

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

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

Завод имеет следующую подпись:

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

имя:

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

уровень:

Уровень ведения журнала (числовой).

fn:

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

лно:

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

глутамат натрия:

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

аргументы:

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

exc_info (дополнительная информация):

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

функция:

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

синфо:

Обратная трассировка стека, такая как обеспечивается traceback.print_stack(), показывает иерархию вызовов.

квар-ги:

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

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

logging.lastResort¶

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

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