logging — Возможность ведения журналов для Python

Kod źródłowy: Lib/logging/__init__.py

Important

Ця сторінка містить довідкову інформацію про API. Інформацію про підручники та обговорення більш складних тем див

• Basic Tutorial

• Advanced Tutorial

• Logging Cookbook

---

Цей модуль визначає функції та класи, які реалізують гнучку систему реєстрації подій для програм і бібліотек.

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

Вот простой пример идиоматического употребления::

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

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

if __name__ == '__main__':
    main()

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

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

Якщо ви запускаєте myapp.py, ви повинні побачити це в myapp.log:

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

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

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

Модуль забезпечує багато функціональних можливостей і гнучкості. Якщо ви не знайомі з веденням журналів, найкращий спосіб зрозуміти це — переглянути навчальні посібники (перегляньте посилання вище та праворуч).

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

• Логери відкривають інтерфейс, який безпосередньо використовує код програми.

• Обробники надсилають записи журналу (створені реєстраторами) у відповідне місце призначення.

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

• Засоби форматування вказують макет записів журналу в кінцевому виведенні.

Логер об’єктів

Реєстратори мають такі атрибути та методи. Зауважте, що Логери НІКОЛИ не повинні створюватися безпосередньо, а завжди через функцію рівня модуля logging.getLogger(name). Кілька викликів getLogger() з однаковою назвою завжди повертатимуть посилання на той самий об’єкт Logger.

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

class logging.Logger

name

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

Informacja

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

level

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

Informacja

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

parent

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

Informacja

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

propagate

Якщо цей атрибут оцінюється як істина, події, зареєстровані в цьому реєстраторі, будуть передані обробникам реєстраторів вищого рівня (предків), на додаток до будь-яких обробників, приєднаних до цього реєстратора. Повідомлення передаються безпосередньо до обробників попередніх реєстраторів - ні рівень, ні фільтри попередніх реєстраторів, про які йдеться.

Якщо це значення має значення 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.

Informacja

Якщо ви приєднаєте обробник до реєстратора і одного або кількох його предків, він може створювати той самий запис кілька разів. Загалом, вам не потрібно приєднувати обробник до кількох реєстраторів — якщо ви просто приєднаєте його до відповідного реєстратора, який є найвищим в ієрархії реєстратора, тоді він бачитиме всі події, зареєстровані всіма нащадками реєстраторів, за умови, що вони поширюються параметр залишається встановленим на True. Поширеним сценарієм є приєднання обробників лише до кореневого реєстратора, а розповсюдження подбає про решту.

handlers

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

Informacja

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

disabled

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

Informacja

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

setLevel(level)

Встановлює порогове значення для цього реєстратора на рівень. Повідомлення журналу, менш суворі, ніж рівень, ігноруватимуться; Повідомлення журналювання, які мають рівень серйозності рівень або вищий, будуть випущені будь-яким обробником або обробниками, які обслуговують цей реєстратор, якщо рівень серйозності обробника не встановлено на вищий рівень серйозності, ніж рівень.

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

Термін „делегування батьківському” означає, що якщо реєстратор має рівень NOTSET, його ланцюжок реєстраторів предків обходиться, доки не буде знайдено предка з рівнем, відмінним від NOTSET, або досягнуто кореня.

Якщо знайдено предка з рівнем, відмінним від NOTSET, тоді цей рівень предка розглядається як ефективний рівень реєстратора, з якого почався пошук предка, і використовується для визначення того, як обробляється подія журналювання.

Якщо кореневий доступ досягнутий і він має рівень NOTSET, то всі повідомлення будуть оброблені. В іншому випадку кореневий рівень буде використано як ефективний рівень.

Перегляньте Рівні реєстрації список рівнів.

Zmienione w wersji 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__, а не літеральний рядок.

Dodane w wersji 3.2.

getChildren()

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

Dodane w wersji 3.12.

debug(msg, *args, **kwargs)

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

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

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

