logging — журналювання подій

Цей модуль надає легковажну підмножину стандартного пакета Python logging, адаптовану для 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

Ініціалізує запис із заданими значеннями та фіксує поточний час.