Сообщить об ошибке.

Функция fileConfig() модуля logging.config в Python.

Настройка регистратора logger при помощи файла конфигурации.

Синтаксис:

import logging

logging.config.fileConfig(fname, defaults=None, 
                            disable_existing_loggers=True)

Параметры:

  • fname - имя файла,
  • defaults=None - словарь значений по умолчанию,
  • disable_existing_loggers=True - совместимость со старыми версиями.

Возвращаемое значение:

  • нет.

Описание:

Функция logging.config.fileConfig() читает конфигурацию, поддерживаемую модулем configparser из файла fname. Формат файла должен быть таким, как описано в "Формате файла конфигурации".

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

Аргумент fname - имя файла в качестве строки или файлоподобный объект. Создается экземпляр Configparser и конфигурация, считываемая им из объекта, передается в fname. Если у него есть метод readline(), то он считается объектом открытого файла и читается с использованием read_file(). В противном случае предполагается, что это имя файла и передается в метод file.read() встроенной функции open().

Аргумент defaults - словарь значений по умолчанию для передачи в ConfigParser.

Если значение аргумент disable_existing_loggers=False, то средства ведения журнала, которые существуют при выполнении этого вызова, остаются включенными. По умолчанию установлено значение True, поскольку это разрешает старое поведение в обратно-совместимом виде. Это приводит к отключению любых существующих регистраторов без полномочий root, если только они или их предки не указаны явно в конфигурации регистратора.

Примеры простой конфигурации:

[loggers]
keys=root,logger

[handlers]
keys=FileHandler

[formatters]
keys=loggerFormatter

[logger_root]
level=DEBUG
handlers=FileHandler

[logger_logger]
level=DEBUG
handlers=FileHandler
qualname=logger
propagate=0

[handler_FileHandler]
class=FileHandler
level=DEBUG
formatter=loggerFormatter
args=('example.log',)

[formatter_loggerFormatter]
format=[%(asctime)s] [%(name)s] [%(levelname)s] > %(message)s
datefmt=%Y-%m-%d %H:%M:%S

Формат файла конфигурации.

Формат файла конфигурации функции logging.config.fileConfig() основан на функциональности модуля configparser .

Файл должен содержать разделы, с названиями [loggers], [handlers] и [formatters], которые идентифицируют по имени сущности каждого типа. Для каждого такого объекта есть отдельный раздел, который определяет, как этот объект настроен. Таким образом, для регистратора log01, указанного в разделе [loggers], соответствующая конфигурация будет содержатся в разделе [logger_log01]. Аналогично, обработчик hand01, указанный в разделе [handlers], будет иметь свою конфигурацию, хранящуюся в разделе с именем [handler_hand01], в то время как объект форматирования form01, указанный в разделе [formatters] будет иметь свою конфигурацию, указанную в разделе [formatter_form01], Конфигурация корневого регистратора должна быть указана в разделе с именем [logger_root].

Примечание. API-интерфейс fileConfig() старше, чем API-интерфейс dictConfig() и не предоставляет функциональных возможностей для покрытия определенных аспектов ведения журнала. Например используя fileConfig() нельзя настроить объекты logging.Filter, которые обеспечивают фильтрацию сообщений за пределами простых целочисленных уровней. Если необходимо использовать экземпляры Filter в конфигурации журналирования, то нужно будет использовать функцию logging.config.dictConfig().

Обратите внимание, что будущие улучшения функциональности конфигурации будут добавляться в dictConfig(), поэтому стоит подумать о переходе на этот более новый API.

Примеры разделов в файле конфигурации:

[loggers]
keys=root,log02,log03,log04,log05,log06,log07

[handlers]
keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09

[formatters]
keys=form01,form02,form03,form04,form05,form06,form07,form08,form09

Корневой регистратор должен указать уровень и список обработчиков. Пример раздела корневого регистратора:

[logger_root]
level=NOTSET
handlers=hand01