Другим необов’язковим ключовим аргументом є stack_info, який за умовчанням має значення False. Якщо значення true, інформація про стек додається до повідомлення журналу, включаючи фактичний виклик журналу. Зауважте, що це інша інформація про стек, яка відображається за допомогою exc_info: перша – це кадри стеку від нижньої частини стеку до виклику журналювання в поточному потоці, тоді як остання – це інформація про кадри стеку, які були переглянуті. unwind, після винятку, під час пошуку обробників винятків.

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

Стек (последний вызов последний):

Це імітує Traceback (останній останній виклик):, який використовується під час відображення кадрів винятків.

Третій необов’язковий аргумент ключового слова — 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. Якщо вони відсутні, повідомлення не буде зареєстровано, оскільки виникне виняток форматування рядка. Тому в цьому випадку вам завжди потрібно передавати додатковий словник за допомогою цих ключів.

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

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

Zmienione w wersji 3.2: Додано параметр stack_info.

Zmienione w wersji 3.5: Параметр exc_info тепер може приймати винятки.

Zmienione w wersji 3.8: Додано параметр stacklevel.

info(msg, *args, **kwargs)

Записує повідомлення з рівнем INFO у цьому реєстраторі. Аргументи інтерпретуються як для debug().

warning(msg, *args, **kwargs)

Записує повідомлення з рівнем WARNING до цього реєстратора. Аргументи інтерпретуються як для debug().

Informacja

Існує застарілий метод 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)

Loguje wiadomość z poziomem ERROR na tym loggerze. Argumenty są interpretowane jak dla debug(). Informacje o wyjątku są dodawane do komunikatu logowania. Ta metoda powinna być wywoływana tylko wewnątrz klauzuli except.

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 - це буде останній реєстратор, який перевіряється на наявність обробників.

Dodane w wersji 3.2.

Zmienione w wersji 3.7: Лісоруби тепер можна маринувати та не пикувати.

Рівні реєстрації

Числові значення рівнів журналювання наведені в наступній таблиці. Це насамперед цікаво, якщо ви бажаєте визначити власні рівні та потребуєте, щоб вони мали певні значення відносно попередньо визначених рівнів. Якщо ви визначаєте рівень з тим самим числовим значенням, він перезаписує попередньо визначене значення; попередньо визначене ім’я втрачено.

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

Об’єкти обробки

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

class logging.Handler

__init__(level=NOTSET)

Ініціалізує екземпляр Handler, встановлюючи його рівень, встановлюючи список фільтрів у порожній список і створюючи блокування (за допомогою createLock()) для серіалізації доступу до механізму введення-виведення.

createLock()

Ініціалізує блокування потоку, який можна використовувати для серіалізації доступу до основної функції введення-виведення, яка може бути небезпечною для потоків.

acquire()

Отримує блокування потоку, створене за допомогою createLock().

release()

Звільняє блокування потоку, отримане за допомогою acquire().

setLevel(level)

Встановлює порогове значення для цього обробника на рівень. Повідомлення журналу, менш суворі, ніж рівень, ігноруватимуться. Коли обробник створюється, рівень встановлюється на NOTSET (що спричиняє обробку всіх повідомлень).

Перегляньте Рівні реєстрації список рівнів.

Zmienione w wersji 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.

Ostrzeżenie

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

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

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

Перелік стандартних обробників див. logging.handlers.

Об’єкти форматування

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

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

Parametry:

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

• datefmt (str) – A format string for the date/time portion of the logged output. If not specified, the default described in formatTime() is used.

