logging — rejestrowanie zdarzeń

Ten moduł udostępnia lekki podzbiór standardowego pakietu logging z Pythona, dostosowany do MicroPython. Obsługuje rejestrowanie z poziomami za pośrednictwem hierarchicznie nazwanych obiektów Logger, niewielki zestaw procedur obsługi (StreamHandler, FileHandler), formatowanie w stylu printf przez Formatter oraz funkcje pomocnicze na poziomie modułu odpowiadające tym operującym na głównym loggerze.

Moduł na tyle wiernie odwzorowuje znane API z CPython, że proste aplikacje napisane dla biblioteki standardowej powinny działać bez zmian. Filtry, blokowanie wielu procesów, format pliku konfiguracyjnego oraz większość klas procedur obsługi nie są dostępne.

Stałe poziomów

logging.CRITICAL: int

Wartość liczbowa 50. Używana dla błędów nieodwracalnych.

logging.ERROR: int

Wartość liczbowa 40. Używana dla poważnych problemów.

logging.WARNING: int

Wartość liczbowa 30. Domyślny poziom dla świeżo skonfigurowanego głównego loggera.

logging.INFO: int

Wartość liczbowa 20. Używana dla komunikatów potwierdzających.

logging.DEBUG: int

Wartość liczbowa 10. Używana dla szczegółowych danych diagnostycznych.

logging.NOTSET: int

Wartość liczbowa 0. Wskazuje logger bez skonfigurowanego poziomu (poziom efektywny jest wówczas dziedziczony z głównego loggera lub WARNING).

Funkcje

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

Zwraca Logger zarejestrowany pod nazwą name, tworząc go przy pierwszym użyciu. Jeśli name ma wartość None, zwracany jest główny logger. Pierwsze wywołanie z name="root" (lub z nieustawionym name) niejawnie wywołuje basicConfig, aby dołączyć domyślny StreamHandler zapisujący do sys.stderr.

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

Rejestruje komunikat na poziomie level w głównym loggerze. args są wstawiane do msg przy użyciu formatowania % w stylu printf; pojedynczy argument typu słownik jest używany jako mapowanie.

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

Równoważne getLogger().debug(msg, *args).

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

Równoważne getLogger().info(msg, *args).

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

Równoważne getLogger().warning(msg, *args).

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

Równoważne getLogger().error(msg, *args).

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

Równoważne getLogger().critical(msg, *args).

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

Równoważne getLogger().exception(msg, *args, exc_info=exc_info). Rejestruje komunikat na poziomie ERROR i dodatkowo formatuje ślad stosu aktywnego wyjątku, gdy exc_info jest prawdziwe. Jeśli samo exc_info jest typu BaseException, używany jest ślad stosu tego wyjątku; w przeciwnym razie, gdy jest dostępne, sprawdzane jest sys.exc_info().

logging.shutdown() → None

Zamyka każdą procedurę obsługi dołączoną do każdego znanego loggera i zapomina o loggerach. Rejestrowane automatycznie przez sys.atexit, gdy ten haczyk jest dostępny.

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

