logging.config.md
1> **Источник:** https://python-all.ru/2.7/library/logging.config.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 15.8. [`logging.config`](https://python-all.ru/2.7/library/logging.config.html#module-logging.config) – Настройка логирования89Важно1011На этой странице представлена только справочная информация. Учебные руководства см. в1213- [Базовое руководство](https://python-all.ru/2.7/howto/logging.html#logging-basic-tutorial)14- [Продвинутое руководство](https://python-all.ru/2.7/howto/logging.html#logging-advanced-tutorial)15- [Поваренная книга по логированию](https://python-all.ru/2.7/howto/logging-cookbook.html#logging-cookbook)1617**Исходный код:** [Lib/logging/config.py](https://python-all.ru/src/2.7/Lib/logging/config.py)1819---2021В этом разделе описывается API для настройки модуля logging.2223## 15.8.1. Функции настройки2425Следующие функции настраивают модуль logging. Они находятся в модуле [`logging.config`](https://python-all.ru/2.7/library/logging.config.html#module-logging.config). Их использование не обязательно – модуль logging можно настраивать с помощью этих функций или напрямую обращаясь к основному API (определённому в самом [`logging`](https://python-all.ru/2.7/library/logging.html#module-logging)), а также определяя обработчики, объявленные в [`logging`](https://python-all.ru/2.7/library/logging.html#module-logging) или [`logging.handlers`](https://python-all.ru/2.7/library/logging.handlers.html#module-logging.handlers).2627#### `logging.config.dictConfig(config)`2829> Принимает конфигурацию логирования из словаря. Содержимое этого словаря описано ниже в разделе [Схема словаря конфигурации](https://python-all.ru/2.7/library/logging.config.html#logging-config-dictschema).30>31> Если во время настройки возникает ошибка, эта функция возбуждает [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError), [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError), [`AttributeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.AttributeError) или [`ImportError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ImportError) с соответствующим описанием. Ниже приведён (возможно, неполный) перечень условий, при которых возникает ошибка:32>33> - Значение `level`, не являющееся строкой или являющееся строкой, не соответствующей ни одному реальному уровню логирования.34> - Значение `propagate`, не являющееся булевым.35> - Идентификатор, для которого нет соответствующего получателя.36> - Идентификатор несуществующего обработчика, обнаруженный во время инкрементального вызова.37> - Некорректное имя логгера.38> - Невозможность разрешить ссылку на внутренний или внешний объект.39>40> Разбор выполняется классом `DictConfigurator`, конструктору которого передаётся словарь конфигурации; этот класс имеет метод `configure()`. В модуле [`logging.config`](https://python-all.ru/2.7/library/logging.config.html#module-logging.config) есть вызываемый атрибут `dictConfigClass`, изначально установленный в `DictConfigurator`. Вы можете заменить значение `dictConfigClass` на собственную подходящую реализацию.41>42> [`dictConfig()`](https://python-all.ru/2.7/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/2.7/reference/datamodel.html#object.__init__), а затем задать пользовательские префиксы, которые будут использоваться при последующем вызове `configure()`. `dictConfigClass` будет привязан к этому новому подклассу, и [`dictConfig()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.dictConfig) можно будет вызывать так же, как и в состоянии по умолчанию, без настройки.5051Новое в версии 2.7.5253#### `logging.config.fileConfig(fname, defaults=None, disable_existing_loggers=True)`5455Читает конфигурацию логирования из файла формата `configparser` с именем *fname*. Формат файла должен соответствовать описанию в [Формат конфигурационного файла](https://python-all.ru/2.7/library/logging.config.html#logging-config-fileformat). Эту функцию можно вызывать несколько раз из приложения, что позволяет конечному пользователю выбирать из различных готовых конфигураций (если разработчик предоставит механизм для отображения вариантов и загрузки выбранной конфигурации).5657**Параметры**5859- **defaults** – значения по умолчанию, передаваемые ConfigParser, можно указать в этом аргументе.60- **disable\_existing\_loggers** – Если указано как `False`, то логгеры, существующие на момент вызова, остаются включёнными. По умолчанию `True`, так как это обеспечивает обратно совместимое поведение. Это поведение отключает все существующие логгеры, если только они или их предки явно не указаны в конфигурации логирования.6162Изменено в версии 2.6: Был добавлен именованный аргумент `disable_existing_loggers`. Ранее существующие регистраторы *всегда* отключались.6364#### `logging.config.listen(port=DEFAULT_LOGGING_CONFIG_PORT)`6566Запускает сокет-сервер на указанном порту и прослушивает новые конфигурации. Если порт не указан, используется значение по умолчанию модуля `DEFAULT_LOGGING_CONFIG_PORT`. Конфигурации логирования будут отправляться в виде файла, пригодного для обработки с помощью [`fileConfig()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.fileConfig). Возвращает экземпляр [`Thread`](https://python-all.ru/2.7/library/threading.html#threading.Thread), на котором можно вызвать [`start()`](https://python-all.ru/2.7/library/threading.html#threading.Thread.start) для запуска сервера и [`join()`](https://python-all.ru/2.7/library/threading.html#threading.Thread.join) в нужный момент. Чтобы остановить сервер, вызовите [`stopListening()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.stopListening).6768Чтобы отправить конфигурацию в сокет, прочитайте конфигурационный файл и отправьте его в сокет в виде строки байтов, перед которой указывается четырёхбайтовая строка длины, упакованная в двоичном формате с помощью `struct.pack('>L', n)`.6970> **Примечание**71>72> Поскольку части конфигурации передаются через [`eval()`](https://python-all.ru/2.7/library/functions.html#eval), использование этой функции может подвергнуть пользователей риску безопасности. Хотя функция привязывается только к сокету на `localhost` и поэтому не принимает соединения от удаленных машин, существуют сценарии, в которых недоверенный код может быть выполнен от имени процесса, вызывающего [`listen()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.listen). В частности, если процесс, вызывающий [`listen()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.listen), работает на многопользовательской машине, где пользователи не доверяют друг другу, то злоумышленник может организовать выполнение практически произвольного кода в процессе жертвы, просто подключившись к сокету жертвы на порту [`listen()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.listen) и отправив конфигурацию, которая запускает любой код, который хочет выполнить злоумышленник в процессе жертвы. Это особенно легко сделать, если используется порт по умолчанию, но не сложно, даже если используется другой порт).7374#### `logging.config.stopListening()`7576Останавливает сервер прослушивания, созданный вызовом [`listen()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.listen). Обычно вызывается перед вызовом `join()` для возвращаемого значения из [`listen()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.listen).7778## 15.8.2. Схема словаря конфигурации7980Описание конфигурации логирования требует перечисления различных создаваемых объектов и связей между ними; например, можно создать обработчик с именем «console», а затем указать, что регистратор с именем «startup» будет отправлять свои сообщения обработчику «console». Эти объекты не ограничиваются теми, что предоставляются модулем [`logging`](https://python-all.ru/2.7/library/logging.html#module-logging), поскольку можно написать собственный класс форматтера или обработчика. Параметры этих классов также могут включать внешние объекты, такие как `sys.stderr`. Синтаксис для описания этих объектов и связей определён ниже в разделе [Связи объектов](https://python-all.ru/2.7/library/logging.config.html#logging-config-dict-connections).8182### 15.8.2.1. Подробности схемы словаря8384Словарь, передаваемый [`dictConfig()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.dictConfig), должен содержать следующие ключи:8586- *version* – должно быть установлено целочисленное значение, представляющее версию схемы. Единственное допустимое значение на данный момент – 1, но наличие этого ключа позволяет схеме развиваться, сохраняя обратную совместимость.8788Все остальные ключи необязательны, но если они присутствуют, то будут интерпретироваться, как описано ниже. Во всех случаях, когда ниже упоминается «настраивающий словарь», в нём будет проверяться наличие специального ключа `'()'`, чтобы определить, требуется ли пользовательское создание экземпляра. Если да, то используется механизм, описанный ниже в разделе [Пользовательские объекты](https://python-all.ru/2.7/library/logging.config.html#logging-config-dict-userdef), для создания экземпляра; в противном случае контекст используется для определения того, что создавать.8990- *formatters* – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор форматтера, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр [`Formatter`](https://python-all.ru/2.7/library/logging.html#logging.Formatter).9192 В словаре конфигурации выполняется поиск ключей `format` и `datefmt` (со значениями по умолчанию `None`), и они используются для создания экземпляра [`Formatter`](https://python-all.ru/2.7/library/logging.html#logging.Formatter).93- *filters* – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор фильтра, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Filter.9495 В настраивающем словаре ищется ключ `name` (по умолчанию пустая строка), и он используется для создания экземпляра [`logging.Filter`](https://python-all.ru/2.7/library/logging.html#logging.Filter).96- *handlers* – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор обработчика, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Handler.9798 В словаре конфигурации ищутся следующие ключи:99100 - `class` (обязательный). Это полное имя класса обработчика.101 - `level` (необязательный). Уровень обработчика.102 - `formatter` (необязательный). Идентификатор форматтера для этого обработчика.103 - `filters` (необязательный). Список идентификаторов фильтров для этого обработчика.104105 Все *остальные* ключи передаются как именованные аргументы конструктору обработчика. Например, для следующего фрагмента:106107 ```yaml108 handlers:109 console:110 class : logging.StreamHandler111 formatter: brief112 level : INFO113 filters: [allow_foo]114 stream : ext://sys.stdout115 file:116 class : logging.handlers.RotatingFileHandler117 formatter: precise118 filename: logconfig.log119 maxBytes: 1024120 backupCount: 3121 ```122123 обработчик с идентификатором `console` создаётся как [`logging.StreamHandler`](https://python-all.ru/2.7/library/logging.handlers.html#logging.StreamHandler), используя `sys.stdout` в качестве базового потока. Обработчик с идентификатором `file` создаётся как [`logging.handlers.RotatingFileHandler`](https://python-all.ru/2.7/library/logging.handlers.html#logging.handlers.RotatingFileHandler) с именованными аргументами `filename='logconfig.log', maxBytes=1024, backupCount=3`.124- *loggers* – соответствующее значение будет словарём, в котором каждый ключ – это имя регистратора, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Logger.125126 В словаре конфигурации ищутся следующие ключи:127128 - `level` (необязательно). Уровень регистратора.129 - `propagate` (необязательно). Настройка распространения записей регистратора.130 - `filters` (необязательно). Список идентификаторов фильтров для этого регистратора.131 - `handlers` (необязательно). Список идентификаторов обработчиков для этого регистратора.132133 Указанные регистраторы будут настроены в соответствии с заданными уровнем, распространением, фильтрами и обработчиками.134- *root* – это конфигурация корневого регистратора. Обработка конфигурации будет такой же, как и для любого другого регистратора, за исключением того, что параметр `propagate` не применяется.135- *incremental* – следует ли интерпретировать конфигурацию как дополнение к существующей. Значение по умолчанию – `False`, что означает, что указанная конфигурация заменяет существующую с той же семантикой, которая используется существующим API [`fileConfig()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.fileConfig).136137 Если указано значение `True`, конфигурация обрабатывается так, как описано в разделе [Incremental Configuration](https://python-all.ru/2.7/library/logging.config.html#logging-config-dict-incremental).138- *disable\_existing\_loggers* – определяет, следует ли отключать все существующие логгеры. Эта настройка соответствует одноимённому параметру в [`fileConfig()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.fileConfig). Если отсутствует, по умолчанию `True`. Это значение игнорируется, если *incremental* равно `True`.139140### 15.8.2.2. Инкрементальная настройка141142Обеспечить полную гибкость для инкрементальной конфигурации сложно. Например, поскольку такие объекты, как фильтры и форматировщики, анонимны, после настройки невозможно сослаться на эти анонимные объекты при дополнении конфигурации.143144Кроме того, нет убедительных причин произвольно изменять граф объектов регистраторов, обработчиков, фильтров и форматировщиков во время выполнения после настройки: уровень подробности регистрации можно контролировать просто установкой уровней (а для регистраторов – флагов распространения). Произвольное изменение графа объектов безопасным способом проблематично в многопоточной среде; хотя это возможно, выгода не стоит сложности, которую это вносит в реализацию.145146Поэтому, когда ключ `incremental` словаря конфигурации присутствует и равен `True`, система полностью игнорирует все записи `formatters` и `filters` и обрабатывает только настройки `level` в записях `handlers`, а также настройки `level` и `propagate` в записях `loggers` и `root`.147148Использование значения в словаре конфигурации позволяет отправлять конфигурации по сети в виде сериализованных словарей в сокетный слушатель. Таким образом, уровень подробности регистрации долго работающего приложения можно изменять со временем без необходимости останавливать и перезапускать приложение.149150### 15.8.2.3. Соединения объектов151152Схема описывает набор объектов логирования – регистраторы, обработчики, форматировщики, фильтры – которые соединены друг с другом в граф объектов. Таким образом, схема должна представлять соединения между объектами. Например, предположим, что после настройки к определённому регистратору прикреплён определённый обработчик. В рамках данного обсуждения можно сказать, что регистратор представляет источник, а обработчик – приёмник соединения между ними. Конечно, в настроенных объектах это реализовано тем, что регистратор хранит ссылку на обработчик. В словаре конфигурации это делается путём присвоения каждому объекту- приёмнику идентификатора, однозначно его определяющего, а затем использования этого идентификатора в конфигурации объекта-источника для указания наличия соединения между источником и объектом-приёмником с этим идентификатором.153154Например, рассмотрим следующий фрагмент YAML:155156```yaml157formatters:158 brief:159 # здесь задаётся конфигурация форматтера с id 'brief'160 precise:161 # здесь задаётся конфигурация форматтера с id 'precise'162handlers:163 h1: #Это идентификатор164 # здесь задаётся конфигурация обработчика с id 'h1'165 formatter: brief166 h2: #Это другой идентификатор167 # здесь задаётся конфигурация обработчика с id 'h2'168 formatter: precise169loggers:170 foo.bar.baz:171 # прочая конфигурация для логгера 'foo.bar.baz'172 handlers: [h1, h2]173```174175(Примечание: YAML используется здесь, потому что он немного более читаем, чем эквивалентная форма исходного кода Python для словаря.)176177Идентификаторами для регистраторов являются имена регистраторов, которые использовались бы программно для получения ссылки на эти регистраторы, например, `foo.bar.baz`. Идентификаторы для форматировщиков и фильтров могут быть любыми строковыми значениями (такими как `brief`, `precise` выше) и являются временными – они имеют смысл только для обработки словаря конфигурации и используются для определения связей между объектами, и нигде не сохраняются после завершения вызова конфигурации.178179Указанный выше фрагмент показывает, что к регистратору с именем `foo.bar.baz` должны быть прикреплены два обработчика, которые описываются идентификаторами обработчиков `h1` и `h2`. Форматировщик для `h1` – это тот, который описывается идентификатором `brief`, а форматировщик для `h2` – тот, который описывается идентификатором `precise`.180181### 15.8.2.4. Пользовательские объекты182183Схема поддерживает пользовательские объекты для обработчиков, фильтров и форматировщиков. (Регистраторам не нужны разные типы для разных экземпляров, поэтому в этой схеме конфигурации нет поддержки пользовательских классов регистраторов.)184185Настраиваемые объекты описываются словарями, которые детализируют их конфигурацию. В некоторых местах система логирования сможет определить из контекста, как создать экземпляр объекта, но когда требуется создать экземпляр пользовательского объекта, система не будет знать, как это сделать. Для обеспечения полной гибкости при создании пользовательских объектов пользователь должен предоставить «фабрику» – вызываемый объект, который вызывается со словарём конфигурации и возвращает созданный экземпляр. Это обозначается абсолютным путём импорта к фабрике, доступным под специальным ключом `'()'`. Вот конкретный пример:186187```yaml188formatters:189 brief:190 format: '%(message)s'191 default:192 format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s'193 datefmt: '%Y-%m-%d %H:%M:%S'194 custom:195 (): my.package.customFormatterFactory196 bar: baz197 spam: 99.9198 answer: 42199```200201Приведённый выше фрагмент YAML определяет три форматировщика. Первый, с идентификатором `brief`, является стандартным экземпляром [`logging.Formatter`](https://python-all.ru/2.7/library/logging.html#logging.Formatter) с указанной строкой формата. Второй, с идентификатором `default`, имеет более длинный формат, а также явно задаёт формат времени, и в результате будет создан экземпляр [`logging.Formatter`](https://python-all.ru/2.7/library/logging.html#logging.Formatter), инициализированный этими двумя строками формата. В форме исходного кода Python под словари конфигурации форматировщиков `brief` и `default` выглядят так:202203```python204{205 'format' : '%(message)s'206}207```208209и:210211```python212{213 'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',214 'datefmt' : '%Y-%m-%d %H:%M:%S'215}216```217218соответственно, и поскольку эти словари не содержат специального ключа `'()'`, создание экземпляра выводится из контекста: в результате создаются стандартные экземпляры [`logging.Formatter`](https://python-all.ru/2.7/library/logging.html#logging.Formatter). Подсловарь конфигурации для третьего форматировщика, с идентификатором `custom`, таков:219220```python221{222 '()' : 'my.package.customFormatterFactory',223 'bar' : 'baz',224 'spam' : 99.9,225 'answer' : 42226}227```228229и он содержит специальный ключ `'()'`, что означает необходимость пользовательского создания экземпляра. В этом случае будет использована указанная фабрика-вызываемый объект. Если это реальный вызываемый объект, он будет использован напрямую; в противном случае, если указана строка (как в примере), фактический вызываемый объект будет найден с помощью обычных механизмов импорта. Вызываемый объект будет вызван с **оставшимися** элементами в подсловаре конфигурации в качестве именованных аргументов. В приведённом выше примере предполагается, что форматировщик с идентификатором `custom` будет возвращён вызовом:230231```python232my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)233```234235Ключ `'()'` был выбран в качестве специального, потому что он не является допустимым именем параметра ключевого слова и, следовательно, не будет конфликтовать с именами именованных аргументов, используемых при вызове. `'()'` также служит мнемоническим напоминанием о том, что соответствующее значение является вызываемым объектом.236237### 15.8.2.5. Доступ к внешним объектам238239Бывают случаи, когда конфигурации требуется ссылаться на объекты внешние по отношению к конфигурации, например, `sys.stderr`. Если словарь конфигурации создаётся с помощью кода Python, это несложно, но проблема возникает, когда конфигурация задаётся через текстовый файл (например, JSON, YAML). В текстовом файле нет стандартного способа отличить `sys.stderr` от литеральной строки `'sys.stderr'`. Чтобы облегчить это различие, система конфигурации ищет определённые специальные префиксы в строковых значениях и обрабатывает их особым образом. Например, если литеральная строка `'ext://sys.stderr'` указана как значение в конфигурации, то префикс `ext://` будет отброшен, а оставшаяся часть значения обработана с помощью стандартных механизмов импорта.240241Обработка таких префиксов выполняется аналогично обработке протоколов: существует общий механизм поиска префиксов, соответствующих регулярному выражению `^(?P<prefix>[a-z]+)://(?P<suffix>.*)$`, при котором, если префикс `prefix` распознан, часть `suffix` обрабатывается зависящим от префикса образом, и результат обработки заменяет строковое значение. Если префикс не распознан, строковое значение остаётся без изменений.242243### 15.8.2.6. Доступ к внутренним объектам244245Помимо внешних объектов, иногда также возникает необходимость ссылаться на объекты в самой конфигурации. Это будет делаться неявно системой конфигурации для тех вещей, о которых она знает. Например, строковое значение `'DEBUG'` для `level` в логгере или обработчике будет автоматически преобразовано в значение `logging.DEBUG`, а записи `handlers`, `filters` и `formatter` будут принимать идентификатор объекта и разрешаться в соответствующий целевой объект.246247Однако необходим более общий механизм для пользовательских объектов, которые не известны модулю [`logging`](https://python-all.ru/2.7/library/logging.html#module-logging). Например, рассмотрим [`logging.handlers.MemoryHandler`](https://python-all.ru/2.7/library/logging.handlers.html#logging.handlers.MemoryHandler), который принимает аргумент `target` – другой обработчик для делегирования. Поскольку системе уже известен этот класс, то в конфигурации указанный `target` просто должен быть идентификатором объекта соответствующего целевого обработчика, и система разрешит его в обработчик по идентификатору. Однако если пользователь определяет `my.package.MyHandler`, у которого есть обработчик `alternate`, система конфигурации не будет знать, что `alternate` ссылается на обработчик. Чтобы учесть это, общая система разрешения позволяет пользователю указать:248249```python250handlers:251 file:252 # здесь задаётся конфигурация файлового обработчика253254 custom:255 (): my.package.MyHandler256 alternate: cfg://handlers.file257```258259Литеральная строка `'cfg://handlers.file'` будет разрешаться аналогично строкам с префиксом `ext://`, но поиск будет вестись в самой конфигурации, а не в пространстве имён импорта. Этот механизм позволяет доступ по точке или по индексу, подобно тому, как это делается в `str.format`. Таким образом, для следующего фрагмента:260261```python262handlers:263 email:264 class: logging.handlers.SMTPHandler265 mailhost: localhost266 fromaddr: my_app@domain.tld267 toaddrs:268 - support_team@domain.tld269 - dev_team@domain.tld270 subject: Houston, we have a problem.271```272273в конфигурации строка `'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]'`. Последняя форма требуется только в том случае, если ключ содержит пробелы или не алфавитно-цифровые символы. Если значение индекса состоит только из десятичных цифр, доступ будет предпринят с использованием соответствующего целочисленного значения, а при необходимости – строкового значения.274275Для строки `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']`.276277### 15.8.2.7. Разрешение импорта и пользовательские импортёры278279По умолчанию для импорта используется встроенная функция [`__import__()`](https://python-all.ru/2.7/library/functions.html#__import__). Возможно, вы захотите заменить её собственным механизмом импорта: в таком случае можно заменить атрибут `importer` класса `DictConfigurator` или его суперкласса, `BaseConfigurator`. Однако нужно быть осторожным из-за того, как функции доступны из классов через дескрипторы. Если вы используете вызываемый объект Python для импорта и хотите определить его на уровне класса, а не экземпляра, необходимо обернуть его в [`staticmethod()`](https://python-all.ru/2.7/library/functions.html#staticmethod). Например:280281```python282from importlib import import_module283from logging.config import BaseConfigurator284285BaseConfigurator.importer = staticmethod(import_module)286```287288Не нужно оборачивать в [`staticmethod()`](https://python-all.ru/2.7/library/functions.html#staticmethod), если вы устанавливаете вызываемый объект импорта на *экземпляре* конфигуратора.289290## 15.8.3. Формат файла конфигурации291292Формат конфигурационного файла, который понимает [`fileConfig()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.fileConfig), основан на функциональности `configparser`. Файл должен содержать разделы с названиями `[loggers]`, `[handlers]` и `[formatters]`, которые идентифицируют по имени сущности каждого типа, определенные в файле. Для каждой такой сущности существует отдельный раздел, который определяет, как эта сущность настраивается. Так, для регистратора с именем `log01` в разделе `[loggers]` соответствующие детали конфигурации хранятся в разделе `[logger_log01]`. Аналогично, обработчик с именем `hand01` в разделе `[handlers]` будет иметь свою конфигурацию в разделе с названием `[handler_hand01]`, а форматировщик с именем `form01` в разделе `[formatters]` будет иметь свою конфигурацию в разделе `[formatter_form01]`. Конфигурация корневого регистратора должна быть задана в разделе `[logger_root]`.293294> **Примечание**295>296> API [`fileConfig()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.fileConfig) старше, чем API [`dictConfig()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.dictConfig), и не предоставляет функциональности для покрытия некоторых аспектов логирования. Например, вы не можете настроить объекты [`Filter`](https://python-all.ru/2.7/library/logging.html#logging.Filter), которые обеспечивают фильтрацию сообщений, выходящую за рамки простых целочисленных уровней, с помощью [`fileConfig()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.fileConfig). Если вам нужны экземпляры [`Filter`](https://python-all.ru/2.7/library/logging.html#logging.Filter) в вашей конфигурации логирования, вам придется использовать [`dictConfig()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.dictConfig). Обратите внимание, что будущие улучшения функциональности конфигурации будут добавляться в [`dictConfig()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.dictConfig), так что стоит рассмотреть переход на этот более новый API, когда это удобно.297298Примеры таких разделов в файле приведены ниже.299300```ini301[loggers]302keys=root,log02,log03,log04,log05,log06,log07303304[handlers]305keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09306307[formatters]308keys=form01,form02,form03,form04,form05,form06,form07,form08,form09309```310311Корневой регистратор должен указывать уровень и список обработчиков. Пример раздела корневого регистратора приведен ниже.312313```ini314[logger_root]315level=NOTSET316handlers=hand01317```318319Запись `level` может быть одной из `DEBUG, INFO, WARNING, ERROR, CRITICAL` или `NOTSET`. Только для корневого логгера конфигурация `NOTSET` означает, что все сообщения будут записаны. Значения уровней [`eval()`](https://python-all.ru/2.7/library/functions.html#eval) вычисляются в контексте пространства имён `logging` пакета.320321Запись `handlers` представляет собой список имен обработчиков, разделенных запятыми; эти имена должны присутствовать в разделе `[handlers]`. Данные имена должны присутствовать в разделе `[handlers]` и иметь соответствующие разделы в конфигурационном файле.322323Для регистраторов, отличных от корневого, требуется некоторая дополнительная информация. Это проиллюстрировано следующим примером.324325```ini326[logger_parser]327level=DEBUG328handlers=hand01329propagate=1330qualname=compiler.parser331```332333Записи `level` и `handlers` интерпретируются так же, как для корневого регистратора, за исключением того, что если уровень не корневого регистратора указан как `NOTSET`, система обращается к регистраторам выше по иерархии, чтобы определить эффективный уровень регистратора. Запись `propagate` устанавливается в 1, чтобы указать, что сообщения должны распространяться на обработчики выше по иерархии регистраторов от этого регистратора, или в 0, чтобы указать, что сообщения **не** распространяются на обработчики выше по иерархии. Запись `qualname` – это иерархическое имя канала регистратора, то есть имя, используемое приложением для получения регистратора.334335Разделы, которые задают конфигурацию обработчика, иллюстрируются следующим примером.336337```ini338[handler_hand01]339class=StreamHandler340level=NOTSET341formatter=form01342args=(sys.stdout,)343```344345Запись `class` указывает класс обработчика (как определено [`eval()`](https://python-all.ru/2.7/library/functions.html#eval) в пространстве имен пакета `logging`). Запись `level` интерпретируется так же, как для регистраторов, а `NOTSET` означает «регистрировать всё».346347Изменено в версии 2.6: Добавлена поддержка разрешения класса обработчика по точечному имени модуля и класса.348349Запись `formatter` указывает ключевое имя форматировщика для этого обработчика. Если пусто, используется форматировщик по умолчанию (`logging._defaultFormatter`). Если указано имя, оно должно присутствовать в разделе `[formatters]` и иметь соответствующий раздел в конфигурационном файле.350351Запись `args`, при [`eval()`](https://python-all.ru/2.7/library/functions.html#eval)вычислении в контексте `logging` пространства имён пакета, представляет собой список аргументов для конструктора класса обработчика. Обратитесь к конструкторам соответствующих обработчиков или к примерам ниже, чтобы увидеть, как строятся типичные записи.352353```ini354[handler_hand02]355class=FileHandler356level=DEBUG357formatter=form02358args=('python.log', 'w')359360[handler_hand03]361class=handlers.SocketHandler362level=INFO363formatter=form03364args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)365366[handler_hand04]367class=handlers.DatagramHandler368level=WARN369formatter=form04370args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)371372[handler_hand05]373class=handlers.SysLogHandler374level=ERROR375formatter=form05376args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)377378[handler_hand06]379class=handlers.NTEventLogHandler380level=CRITICAL381formatter=form06382args=('Python Application', '', 'Application')383384[handler_hand07]385class=handlers.SMTPHandler386level=WARN387formatter=form07388args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')389390[handler_hand08]391class=handlers.MemoryHandler392level=NOTSET393formatter=form08394target=395args=(10, ERROR)396397[handler_hand09]398class=handlers.HTTPHandler399level=NOTSET400formatter=form09401args=('localhost:9022', '/log', 'GET')402```403404Разделы, которые задают конфигурацию форматировщика, обычно выглядят следующим образом.405406```ini407[formatter_form01]408format=F1 %(asctime)s %(levelname)s %(message)s409datefmt=410class=logging.Formatter411```412413Запись `format` задаёт общую строку формата, а запись `datefmt` задаёт строку формата даты/времени, совместимую с `strftime()`. Если она пуста, пакет подставляет даты/время в формате ISO8601, что почти эквивалентно указанию строки формата даты `'%Y-%m-%d %H:%M:%S'`. Формат ISO8601 также задаёт миллисекунды, которые добавляются к результату использования указанной строки формата через запятую. Пример времени в формате ISO8601: `2003-01-23 00:29:50,411`.414415Запись `class` является необязательной. Она указывает имя класса форматера (в виде полного имени модуля и класса через точку.) Этот параметр полезен для создания экземпляра подкласса [`Formatter`](https://python-all.ru/2.7/library/logging.html#logging.Formatter). Подклассы [`Formatter`](https://python-all.ru/2.7/library/logging.html#logging.Formatter) могут отображать трассировку исключений в развёрнутом или сжатом формате.416417> **Примечание**418>419> Из-за использования [`eval()`](https://python-all.ru/2.7/library/functions.html#eval), как описано выше, существуют потенциальные угрозы безопасности, связанные с использованием [`listen()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.listen) для отправки и получения конфигураций через сокеты. Риски ограничены случаями, когда несколько пользователей, не доверяющих друг другу, запускают код на одной машине; обратитесь к документации [`listen()`](https://python-all.ru/2.7/library/logging.config.html#logging.config.listen) для получения дополнительной информации.420421> **См. также**422>423> **Модуль [`logging`](https://python-all.ru/2.7/library/logging.html#module-logging)**424>425> Справочник API для модуля logging.426>427> **Модуль [`logging.handlers`](https://python-all.ru/2.7/library/logging.handlers.html#module-logging.handlers)**428>429> Полезные обработчики, входящие в состав модуля logging.430