• style (str) – Can be one of '%', '{' or '$' and determines how the format string will be merged with its data: using one of Форматування рядків у стилі printf (%), str.format() ({) or string.Template ($). This only applies to fmt (e.g. '%(message)s' versus '{message}'), not to the actual log messages passed to the logging methods. However, there are other ways to use {- and $-formatting for log messages.

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

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

Zmienione w wersji 3.2: Добавлен параметр style.

Zmienione w wersji 3.8: Добавлен параметр validate.

Zmienione w wersji 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.

Zmienione w wersji 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 (для додавання значення в мілісекундах).

Zmienione w wersji 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)

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

Фільтр об’єктів

Фільтри можуть використовуватися Обробниками і Реєстраторами для більш складної фільтрації, ніж передбачено рівнями. Базовий клас фільтра дозволяє лише події, які знаходяться нижче певної точки в ієрархії реєстратора. Наприклад, фільтр, ініціалізований „A.B”, дозволить події, зареєстровані реєстраторами „A.B”, „A.B.C”, „A.B.C.D”, „A.B.D” тощо, але не „A.BB”, „B.A.B” тощо. Якщо ініціалізовано порожнім рядком, усі події передаються.

class logging.Filter(name='')

Повертає екземпляр класу Filter. Якщо вказано ім’я, воно називає реєстратор, події якого разом із дочірніми елементами будуть дозволені через фільтр. Якщо ім’я є порожнім рядком, дозволяється кожна подія.

filter(record)

Должна ли быть зарегистрирована указанная запись? Возвращает false в случае «нет», true в случае «да». Фильтры могут либо изменять записи журнала на месте, либо возвращать совершенно другой экземпляр записи, который заменит исходную запись журнала при любой будущей обработке события.

Зауважте, що фільтри, приєднані до обробників, звертаються до того, як обробник випустить подію, тоді як фільтри, приєднані до реєстраторів, звертаються до кожного, коли подія реєструється (за допомогою debug(), info() тощо), до відправка події обробникам. Це означає, що події, які були згенеровані нащадками реєстраторів, не будуть відфільтровані налаштуваннями фільтра реєстратора, якщо фільтр також не застосовано до цих нащадків реєстраторів.

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

Zmienione w wersji 3.2: Вам не потрібно створювати спеціалізовані класи Filter або використовувати інші класи з методом filter: ви можете використовувати функцію (або інший виклик) як фільтр. Логіка фільтрації перевірить, чи має об’єкт фільтра атрибут filter: якщо він має, він вважається Filter і викликається його метод filter(). В іншому випадку вважається, що він викликається та викликається із записом як єдиним параметром. Повернене значення має відповідати тому, яке повертає filter().

Zmienione w wersji 3.12: Теперь вы можете вернуть экземпляр LogRecord из фильтров, чтобы заменить запись журнала, а не изменять ее на месте. Это позволяет фильтрам, прикрепленным к Handler, изменять запись журнала до ее создания, не оказывая побочных эффектов на другие обработчики.

Хоча фільтри використовуються в основному для фільтрації записів на основі більш складних критеріїв, ніж рівні, вони бачать кожен запис, який обробляється обробником або реєстратором, до якого вони підключені: це може бути корисним, якщо ви хочете зробити щось, наприклад, підрахувати, скільки записи були оброблені певним реєстратором чи обробником, або додаванням, зміною чи видаленням атрибутів у LogRecord, що обробляється. Очевидно, змінювати LogRecord потрібно з певною обережністю, але це дозволяє вставляти контекстну інформацію в журнали (див. Using Filters to impart contextual information).

Об’єкти LogRecord

Екземпляри LogRecord створюються автоматично Logger щоразу, коли щось реєструється, і можуть бути створені вручну за допомогою makeLogRecord() (наприклад, з марінованої події, отриманої по мережі).

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

Містить всю інформацію, що стосується події, яка реєструється.

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

Parametry:

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

• level (int) – числовой уровень события регистрации (например, 10 для DEBUG, 20 для INFO и т. д.). Обратите внимание, что это преобразуется в два атрибута LogRecord: levelno для числового значения и levelname для соответствующего имени уровня.

• pathname (str) – Полный строковый путь к исходному файлу, в котором был выполнен вызов журнала.

• lineno (int) – Номер рядка у вихідному файлі, де було здійснено виклик журналювання.

• msg (Any) – Сообщение с описанием события, которое может быть %-f Строка формата с заполнителями для переменных данных или произвольного объекта (см. произвольные-объектные-сообщения).

• 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__ може повертати фактичний рядок формату для використання.

Zmienione w wersji 3.2: Створення LogRecord було зроблено більш настроюваним шляхом надання фабрики, яка використовується для створення запису. Фабрику можна встановити за допомогою getLogRecordFactory() і setLogRecordFactory() (див. тут підпис фабрики).

Цю функцію можна використовувати для введення ваших власних значень у LogRecord під час створення. Ви можете використовувати наступний шаблон:

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

За допомогою цього шаблону кілька фабрик можуть бути з’єднані в ланцюг, і якщо вони не перезаписують атрибути одна одної або ненавмисно перезаписують стандартні атрибути, перелічені вище, не повинно бути сюрпризів.

Атрибути LogRecord

LogRecord має низку атрибутів, більшість із яких є похідними від параметрів конструктора. (Зауважте, що імена параметрів конструктора LogRecord і атрибутів LogRecord не завжди точно збігаються.) Ці атрибути можна використовувати для об’єднання даних із запису в рядок формату. У наведеній нижче таблиці наведено (в алфавітному порядку) назви атрибутів, їх значення та відповідний заповнювач у рядку формату %-style.

Якщо ви використовуєте {}-formatting (str.format()), ви можете використовувати {attrname} як заповнювач у рядку формату. Якщо ви використовуєте $-форматування (string.Template), використовуйте форму ${attrname}. В обох випадках, звичайно, замініть attrname фактичним ім’ям атрибута, який ви хочете використовувати.

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

Назва атрибута	Format	Opis
args	Вам не потрібно форматувати це самостійно.	Кортеж аргументів об’єднано в msg для створення message або dict, значення якого використовуються для злиття (якщо є лише один аргумент, і це словник).
asctime	%(asctime)s	Зрозумілий для людини час створення LogRecord. За замовчуванням це має форму „2003-07-08 16:49:45,896” (числа після коми є частиною часу в мілісекундах).
створений	%(created)f	Время создания LogRecord (возвращенное time.time_ns() / 1e9).
exc_info	Вам не потрібно форматувати це самостійно.	Кортеж винятків (à la sys.exc_info) або, якщо винятків не сталося, None.
ім’я файлу	%(filename)s	Частина імені файлу шляху.
funcName	%(funcName)s	Назва функції, яка містить виклик журналювання.
ім’я рівня	%(levelname)s	Рівень реєстрації тексту для повідомлення ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
levelno	%(levelno)s	Числовий рівень журналювання для повідомлення (DEBUG, INFO, WARNING, ERROR, CRITICAL).
lineno	%(lineno)d	Номер вихідного рядка, де було здійснено виклик реєстрації (за наявності).
повідомлення	%(message)s	Зареєстроване повідомлення, обчислене як msg % args. Це встановлюється під час виклику Formatter.format().
moduł	%(module)s	Модуль (частина назви назви файлу).
мс	%(msecs)d	Частина мілісекунд часу, коли було створено LogRecord.
msg	Вам не потрібно форматувати це самостійно.	Рядок формату, переданий у вихідному виклику журналювання. Об’єднано з args для отримання message або довільного об’єкта (див. Using arbitrary objects as messages).
nazwa	%(name)s	Ім’я реєстратора, який використовувався для реєстрації виклику.
шлях	%(pathname)s	Повний шлях до вихідного файлу, до якого було здійснено виклик журналювання (за наявності).
процес	%(process)d	ID процесу (за наявності).
назва процесу	%(processName)s	Назва процесу (якщо є).
relativeCreated	%(relativeCreated)d	Час у мілісекундах, коли було створено LogRecord, відносно часу завантаження модуля журналювання.
stack_info	Вам не потрібно форматувати це самостійно.	Інформація про стек (якщо доступно) від нижньої частини стека в поточному потоці до та включно з кадром стека виклику журналювання, який призвів до створення цього запису.
нитка	%(thread)d	ID потоку (якщо є).
ім’я потоку	%(threadName)s	Назва теми (за наявності).
taskName	%(taskName)s	asyncio.Task имя (если доступно).

Zmienione w wersji 3.1: Додано processName.

Zmienione w wersji 3.12: taskName добавлено.

Об’єкти LoggerAdapter

Екземпляри LoggerAdapter використовуються для зручної передачі контекстної інформації у виклики журналювання. Для прикладу використання дивіться розділ про додавання контекстної інформації до вихідних даних журналу.

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

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

Zmienione w wersji 3.2: Методи isEnabledFor(), getEffectiveLevel(), setLevel() і hasHandlers() додано до LoggerAdapter . Ці методи делегують базовому реєстратору.

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

Zmienione w wersji 3.13: Был добавлен аргумент merge_extra.

Безпека ниток

The logging module is intended to be thread-safe without any special work needing to be done by its clients. It achieves this through using threading locks; there is one lock to serialize access to the module’s shared data, and each handler also creates a lock to serialize access to its underlying I/O.

Якщо ви впроваджуєте асинхронні обробники сигналів за допомогою модуля signal, можливо, ви не зможете використовувати журналювання в таких обробниках. Це пов’язано з тим, що реалізації блокувань у модулі threading не завжди можна повторно входити, і тому їх не можна викликати з таких обробників сигналів.

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

На додаток до класів, описаних вище, існує ряд функцій рівня модуля.

logging.getLogger(name=None)

Возвращает регистратор с указанным именем или, если имя равно «Нет», возвращает корневой регистратор иерархии. Если указано, имя обычно представляет собой иерархическое имя, разделенное точкой, например «a», «ab» или «abcd». Выбор этих имен полностью зависит от разработчика, использующего журналирование, хотя рекомендуется использовать __name__, если у вас нет особой причины не делать этого, как указано в Логер об’єктів.

Усі виклики цієї функції з заданим іменем повертають той самий екземпляр журналу. Це означає, що екземпляри реєстратора ніколи не потрібно передавати між різними частинами програми.

logging.getLoggerClass()

Повертає або стандартний клас Logger, або останній клас, переданий setLoggerClass(). Цю функцію можна викликати з нового визначення класу, щоб гарантувати, що встановлення налаштованого класу Logger не скасує налаштування, уже застосовані іншим кодом. Наприклад:

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

logging.getLogRecordFactory()

Повертає виклик, який використовується для створення LogRecord.

Dodane w wersji 3.2: Цю функцію було надано разом із setLogRecordFactory(), щоб дозволити розробникам більше контролювати те, як створюється LogRecord, що представляє подію журналювання.

Перегляньте setLogRecordFactory() для отримання додаткової інформації про те, як називається фабрика.

logging.debug(msg, *args, **kwargs)

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

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

For very short scripts or quick demonstrations of logging facilities, debug and the other module-level functions may be convenient. However, most programs will want to carefully and explicitly control the logging configuration, and should therefore prefer creating a module-level logger and calling Logger.debug() (or other level-specific methods) on it, as described at the beginnning of this documentation.

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

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

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

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

Informacja

Існує застаріла функція 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)

