logging.config.md
1> **Источник:** https://python-all.ru/3.8/library/logging.config.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`logging.config`](https://python-all.ru/3.8/library/logging.config.html#module-logging.config) – Конфигурация логирования89**Исходный код:** [Lib/logging/config.py](https://python-all.ru/src/3.8/Lib/logging/config.py)1011Важно1213На этой странице представлена только справочная информация. Учебные руководства см. в1415- [Базовое руководство](https://python-all.ru/3.8/howto/logging.html#logging-basic-tutorial)16- [Продвинутое руководство](https://python-all.ru/3.8/howto/logging.html#logging-advanced-tutorial)17- [Поваренная книга по логированию](https://python-all.ru/3.8/howto/logging-cookbook.html#logging-cookbook)1819---2021В этом разделе описывается API для настройки модуля logging.2223## Функции настройки2425Следующие функции настраивают модуль logging. Они находятся в модуле [`logging.config`](https://python-all.ru/3.8/library/logging.config.html#module-logging.config). Их использование не обязательно – модуль logging можно настраивать с помощью этих функций или напрямую обращаясь к основному API (определённому в самом [`logging`](https://python-all.ru/3.8/library/logging.html#module-logging)), а также определяя обработчики, объявленные в [`logging`](https://python-all.ru/3.8/library/logging.html#module-logging) или [`logging.handlers`](https://python-all.ru/3.8/library/logging.handlers.html#module-logging.handlers).2627#### `logging.config.dictConfig(config)`2829Принимает конфигурацию логирования из словаря. Содержимое этого словаря описано ниже в разделе [Схема словаря конфигурации](https://python-all.ru/3.8/library/logging.config.html#logging-config-dictschema).3031Если во время настройки возникает ошибка, эта функция возбуждает [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError), [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError), [`AttributeError`](https://python-all.ru/3.8/library/exceptions.html#AttributeError) или [`ImportError`](https://python-all.ru/3.8/library/exceptions.html#ImportError) с соответствующим описанием. Ниже приведён (возможно, неполный) перечень условий, при которых возникает ошибка:3233- Значение `level`, не являющееся строкой или являющееся строкой, не соответствующей ни одному реальному уровню логирования.34- Значение `propagate`, не являющееся булевым.35- Идентификатор, для которого нет соответствующего получателя.36- Идентификатор несуществующего обработчика, обнаруженный во время инкрементального вызова.37- Некорректное имя логгера.38- Невозможность разрешить ссылку на внутренний или внешний объект.3940Разбор выполняется классом `DictConfigurator`, конструктору которого передаётся словарь конфигурации; этот класс имеет метод `configure()`. В модуле [`logging.config`](https://python-all.ru/3.8/library/logging.config.html#module-logging.config) есть вызываемый атрибут `dictConfigClass`, изначально установленный в `DictConfigurator`. Вы можете заменить значение `dictConfigClass` на собственную подходящую реализацию.4142[`dictConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.dictConfig) вызывает `dictConfigClass`, передавая указанный словарь, а затем вызывает метод `configure()` возвращённого объекта, чтобы применить конфигурацию:4344```python45def dictConfig(config):46 dictConfigClass(config).configure()47```4849Например, подкласс `DictConfigurator` может вызывать `DictConfigurator.__init__()` в собственном методе [`__init__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__init__), а затем задать пользовательские префиксы, которые будут использоваться при последующем вызове `configure()`. `dictConfigClass` будет привязан к этому новому подклассу, и [`dictConfig()`](https://python-all.ru/3.8/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.8/library/configparser.html#module-configparser). Формат файла должен соответствовать описанию в разделе [Формат конфигурационного файла](https://python-all.ru/3.8/library/logging.config.html#logging-config-fileformat). Эту функцию можно вызывать несколько раз в приложении, что позволяет конечному пользователю выбирать из нескольких готовых конфигураций (если разработчик предоставляет механизм для выбора и загрузки выбранной конфигурации).5657**Параметры**5859- **fname** – имя файла, или файлоподобный объект, или экземпляр, производный от [`RawConfigParser`](https://python-all.ru/3.8/library/configparser.html#configparser.RawConfigParser). Если передан экземпляр, производный от `RawConfigParser`, он используется как есть. В противном случае создаётся `Configparser`, и конфигурация считывается им из объекта, переданного в `fname`. Если у этого объекта есть метод [`readline()`](https://python-all.ru/3.8/library/readline.html#module-readline), предполагается, что это файлоподобный объект, и чтение выполняется через [`read_file()`](https://python-all.ru/3.8/library/configparser.html#configparser.ConfigParser.read_file); в противном случае считается, что это имя файла, и оно передаётся в [`read()`](https://python-all.ru/3.8/library/configparser.html#configparser.ConfigParser.read).60- **defaults** – значения по умолчанию, передаваемые ConfigParser, можно указать в этом аргументе.61- **disable\_existing\_loggers** – если указано `False`, логгеры, существующие на момент вызова, остаются включёнными. Значение по умолчанию – `True`, поскольку это обеспечивает обратную совместимость со старым поведением. Это поведение отключает все существующие не корневые логгеры, если только они или их предки явно не указаны в конфигурации логирования.6263Изменено в версии 3.4: Экземпляр подкласса [`RawConfigParser`](https://python-all.ru/3.8/library/configparser.html#configparser.RawConfigParser) теперь принимается как значение для `fname`. Это позволяет:6465- Использование конфигурационного файла, где настройка логирования является лишь частью общей конфигурации приложения.66- Использование конфигурации, прочитанной из файла и затем изменённой приложением (например, на основе параметров командной строки или других аспектов среды выполнения) перед передачей в `fileConfig`.6768#### `logging.config.listen(port=DEFAULT_LOGGING_CONFIG_PORT, verify=None)`6970Запускает сокет-сервер на указанном порту и ожидает новые конфигурации. Если порт не указан, используется значение по умолчанию модуля `DEFAULT_LOGGING_CONFIG_PORT`. Конфигурации логирования будут отправляться в виде файла, пригодного для обработки с помощью [`dictConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.dictConfig) или [`fileConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.fileConfig). Возвращает экземпляр [`Thread`](https://python-all.ru/3.8/library/threading.html#threading.Thread), на котором можно вызвать [`start()`](https://python-all.ru/3.8/library/threading.html#threading.Thread.start) для запуска сервера и который можно [`join()`](https://python-all.ru/3.8/library/threading.html#threading.Thread.join), когда необходимо. Чтобы остановить сервер, вызовите [`stopListening()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.stopListening).7172Аргумент `verify`, если он указан, должен быть вызываемым объектом, который проверяет, являются ли полученные через сокет байты допустимыми и должны ли быть обработаны. Это можно сделать, зашифровав и/или подписав передаваемые через сокет данные, чтобы вызываемый объект `verify` мог выполнить проверку подписи и/или расшифровку. Вызываемый объект `verify` вызывается с одним аргументом – байтами, полученными через сокет, – и должен вернуть байты для обработки или `None`, чтобы указать, что байты следует отбросить. Возвращённые байты могут совпадать с переданными (например, когда выполняется только проверка) или быть совершенно другими (возможно, если была выполнена расшифровка).7374Чтобы отправить конфигурацию в сокет, прочитайте файл конфигурации и отправьте его в сокет в виде последовательности байтов, перед которыми идёт четырёхбайтовая строка длины, упакованная в двоичном виде с помощью `struct.pack('>L', n)`.7576> **Примечание**77>78> Поскольку части конфигурации передаются через [`eval()`](https://python-all.ru/3.8/library/functions.html#eval), использование этой функции может подвергнуть пользователей риску безопасности. Хотя функция привязывается только к сокету на `localhost` и поэтому не принимает соединения с удалённых машин, существуют сценарии, в которых недоверенный код может быть выполнен под учётной записью процесса, вызывающего [`listen()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.listen). В частности, если процесс, вызывающий [`listen()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.listen), работает на многопользовательской машине, где пользователи не доверяют друг другу, злоумышленник может организовать выполнение произвольного кода в процессе жертвы, просто подключившись к сокету [`listen()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.listen) жертвы и отправив конфигурацию, которая запускает любой код, который злоумышленник хочет выполнить в процессе жертвы. Это особенно легко сделать, если используется порт по умолчанию, но не сложно, даже если используется другой порт). Чтобы избежать риска, используйте аргумент `verify` в [`listen()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.listen), чтобы предотвратить применение нераспознанных конфигураций.7980Изменено в версии 3.4: Добавлен аргумент `verify`.8182> **Примечание**83>84> Если вы хотите отправлять прослушивателю конфигурации, которые не отключают существующие регистраторы, вам нужно использовать формат JSON для конфигурации, который будет использовать [`dictConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.dictConfig) для настройки. Этот метод позволяет указать `disable_existing_loggers` как `False` в отправляемой конфигурации.8586#### `logging.config.stopListening()`8788Останавливает сервер прослушивания, созданный вызовом [`listen()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.listen). Обычно вызывается перед вызовом `join()` для возвращаемого значения из [`listen()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.listen).8990## Схема словаря конфигурации9192Описание конфигурации логирования требует перечисления различных создаваемых объектов и связей между ними; например, можно создать обработчик с именем «console», а затем указать, что регистратор с именем «startup» будет отправлять свои сообщения обработчику «console». Эти объекты не ограничиваются теми, что предоставляются модулем [`logging`](https://python-all.ru/3.8/library/logging.html#module-logging), поскольку можно написать собственный класс форматтера или обработчика. Параметры этих классов также могут включать внешние объекты, такие как `sys.stderr`. Синтаксис для описания этих объектов и связей определён ниже в разделе [Связи объектов](https://python-all.ru/3.8/library/logging.config.html#logging-config-dict-connections).9394### Подробности схемы словаря9596Словарь, передаваемый [`dictConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.dictConfig), должен содержать следующие ключи:9798- *version* – должно быть установлено целочисленное значение, представляющее версию схемы. Единственное допустимое значение на данный момент – 1, но наличие этого ключа позволяет схеме развиваться, сохраняя обратную совместимость.99100Все остальные ключи необязательны, но если они присутствуют, то будут интерпретироваться, как описано ниже. Во всех случаях, когда ниже упоминается «настраивающий словарь», в нём будет проверяться наличие специального ключа `'()'`, чтобы определить, требуется ли пользовательское создание экземпляра. Если да, то используется механизм, описанный ниже в разделе [Пользовательские объекты](https://python-all.ru/3.8/library/logging.config.html#logging-config-dict-userdef), для создания экземпляра; в противном случае контекст используется для определения того, что создавать.101102- *formatters* – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор форматтера, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр [`Formatter`](https://python-all.ru/3.8/library/logging.html#logging.Formatter).103104 В словаре конфигурации выполняется поиск ключей `format` и `datefmt` (со значениями по умолчанию `None`), и они используются для создания экземпляра [`Formatter`](https://python-all.ru/3.8/library/logging.html#logging.Formatter).105106 Изменено в версии 3.8: ключ `validate` (со значением по умолчанию `True`) может быть добавлен в раздел `formatters` словаря конфигурации; это необходимо для проверки формата.107- *filters* – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор фильтра, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Filter.108109 В настраивающем словаре ищется ключ `name` (по умолчанию пустая строка), и он используется для создания экземпляра [`logging.Filter`](https://python-all.ru/3.8/library/logging.html#logging.Filter).110- *handlers* – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор обработчика, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Handler.111112 В словаре конфигурации ищутся следующие ключи:113114 - `class` (обязательный). Это полное имя класса обработчика.115 - `level` (необязательный). Уровень обработчика.116 - `formatter` (необязательный). Идентификатор форматтера для этого обработчика.117 - `filters` (необязательный). Список идентификаторов фильтров для этого обработчика.118119 Все *остальные* ключи передаются как именованные аргументы конструктору обработчика. Например, для следующего фрагмента:120121 ```yaml122 handlers:123 console:124 class : logging.StreamHandler125 formatter: brief126 level : INFO127 filters: [allow_foo]128 stream : ext://sys.stdout129 file:130 class : logging.handlers.RotatingFileHandler131 formatter: precise132 filename: logconfig.log133 maxBytes: 1024134 backupCount: 3135 ```136137 обработчик с идентификатором `console` создаётся как [`logging.StreamHandler`](https://python-all.ru/3.8/library/logging.handlers.html#logging.StreamHandler), используя `sys.stdout` в качестве базового потока. Обработчик с идентификатором `file` создаётся как [`logging.handlers.RotatingFileHandler`](https://python-all.ru/3.8/library/logging.handlers.html#logging.handlers.RotatingFileHandler) с именованными аргументами `filename='logconfig.log', maxBytes=1024, backupCount=3`.138- *loggers* – соответствующее значение будет словарём, в котором каждый ключ – это имя регистратора, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Logger.139140 В словаре конфигурации ищутся следующие ключи:141142 - `level` (необязательно). Уровень регистратора.143 - `propagate` (необязательно). Настройка распространения записей регистратора.144 - `filters` (необязательно). Список идентификаторов фильтров для этого регистратора.145 - `handlers` (необязательно). Список идентификаторов обработчиков для этого регистратора.146147 Указанные регистраторы будут настроены в соответствии с заданными уровнем, распространением, фильтрами и обработчиками.148- *root* – это конфигурация корневого регистратора. Обработка конфигурации будет такой же, как и для любого другого регистратора, за исключением того, что параметр `propagate` не применяется.149- *incremental* – следует ли интерпретировать конфигурацию как дополнение к существующей. Значение по умолчанию – `False`, что означает, что указанная конфигурация заменяет существующую с той же семантикой, которая используется существующим API [`fileConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.fileConfig).150151 Если указано значение `True`, конфигурация обрабатывается так, как описано в разделе [Incremental Configuration](https://python-all.ru/3.8/library/logging.config.html#logging-config-dict-incremental).152- *disable\_existing\_loggers* – следует ли отключать все существующие некорневые регистраторы. Этот параметр повторяет одноимённый параметр в [`fileConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.fileConfig). Если отсутствует, по умолчанию принимает значение `True`. Это значение игнорируется, если *incremental* равно `True`.153154### Инкрементальная конфигурация155156Обеспечить полную гибкость для инкрементальной конфигурации сложно. Например, поскольку такие объекты, как фильтры и форматировщики, анонимны, после настройки невозможно сослаться на эти анонимные объекты при дополнении конфигурации.157158Кроме того, нет убедительных причин произвольно изменять граф объектов регистраторов, обработчиков, фильтров и форматировщиков во время выполнения после настройки: уровень подробности регистрации можно контролировать просто установкой уровней (а для регистраторов – флагов распространения). Произвольное изменение графа объектов безопасным способом проблематично в многопоточной среде; хотя это возможно, выгода не стоит сложности, которую это вносит в реализацию.159160Поэтому, когда ключ `incremental` словаря конфигурации присутствует и равен `True`, система полностью игнорирует все записи `formatters` и `filters` и обрабатывает только настройки `level` в записях `handlers`, а также настройки `level` и `propagate` в записях `loggers` и `root`.161162Использование значения в словаре конфигурации позволяет отправлять конфигурации по сети в виде сериализованных словарей в сокетный слушатель. Таким образом, уровень подробности регистрации долго работающего приложения можно изменять со временем без необходимости останавливать и перезапускать приложение.163164### Соединения объектов165166Схема описывает набор объектов логирования – регистраторы, обработчики, форматировщики, фильтры – которые соединены друг с другом в граф объектов. Таким образом, схема должна представлять соединения между объектами. Например, предположим, что после настройки к определённому регистратору прикреплён определённый обработчик. В рамках данного обсуждения можно сказать, что регистратор представляет источник, а обработчик – приёмник соединения между ними. Конечно, в настроенных объектах это реализовано тем, что регистратор хранит ссылку на обработчик. В словаре конфигурации это делается путём присвоения каждому объекту- приёмнику идентификатора, однозначно его определяющего, а затем использования этого идентификатора в конфигурации объекта-источника для указания наличия соединения между источником и объектом-приёмником с этим идентификатором.167168Например, рассмотрим следующий фрагмент YAML:169170```yaml171formatters:172 brief:173 # здесь задаётся конфигурация форматтера с id 'brief'174 precise:175 # здесь задаётся конфигурация форматтера с id 'precise'176handlers:177 h1: #Это идентификатор178 # здесь задаётся конфигурация обработчика с id 'h1'179 formatter: brief180 h2: #Это другой идентификатор181 # здесь задаётся конфигурация обработчика с id 'h2'182 formatter: precise183loggers:184 foo.bar.baz:185 # прочая конфигурация для логгера 'foo.bar.baz'186 handlers: [h1, h2]187```188189(Примечание: YAML используется здесь, потому что он немного более читаем, чем эквивалентная форма исходного кода Python для словаря.)190191Идентификаторами для регистраторов являются имена регистраторов, которые использовались бы программно для получения ссылки на эти регистраторы, например, `foo.bar.baz`. Идентификаторы для форматировщиков и фильтров могут быть любыми строковыми значениями (такими как `brief`, `precise` выше) и являются временными – они имеют смысл только для обработки словаря конфигурации и используются для определения связей между объектами, и нигде не сохраняются после завершения вызова конфигурации.192193Указанный выше фрагмент показывает, что к регистратору с именем `foo.bar.baz` должны быть прикреплены два обработчика, которые описываются идентификаторами обработчиков `h1` и `h2`. Форматировщик для `h1` – это тот, который описывается идентификатором `brief`, а форматировщик для `h2` – тот, который описывается идентификатором `precise`.194195### Пользовательские объекты196197Схема поддерживает пользовательские объекты для обработчиков, фильтров и форматировщиков. (Регистраторам не нужны разные типы для разных экземпляров, поэтому в этой схеме конфигурации нет поддержки пользовательских классов регистраторов.)198199Настраиваемые объекты описываются словарями, которые детализируют их конфигурацию. В некоторых местах система логирования сможет определить из контекста, как создать экземпляр объекта, но когда требуется создать экземпляр пользовательского объекта, система не будет знать, как это сделать. Для обеспечения полной гибкости при создании пользовательских объектов пользователь должен предоставить «фабрику» – вызываемый объект, который вызывается со словарём конфигурации и возвращает созданный экземпляр. Это обозначается абсолютным путём импорта к фабрике, доступным под специальным ключом `'()'`. Вот конкретный пример:200201```yaml202formatters:203 brief:204 format: '%(message)s'205 default:206 format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s'207 datefmt: '%Y-%m-%d %H:%M:%S'208 custom:209 (): my.package.customFormatterFactory210 bar: baz211 spam: 99.9212 answer: 42213```214215Приведённый выше фрагмент YAML определяет три форматировщика. Первый, с идентификатором `brief`, является стандартным экземпляром [`logging.Formatter`](https://python-all.ru/3.8/library/logging.html#logging.Formatter) с указанной строкой формата. Второй, с идентификатором `default`, имеет более длинный формат, а также явно задаёт формат времени, и в результате будет создан экземпляр [`logging.Formatter`](https://python-all.ru/3.8/library/logging.html#logging.Formatter), инициализированный этими двумя строками формата. В форме исходного кода Python под словари конфигурации форматировщиков `brief` и `default` выглядят так:216217```python218{219 'format' : '%(message)s'220}221```222223и:224225```python226{227 'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',228 'datefmt' : '%Y-%m-%d %H:%M:%S'229}230```231232соответственно, и поскольку эти словари не содержат специального ключа `'()'`, создание экземпляра выводится из контекста: в результате создаются стандартные экземпляры [`logging.Formatter`](https://python-all.ru/3.8/library/logging.html#logging.Formatter). Подсловарь конфигурации для третьего форматировщика, с идентификатором `custom`, таков:233234```python235{236 '()' : 'my.package.customFormatterFactory',237 'bar' : 'baz',238 'spam' : 99.9,239 'answer' : 42240}241```242243и он содержит специальный ключ `'()'`, что означает необходимость пользовательского создания экземпляра. В этом случае будет использована указанная фабрика-вызываемый объект. Если это реальный вызываемый объект, он будет использован напрямую; в противном случае, если указана строка (как в примере), фактический вызываемый объект будет найден с помощью обычных механизмов импорта. Вызываемый объект будет вызван с **оставшимися** элементами в подсловаре конфигурации в качестве именованных аргументов. В приведённом выше примере предполагается, что форматировщик с идентификатором `custom` будет возвращён вызовом:244245```python246my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)247```248249Ключ `'()'` был выбран в качестве специального, потому что он не является допустимым именем параметра ключевого слова и, следовательно, не будет конфликтовать с именами именованных аргументов, используемых при вызове. `'()'` также служит мнемоническим напоминанием о том, что соответствующее значение является вызываемым объектом.250251### Доступ к внешним объектам252253Бывают случаи, когда конфигурации требуется ссылаться на объекты внешние по отношению к конфигурации, например, `sys.stderr`. Если словарь конфигурации создаётся с помощью кода Python, это несложно, но проблема возникает, когда конфигурация задаётся через текстовый файл (например, JSON, YAML). В текстовом файле нет стандартного способа отличить `sys.stderr` от литеральной строки `'sys.stderr'`. Чтобы облегчить это различие, система конфигурации ищет определённые специальные префиксы в строковых значениях и обрабатывает их особым образом. Например, если литеральная строка `'ext://sys.stderr'` указана как значение в конфигурации, то префикс `ext://` будет отброшен, а оставшаяся часть значения обработана с помощью стандартных механизмов импорта.254255Обработка таких префиксов выполняется аналогично обработке протоколов: существует общий механизм поиска префиксов, соответствующих регулярному выражению `^(?P<prefix>[a-z]+)://(?P<suffix>.*)$`, при котором, если префикс `prefix` распознан, часть `suffix` обрабатывается зависящим от префикса образом, и результат обработки заменяет строковое значение. Если префикс не распознан, строковое значение остаётся без изменений.256257### Доступ к внутренним объектам258259Помимо внешних объектов, иногда также возникает необходимость ссылаться на объекты в самой конфигурации. Это будет делаться неявно системой конфигурации для тех вещей, о которых она знает. Например, строковое значение `'DEBUG'` для `level` в логгере или обработчике будет автоматически преобразовано в значение `logging.DEBUG`, а записи `handlers`, `filters` и `formatter` будут принимать идентификатор объекта и разрешаться в соответствующий целевой объект.260261Однако необходим более общий механизм для пользовательских объектов, которые не известны модулю [`logging`](https://python-all.ru/3.8/library/logging.html#module-logging). Например, рассмотрим [`logging.handlers.MemoryHandler`](https://python-all.ru/3.8/library/logging.handlers.html#logging.handlers.MemoryHandler), который принимает аргумент `target` – другой обработчик для делегирования. Поскольку системе уже известен этот класс, то в конфигурации указанный `target` просто должен быть идентификатором объекта соответствующего целевого обработчика, и система разрешит его в обработчик по идентификатору. Однако если пользователь определяет `my.package.MyHandler`, у которого есть обработчик `alternate`, система конфигурации не будет знать, что `alternate` ссылается на обработчик. Чтобы учесть это, общая система разрешения позволяет пользователю указать:262263```yaml264handlers:265 file:266 # здесь задаётся конфигурация файлового обработчика267268 custom:269 (): my.package.MyHandler270 alternate: cfg://handlers.file271```272273Литеральная строка `'cfg://handlers.file'` будет разрешаться аналогично строкам с префиксом `ext://`, но поиск будет вестись в самой конфигурации, а не в пространстве имён импорта. Этот механизм позволяет доступ по точке или по индексу, подобно тому, как это делается в `str.format`. Таким образом, для следующего фрагмента:274275```yaml276handlers:277 email:278 class: logging.handlers.SMTPHandler279 mailhost: localhost280 fromaddr: my_app@domain.tld281 toaddrs:282 - support_team@domain.tld283 - dev_team@domain.tld284 subject: Houston, we have a problem.285```286287в конфигурации строка `'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]'`. Последняя форма требуется только в том случае, если ключ содержит пробелы или не алфавитно-цифровые символы. Если значение индекса состоит только из десятичных цифр, доступ будет предпринят с использованием соответствующего целочисленного значения, а при необходимости – строкового значения.288289Для строки `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']`.290291### Разрешение импорта и пользовательские импортёры292293По умолчанию для импорта используется встроенная функция [`__import__()`](https://python-all.ru/3.8/library/functions.html#__import__). Возможно, вы захотите заменить её собственным механизмом импорта: в таком случае можно заменить атрибут `importer` класса `DictConfigurator` или его суперкласса, `BaseConfigurator`. Однако нужно быть осторожным из-за того, как функции доступны из классов через дескрипторы. Если вы используете вызываемый объект Python для импорта и хотите определить его на уровне класса, а не экземпляра, необходимо обернуть его в [`staticmethod()`](https://python-all.ru/3.8/library/functions.html#staticmethod). Например:294295```python296from importlib import import_module297from logging.config import BaseConfigurator298299BaseConfigurator.importer = staticmethod(import_module)300```301302Не нужно оборачивать в [`staticmethod()`](https://python-all.ru/3.8/library/functions.html#staticmethod), если вы устанавливаете вызываемый объект импорта на *экземпляре* конфигуратора.303304## Формат файла конфигурации305306Формат конфигурационного файла, который понимает [`fileConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.fileConfig), основан на функциональности [`configparser`](https://python-all.ru/3.8/library/configparser.html#module-configparser). Файл должен содержать разделы с названиями `[loggers]`, `[handlers]` и `[formatters]`, которые идентифицируют по имени сущности каждого типа, определенные в файле. Для каждой такой сущности существует отдельный раздел, который определяет, как эта сущность настраивается. Так, для регистратора с именем `log01` в разделе `[loggers]` соответствующие детали конфигурации хранятся в разделе `[logger_log01]`. Аналогично, обработчик с именем `hand01` в разделе `[handlers]` будет иметь свою конфигурацию в разделе с названием `[handler_hand01]`, а форматировщик с именем `form01` в разделе `[formatters]` будет иметь свою конфигурацию в разделе `[formatter_form01]`. Конфигурация корневого регистратора должна быть задана в разделе `[logger_root]`.307308> **Примечание**309>310> API [`fileConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.fileConfig) старше, чем API [`dictConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.dictConfig), и не предоставляет функциональности для покрытия некоторых аспектов логирования. Например, вы не можете настроить объекты [`Filter`](https://python-all.ru/3.8/library/logging.html#logging.Filter), которые обеспечивают фильтрацию сообщений, выходящую за рамки простых целочисленных уровней, с помощью [`fileConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.fileConfig). Если вам нужны экземпляры [`Filter`](https://python-all.ru/3.8/library/logging.html#logging.Filter) в вашей конфигурации логирования, вам придется использовать [`dictConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.dictConfig). Обратите внимание, что будущие улучшения функциональности конфигурации будут добавляться в [`dictConfig()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.dictConfig), так что стоит рассмотреть переход на этот более новый API, когда это удобно.311312Примеры таких разделов в файле приведены ниже.313314```ini315[loggers]316keys=root,log02,log03,log04,log05,log06,log07317318[handlers]319keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09320321[formatters]322keys=form01,form02,form03,form04,form05,form06,form07,form08,form09323```324325Корневой регистратор должен указывать уровень и список обработчиков. Пример раздела корневого регистратора приведен ниже.326327```ini328[logger_root]329level=NOTSET330handlers=hand01331```332333Запись `level` может быть одной из `DEBUG, INFO, WARNING, ERROR, CRITICAL` или `NOTSET`. Только для корневого логгера конфигурация `NOTSET` означает, что все сообщения будут записаны. Значения уровней [`eval()`](https://python-all.ru/3.8/library/functions.html#eval) вычисляются в контексте пространства имён `logging` пакета.334335Запись `handlers` представляет собой список имен обработчиков, разделенных запятыми; эти имена должны присутствовать в разделе `[handlers]`. Данные имена должны присутствовать в разделе `[handlers]` и иметь соответствующие разделы в конфигурационном файле.336337Для регистраторов, отличных от корневого, требуется некоторая дополнительная информация. Это проиллюстрировано следующим примером.338339```ini340[logger_parser]341level=DEBUG342handlers=hand01343propagate=1344qualname=compiler.parser345```346347Записи `level` и `handlers` интерпретируются так же, как для корневого регистратора, за исключением того, что если уровень не корневого регистратора указан как `NOTSET`, система обращается к регистраторам выше по иерархии, чтобы определить эффективный уровень регистратора. Запись `propagate` устанавливается в 1, чтобы указать, что сообщения должны распространяться на обработчики выше по иерархии регистраторов от этого регистратора, или в 0, чтобы указать, что сообщения **не** распространяются на обработчики выше по иерархии. Запись `qualname` – это иерархическое имя канала регистратора, то есть имя, используемое приложением для получения регистратора.348349Разделы, которые задают конфигурацию обработчика, иллюстрируются следующим примером.350351```ini352[handler_hand01]353class=StreamHandler354level=NOTSET355formatter=form01356args=(sys.stdout,)357```358359Запись `class` указывает класс обработчика (как определено [`eval()`](https://python-all.ru/3.8/library/functions.html#eval) в пространстве имен пакета `logging`). Запись `level` интерпретируется так же, как для регистраторов, а `NOTSET` означает «регистрировать всё».360361Запись `formatter` указывает ключевое имя форматировщика для этого обработчика. Если пусто, используется форматировщик по умолчанию (`logging._defaultFormatter`). Если указано имя, оно должно присутствовать в разделе `[formatters]` и иметь соответствующий раздел в конфигурационном файле.362363The `args` entry, when [`eval()`](https://python-all.ru/3.8/library/functions.html#eval)uated in the context of the `logging` package’s namespace, is the list of arguments to the constructor for the handler class. Refer to the constructors for the relevant handlers, or to the examples below, to see how typical entries are constructed. If not provided, it defaults to `()`.364365The optional `kwargs` entry, when [`eval()`](https://python-all.ru/3.8/library/functions.html#eval)uated in the context of the `logging` package’s namespace, is the keyword argument dict to the constructor for the handler class. If not provided, it defaults to `{}`.366367```ini368[handler_hand02]369class=FileHandler370level=DEBUG371formatter=form02372args=('python.log', 'w')373374[handler_hand03]375class=handlers.SocketHandler376level=INFO377formatter=form03378args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)379380[handler_hand04]381class=handlers.DatagramHandler382level=WARN383formatter=form04384args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)385386[handler_hand05]387class=handlers.SysLogHandler388level=ERROR389formatter=form05390args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)391392[handler_hand06]393class=handlers.NTEventLogHandler394level=CRITICAL395formatter=form06396args=('Python Application', '', 'Application')397398[handler_hand07]399class=handlers.SMTPHandler400level=WARN401formatter=form07402args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')403kwargs={'timeout': 10.0}404405[handler_hand08]406class=handlers.MemoryHandler407level=NOTSET408formatter=form08409target=410args=(10, ERROR)411412[handler_hand09]413class=handlers.HTTPHandler414level=NOTSET415formatter=form09416args=('localhost:9022', '/log', 'GET')417kwargs={'secure': True}418```419420Разделы, которые задают конфигурацию форматировщика, обычно выглядят следующим образом.421422```ini423[formatter_form01]424format=F1 %(asctime)s %(levelname)s %(message)s425datefmt=426class=logging.Formatter427```428429Запись `format` – это общая строка форматирования, а запись `datefmt` – это строка формата даты/времени, совместимая с `strftime()`. Если она пуста, пакет подставляет нечто почти эквивалентное указанию строки формата даты `'%Y-%m-%d %H:%M:%S'`. Этот формат также задаёт миллисекунды, которые добавляются к результату использования указанной выше строки формата с запятой в качестве разделителя. Пример времени в этом формате: `2003-01-23 00:29:50,411`.430431Запись `class` является необязательной. Она указывает имя класса форматера (в виде полного имени модуля и класса через точку.) Этот параметр полезен для создания экземпляра подкласса [`Formatter`](https://python-all.ru/3.8/library/logging.html#logging.Formatter). Подклассы [`Formatter`](https://python-all.ru/3.8/library/logging.html#logging.Formatter) могут отображать трассировку исключений в развёрнутом или сжатом формате.432433> **Примечание**434>435> Из-за использования [`eval()`](https://python-all.ru/3.8/library/functions.html#eval), как описано выше, существуют потенциальные угрозы безопасности, связанные с использованием [`listen()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.listen) для отправки и получения конфигураций через сокеты. Риски ограничены случаями, когда несколько пользователей, не доверяющих друг другу, запускают код на одной машине; обратитесь к документации [`listen()`](https://python-all.ru/3.8/library/logging.config.html#logging.config.listen) для получения дополнительной информации.436437> **См. также**438>439> **Модуль [`logging`](https://python-all.ru/3.8/library/logging.html#module-logging)**440>441> Справочник API для модуля logging.442>443> **Модуль [`logging.handlers`](https://python-all.ru/3.8/library/logging.handlers.html#module-logging.handlers)**444>445> Полезные обработчики, входящие в состав модуля logging.446