logging — protokolování událostí

Tento modul poskytuje odlehčenou podmnožinu standardního balíčku logging z jazyka Python přizpůsobenou pro MicroPython. Podporuje úrovňové protokolování prostřednictvím hierarchicky pojmenovaných objektů Logger, malou sadu obslužných rutin (StreamHandler, FileHandler), formátování ve stylu printf přes Formatter a funkce na úrovni modulu odpovídající těm, které pracují s kořenovým loggerem.

Modul dostatečně přesně kopíruje známé CPython API, takže jednoduché aplikace napsané pro standardní knihovnu by měly fungovat beze změn. Filtry, zamykání mezi více procesy, formát konfiguračního souboru a většina tříd obslužných rutin nejsou k dispozici.

Konstanty úrovní

logging.CRITICAL: int

Číselná hodnota 50. Používá se pro neopravitelné chyby.

logging.ERROR: int

Číselná hodnota 40. Používá se pro vážné problémy.

logging.WARNING: int

Číselná hodnota 30. Výchozí úroveň pro čerstvě nakonfigurovaný kořenový logger.

logging.INFO: int

Číselná hodnota 20. Používá se pro potvrzovací zprávy.

logging.DEBUG: int

Číselná hodnota 10. Používá se pro podrobný diagnostický výstup.

logging.NOTSET: int

Číselná hodnota 0. Označuje logger bez nastavené úrovně (efektivní úroveň se pak dědí od kořenového loggeru nebo z WARNING).

Funkce

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

Vrátí Logger registrovaný pod jménem name a při prvním použití jej vytvoří. Pokud je name None, vrátí se kořenový logger. První volání s name="root" (nebo s nenastaveným name) implicitně vyvolá basicConfig, aby připojilo výchozí StreamHandler zapisující do sys.stderr.

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

Zaprotokoluje zprávu na úrovni level v kořenovém loggeru. args se interpolují do msg pomocí formátování % ve stylu printf; jediný argument typu dict se použije jako mapování.

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

Ekvivalent getLogger().debug(msg, *args).

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

Ekvivalent getLogger().info(msg, *args).

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

Ekvivalent getLogger().warning(msg, *args).

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

Ekvivalent getLogger().error(msg, *args).

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

Ekvivalent getLogger().critical(msg, *args).

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

Ekvivalent getLogger().exception(msg, *args, exc_info=exc_info). Zaprotokoluje zprávu na úrovni ERROR a navíc zformátuje traceback aktivní výjimky, je-li exc_info pravdivé. Pokud je exc_info samo o sobě BaseException, použije se traceback této výjimky; jinak se, je-li to možné, použije sys.exc_info().

logging.shutdown() → None

Zavře každou obslužnou rutinu připojenou ke každému známému loggeru a zapomene loggery. Automaticky se registruje prostřednictvím sys.atexit, je-li tento hook k dispozici.

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

Přiřadí textové jméno name číselné úrovni level, aby je Formatter mohl vykreslit 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

Nakonfiguruje kořenový logger s jedinou obslužnou rutinou.

Je-li zadán filename, vytvoří se FileHandler používající filemode a encoding; jinak se použije StreamHandler zapisující do stream (výchozí sys.stderr).

format a datefmt se předají novému objektu Formatter.

level nastaví úroveň obslužné rutiny i úroveň kořenového loggeru.

Pokud kořenový logger již má obslužné rutiny, je tato funkce bez efektu, ledaže je force True, v kterémžto případě se stávající obslužné rutiny zavřou a nahradí.

Třídy

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

Pojmenovaný logger. Loggery vytvářejte přes getLogger, nikoli přímo, aby getLogger mohl pro stejné jméno vracet stejnou instanci.

name: str

Tečkované jméno loggeru.

level: int

Nakonfigurovaná číselná úroveň. 0 (NOTSET) znamená „dědit“.

handlers: list

Seznam instancí Handler připojených k tomuto loggeru. Je-li prázdný, zprávy se odesílají obslužným rutinám kořenového loggeru.

setLevel(level: int) → None

Nastaví prahovou úroveň loggeru.

isEnabledFor(level: int) → bool

Vrátí True, pokud by zpráva úrovně level byla tímto loggerem zpracována.

