logging — jurnalizarea evenimentelor

Acest modul oferă un subset ușor al pachetului standard Python logging, adaptat pentru MicroPython. Acceptă jurnalizarea pe niveluri prin obiecte Logger denumite ierarhic, un set restrâns de handlere (StreamHandler, FileHandler), formatare în stil printf prin Formatter și funcții de conveniență la nivel de modul echivalente cu cele care operează pe loggerul rădăcină.

Modulul urmărește API-ul familiar CPython suficient de îndeaproape încât aplicațiile simple scrise pentru biblioteca standard ar trebui să funcționeze nemodificate. Filtrele, blocarea pe mai multe procese, formatul fișierului de configurare și majoritatea claselor de handlere nu sunt furnizate.

Constante de nivel

logging.CRITICAL: int

Valoare numerică 50. Utilizată pentru erori nerecuperabile.

logging.ERROR: int

Valoare numerică 40. Utilizată pentru probleme grave.

logging.WARNING: int

Valoare numerică 30. Nivelul implicit pentru un logger rădăcină proaspăt configurat.

logging.INFO: int

Valoare numerică 20. Utilizată pentru mesaje de confirmare.

logging.DEBUG: int

Valoare numerică 10. Utilizată pentru ieșire de diagnosticare detaliată.

logging.NOTSET: int

Valoare numerică 0. Indică un logger fără niciun nivel configurat (nivelul efectiv este atunci moștenit de la loggerul rădăcină sau WARNING).

Funcții

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

Returnează Logger-ul înregistrat sub name, creându-l la prima utilizare. Dacă name este None, este returnat loggerul rădăcină. Primul apel cu name="root" (sau cu name nesetat) invocă implicit basicConfig pentru a atașa un StreamHandler implicit care scrie în sys.stderr.

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

Jurnalizează un mesaj la nivelul level pe loggerul rădăcină. args sunt interpolate în msg folosind formatarea în stil printf %; un singur argument de tip dicționar este utilizat ca mapare.

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

Echivalent cu getLogger().debug(msg, *args).

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

Echivalent cu getLogger().info(msg, *args).

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

Echivalent cu getLogger().warning(msg, *args).

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

Echivalent cu getLogger().error(msg, *args).

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

Echivalent cu getLogger().critical(msg, *args).

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

Echivalent cu getLogger().exception(msg, *args, exc_info=exc_info). Jurnalizează mesajul la ERROR și, în plus, formatează traceback-ul excepției active atunci când exc_info este adevărat. Dacă exc_info este el însuși o BaseException, se utilizează traceback-ul acelei excepții; altfel se consultă sys.exc_info() atunci când este disponibil.

logging.shutdown() → None

Închide fiecare handler atașat fiecărui logger cunoscut și uită loggerele. Înregistrată automat prin sys.atexit atunci când acest hook este disponibil.

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

