# `logging` — Logging facility for Python

Вихідний код: Lib/logging/__init__.py

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

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

Here’s a simple example of idiomatic usage:

    # 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

The key features of this idiomatic usage is that the majority of code is simply creating a module level logger with `getLogger(__name__)`, and using that logger to do any needed logging. This is concise while allowing downstream code fine grained control if needed. Logged messages to the module-level logger get forwarded up to handlers of loggers in higher-level modules, all the way up to the root logger; for this reason this approach is known as hierarchical logging.

For logging to be useful, it needs to be configured: setting the levels and destinations for each logger, potentially changing how specific modules log, often based on command-line arguments or application configuration. In most cases, like the one above, only the root logger needs to be so configured, since all the lower level loggers at module level eventually forward their messages to its handlers. `basicConfig()` provides a quick way to configure the root logger that handles many use cases.

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

The basic classes defined by the module, together with their functions, are listed below.

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

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

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

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

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

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

The `name` is potentially a period-separated hierarchical value, like `foo.bar.baz` (though it could also be just plain `foo`, for example). Loggers that are further down in the hierarchical list are children of loggers higher up in the list. For example, given a logger with a name of `foo`, loggers with names of `foo.bar`, `foo.bar.baz`, and `foo.bam` are all descendants of `foo`. The logger name hierarchy is analogous to the Python package hierarchy, and identical to it if you organise your loggers on a per-module basis using the recommended construction `logging.getLogger(__name__)`. That’s because in a module, `__name__` is the module’s name in the Python package namespace.