Уровень логирования level может быть одним из: DEBUG, INFO, WARNING, ERROR, CRITICAL или NOTSET. Только для корневого регистратора NOTSET означает, что будут регистрироваться все сообщения. Значения уровня eval() используются в контексте пространства имен пакета логирования.

Запись обработчиков handlers представляет собой разделенный запятыми список имен обработчиков, который записывается в разделе [handlers]. Эти имена должны иметь соответствующие разделы в файле конфигурации.

Для регистраторов Logger, отличных от корневого регистратора, требуется некоторая дополнительная информация. Это иллюстрируется следующим примером.

[logger_parser]
level=DEBUG
handlers=hand01
propagate=1
qualname=compiler.parser

Записи об уровне логирования и обработчиках интерпретируются как для корневого регистратора, за исключением того, что если уровень НЕ корневого регистратора указан как NOTSET, то система опрашивает регистраторы выше по иерархии для определения эффективного уровеня регистратора. Запись распространения установлена ​​в 1, чтобы указать, что сообщения должны распространяться на обработчики выше иерархии регистратора от этого регистратора или в 0 - сообщения не распространяются на обработчики вверх по иерархии. Запись qualname - это имя иерархического канала регистратора, то есть имя, используемое приложением для получения регистратора.

Разделы, которые определяют конфигурацию обработчика:

[handler_hand01]
class=StreamHandler
level=NOTSET
formatter=form01
args=(sys.stdout,)

Запись class указывает класс обработчика как определено eval() в пространстве имен пакета регистрации. Уровень логирования интерпретируется как для регистраторов, а NOTSET используется для обозначения "регистрировать все".

Запись formatter указывает имя ключа объекта форматирования для этого обработчика. Если пусто, используется форматтер по умолчанию logging._defaultFormatter). Если указано имя, то оно должно появиться в разделе[formatters]` и иметь соответствующий раздел в файле конфигурации.

Запись args, представляет собой список аргументов конструктора для класса обработчика. Смотрите примеры ниже, чтобы понять, как создаются типичные записи. Если args не указано, то по умолчанию используется значение ().

Необязательная запись kwargs, является словарем dict для конструктора класса обработчика. Если не указано, то по умолчанию используется {}.

[handler_hand02]
class=FileHandler
level=DEBUG
formatter=form02
args=('python.log', 'w')

[handler_hand03]
class=handlers.SocketHandler
level=INFO
formatter=form03
args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)

[handler_hand04]
class=handlers.DatagramHandler
level=WARN
formatter=form04
args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)

[handler_hand05]
class=handlers.SysLogHandler
level=ERROR
formatter=form05
args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)

[handler_hand06]
class=handlers.NTEventLogHandler
level=CRITICAL
formatter=form06
args=('Python Application', '', 'Application')

[handler_hand07]
class=handlers.SMTPHandler
level=WARN
formatter=form07
args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
kwargs={'timeout': 10.0}

[handler_hand08]
class=handlers.MemoryHandler
level=NOTSET
formatter=form08
target=
args=(10, ERROR)

[handler_hand09]
class=handlers.HTTPHandler
level=NOTSET
formatter=form09
args=('localhost:9022', '/log', 'GET')
kwargs={'secure': True}

Разделы, которые определяют конфигурацию объекта форматирования:

[formatter_form01]
format=F1 %(asctime)s %(levelname)s %(message)s
datefmt=
class=logging.Formatter

Запись format - это общая строка формата, а запись datefmt - строка формата даты/времени, совместимая с time.strftime().

Если datefmt пуст, то это эквивалентно указанию строки формата даты '%Y-%m-%d %H:%M:%S'. Этот формат также определяет миллисекунды, которые добавляются к результату с разделителем запятых. Пример времени в этом формате: 2003-01-23 00: 29: 50,411.

Запись class является необязательной и указывает имя класса Formatter. Этот параметр полезен для создания экземпляра подкласса Formatter. Подклассы Formatter могут представлять трассировки исключений в расширенном или сжатом формате.