Забезпечує переважний рівень рівень для всіх реєстраторів, який має перевагу над власним рівнем реєстратора. Ця функція може бути корисною, коли виникає потреба тимчасово зменшити вивід журналювання в усій програмі. Його ефект полягає в тому, щоб вимкнути всі виклики журналювання рівня серйозності рівня і нижче, так що якщо ви викликаєте його зі значенням INFO, тоді всі події INFO та DEBUG будуть відхилені, тоді як події серйозності WARNING і вище будуть оброблені відповідно до ефективний рівень реєстратора. Якщо викликається logging.disable(logging.NOTSET), це фактично видаляє цей переважний рівень, так що вихід журналу знову залежить від ефективних рівнів окремих реєстраторів.

Зауважте, що якщо ви визначили будь-який спеціальний рівень журналювання, вищий за КРИТИЧНИЙ (це не рекомендовано), ви не зможете покладатися на значення за замовчуванням для параметра level, але вам доведеться явно вказати відповідне значення.

Zmienione w wersji 3.7: Параметр level за замовчуванням мав рівень КРИТИЧНИЙ. Перегляньте bpo-28524, щоб дізнатися більше про цю зміну.

logging.addLevelName(level, levelName)

Пов’язує рівень level із текстом levelName у внутрішньому словнику, який використовується для відображення числових рівнів у текстовому представленні, наприклад, коли Formatter форматує повідомлення. Цю функцію також можна використовувати для визначення власних рівнів. Єдині обмеження полягають у тому, що всі використовувані рівні мають бути зареєстровані за допомогою цієї функції, рівні мають бути додатними цілими числами, і вони мають збільшуватися в порядку зростання серйозності.