class logging.Logger
  name

    This is the logger’s name, and is the value that was passed to `getLogger()` to obtain the logger.

    Примітка

    This attribute should be treated as read-only.

  level

    The threshold of this logger, as set by the `setLevel()` method.

    Примітка

    Do not set this attribute directly - always use `setLevel()`, which has checks for the level passed to it.

  parent

    The parent logger of this logger. It may change based on later instantiation of loggers which are higher up in the namespace hierarchy.

    Примітка

    This value should be treated as read-only.

  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`.

    Примітка

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

  handlers

    The list of handlers directly attached to this logger instance.

    Примітка

    This attribute should be treated as read-only; it is normally changed via the `addHandler()` and `removeHandler()` methods, which use locks to ensure thread-safe operation.

  disabled

    This attribute disables handling of any events. It is set to `False` in the initializer, and only changed by logging configuration code.

    Примітка

    This attribute should be treated as read-only.

  setLevel(level)

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

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

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

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

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

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

    Змінено в версії 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, якщо не надано 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, наприклад. щоб просто показати, як ви дійшли до певної точки у своєму коді, навіть якщо винятків не було викликано. Фрейми стека друкуються після рядка заголовка, який говорить:

        Stack (most recent call last):

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

    Третій необов’язковий аргумент ключового слова — stacklevel, який за замовчуванням має значення «1». Якщо більше 1, відповідна кількість кадрів стека пропускається під час обчислення номера рядка та назви функції, встановленої в `LogRecord`, створеному для події журналювання. Це можна використовувати в помічниках журналювання, щоб ім’я функції, ім’я файлу та номер рядка були записані не для допоміжної функції/методу, а для її викликаючого. Назва цього параметра відображає еквівалентну назву в модулі `warnings`.

    The fourth keyword argument is extra which can be used to pass a dictionary which is used to populate the __dict__ of the `LogRecord` created for the logging event with user-defined attributes. These custom attributes can then be used as you like. For example, they could be incorporated into logged messages. For example:

        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

    The keys in the dictionary passed in extra should not clash with the keys used by the logging system. (See the section on Атрибути LogRecord for more information on which keys are used by the logging system.)

    Якщо ви вирішите використовувати ці атрибути в зареєстрованих повідомленнях, вам потрібно бути обережними. У наведеному вище прикладі, наприклад, `Formatter` було налаштовано за допомогою рядка формату, який очікує „clientip“ і „user“ у словнику атрибутів `LogRecord`. Якщо вони відсутні, повідомлення не буде зареєстровано, оскільки виникне виняток форматування рядка. Тому в цьому випадку вам завжди потрібно передавати додатковий словник за допомогою цих ключів.

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

    If no handler is attached to this logger (or any of its ancestors, taking into account the relevant `Logger.propagate` attributes), the message will be sent to the handler set on `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`. Оскільки `попередження` є застарілим, будь ласка, не використовуйте його - використовуйте замість нього `попередження`.

  error(msg, *args, **kwargs)

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

  critical(msg, *args, **kwargs)

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

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

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

  exception(msg, *args, **kwargs)

    Реєструє повідомлення з рівнем `ERROR` у цьому реєстраторі. Аргументи інтерпретуються як для `debug()`. Інформація про винятки додається до повідомлення журналу. Цей метод слід викликати лише з обробника винятків.

  addFilter(filter)

    Додає вказаний фільтр filter до цього реєстратора.

  removeFilter(filter)

    Видаляє вказаний фільтр filter з цього реєстратора.

  filter(record)

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

  addHandler(hdlr)

    Додає вказаний обробник hdlr до цього реєстратора.

  removeHandler(hdlr)

    Видаляє вказаний обробник hdlr із цього реєстратора.

  findCaller(stack_info=False, stacklevel=1)

    Знаходить назву вихідного файлу абонента та номер рядка. Повертає назву файлу, номер рядка, назву функції та інформацію про стек у вигляді 4-елементного кортежу. Інформація про стек повертається як `None`, якщо stack_info не має значення `True`.

    Параметр stacklevel передається з коду, який викликає `debug()` та інші API. Якщо більше 1, надлишок використовується для пропуску кадрів стека перед визначенням значень, які потрібно повернути. Як правило, це буде корисно під час виклику API реєстрації з допоміжного коду/обгортки, щоб інформація в журналі подій стосувалася не допоміжного/оболонкового коду, а коду, який його викликає.

  handle(record)

    Обробляє запис, передаючи його всім обробникам, пов’язаним із цим реєстратором та його предками (поки не буде знайдено хибне значення propagate). Цей метод використовується для невибраних записів, отриманих із сокета, а також тих, що створюються локально. Фільтрування на рівні реєстратора застосовується за допомогою `filter()`.

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

    Це фабричний метод, який можна замінити в підкласах для створення спеціалізованих екземплярів `LogRecord`.

  hasHandlers()

    Перевіряє, чи цей реєстратор має налаштовані обробники. Це робиться шляхом пошуку обробників у цьому реєстраторі та його батьків в ієрархії реєстратора. Повертає `True`, якщо обробник знайдено, інакше `False`. Метод припиняє пошук в ієрархії щоразу, коли знайдено реєстратор з атрибутом „propagate“, встановленим на false - це буде останній реєстратор, який перевіряється на наявність обробників.

    Нове в версії 3.2.

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

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

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

Рівень | Числове значення | What it means / When to use it
--- | --- | ---
logging.NOTSET | 0 | When set on a logger, indicates that ancestor loggers are to be consulted to determine the effective level. If that still resolves to `NOTSET`, then all events are logged. When set on a handler, all events are handled.
logging.DEBUG | 10 | Detailed information, typically only of interest to a developer trying to diagnose a problem.
logging.INFO | 20 | Підтвердження того, що все працює належним чином.
logging.WARNING | 30 | An indication that something unexpected happened, or that a problem might occur in the near future (e.g. „disk space low“). The software is still working as expected.
logging.ERROR | 40 | Через більш серйозну проблему програмне забезпечення не може виконувати деякі функції.
logging.CRITICAL | 50 | Серйозна помилка, яка вказує на те, що сама програма може не працювати далі.

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

Handlers have the following attributes and methods. Note that `Handler` is never instantiated directly; this class acts as a base for more useful subclasses. However, the `__init__()` method in subclasses needs to call `Handler.__init__()`.

class logging.Handler
  __init__(level=NOTSET)

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

  createLock()

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

  acquire()

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

  release()

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

  setLevel(level)

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

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

    Змінено в версії 3.2: Параметр level тепер приймає рядкове представлення рівня, наприклад «INFO», як альтернативу цілим константам, таким як `INFO`.

  setFormatter(fmt)

    Sets the `Formatter` for this handler to fmt.

  addFilter(filter)

    Додає вказаний фільтр filter до цього обробника.

  removeFilter(filter)

    Видаляє вказаний фільтр filter з цього обробника.

  filter(record)

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

  flush()

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

  close()

    Tidy up any resources used by the handler. This version does no output but removes the handler from an internal list of handlers which is closed when `shutdown()` is called. Subclasses should ensure that this gets called from overridden `close()` methods.

  handle(record)

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

  handleError(record)

    This method should be called from handlers when an exception is encountered during an `emit()` call. If the module-level attribute `raiseExceptions` is `False`, exceptions get silently ignored. This is what is mostly wanted for a logging system - most users will not care about errors in the logging system, they are more interested in application errors. You could, however, replace this with a custom handler if you wish. The specified record is the one which was being processed when the exception occurred. (The default value of `raiseExceptions` is `True`, as that is more useful during development).

  format(record)

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

  emit(record)

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

    Попередження

    This method is called after a handler-level lock is acquired, which is released after this method returns. When you override this method, note that you should be careful when calling anything that invokes other parts of the logging API which might do locking, because that might result in a deadlock. Specifically:

    - Logging configuration APIs acquire the module-level lock, and then individual handler-level locks as those handlers are configured.

    - Many logging APIs lock the module-level lock. If such an API is called from this method, it could cause a deadlock if a configuration call is made on another thread, because that thread will try to acquire the module-level lock before the handler-level lock, whereas this thread tries to acquire the module-level lock after the handler-level lock (because in this method, the handler-level lock has already been acquired).

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

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

`Formatter` objects have the following attributes and methods. They are responsible for converting a `LogRecord` to (usually) a string which can be interpreted by either a human or an external system. The base `Formatter` allows a formatting string to be specified. If none is supplied, the default value of `'%(message)s'` is used, which just includes the message in the logging call. To have additional items of information in the formatted output (such as a timestamp), keep reading.

A Formatter can be initialized with a format string which makes use of knowledge of the `LogRecord` attributes - such as the default value mentioned above making use of the fact that the user’s message and arguments are pre-formatted into a `LogRecord`’s message attribute. This format string contains standard Python %-style mapping keys. See section Форматування рядків у стилі printf for more information on string formatting.

The useful mapping keys in a `LogRecord` are given in the section on Атрибути LogRecord.

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

  Returns a new instance of the `Formatter` class. The instance is initialized with a format string for the message as a whole, as well as a format string for the date/time portion of a message. If no fmt is specified, `'%(message)s'` is used. If no datefmt is specified, a format is used which is described in the `formatTime()` documentation.

  The style parameter can be one of „%“, „{“ or „$“ and determines how the format string will be merged with its data: using one of %-formatting, `str.format()` or `string.Template`. This only applies to the format string fmt (e.g. `'%(message)s'` or `{message}`), not to the actual log messages passed to `Logger.debug` etc; see Використання певних стилів форматування у вашій програмі for more information on using {- and $-formatting for log messages.

  The defaults parameter can be a dictionary with default values to use in custom fields. For example: `logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})`

  Змінено в версії 3.2: The style parameter was added.

  Змінено в версії 3.8: The validate parameter was added. Incorrect or mismatched style and fmt will raise a `ValueError`. For example: `logging.Formatter('%(asctime)s - %(message)s', style='{')`.

  Змінено в версії 3.10: The defaults parameter was added.

  format(record)

    Словник атрибутів запису використовується як операнд для операції форматування рядка. Повертає отриманий рядок. Перед форматуванням словника виконується кілька підготовчих кроків. Атрибут message запису обчислюється за допомогою msg % args. Якщо рядок форматування містить `'(asctime)'`, `formatTime()` викликається для форматування часу події. Якщо є інформація про винятки, вона форматується за допомогою `formatException()` і додається до повідомлення. Зауважте, що відформатована інформація про винятки кешується в атрибуті exc_text. Це корисно, оскільки інформацію про винятки можна відібрати та надіслати по мережі, але ви повинні бути обережними, якщо у вас є більше одного підкласу `Formatter`, який налаштовує форматування інформації про винятки. У цьому випадку вам доведеться очистити кешоване значення (встановивши для атрибута exc_text значення `None`) після того, як засіб форматування виконає своє форматування, щоб наступний засіб форматування для обробки події не використовував кешований значення, але перераховує його заново.

    Якщо інформація про стек доступна, вона додається після інформації про винятки, використовуючи `formatStack()` для її перетворення, якщо необхідно.

  formatTime(record, datefmt=None)

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

    Ця функція використовує настроювану користувачем функцію для перетворення часу створення в кортеж. За замовчуванням використовується `time.localtime()`; щоб змінити це для конкретного екземпляра форматера, встановіть атрибут `converter` на функцію з тим самим підписом, що й `time.localtime()` або `time.gmtime()`. Щоб змінити його для всіх засобів форматування, наприклад, якщо ви хочете, щоб усі часи журналювання відображалися за GMT, установіть атрибут `converter` у класі `Formatter`.

    Змінено в версії 3.3: Раніше формат за замовчуванням був жорстко закодований, як у цьому прикладі: `2010-09-06 22:38:15,292`, де частина перед комою обробляється рядком формату strptime (`'%Y-%m -%d %H:%M:%S''`), а частина після коми є значенням у мілісекундах. Оскільки strptime не має заповнювача формату для мілісекунд, значення мілісекунди додається за допомогою іншого рядка формату, `'%s,%03d''` — і обидва ці рядки формату були жорстко закодовані в цьому методі. Зі зміною ці рядки визначаються як атрибути рівня класу, які за бажанням можна замінити на рівні екземпляра. Назви атрибутів: `default_time_format` (для рядка формату strptime) і `default_msec_format` (для додавання значення в мілісекундах).

    Змінено в версії 3.9: `default_msec_format` може бути `None`.

  formatException(exc_info)

    Форматує вказану інформацію про винятки (стандартний кортеж винятків, який повертає `sys.exc_info()`) як рядок. Ця реалізація за умовчанням просто використовує `traceback.print_exception()`. Повертається отриманий рядок.

  formatStack(stack_info)

    Форматує вказану інформацію про стек (рядок, який повертає `traceback.print_stack()`, але з видаленням останнього нового рядка) як рядок. Ця реалізація за умовчанням лише повертає вхідне значення.

class logging.BufferingFormatter(linefmt=None)

  A base formatter class suitable for subclassing when you want to format a number of records. You can pass a `Formatter` instance which you want to use to format each line (that corresponds to a single record). If not specified, the default formatter (which just outputs the event message) is used as the line formatter.

  formatHeader(records)

    Return a header for a list of records. The base implementation just returns the empty string. You will need to override this method if you want specific behaviour, e.g. to show the count of records, a title or a separator line.

  formatFooter(records)

    Return a footer for a list of records. The base implementation just returns the empty string. You will need to override this method if you want specific behaviour, e.g. to show the count of records or a separator line.

  format(records)

    Return formatted text for a list of records. The base implementation just returns the empty string if there are no records; otherwise, it returns the concatenation of the header, each record formatted with the line formatter, and the footer.

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

`Фільтри` можуть використовуватися `Обробниками` і `Реєстраторами` для більш складної фільтрації, ніж передбачено рівнями. Базовий клас фільтра дозволяє лише події, які знаходяться нижче певної точки в ієрархії реєстратора. Наприклад, фільтр, ініціалізований «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)

    Is the specified record to be logged? Returns zero for no, nonzero for yes. If deemed appropriate, the record may be modified in-place by this method.

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

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

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

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

## Об’єкти LogRecord

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

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

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

  The primary information is passed in msg and args, which are combined using `msg % args` to create the `message` attribute of the record.

  Параметри:

    - name (str) – The name of the logger used to log the event represented by this `LogRecord`. Note that the logger name in the `LogRecord` will always have this value, even though it may be emitted by a handler attached to a different (ancestor) logger.

    - level (int) – The numeric level of the logging event (such as `10` for `DEBUG`, `20` for `INFO`, etc). Note that this is converted to two attributes of the LogRecord: `levelno` for the numeric value and `levelname` for the corresponding level name.

    - pathname (str) – The full string path of the source file where the logging call was made.

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

    - msg (Any) – The event description message, which can be a %-format string with placeholders for variable data, or an arbitrary object (see Використання довільних об’єктів як повідомлень).

    - args (tuple | dict[str, Any]) – Змінні дані, які потрібно об’єднати в аргумент msg, щоб отримати опис події.

    - exc_info (tuple[type[BaseException], BaseException, types.TracebackType] | None) – An exception tuple with the current exception information, as returned by `sys.exc_info()`, or `None` if no exception information is available.

    - func (str | None) – Ім’я функції або методу, з якого було викликано журналювання.

    - sinfo (str | None) – Текстовий рядок, що представляє інформацію про стек від основи стека в поточному потоці до виклику журналювання.

  getMessage()

    Повертає повідомлення для цього екземпляра `LogRecord` після об’єднання будь-яких наданих користувачем аргументів із повідомленням. Якщо наданий користувачем аргумент повідомлення для виклику журналювання не є рядком, `str()` викликається для нього, щоб перетворити його на рядок. Це дозволяє використовувати визначені користувачем класи як повідомлення, чий метод `__str__` може повертати фактичний рядок формату для використання.

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

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

      old_factory = logging.getLogRecordFactory()

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

      logging.setLogRecordFactory(record_factory)

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

## Атрибути LogRecord

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

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

In the case of {}-formatting, you can specify formatting flags by placing them after the attribute name, separated from it with a colon. For example: a placeholder of `{msecs:03.0f}` would format a millisecond value of `4` as `004`. Refer to the `str.format()` documentation for full details on the options available to you.

Назва атрибута | Формат | опис
--- | --- | ---
арг | Вам не потрібно форматувати це самостійно. | Кортеж аргументів об’єднано в `msg` для створення `message` або dict, значення якого використовуються для злиття (якщо є лише один аргумент, і це словник).
asctime | `%(asctime)s` | Зрозумілий для людини час створення `LogRecord`. За замовчуванням це має форму «2003-07-08 16:49:45,896» (числа після коми є частиною часу в мілісекундах).
створений | `%(created)f` | Time when the `LogRecord` was created (as returned by `time.time()`).
exc_info | Вам не потрібно форматувати це самостійно. | Кортеж винятків (à la `sys.exc_info`) або, якщо винятків не сталося, `None`.
ім’я файлу | `%(filename)s` | Частина імені файлу `шляху`.
ім’я функції | `%(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()`.
модуль | `%(module)s` | Модуль (частина назви `назви файлу`).
мс | `%(msecs)d` | Частина мілісекунд часу, коли було створено `LogRecord`.
повідомлення | Вам не потрібно форматувати це самостійно. | Рядок формату, переданий у вихідному виклику журналювання. Об’єднано з `args` для отримання `message` або довільного об’єкта (див. Використання довільних об’єктів як повідомлень).
назва | `%(name)s` | Ім’я реєстратора, який використовувався для реєстрації виклику.
шлях | `%(pathname)s` | Повний шлях до вихідного файлу, до якого було здійснено виклик журналювання (за наявності).
процес | `%(process)d` | ID процесу (за наявності).
назва процесу | `%(processName)s` | Назва процесу (якщо є).
relativeCreated | `%(relativeCreated)d` | Час у мілісекундах, коли було створено LogRecord, відносно часу завантаження модуля журналювання.
stack_info | Вам не потрібно форматувати це самостійно. | Інформація про стек (якщо доступно) від нижньої частини стека в поточному потоці до та включно з кадром стека виклику журналювання, який призвів до створення цього запису.
нитка | `%(thread)d` | ID потоку (якщо є).
ім’я потоку | `%(threadName)s` | Назва теми (за наявності).

Змінено в версії 3.1: Додано processName.

## Об’єкти LoggerAdapter

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

class logging.LoggerAdapter(logger, extra)

  Returns an instance of `LoggerAdapter` initialized with an underlying `Logger` instance and a dict-like object.

  process(msg, kwargs)

    Змінює повідомлення та/або ключові аргументи, передані виклику журналювання, щоб вставити контекстну інформацію. Ця реалізація приймає об’єкт, переданий як extra до конструктора, і додає його до kwargs за допомогою ключа «extra». Поверненим значенням є кортеж (msg, kwargs), який містить (можливо, змінені) версії переданих аргументів.

  manager

    Delegates to the underlying `manager`` on logger.

  _log

    Delegates to the underlying `_log`()` method on logger.

  На додаток до вищезазначеного, `LoggerAdapter` підтримує такі методи `Logger`: `debug()`, `info()`, `warning()`, `error()`, `exception()`, `critical()`, `log()`, `isEnabledFor()`, `getEffectiveLevel()`, `setLevel()` і `hasHandlers()`. Ці методи мають ті самі сигнатури, що й їхні аналоги в `Logger`, тому ви можете використовувати обидва типи екземплярів як взаємозамінні.

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

  Змінено в версії 3.6: Attribute `manager` and method `_log()` were added, which delegate to the underlying logger and allow adapters to be nested.

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

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

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

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

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

logging.getLogger(name=None)

  Return a logger with the specified name or, if name is `None`, return a logger which is the root logger of the hierarchy. If specified, the name is typically a dot-separated hierarchical name like „a“, „a.b“ or „a.b.c.d“. Choice of these names is entirely up to the developer who is using logging.

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

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)

  This is a convenience function that calls `Logger.debug()`, on the root logger. The handling of the arguments is in every way identical to what is described in that method.

  The only difference is that if the root logger has no handlers, then `basicConfig()` is called, prior to calling `debug` on the root logger.

  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)

  Logs a message with level `INFO` on the root logger. The arguments and behavior are otherwise the same as for `debug()`.

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

  Logs a message with level `WARNING` on the root logger. The arguments and behavior are otherwise the same as for `debug()`.

  Примітка

  Існує застаріла функція `warn`, яка функціонально ідентична `warning`. Оскільки `попередження` застаріло, будь ласка, не використовуйте його - використовуйте замість нього `попередження`.

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

  Logs a message with level `ERROR` on the root logger. The arguments and behavior are otherwise the same as for `debug()`.

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

  Logs a message with level `CRITICAL` on the root logger. The arguments and behavior are otherwise the same as for `debug()`.

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

  Logs a message with level `ERROR` on the root logger. The arguments and behavior are otherwise the same as for `debug()`. Exception info is added to the logging message. This function should only be called from an exception handler.

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

  Logs a message with level level on the root logger. The arguments and behavior are otherwise the same as for `debug()`.

logging.disable(level=CRITICAL)

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

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

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

logging.addLevelName(level, levelName)

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

  Примітка

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

logging.getLevelNamesMapping()

  Returns a mapping from level names to their corresponding logging levels. For example, the string «CRITICAL» maps to `CRITICAL`. The returned mapping is copied from an internal mapping on each call to this function.

  Нове в версії 3.11.

logging.getLevelName(level)

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

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

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

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

  Примітка

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

  Змінено в версії 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`.
  файловий режим | Якщо вказано ім’я файлу, відкрийте файл у цьому режимі. За замовчуванням `'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“.

  Змінено в версії 3.2: Додано аргумент style.

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

  Змінено в версії 3.8: Додано аргумент force.

  Змінено в версії 3.9: Додано аргументи encoding і errors.

logging.shutdown()

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

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

logging.setLoggerClass(klass)

  Tells the logging system to use the class klass when instantiating a logger. The class should define `__init__()` such that only a name argument is required, and the `__init__()` should call `Logger.__init__()`. This function is typically called before any loggers are instantiated by applications which need to use custom logger behavior. After this call, as at any other time, do not instantiate loggers directly using the subclass: continue to use the `logging.getLogger()` API to get your loggers.

logging.setLogRecordFactory(factory)

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

  Параметри:

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

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

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

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

  > назва:

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

  > рівень:

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

  > фн:

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

  > льно:

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

  > повідомлення:

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

  > арг:

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

  > exc_info:

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

  > функц:

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

  > sinfo:

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

  > kwargs:

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

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

logging.lastResort

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

  Нове в версії 3.2.

logging.raiseExceptions

  Used to see if exceptions during handling should be propagated.

  Default: `True`.

  If `raiseExceptions` is `False`, exceptions get silently ignored. This is what is mostly wanted for a logging system - most users will not care about errors in the logging system, they are more interested in application errors.

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

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

logging.captureWarnings(capture)

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

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

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

Дивись також

Модуль `logging.config`

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

Модуль `logging.handlers`

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

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

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

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

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