logging — журналирование событий

Этот модуль предоставляет облегчённое подмножество стандартного пакета logging из Python, адаптированное для MicroPython. Он поддерживает журналирование по уровням через иерархически именованные объекты Logger, небольшой набор обработчиков (StreamHandler, FileHandler), форматирование в стиле printf через Formatter, а также удобные функции уровня модуля, эквивалентные тем, что работают с корневым логгером.

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

Константы уровней

logging.CRITICAL: int

Числовое значение 50. Используется для невосстановимых ошибок.

logging.ERROR: int

Числовое значение 40. Используется для серьёзных проблем.

logging.WARNING: int

Числовое значение 30. Уровень по умолчанию для только что настроенного корневого логгера.

logging.INFO: int

Числовое значение 20. Используется для подтверждающих сообщений.

logging.DEBUG: int

Числовое значение 10. Используется для подробного диагностического вывода.

logging.NOTSET: int

Числовое значение 0. Указывает на логгер без настроенного уровня (в этом случае эффективный уровень наследуется от корневого логгера или равен WARNING).

Функции

logging.getLogger(name: str | None = None) → Logger

Возвращает Logger, зарегистрированный под именем name, создавая его при первом использовании. Если name равно None, возвращается корневой логгер. Первый вызов с name="root" (или с неуказанным name) неявно вызывает basicConfig, чтобы присоединить StreamHandler по умолчанию, пишущий в sys.stderr.

logging.log(level: int, msg: str, *args) → None

Журналирует сообщение с уровнем level на корневом логгере. Аргументы args подставляются в msg с использованием форматирования в стиле printf через %; единственный аргумент-словарь используется как отображение.

logging.debug(msg: str, *args) → None

Эквивалентно getLogger().debug(msg, *args).

logging.info(msg: str, *args) → None

Эквивалентно getLogger().info(msg, *args).

logging.warning(msg: str, *args) → None

Эквивалентно getLogger().warning(msg, *args).

logging.error(msg: str, *args) → None

Эквивалентно getLogger().error(msg, *args).

logging.critical(msg: str, *args) → None

Эквивалентно getLogger().critical(msg, *args).

logging.exception(msg: str, *args, exc_info: bool | BaseException = True) → None

Эквивалентно getLogger().exception(msg, *args, exc_info=exc_info). Журналирует сообщение с уровнем ERROR и дополнительно форматирует трассировку активного исключения, когда exc_info истинно. Если exc_info само является BaseException, используется трассировка этого исключения; иначе при наличии вызывается sys.exc_info().

logging.shutdown() → None

Закрывает каждый обработчик, присоединённый к каждому известному логгеру, и забывает логгеры. Регистрируется автоматически через sys.atexit, когда этот хук доступен.

logging.addLevelName(level: int, name: str) → None

Связывает текстовое имя name с числовым уровнем level, чтобы Formatter мог отобразить его через %(levelname)s.

logging.basicConfig(filename: str | None = None, filemode: str = 'a', format: str | None = None, datefmt: str | None = None, level: int = WARNING, stream=None, encoding: str = 'UTF-8', force: bool = False) → None

Настраивает корневой логгер с единственным обработчиком.

Если задан filename, создаётся FileHandler с использованием filemode и encoding; иначе используется StreamHandler, пишущий в stream (по умолчанию sys.stderr).

Параметры format и datefmt передаются в новый Formatter.

Параметр level задаёт уровень как обработчика, так и корневого логгера.

Если у корневого логгера уже есть обработчики, эта функция ничего не делает, если только force не равно True — в этом случае существующие обработчики закрываются и заменяются.

Классы

class logging.Logger(name: str, level: int = NOTSET)

Именованный логгер. Создавайте логгеры через getLogger, а не напрямую, чтобы getLogger мог возвращать один и тот же экземпляр для одного и того же имени.

name: str

Имя логгера с точечной нотацией.

level: int

Настроенный числовой уровень. 0 (NOTSET) означает «наследовать».

handlers: list

Список экземпляров Handler, присоединённых к этому логгеру. Когда он пуст, сообщения направляются обработчикам корневого логгера.

setLevel(level: int) → None

Устанавливает пороговый уровень логгера.

isEnabledFor(level: int) → bool