Informacja

Якщо ви плануєте визначити власні рівні, перегляньте розділ про Custom Levels.

logging.getLevelNamesMapping()

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

Dodane w wersji 3.11.

logging.getLevelName(level)

Повертає текстове або числове представлення рівня реєстрації level.

Якщо level є одним із попередньо визначених рівнів CRITICAL, ERROR, WARNING, INFO або DEBUG, тоді ви отримаєте відповідний рядок . Якщо ви пов’язали рівні з іменами за допомогою addLevelName(), тоді повертається ім’я, яке ви пов’язали з рівнем. Якщо передано числове значення, що відповідає одному з визначених рівнів, повертається відповідне представлення рядка.

Параметр level також приймає рядкове представлення рівня, наприклад „INFO”. У таких випадках ця функція повертає відповідне числове значення рівня.

Якщо відповідного числового або рядкового значення не передано, повертається рядок „Рівень %s” % рівня.

Informacja

Рівні є внутрішніми цілими числами (оскільки їх потрібно порівнювати в логіці журналювання). Ця функція використовується для перетворення між цілочисельним рівнем і назвою рівня, що відображається у форматованому виведенні журналу за допомогою специфікатора формату %(levelname)s (див. Атрибути LogRecord), і навпаки.

Zmienione w wersji 3.4: У версіях Python, раніших за 3.4, ця функція також могла передаватися на текстовий рівень і повертала б відповідне числове значення рівня. Ця незадокументована поведінка вважалася помилкою та була видалена в Python 3.4, але відновлена в 3.4.2 через збереження зворотної сумісності.