Asociază name-ul textual cu level-ul numeric, astfel încât Formatter să îl poată reda prin %(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

Configurează loggerul rădăcină cu un singur handler.

Dacă filename este furnizat, se creează un FileHandler folosind filemode și encoding; altfel se utilizează un StreamHandler care scrie în stream (implicit sys.stderr).

format și datefmt sunt transmise mai departe către un nou Formatter.

level setează atât nivelul handlerului, cât și nivelul loggerului rădăcină.

Dacă loggerul rădăcină are deja handlere, această funcție nu face nimic, cu excepția cazului în care force este True, caz în care handlerele existente sunt închise și înlocuite.

Clase

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

Un logger denumit. Construiți loggerele prin getLogger, mai degrabă decât direct, astfel încât getLogger să poată returna aceeași instanță pentru același nume.

name: str

Numele punctat al loggerului.

level: int

Nivelul numeric configurat. 0 (NOTSET) înseamnă „moștenește”.

handlers: list

Lista instanțelor Handler atașate acestui logger. Când este goală, mesajele sunt trimise către handlerele loggerului rădăcină.

setLevel(level: int) → None

Setează nivelul de prag al loggerului.

isEnabledFor(level: int) → bool

Returnează True dacă un mesaj de nivel level ar fi procesat de acest logger.

getEffectiveLevel() → int

Returnează primul nivel diferit de zero dintre: nivelul acestui logger, nivelul loggerului rădăcină sau WARNING.

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

Jurnalizează msg la nivelul level. args sunt interpolate în msg cu operatorul %; dacă primul argument pozițional este un dicționar, acesta este utilizat ca mapare.

debug(msg: str, *args) → None

Jurnalizează msg la DEBUG.

info(msg: str, *args) → None

Jurnalizează msg la INFO.

warning(msg: str, *args) → None

Jurnalizează msg la WARNING.

error(msg: str, *args) → None

Jurnalizează msg la ERROR.

critical(msg: str, *args) → None

Jurnalizează msg la CRITICAL.

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

Jurnalizează msg la ERROR și, când exc_info este adevărat, adaugă traceback-ul formatat. Dacă exc_info este o instanță BaseException, se redă traceback-ul acelei excepții; altfel se consultă excepția activă prin sys.exc_info().

addHandler(handler: Handler) → None

Atașează handler la acest logger.

hasHandlers() → bool

Returnează True dacă există handlere atașate acestui logger.

class logging.Handler(level: int = NOTSET)

Clasa de bază pentru toate handlerele. Subclasele implementează emit().

level: int

Nivelul de prag al handlerului.

formatter: 'Formatter | None'

Formatter-ul activ sau None.

setLevel(level: int) → None

Setează nivelul de prag al handlerului.

setFormatter(formatter: Formatter) → None

Atașează formatter la acest handler.

format(record: LogRecord) → str

Redă record folosind formatatorul configurat.

close() → None

Eliberează resursele deținute de handler. Apelată de shutdown și de FileHandler atunci când acesta este închis.

class logging.StreamHandler(stream=None)

Handler care scrie înregistrările formatate, urmate de self.terminator ("\n" în mod implicit), în stream. stream are valoarea implicită sys.stderr.

stream

Obiectul stream de destinație.

terminator: str

Șir adăugat după fiecare înregistrare formatată. Valoarea implicită este "\n".

emit(record: LogRecord) → None

Scrie record în stream dacă nivelul său atinge pragul handlerului.

close() → None

Golește stream-ul subiacent atunci când acesta expune o metodă flush.

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

Subclasă StreamHandler care deschide filename cu mode și encoding date și scrie în el înregistrările formatate. Fișierul subiacent este închis la close().

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

Redă instanțele LogRecord ca șiruri de caractere.

fmt este un șablon în stil printf. Cheile recunoscute sunt %(name)s, %(message)s, %(msecs)d, %(asctime)s și %(levelname)s. Când nu este setat, valoarea implicită este "%(levelname)s:%(name)s:%(message)s".

datefmt este șablonul time.strftime utilizat pentru a reda %(asctime)s. Valoarea implicită este "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Returnează True dacă șablonul de format face referire la asctime.

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

Formatează record.ct folosind time.strftime și datefmt. Returnează None pe platformele unde time.strftime nu este disponibil.

format(record: LogRecord) → str

Redă record. Dacă șablonul utilizează asctime, formatTime() este invocată mai întâi pentru a popula record.asctime.

class logging.LogRecord

Container pentru datele transmise de la un Logger către handlerele sale. Instanțele sunt populate prin set(); implementările de logger reutilizează o singură înregistrare per logger pentru a reduce alocările.

name: str

Numele loggerului de origine.

levelno: int

Nivelul numeric al acestei înregistrări.

levelname: str

Numele textual al nivelului.

message: str

Mesajul de jurnal complet formatat.

ct: float

Momentul creării, așa cum este returnat de time.time().

msecs: int

Componenta de milisecunde a ct.

asctime: str | None

Marcaj temporal lizibil pentru oameni; populat în mod întârziat de Formatter.

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

Inițializează înregistrarea cu valorile date și captează momentul curent.