Wiąże nazwę tekstową name z poziomem liczbowym level, tak aby Formatter mógł ją wyrenderować za pomocą %(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

Konfiguruje główny logger z pojedynczą procedurą obsługi.

Jeśli podano filename, tworzony jest FileHandler przy użyciu filemode i encoding; w przeciwnym razie używany jest StreamHandler zapisujący do stream (domyślnie sys.stderr).

format i datefmt są przekazywane do nowego Formatter.

level ustawia zarówno poziom procedury obsługi, jak i poziom głównego loggera.

Jeśli główny logger ma już procedury obsługi, ta funkcja nie wykonuje żadnych działań, chyba że force ma wartość True — wtedy istniejące procedury obsługi są zamykane i zastępowane.

Klasy

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

Nazwany logger. Loggery należy tworzyć za pośrednictwem getLogger, a nie bezpośrednio, aby getLogger mógł zwracać tę samą instancję dla tej samej nazwy.

name: str

Nazwa loggera z kropkami.

level: int

Skonfigurowany poziom liczbowy. 0 (NOTSET) oznacza „dziedzicz”.

handlers: list

Lista instancji Handler dołączonych do tego loggera. Gdy jest pusta, komunikaty są kierowane do procedur obsługi głównego loggera.

setLevel(level: int) → None

Ustawia poziom progowy loggera.

isEnabledFor(level: int) → bool

Zwraca True, jeśli komunikat o poziomie level zostałby przetworzony przez ten logger.

getEffectiveLevel() → int

Zwraca pierwszą niezerową wartość spośród: poziomu tego loggera, poziomu głównego loggera lub WARNING.

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

Rejestruje msg na poziomie level. args są wstawiane do msg za pomocą operatora %; jeśli pierwszy argument pozycyjny jest słownikiem, jest on używany jako mapowanie.

debug(msg: str, *args) → None

Rejestruje msg na poziomie DEBUG.

info(msg: str, *args) → None

Rejestruje msg na poziomie INFO.

warning(msg: str, *args) → None

Rejestruje msg na poziomie WARNING.

error(msg: str, *args) → None

Rejestruje msg na poziomie ERROR.

critical(msg: str, *args) → None

Rejestruje msg na poziomie CRITICAL.

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

Rejestruje msg na poziomie ERROR i, gdy exc_info jest prawdziwe, dołącza sformatowany ślad stosu. Jeśli exc_info jest instancją BaseException, renderowany jest ślad stosu tego wyjątku; w przeciwnym razie aktywny wyjątek jest sprawdzany przez sys.exc_info().

addHandler(handler: Handler) → None

Dołącza handler do tego loggera.

hasHandlers() → bool

Zwraca True, jeśli do tego loggera dołączone są jakiekolwiek procedury obsługi.

class logging.Handler(level: int = NOTSET)

Klasa bazowa dla wszystkich procedur obsługi. Podklasy implementują emit().

level: int

Poziom progowy procedury obsługi.

formatter: 'Formatter | None'

Aktywny Formatter lub None.

setLevel(level: int) → None

Ustawia poziom progowy procedury obsługi.

setFormatter(formatter: Formatter) → None

Dołącza formatter do tej procedury obsługi.

format(record: LogRecord) → str

Renderuje record przy użyciu skonfigurowanego formattera.

close() → None

Zwalnia zasoby przechowywane przez procedurę obsługi. Wywoływane przez shutdown oraz przez FileHandler przy jego zamykaniu.

class logging.StreamHandler(stream=None)

Procedura obsługi, która zapisuje sformatowane rekordy, zakończone self.terminator (domyślnie "\n"), do stream. stream domyślnie przyjmuje wartość sys.stderr.

stream

Docelowy obiekt strumienia.

terminator: str

Ciąg znaków dołączany po każdym sformatowanym rekordzie. Domyślnie "\n".

emit(record: LogRecord) → None

Zapisuje record do stream, jeśli jego poziom spełnia próg procedury obsługi.

close() → None

Opróżnia bazowy strumień, gdy udostępnia on metodę flush.

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

Podklasa StreamHandler, która otwiera filename z podanymi mode i encoding oraz zapisuje do niego sformatowane rekordy. Bazowy plik jest zamykany przy close().

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

Renderuje instancje LogRecord do ciągów znaków.

fmt to szablon w stylu printf. Rozpoznawane klucze to %(name)s, %(message)s, %(msecs)d, %(asctime)s oraz %(levelname)s. Gdy nie jest ustawiony, przyjmuje domyślną wartość "%(levelname)s:%(name)s:%(message)s".

datefmt to szablon time.strftime używany do renderowania %(asctime)s. Domyślnie "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Zwraca True, jeśli szablon formatu odwołuje się do asctime.

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

Formatuje record.ct przy użyciu time.strftime i datefmt. Zwraca None na platformach, gdzie time.strftime jest niedostępne.

format(record: LogRecord) → str

Renderuje record. Jeśli szablon używa asctime, najpierw wywoływane jest formatTime(), aby wypełnić record.asctime.

class logging.LogRecord

Kontener na dane przekazywane z Logger do jego procedur obsługi. Instancje są wypełniane za pomocą set(); implementacje loggerów ponownie wykorzystują pojedynczy rekord na logger, aby ograniczyć alokacje.

name: str

Nazwa loggera, z którego pochodzi rekord.

levelno: int

Poziom liczbowy tego rekordu.

levelname: str

Tekstowa nazwa poziomu.

message: str

W pełni sformatowany komunikat dziennika.

ct: float

Czas utworzenia zwracany przez time.time().

msecs: int

Składowa milisekundowa ct.

asctime: str | None

Czytelny dla człowieka znacznik czasu; wypełniany leniwie przez Formatter.

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

Inicjalizuje rekord podanymi wartościami i przechwytuje bieżący czas.