Возвращает True, если сообщение уровня level будет обработано этим логгером.

getEffectiveLevel() → int

Возвращает первое ненулевое из: уровня этого логгера, уровня корневого логгера или WARNING.

log(level: int, msg: str, *args) → None

Журналирует msg с уровнем level. Аргументы args подставляются в msg с помощью оператора %; если первый позиционный аргумент является словарём, он используется как отображение.

debug(msg: str, *args) → None

Журналирует msg с уровнем DEBUG.

info(msg: str, *args) → None

Журналирует msg с уровнем INFO.

warning(msg: str, *args) → None

Журналирует msg с уровнем WARNING.

error(msg: str, *args) → None

Журналирует msg с уровнем ERROR.

critical(msg: str, *args) → None

Журналирует msg с уровнем CRITICAL.

exception(msg: str, *args, exc_info: bool | BaseException = True) → None

Журналирует msg с уровнем ERROR и, когда exc_info истинно, добавляет отформатированную трассировку. Если exc_info является экземпляром BaseException, отображается трассировка этого исключения; иначе активное исключение запрашивается через sys.exc_info().

addHandler(handler: Handler) → None

Присоединяет handler к этому логгеру.

hasHandlers() → bool

Возвращает True, если к этому логгеру присоединены какие-либо обработчики.

class logging.Handler(level: int = NOTSET)

Базовый класс для всех обработчиков. Подклассы реализуют emit().

level: int

Пороговый уровень обработчика.

formatter: 'Formatter | None'

Активный Formatter или None.

setLevel(level: int) → None

Устанавливает пороговый уровень обработчика.

setFormatter(formatter: Formatter) → None

Присоединяет formatter к этому обработчику.

format(record: LogRecord) → str

Отображает record с использованием настроенного форматтера.

close() → None

Освобождает ресурсы, удерживаемые обработчиком. Вызывается из shutdown и из FileHandler при его закрытии.

class logging.StreamHandler(stream=None)

Обработчик, который записывает отформатированные записи, за которыми следует self.terminator (по умолчанию "\n"), в stream. По умолчанию stream равен sys.stderr.

stream

Объект целевого потока.

terminator: str

Строка, добавляемая после каждой отформатированной записи. По умолчанию "\n".

emit(record: LogRecord) → None

Записывает record в stream, если его уровень соответствует порогу обработчика.

close() → None

Сбрасывает буфер нижележащего потока, когда тот предоставляет метод flush.

class logging.FileHandler(filename: str, mode: str = 'a', encoding: str = 'UTF-8')

Подкласс StreamHandler, который открывает filename с заданными mode и encoding и записывает в него отформатированные записи. Нижележащий файл закрывается при close().

class logging.Formatter(fmt: str | None = None, datefmt: str | None = None)

Отображает экземпляры LogRecord в строки.

fmt — это шаблон в стиле printf. Распознаваемые ключи: %(name)s, %(message)s, %(msecs)d, %(asctime)s и %(levelname)s. Если не задан, по умолчанию используется "%(levelname)s:%(name)s:%(message)s".

datefmt — это шаблон time.strftime, используемый для отображения %(asctime)s. По умолчанию "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Возвращает True, если шаблон формата ссылается на asctime.

formatTime(datefmt: str, record: LogRecord) → str | None

Форматирует record.ct с использованием time.strftime и datefmt. Возвращает None на платформах, где time.strftime недоступен.

format(record: LogRecord) → str

Отображает record. Если шаблон использует asctime, сначала вызывается formatTime(), чтобы заполнить record.asctime.

class logging.LogRecord

Контейнер для данных, передаваемых от Logger его обработчикам. Экземпляры заполняются через set(); реализации логгера повторно используют одну запись на логгер, чтобы сократить количество выделений памяти.

name: str

Имя логгера-источника.

levelno: int

Числовой уровень этой записи.

levelname: str

Текстовое имя уровня.

message: str

Полностью отформатированное сообщение журнала.

ct: float

Время создания, как возвращает time.time().

msecs: int

Миллисекундная составляющая ct.

asctime: str | None

Человекочитаемая временная метка; заполняется отложенно через Formatter.

set(name: str, level: int, message: str) → None

Инициализирует запись заданными значениями и фиксирует текущее время.