getEffectiveLevel() → int

Vrátí první nenulovou z hodnot: úroveň tohoto loggeru, úroveň kořenového loggeru nebo WARNING.

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

Zaprotokoluje msg na úrovni level. args se interpolují do msg operátorem %; je-li první poziční argument dict, použije se jako mapování.

debug(msg: str, *args) → None

Zaprotokoluje msg na úrovni DEBUG.

info(msg: str, *args) → None

Zaprotokoluje msg na úrovni INFO.

warning(msg: str, *args) → None

Zaprotokoluje msg na úrovni WARNING.

error(msg: str, *args) → None

Zaprotokoluje msg na úrovni ERROR.

critical(msg: str, *args) → None

Zaprotokoluje msg na úrovni CRITICAL.

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

Zaprotokoluje msg na úrovni ERROR a, je-li exc_info pravdivé, připojí zformátovaný traceback. Pokud je exc_info instance BaseException, vykreslí se traceback této výjimky; jinak se aktivní výjimka získá přes sys.exc_info().

addHandler(handler: Handler) → None

Připojí handler k tomuto loggeru.

hasHandlers() → bool

Vrátí True, pokud jsou k tomuto loggeru připojeny nějaké obslužné rutiny.

class logging.Handler(level: int = NOTSET)

Základní třída pro všechny obslužné rutiny. Podtřídy implementují emit().

level: int

Prahová úroveň obslužné rutiny.

formatter: 'Formatter | None'

Aktivní Formatter, nebo None.

setLevel(level: int) → None

Nastaví prahovou úroveň obslužné rutiny.

setFormatter(formatter: Formatter) → None

Připojí formatter k této obslužné rutině.

format(record: LogRecord) → str

Vykreslí record pomocí nakonfigurovaného formátovače.

close() → None

Uvolní prostředky držené obslužnou rutinou. Volá se z shutdown a z FileHandler, když je zavírána.

class logging.StreamHandler(stream=None)

Obslužná rutina, která zapisuje zformátované záznamy následované self.terminator (ve výchozím stavu "\n") do stream. stream je ve výchozím stavu sys.stderr.

stream

Cílový objekt streamu.

terminator: str

Řetězec připojovaný za každý zformátovaný záznam. Výchozí hodnota je "\n".

emit(record: LogRecord) → None

Zapíše record do stream, pokud jeho úroveň dosahuje prahu obslužné rutiny.

close() → None

Vyprázdní podkladový stream, pokud poskytuje metodu flush.

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

Podtřída StreamHandler, která otevře filename s daným mode a encoding a zapisuje do něj zformátované záznamy. Podkladový soubor se zavře při close().

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

Vykresluje instance LogRecord do řetězců.

fmt je šablona ve stylu printf. Rozpoznávané klíče jsou %(name)s, %(message)s, %(msecs)d, %(asctime)s a %(levelname)s. Není-li nastaven, použije se výchozí "%(levelname)s:%(name)s:%(message)s".

datefmt je šablona time.strftime použitá k vykreslení %(asctime)s. Výchozí hodnota je "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Vrátí True, pokud formátovací šablona odkazuje na asctime.

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

Zformátuje record.ct pomocí time.strftime a datefmt. Na platformách, kde time.strftime není k dispozici, vrátí None.

format(record: LogRecord) → str

Vykreslí record. Pokud šablona používá asctime, nejprve se vyvolá formatTime(), aby naplnila record.asctime.

class logging.LogRecord

Kontejner pro data předávaná z Logger jeho obslužným rutinám. Instance se plní prostřednictvím set(); implementace loggeru opakovaně používají jediný záznam na logger, aby se omezily alokace.

name: str

Jméno původního loggeru.

levelno: int

Číselná úroveň tohoto záznamu.

levelname: str

Textový název úrovně.

message: str

Plně zformátovaná zpráva protokolu.

ct: float

Čas vytvoření vrácený funkcí time.time().

msecs: int

Milisekundová složka ct.

asctime: str | None

Časová značka čitelná člověkem; naplňuje se líně objektem Formatter.

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

Inicializuje záznam danými hodnotami a zachytí aktuální čas.