logging.getHandlerByName(name)

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

Dodane w wersji 3.12.

logging.getHandlerNames()

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

Dodane w wersji 3.12.

logging.makeLogRecord(attrdict)

Створює та повертає новий екземпляр LogRecord, атрибути якого визначено attrdict. Ця функція корисна для того, щоб взяти вибраний словник атрибутів LogRecord, надісланий через сокет, і відтворити його як екземпляр LogRecord на кінці прийому.

logging.basicConfig(**kwargs)

Виконує базову конфігурацію для системи журналювання, створюючи StreamHandler із стандартним Formatter і додаючи його до кореневого реєстратора. Функції debug(), info(), warning(), error() і critical() викличуть basicConfig() автоматично, якщо не визначено обробників для кореневого реєстратора.

Ця функція нічого не робить, якщо кореневий реєстратор уже має налаштовані обробники, якщо для ключового аргументу force не встановлено значення True.

Informacja

Цю функцію слід викликати з основного потоку перед запуском інших потоків. У версіях Python до 2.7.1 і 3.2, якщо ця функція викликається з кількох потоків, можливо (у рідкісних випадках), що обробник буде додано до кореневого журналу більше одного разу, що призведе до неочікуваних результатів, таких як повідомлення дублюється в журналі.

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

Format	Opis
назва файлу	Вказує, що буде створено FileHandler, використовуючи вказане ім’я файлу, а не StreamHandler.
файловий режим	Якщо вказано ім’я файлу, відкрийте файл у цьому режимі. За замовчуванням 'a''.
формат	Використовуйте вказаний рядок формату для обробника. За замовчуванням атрибути levelname, name і message, розділені двокрапками.
datefmt	Використовуйте вказаний формат дати/часу, прийнятний time.strftime().
стиль	Якщо вказано format, використовуйте цей стиль для рядка формату. Один із '%', '{' або '$' для printf-style, str.format() або string .Template відповідно. За замовчуванням '%''.
рівень	Встановіть рівень кореневого реєстратора на вказаний level.
потік	Використовуйте вказаний потік для ініціалізації StreamHandler. Зауважте, що цей аргумент несумісний з ім’ям файлу – якщо присутні обидва, виникає помилка „ValueError”.
обробники	Якщо вказано, це має бути ітерація вже створених обробників для додавання до кореневого реєстратора. Усім обробникам, які ще не мають встановленого форматера, буде призначено стандартний форматер, створений у цій функції. Зауважте, що цей аргумент несумісний з filename або stream - якщо обидва присутні, виникає помилка ValueError.
сила	Якщо цей аргумент ключового слова вказано як true, будь-які існуючі обробники, приєднані до кореневого реєстратора, видаляються та закриваються перед виконанням конфігурації, як зазначено іншими аргументами.
кодування	Якщо цей аргумент ключового слова вказано разом із filename, його значення використовується під час створення FileHandler і, таким чином, використовується під час відкриття вихідного файлу.
помилки	Якщо цей аргумент ключового слова вказано разом із filename, його значення використовується під час створення FileHandler і, таким чином, використовується під час відкриття вихідного файлу. Якщо не вказано, використовується значення „backslashreplace”. Зауважте, що якщо вказано None, воно буде передано як таке до open(), що означає, що воно розглядатиметься так само, як передача «errors».

