logging.config.md
1> **Источник:** https://python-all.ru/3.5/library/logging.config.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 16.7. [`logging.config`](https://python-all.ru/3.5/library/logging.config.html#module-logging.config) – Конфигурация логирования89**Исходный код:** [Lib/logging/config.py](https://python-all.ru/src/3.5/Lib/logging/config.py)1011Важно1213На этой странице представлена только справочная информация. Учебные руководства см. в1415- [Базовое руководство](https://python-all.ru/3.5/howto/logging.html#logging-basic-tutorial)16- [Продвинутое руководство](https://python-all.ru/3.5/howto/logging.html#logging-advanced-tutorial)17- [Поваренная книга по логированию](https://python-all.ru/3.5/howto/logging-cookbook.html#logging-cookbook)1819---2021В этом разделе описывается API для настройки модуля logging.2223## 16.7.1. Функции конфигурации2425Следующие функции настраивают модуль logging. Они находятся в модуле [`logging.config`](https://python-all.ru/3.5/library/logging.config.html#module-logging.config). Их использование не обязательно – модуль logging можно настраивать с помощью этих функций или напрямую обращаясь к основному API (определённому в самом [`logging`](https://python-all.ru/3.5/library/logging.html#module-logging)), а также определяя обработчики, объявленные в [`logging`](https://python-all.ru/3.5/library/logging.html#module-logging) или [`logging.handlers`](https://python-all.ru/3.5/library/logging.handlers.html#module-logging.handlers).2627#### `logging.config.dictConfig(config)`2829> Принимает конфигурацию логирования из словаря. Содержимое этого словаря описано ниже в разделе [Схема словаря конфигурации](https://python-all.ru/3.5/library/logging.config.html#logging-config-dictschema).30>31> Если во время настройки возникает ошибка, эта функция возбуждает [`ValueError`](https://python-all.ru/3.5/library/exceptions.html#ValueError), [`TypeError`](https://python-all.ru/3.5/library/exceptions.html#TypeError), [`AttributeError`](https://python-all.ru/3.5/library/exceptions.html#AttributeError) или [`ImportError`](https://python-all.ru/3.5/library/exceptions.html#ImportError) с соответствующим описанием. Ниже приведён (возможно, неполный) перечень условий, при которых возникает ошибка:32>33> - Значение `level`, не являющееся строкой или являющееся строкой, не соответствующей ни одному реальному уровню логирования.34> - Значение `propagate`, не являющееся булевым.35> - Идентификатор, для которого нет соответствующего получателя.36> - Идентификатор несуществующего обработчика, обнаруженный во время инкрементального вызова.37> - Некорректное имя логгера.38> - Невозможность разрешить ссылку на внутренний или внешний объект.39>40> Разбор выполняется классом `DictConfigurator`, конструктору которого передаётся словарь конфигурации; этот класс имеет метод `configure()`. В модуле [`logging.config`](https://python-all.ru/3.5/library/logging.config.html#module-logging.config) есть вызываемый атрибут `dictConfigClass`, изначально установленный в `DictConfigurator`. Вы можете заменить значение `dictConfigClass` на собственную подходящую реализацию.41>42> [`dictConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.dictConfig) вызывает `dictConfigClass`, передавая указанный словарь, а затем вызывает метод `configure()` возвращённого объекта, чтобы применить конфигурацию:43>44> ```python45> def dictConfig(config):46> dictConfigClass(config).configure()47> ```48>49> Например, подкласс `DictConfigurator` может вызывать `DictConfigurator.__init__()` в собственном методе [`__init__()`](https://python-all.ru/3.5/reference/datamodel.html#object.__init__), а затем задать пользовательские префиксы, которые будут использоваться при последующем вызове `configure()`. `dictConfigClass` будет привязан к этому новому подклассу, и [`dictConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.dictConfig) можно будет вызывать так же, как и в состоянии по умолчанию, без настройки.5051Новое в версии 3.2.5253#### `logging.config.fileConfig(fname, defaults=None, disable_existing_loggers=True)`5455Читает конфигурацию логирования из файла в формате [`configparser`](https://python-all.ru/3.5/library/configparser.html#module-configparser). Формат файла должен соответствовать описанию в разделе [Формат конфигурационного файла](https://python-all.ru/3.5/library/logging.config.html#logging-config-fileformat). Эту функцию можно вызывать несколько раз в приложении, что позволяет конечному пользователю выбирать из нескольких готовых конфигураций (если разработчик предоставляет механизм для выбора и загрузки выбранной конфигурации).5657| Параметры: | **fname** – имя файла, или файлоподобный объект, или экземпляр, производный от [`RawConfigParser`](https://python-all.ru/3.5/library/configparser.html#configparser.RawConfigParser). Если передан экземпляр, производный от `RawConfigParser`, он используется как есть. В противном случае создаётся `Configparser`, и конфигурация считывается им из объекта, переданного в `fname`. Если у этого объекта есть метод [`readline()`](https://python-all.ru/3.5/library/readline.html#module-readline), предполагается, что это файлоподобный объект, и чтение выполняется через [`read_file()`](https://python-all.ru/3.5/library/configparser.html#configparser.ConfigParser.read_file); в противном случае считается, что это имя файла, и оно передаётся в [`read()`](https://python-all.ru/3.5/library/configparser.html#configparser.ConfigParser.read). **defaults** – значения по умолчанию, передаваемые ConfigParser, можно указать в этом аргументе. **disable\_existing\_loggers** – Если указано как `False`, то логгеры, существующие на момент вызова, остаются включёнными. По умолчанию `True`, так как это обеспечивает обратно совместимое поведение. Это поведение отключает все существующие логгеры, если только они или их предки явно не указаны в конфигурации логирования. |58| --- | --- |5960Изменено в версии 3.4: Экземпляр подкласса [`RawConfigParser`](https://python-all.ru/3.5/library/configparser.html#configparser.RawConfigParser) теперь принимается как значение для `fname`. Это позволяет:6162- Использование конфигурационного файла, где настройка логирования является лишь частью общей конфигурации приложения.63- Использование конфигурации, прочитанной из файла и затем изменённой приложением (например, на основе параметров командной строки или других аспектов среды выполнения) перед передачей в `fileConfig`.6465#### `logging.config.listen(port=DEFAULT_LOGGING_CONFIG_PORT, verify=None)`6667Запускает сокет-сервер на указанном порту и ожидает новые конфигурации. Если порт не указан, используется значение по умолчанию модуля `DEFAULT_LOGGING_CONFIG_PORT`. Конфигурации логирования будут отправляться в виде файла, пригодного для обработки с помощью [`dictConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.dictConfig) или [`fileConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.fileConfig). Возвращает экземпляр [`Thread`](https://python-all.ru/3.5/library/threading.html#threading.Thread), на котором можно вызвать [`start()`](https://python-all.ru/3.5/library/threading.html#threading.Thread.start) для запуска сервера и который можно [`join()`](https://python-all.ru/3.5/library/threading.html#threading.Thread.join), когда необходимо. Чтобы остановить сервер, вызовите [`stopListening()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.stopListening).6869Аргумент `verify`, если он указан, должен быть вызываемым объектом, который проверяет, являются ли полученные через сокет байты допустимыми и должны ли быть обработаны. Это можно сделать, зашифровав и/или подписав передаваемые через сокет данные, чтобы вызываемый объект `verify` мог выполнить проверку подписи и/или расшифровку. Вызываемый объект `verify` вызывается с одним аргументом – байтами, полученными через сокет, – и должен вернуть байты для обработки или `None`, чтобы указать, что байты следует отбросить. Возвращённые байты могут совпадать с переданными (например, когда выполняется только проверка) или быть совершенно другими (возможно, если была выполнена расшифровка).7071Чтобы отправить конфигурацию в сокет, прочитайте файл конфигурации и отправьте его в сокет в виде последовательности байтов, перед которыми идёт четырёхбайтовая строка длины, упакованная в двоичном виде с помощью `struct.pack('>L', n)`.7273> **Примечание**74>75> Поскольку части конфигурации передаются через [`eval()`](https://python-all.ru/3.5/library/functions.html#eval), использование этой функции может подвергнуть пользователей риску безопасности. Хотя функция привязывается только к сокету на `localhost` и поэтому не принимает соединения с удалённых машин, существуют сценарии, в которых недоверенный код может быть выполнен под учётной записью процесса, вызывающего [`listen()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.listen). В частности, если процесс, вызывающий [`listen()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.listen), работает на многопользовательской машине, где пользователи не доверяют друг другу, злоумышленник может организовать выполнение произвольного кода в процессе жертвы, просто подключившись к сокету [`listen()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.listen) жертвы и отправив конфигурацию, которая запускает любой код, который злоумышленник хочет выполнить в процессе жертвы. Это особенно легко сделать, если используется порт по умолчанию, но не сложно, даже если используется другой порт). Чтобы избежать риска, используйте аргумент `verify` в [`listen()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.listen), чтобы предотвратить применение нераспознанных конфигураций.7677Изменено в версии 3.4: Добавлен аргумент `verify`.7879> **Примечание**80>81> Если вы хотите отправлять прослушивателю конфигурации, которые не отключают существующие регистраторы, вам нужно использовать формат JSON для конфигурации, который будет использовать [`dictConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.dictConfig) для настройки. Этот метод позволяет указать `disable_existing_loggers` как `False` в отправляемой конфигурации.8283#### `logging.config.stopListening()`8485Останавливает сервер прослушивания, созданный вызовом [`listen()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.listen). Обычно вызывается перед вызовом `join()` для возвращаемого значения из [`listen()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.listen).8687## 16.7.2. Схема словаря конфигурации8889Описание конфигурации логирования требует перечисления различных создаваемых объектов и связей между ними; например, можно создать обработчик с именем «console», а затем указать, что регистратор с именем «startup» будет отправлять свои сообщения обработчику «console». Эти объекты не ограничиваются теми, что предоставляются модулем [`logging`](https://python-all.ru/3.5/library/logging.html#module-logging), поскольку можно написать собственный класс форматтера или обработчика. Параметры этих классов также могут включать внешние объекты, такие как `sys.stderr`. Синтаксис для описания этих объектов и связей определён ниже в разделе [Связи объектов](https://python-all.ru/3.5/library/logging.config.html#logging-config-dict-connections).9091### 16.7.2.1. Подробности схемы словаря9293Словарь, передаваемый [`dictConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.dictConfig), должен содержать следующие ключи:9495- *version* – должно быть установлено целочисленное значение, представляющее версию схемы. Единственное допустимое значение на данный момент – 1, но наличие этого ключа позволяет схеме развиваться, сохраняя обратную совместимость.9697Все остальные ключи необязательны, но если они присутствуют, то будут интерпретироваться, как описано ниже. Во всех случаях, когда ниже упоминается «настраивающий словарь», в нём будет проверяться наличие специального ключа `'()'`, чтобы определить, требуется ли пользовательское создание экземпляра. Если да, то используется механизм, описанный ниже в разделе [Пользовательские объекты](https://python-all.ru/3.5/library/logging.config.html#logging-config-dict-userdef), для создания экземпляра; в противном случае контекст используется для определения того, что создавать.9899- *formatters* – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор форматтера, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр [`Formatter`](https://python-all.ru/3.5/library/logging.html#logging.Formatter).100101 В словаре конфигурации выполняется поиск ключей `format` и `datefmt` (со значениями по умолчанию `None`), и они используются для создания экземпляра [`Formatter`](https://python-all.ru/3.5/library/logging.html#logging.Formatter).102- *filters* – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор фильтра, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Filter.103104 В настраивающем словаре ищется ключ `name` (по умолчанию пустая строка), и он используется для создания экземпляра [`logging.Filter`](https://python-all.ru/3.5/library/logging.html#logging.Filter).105- *handlers* – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор обработчика, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Handler.106107 В словаре конфигурации ищутся следующие ключи:108109 - `class` (обязательный). Это полное имя класса обработчика.110 - `level` (необязательный). Уровень обработчика.111 - `formatter` (необязательный). Идентификатор форматтера для этого обработчика.112 - `filters` (необязательный). Список идентификаторов фильтров для этого обработчика.113114 Все *остальные* ключи передаются как именованные аргументы конструктору обработчика. Например, для следующего фрагмента:115116 ```yaml117 handlers:118 console:119 class : logging.StreamHandler120 formatter: brief121 level : INFO122 filters: [allow_foo]123 stream : ext://sys.stdout124 file:125 class : logging.handlers.RotatingFileHandler126 formatter: precise127 filename: logconfig.log128 maxBytes: 1024129 backupCount: 3130 ```131132 обработчик с идентификатором `console` создаётся как [`logging.StreamHandler`](https://python-all.ru/3.5/library/logging.handlers.html#logging.StreamHandler), используя `sys.stdout` в качестве базового потока. Обработчик с идентификатором `file` создаётся как [`logging.handlers.RotatingFileHandler`](https://python-all.ru/3.5/library/logging.handlers.html#logging.handlers.RotatingFileHandler) с именованными аргументами `filename='logconfig.log', maxBytes=1024, backupCount=3`.133- *loggers* – соответствующее значение будет словарём, в котором каждый ключ – это имя регистратора, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Logger.134135 В словаре конфигурации ищутся следующие ключи:136137 - `level` (необязательно). Уровень регистратора.138 - `propagate` (необязательно). Настройка распространения записей регистратора.139 - `filters` (необязательно). Список идентификаторов фильтров для этого регистратора.140 - `handlers` (необязательно). Список идентификаторов обработчиков для этого регистратора.141142 Указанные регистраторы будут настроены в соответствии с заданными уровнем, распространением, фильтрами и обработчиками.143- *root* – это конфигурация корневого регистратора. Обработка конфигурации будет такой же, как и для любого другого регистратора, за исключением того, что параметр `propagate` не применяется.144- *incremental* – следует ли интерпретировать конфигурацию как дополнение к существующей. Значение по умолчанию – `False`, что означает, что указанная конфигурация заменяет существующую с той же семантикой, которая используется существующим API [`fileConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.fileConfig).145146 Если указано значение `True`, конфигурация обрабатывается так, как описано в разделе [Incremental Configuration](https://python-all.ru/3.5/library/logging.config.html#logging-config-dict-incremental).147- *disable\_existing\_loggers* – определяет, следует ли отключать все существующие логгеры. Эта настройка соответствует одноимённому параметру в [`fileConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.fileConfig). Если отсутствует, по умолчанию `True`. Это значение игнорируется, если *incremental* равно `True`.148149### 16.7.2.2. Инкрементная конфигурация150151Обеспечить полную гибкость для инкрементальной конфигурации сложно. Например, поскольку такие объекты, как фильтры и форматировщики, анонимны, после настройки невозможно сослаться на эти анонимные объекты при дополнении конфигурации.152153Кроме того, нет убедительных причин произвольно изменять граф объектов регистраторов, обработчиков, фильтров и форматировщиков во время выполнения после настройки: уровень подробности регистрации можно контролировать просто установкой уровней (а для регистраторов – флагов распространения). Произвольное изменение графа объектов безопасным способом проблематично в многопоточной среде; хотя это возможно, выгода не стоит сложности, которую это вносит в реализацию.154155Поэтому, когда ключ `incremental` словаря конфигурации присутствует и равен `True`, система полностью игнорирует все записи `formatters` и `filters` и обрабатывает только настройки `level` в записях `handlers`, а также настройки `level` и `propagate` в записях `loggers` и `root`.156157Использование значения в словаре конфигурации позволяет отправлять конфигурации по сети в виде сериализованных словарей в сокетный слушатель. Таким образом, уровень подробности регистрации долго работающего приложения можно изменять со временем без необходимости останавливать и перезапускать приложение.158159### 16.7.2.3. Связи объектов160161Схема описывает набор объектов логирования – регистраторы, обработчики, форматировщики, фильтры – которые соединены друг с другом в граф объектов. Таким образом, схема должна представлять соединения между объектами. Например, предположим, что после настройки к определённому регистратору прикреплён определённый обработчик. В рамках данного обсуждения можно сказать, что регистратор представляет источник, а обработчик – приёмник соединения между ними. Конечно, в настроенных объектах это реализовано тем, что регистратор хранит ссылку на обработчик. В словаре конфигурации это делается путём присвоения каждому объекту- приёмнику идентификатора, однозначно его определяющего, а затем использования этого идентификатора в конфигурации объекта-источника для указания наличия соединения между источником и объектом-приёмником с этим идентификатором.162163Например, рассмотрим следующий фрагмент YAML:164165```yaml166formatters:167 brief:168 # здесь задаётся конфигурация форматтера с id 'brief'169 precise:170 # здесь задаётся конфигурация форматтера с id 'precise'171handlers:172 h1: #Это идентификатор173 # здесь задаётся конфигурация обработчика с id 'h1'174 formatter: brief175 h2: #Это другой идентификатор176 # здесь задаётся конфигурация обработчика с id 'h2'177 formatter: precise178loggers:179 foo.bar.baz:180 # прочая конфигурация для логгера 'foo.bar.baz'181 handlers: [h1, h2]182```183184(Примечание: YAML используется здесь, потому что он немного более читаем, чем эквивалентная форма исходного кода Python для словаря.)185186Идентификаторами для регистраторов являются имена регистраторов, которые использовались бы программно для получения ссылки на эти регистраторы, например, `foo.bar.baz`. Идентификаторы для форматировщиков и фильтров могут быть любыми строковыми значениями (такими как `brief`, `precise` выше) и являются временными – они имеют смысл только для обработки словаря конфигурации и используются для определения связей между объектами, и нигде не сохраняются после завершения вызова конфигурации.187188Указанный выше фрагмент показывает, что к регистратору с именем `foo.bar.baz` должны быть прикреплены два обработчика, которые описываются идентификаторами обработчиков `h1` и `h2`. Форматировщик для `h1` – это тот, который описывается идентификатором `brief`, а форматировщик для `h2` – тот, который описывается идентификатором `precise`.189190### 16.7.2.4. Объекты, определённые пользователем191192Схема поддерживает пользовательские объекты для обработчиков, фильтров и форматировщиков. (Регистраторам не нужны разные типы для разных экземпляров, поэтому в этой схеме конфигурации нет поддержки пользовательских классов регистраторов.)193194Настраиваемые объекты описываются словарями, которые детализируют их конфигурацию. В некоторых местах система логирования сможет определить из контекста, как создать экземпляр объекта, но когда требуется создать экземпляр пользовательского объекта, система не будет знать, как это сделать. Для обеспечения полной гибкости при создании пользовательских объектов пользователь должен предоставить «фабрику» – вызываемый объект, который вызывается со словарём конфигурации и возвращает созданный экземпляр. Это обозначается абсолютным путём импорта к фабрике, доступным под специальным ключом `'()'`. Вот конкретный пример:195196```yaml197formatters:198 brief:199 format: '%(message)s'200 default:201 format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s'202 datefmt: '%Y-%m-%d %H:%M:%S'203 custom:204 (): my.package.customFormatterFactory205 bar: baz206 spam: 99.9207 answer: 42208```209210Приведённый выше фрагмент YAML определяет три форматировщика. Первый, с идентификатором `brief`, является стандартным экземпляром [`logging.Formatter`](https://python-all.ru/3.5/library/logging.html#logging.Formatter) с указанной строкой формата. Второй, с идентификатором `default`, имеет более длинный формат, а также явно задаёт формат времени, и в результате будет создан экземпляр [`logging.Formatter`](https://python-all.ru/3.5/library/logging.html#logging.Formatter), инициализированный этими двумя строками формата. В форме исходного кода Python под словари конфигурации форматировщиков `brief` и `default` выглядят так:211212```python213{214 'format' : '%(message)s'215}216```217218и:219220```python221{222 'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',223 'datefmt' : '%Y-%m-%d %H:%M:%S'224}225```226227соответственно, и поскольку эти словари не содержат специального ключа `'()'`, создание экземпляра выводится из контекста: в результате создаются стандартные экземпляры [`logging.Formatter`](https://python-all.ru/3.5/library/logging.html#logging.Formatter). Подсловарь конфигурации для третьего форматировщика, с идентификатором `custom`, таков:228229```python230{231 '()' : 'my.package.customFormatterFactory',232 'bar' : 'baz',233 'spam' : 99.9,234 'answer' : 42235}236```237238и он содержит специальный ключ `'()'`, что означает необходимость пользовательского создания экземпляра. В этом случае будет использована указанная фабрика-вызываемый объект. Если это реальный вызываемый объект, он будет использован напрямую; в противном случае, если указана строка (как в примере), фактический вызываемый объект будет найден с помощью обычных механизмов импорта. Вызываемый объект будет вызван с **оставшимися** элементами в подсловаре конфигурации в качестве именованных аргументов. В приведённом выше примере предполагается, что форматировщик с идентификатором `custom` будет возвращён вызовом:239240```python241my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)242```243244Ключ `'()'` был выбран в качестве специального, потому что он не является допустимым именем параметра ключевого слова и, следовательно, не будет конфликтовать с именами именованных аргументов, используемых при вызове. `'()'` также служит мнемоническим напоминанием о том, что соответствующее значение является вызываемым объектом.245246### 16.7.2.5. Доступ к внешним объектам247248Бывают случаи, когда конфигурации требуется ссылаться на объекты внешние по отношению к конфигурации, например, `sys.stderr`. Если словарь конфигурации создаётся с помощью кода Python, это несложно, но проблема возникает, когда конфигурация задаётся через текстовый файл (например, JSON, YAML). В текстовом файле нет стандартного способа отличить `sys.stderr` от литеральной строки `'sys.stderr'`. Чтобы облегчить это различие, система конфигурации ищет определённые специальные префиксы в строковых значениях и обрабатывает их особым образом. Например, если литеральная строка `'ext://sys.stderr'` указана как значение в конфигурации, то префикс `ext://` будет отброшен, а оставшаяся часть значения обработана с помощью стандартных механизмов импорта.249250Обработка таких префиксов выполняется аналогично обработке протоколов: существует общий механизм поиска префиксов, соответствующих регулярному выражению `^(?P<prefix>[a-z]+)://(?P<suffix>.*)$`, при котором, если префикс `prefix` распознан, часть `suffix` обрабатывается зависящим от префикса образом, и результат обработки заменяет строковое значение. Если префикс не распознан, строковое значение остаётся без изменений.251252### 16.7.2.6. Доступ к внутренним объектам253254Помимо внешних объектов, иногда также возникает необходимость ссылаться на объекты в самой конфигурации. Это будет делаться неявно системой конфигурации для тех вещей, о которых она знает. Например, строковое значение `'DEBUG'` для `level` в логгере или обработчике будет автоматически преобразовано в значение `logging.DEBUG`, а записи `handlers`, `filters` и `formatter` будут принимать идентификатор объекта и разрешаться в соответствующий целевой объект.255256Однако необходим более общий механизм для пользовательских объектов, которые не известны модулю [`logging`](https://python-all.ru/3.5/library/logging.html#module-logging). Например, рассмотрим [`logging.handlers.MemoryHandler`](https://python-all.ru/3.5/library/logging.handlers.html#logging.handlers.MemoryHandler), который принимает аргумент `target` – другой обработчик для делегирования. Поскольку системе уже известен этот класс, то в конфигурации указанный `target` просто должен быть идентификатором объекта соответствующего целевого обработчика, и система разрешит его в обработчик по идентификатору. Однако если пользователь определяет `my.package.MyHandler`, у которого есть обработчик `alternate`, система конфигурации не будет знать, что `alternate` ссылается на обработчик. Чтобы учесть это, общая система разрешения позволяет пользователю указать:257258```python259handlers:260 file:261 # здесь задаётся конфигурация файлового обработчика262263 custom:264 (): my.package.MyHandler265 alternate: cfg://handlers.file266```267268Литеральная строка `'cfg://handlers.file'` будет разрешаться аналогично строкам с префиксом `ext://`, но поиск будет вестись в самой конфигурации, а не в пространстве имён импорта. Этот механизм позволяет доступ по точке или по индексу, подобно тому, как это делается в `str.format`. Таким образом, для следующего фрагмента:269270```python271handlers:272 email:273 class: logging.handlers.SMTPHandler274 mailhost: localhost275 fromaddr: my_app@domain.tld276 toaddrs:277 - support_team@domain.tld278 - dev_team@domain.tld279 subject: Houston, we have a problem.280```281282в конфигурации строка `'cfg://handlers'` разрешается в словарь с ключом `handlers`, строка `'cfg://handlers.email` разрешается в словарь с ключом `email` в словаре `handlers`, и так далее. Строка `'cfg://handlers.email.toaddrs[1]` разрешается в `'dev_team.domain.tld'`, а строка `'cfg://handlers.email.toaddrs[0]'` разрешается в значение `'support_team@domain.tld'`. Значение `subject` может быть получено с помощью либо `'cfg://handlers.email.subject'`, либо (что эквивалентно) `'cfg://handlers.email[subject]'`. Последняя форма требуется только в том случае, если ключ содержит пробелы или не алфавитно-цифровые символы. Если значение индекса состоит только из десятичных цифр, доступ будет предпринят с использованием соответствующего целочисленного значения, а при необходимости – строкового значения.283284Для строки `cfg://handlers.myhandler.mykey.123` результат будет `config_dict['handlers']['myhandler']['mykey']['123']`. Если строка указана как `cfg://handlers.myhandler.mykey[123]`, система попытается получить значение из `config_dict['handlers']['myhandler']['mykey'][123]`, а в случае неудачи вернётся к `config_dict['handlers']['myhandler']['mykey']['123']`.285286### 16.7.2.7. Разрешение импортов и пользовательские импортёры287288По умолчанию для импорта используется встроенная функция [`__import__()`](https://python-all.ru/3.5/library/functions.html#__import__). Возможно, вы захотите заменить её собственным механизмом импорта: в таком случае можно заменить атрибут `importer` класса `DictConfigurator` или его суперкласса, `BaseConfigurator`. Однако нужно быть осторожным из-за того, как функции доступны из классов через дескрипторы. Если вы используете вызываемый объект Python для импорта и хотите определить его на уровне класса, а не экземпляра, необходимо обернуть его в [`staticmethod()`](https://python-all.ru/3.5/library/functions.html#staticmethod). Например:289290```python291from importlib import import_module292from logging.config import BaseConfigurator293294BaseConfigurator.importer = staticmethod(import_module)295```296297Не нужно оборачивать в [`staticmethod()`](https://python-all.ru/3.5/library/functions.html#staticmethod), если вы устанавливаете вызываемый объект импорта на *экземпляре* конфигуратора.298299## 16.7.3. Формат файла конфигурации300301Формат конфигурационного файла, который понимает [`fileConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.fileConfig), основан на функциональности [`configparser`](https://python-all.ru/3.5/library/configparser.html#module-configparser). Файл должен содержать разделы с названиями `[loggers]`, `[handlers]` и `[formatters]`, которые идентифицируют по имени сущности каждого типа, определенные в файле. Для каждой такой сущности существует отдельный раздел, который определяет, как эта сущность настраивается. Так, для регистратора с именем `log01` в разделе `[loggers]` соответствующие детали конфигурации хранятся в разделе `[logger_log01]`. Аналогично, обработчик с именем `hand01` в разделе `[handlers]` будет иметь свою конфигурацию в разделе с названием `[handler_hand01]`, а форматировщик с именем `form01` в разделе `[formatters]` будет иметь свою конфигурацию в разделе `[formatter_form01]`. Конфигурация корневого регистратора должна быть задана в разделе `[logger_root]`.302303> **Примечание**304>305> API [`fileConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.fileConfig) старше, чем API [`dictConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.dictConfig), и не предоставляет функциональности для покрытия некоторых аспектов логирования. Например, вы не можете настроить объекты [`Filter`](https://python-all.ru/3.5/library/logging.html#logging.Filter), которые обеспечивают фильтрацию сообщений, выходящую за рамки простых целочисленных уровней, с помощью [`fileConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.fileConfig). Если вам нужны экземпляры [`Filter`](https://python-all.ru/3.5/library/logging.html#logging.Filter) в вашей конфигурации логирования, вам придется использовать [`dictConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.dictConfig). Обратите внимание, что будущие улучшения функциональности конфигурации будут добавляться в [`dictConfig()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.dictConfig), так что стоит рассмотреть переход на этот более новый API, когда это удобно.306307Примеры таких разделов в файле приведены ниже.308309```ini310[loggers]311keys=root,log02,log03,log04,log05,log06,log07312313[handlers]314keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09315316[formatters]317keys=form01,form02,form03,form04,form05,form06,form07,form08,form09318```319320Корневой регистратор должен указывать уровень и список обработчиков. Пример раздела корневого регистратора приведен ниже.321322```ini323[logger_root]324level=NOTSET325handlers=hand01326```327328Запись `level` может быть одной из `DEBUG, INFO, WARNING, ERROR, CRITICAL` или `NOTSET`. Только для корневого логгера конфигурация `NOTSET` означает, что все сообщения будут записаны. Значения уровней [`eval()`](https://python-all.ru/3.5/library/functions.html#eval) вычисляются в контексте пространства имён `logging` пакета.329330Запись `handlers` представляет собой список имен обработчиков, разделенных запятыми; эти имена должны присутствовать в разделе `[handlers]`. Данные имена должны присутствовать в разделе `[handlers]` и иметь соответствующие разделы в конфигурационном файле.331332Для регистраторов, отличных от корневого, требуется некоторая дополнительная информация. Это проиллюстрировано следующим примером.333334```ini335[logger_parser]336level=DEBUG337handlers=hand01338propagate=1339qualname=compiler.parser340```341342Записи `level` и `handlers` интерпретируются так же, как для корневого регистратора, за исключением того, что если уровень не корневого регистратора указан как `NOTSET`, система обращается к регистраторам выше по иерархии, чтобы определить эффективный уровень регистратора. Запись `propagate` устанавливается в 1, чтобы указать, что сообщения должны распространяться на обработчики выше по иерархии регистраторов от этого регистратора, или в 0, чтобы указать, что сообщения **не** распространяются на обработчики выше по иерархии. Запись `qualname` – это иерархическое имя канала регистратора, то есть имя, используемое приложением для получения регистратора.343344Разделы, которые задают конфигурацию обработчика, иллюстрируются следующим примером.345346```ini347[handler_hand01]348class=StreamHandler349level=NOTSET350formatter=form01351args=(sys.stdout,)352```353354Запись `class` указывает класс обработчика (как определено [`eval()`](https://python-all.ru/3.5/library/functions.html#eval) в пространстве имен пакета `logging`). Запись `level` интерпретируется так же, как для регистраторов, а `NOTSET` означает «регистрировать всё».355356Запись `formatter` указывает ключевое имя форматировщика для этого обработчика. Если пусто, используется форматировщик по умолчанию (`logging._defaultFormatter`). Если указано имя, оно должно присутствовать в разделе `[formatters]` и иметь соответствующий раздел в конфигурационном файле.357358Запись `args`, при [`eval()`](https://python-all.ru/3.5/library/functions.html#eval)вычислении в контексте `logging` пространства имён пакета, представляет собой список аргументов для конструктора класса обработчика. Обратитесь к конструкторам соответствующих обработчиков или к примерам ниже, чтобы увидеть, как строятся типичные записи.359360```ini361[handler_hand02]362class=FileHandler363level=DEBUG364formatter=form02365args=('python.log', 'w')366367[handler_hand03]368class=handlers.SocketHandler369level=INFO370formatter=form03371args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)372373[handler_hand04]374class=handlers.DatagramHandler375level=WARN376formatter=form04377args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)378379[handler_hand05]380class=handlers.SysLogHandler381level=ERROR382formatter=form05383args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)384385[handler_hand06]386class=handlers.NTEventLogHandler387level=CRITICAL388formatter=form06389args=('Python Application', '', 'Application')390391[handler_hand07]392class=handlers.SMTPHandler393level=WARN394formatter=form07395args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')396397[handler_hand08]398class=handlers.MemoryHandler399level=NOTSET400formatter=form08401target=402args=(10, ERROR)403404[handler_hand09]405class=handlers.HTTPHandler406level=NOTSET407formatter=form09408args=('localhost:9022', '/log', 'GET')409```410411Разделы, которые задают конфигурацию форматировщика, обычно выглядят следующим образом.412413```ini414[formatter_form01]415format=F1 %(asctime)s %(levelname)s %(message)s416datefmt=417class=logging.Formatter418```419420Запись `format` задаёт общую строку формата, а запись `datefmt` задаёт строку формата даты/времени, совместимую с `strftime()`. Если она пуста, пакет подставляет даты/время в формате ISO8601, что почти эквивалентно указанию строки формата даты `'%Y-%m-%d %H:%M:%S'`. Формат ISO8601 также задаёт миллисекунды, которые добавляются к результату использования указанной строки формата через запятую. Пример времени в формате ISO8601: `2003-01-23 00:29:50,411`.421422Запись `class` является необязательной. Она указывает имя класса форматера (в виде полного имени модуля и класса через точку.) Этот параметр полезен для создания экземпляра подкласса [`Formatter`](https://python-all.ru/3.5/library/logging.html#logging.Formatter). Подклассы [`Formatter`](https://python-all.ru/3.5/library/logging.html#logging.Formatter) могут отображать трассировку исключений в развёрнутом или сжатом формате.423424> **Примечание**425>426> Из-за использования [`eval()`](https://python-all.ru/3.5/library/functions.html#eval), как описано выше, существуют потенциальные угрозы безопасности, связанные с использованием [`listen()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.listen) для отправки и получения конфигураций через сокеты. Риски ограничены случаями, когда несколько пользователей, не доверяющих друг другу, запускают код на одной машине; обратитесь к документации [`listen()`](https://python-all.ru/3.5/library/logging.config.html#logging.config.listen) для получения дополнительной информации.427428> **См. также**429>430> **Модуль [`logging`](https://python-all.ru/3.5/library/logging.html#module-logging)**431>432> Справочник API для модуля logging.433>434> **Модуль [`logging.handlers`](https://python-all.ru/3.5/library/logging.handlers.html#module-logging.handlers)**435>436> Полезные обработчики, входящие в состав модуля logging.437