Zmienione w wersji 3.2: Додано аргумент style.

Zmienione w wersji 3.3: Додано аргумент обробники. Було додано додаткові перевірки для виявлення ситуацій, коли вказано несумісні аргументи (наприклад, обробники разом із потоком або ім’ям файлу, або потік разом із ім’ям файлу).

Zmienione w wersji 3.8: Додано аргумент force.

Zmienione w wersji 3.9: Додано аргументи encoding і errors.

logging.shutdown()

Повідомляє системі журналювання виконати впорядковане завершення роботи шляхом очищення та закриття всіх обробників. Це слід викликати під час виходу з програми, і після цього виклику не слід використовувати систему журналювання.

Коли модуль журналювання імпортовано, він реєструє цю функцію як обробник виходу (див. atexit), тому зазвичай немає потреби робити це вручну.

logging.setLoggerClass(klass)

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

logging.setLogRecordFactory(factory)

Встановіть виклик, який використовується для створення LogRecord.

Parametry:

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

Dodane w wersji 3.2: Цю функцію було надано разом із getLogRecordFactory(), щоб дозволити розробникам більше контролювати те, як створюється LogRecord, що представляє подію журналювання.

Завод має такий підпис:

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

nazwa:

Ім’я реєстратора.

рівень:

Рівень журналювання (числовий).

fn:

Повний шлях до файлу, у якому було здійснено виклик журналювання.

lno:

Номер рядка у файлі, де було здійснено виклик журналювання.

msg:

Повідомлення реєстрації.

args:

Аргументи для повідомлення журналу.

exc_info:

Кортеж винятків або None.

func:

Ім’я функції або методу, які викликали журналювання.

sinfo:

Зворотне трасування стека, наприклад, надається traceback.print_stack(), показуючи ієрархію викликів.

kwargs:

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

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

logging.lastResort

Через цей атрибут доступний „обробник останньої надії”. Це StreamHandler, який записує в sys.stderr з рівнем WARNING і використовується для обробки подій журналювання за відсутності будь-якої конфігурації журналювання. Кінцевим результатом є просто друк повідомлення в sys.stderr. Це замінює попереднє повідомлення про помилку про те, що „не вдалося знайти обробників для реєстратора XYZ”. Якщо з якоїсь причини вам потрібна попередня поведінка, для lastResort можна встановити значення None.

Dodane w wersji 3.2.

logging.raiseExceptions

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

По умолчанию: Истина.

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

Інтеграція з модулем попереджень

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

logging.captureWarnings(capture)

Ця функція використовується для ввімкнення та вимкнення захоплення попереджень під час входу.

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

Якщо capture має значення False, перенаправлення попереджень до системи журналювання припиниться, і попередження будуть перенаправлені до початкових місць призначення (тобто тих, які діяли до виклику captureWarnings(True)).

Zobacz także

Модуль logging.config

API конфігурації для модуля журналювання.

Модуль logging.handlers

Корисні обробники, включені в модуль журналювання.

PEP 282 - Система реєстрації

Пропозиція, яка описує цю функцію для включення в стандартну бібліотеку Python.

Оригінальний пакет журналювання Python

Це оригінальне джерело пакета logging. Версія пакета, доступна на цьому сайті, підходить для використання з Python 1.5.2, 2.1.x і 2.2.x, які не містять пакет logging у стандартній бібліотеці.