logging — registrazione degli eventi

Questo modulo fornisce un sottoinsieme leggero del pacchetto logging standard di Python, adattato a MicroPython. Supporta la registrazione per livelli tramite oggetti Logger con nomi gerarchici, un piccolo insieme di handler (StreamHandler, FileHandler), la formattazione in stile printf tramite Formatter e funzioni di comodità a livello di modulo equivalenti a quelle che operano sul logger radice.

Il modulo segue l’API familiare di CPython in modo abbastanza fedele da far funzionare senza modifiche le applicazioni semplici scritte per la libreria standard. Non sono forniti i filtri, il blocco multi-processo, il formato del file di configurazione e la maggior parte delle classi di handler.

Costanti di livello

logging.CRITICAL: int

Valore numerico 50. Usato per errori irrecuperabili.

logging.ERROR: int

Valore numerico 40. Usato per problemi gravi.

logging.WARNING: int

Valore numerico 30. Livello predefinito per un logger radice appena configurato.

logging.INFO: int

Valore numerico 20. Usato per i messaggi di conferma.

logging.DEBUG: int

Valore numerico 10. Usato per l’output diagnostico dettagliato.

logging.NOTSET: int

Valore numerico 0. Indica un logger senza livello configurato (il livello effettivo viene quindi ereditato dal logger radice o da WARNING).

Funzioni

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

Restituisce il Logger registrato sotto name, creandolo al primo utilizzo. Se name è None viene restituito il logger radice. La prima chiamata con name="root" (o con name non impostato) invoca implicitamente basicConfig per collegare uno StreamHandler predefinito che scrive su sys.stderr.

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

Registra un messaggio a livello level sul logger radice. Gli args vengono interpolati in msg usando la formattazione in stile printf con %; un singolo argomento dict viene usato come mappatura.

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

Equivalente a getLogger().debug(msg, *args).

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

Equivalente a getLogger().info(msg, *args).

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

Equivalente a getLogger().warning(msg, *args).

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

Equivalente a getLogger().error(msg, *args).

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

Equivalente a getLogger().critical(msg, *args).

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

Equivalente a getLogger().exception(msg, *args, exc_info=exc_info). Registra il messaggio a livello ERROR e, inoltre, formatta il traceback dell’eccezione attiva quando exc_info è vero. Se exc_info è esso stesso un BaseException, viene usato il traceback di tale eccezione; altrimenti, quando disponibile, viene consultato sys.exc_info().

logging.shutdown() → None

Chiude ogni handler collegato a ogni logger noto e dimentica i logger. Registrato automaticamente tramite sys.atexit quando tale hook è disponibile.

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

Associa il nome testuale name al livello numerico level in modo che Formatter possa renderizzarlo tramite %(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

Configura il logger radice con un singolo handler.

Se viene fornito filename viene creato un FileHandler usando filemode e encoding; altrimenti viene usato uno StreamHandler che scrive su stream (con valore predefinito sys.stderr).

format e datefmt vengono passati a un nuovo Formatter.

level imposta sia il livello dell’handler sia il livello del logger radice.

Se il logger radice ha già degli handler questa funzione non ha effetto a meno che force non sia True, nel qual caso gli handler esistenti vengono chiusi e sostituiti.

Classi

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

Un logger con nome. Costruisci i logger tramite getLogger anziché direttamente, in modo che getLogger possa restituire la stessa istanza per lo stesso nome.

name: str

Il nome puntato del logger.

level: int

Il livello numerico configurato. 0 (NOTSET) significa «eredita».

handlers: list

L’elenco delle istanze di Handler collegate a questo logger. Quando è vuoto, i messaggi vengono inviati agli handler del logger radice.

setLevel(level: int) → None

Imposta il livello di soglia del logger.

isEnabledFor(level: int) → bool

Restituisce True se un messaggio di livello level verrebbe elaborato da questo logger.

getEffectiveLevel() → int

Restituisce il primo valore diverso da zero tra: il livello di questo logger, il livello del logger radice o WARNING.

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

Registra msg a livello level. Gli args vengono interpolati in msg con l’operatore %; se il primo argomento posizionale è un dict, viene usato come mappatura.

debug(msg: str, *args) → None

Registra msg a livello DEBUG.

info(msg: str, *args) → None

Registra msg a livello INFO.

warning(msg: str, *args) → None

Registra msg a livello WARNING.

error(msg: str, *args) → None

Registra msg a livello ERROR.

critical(msg: str, *args) → None

Registra msg a livello CRITICAL.

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

Registra msg a livello ERROR e, quando exc_info è vero, accoda il traceback formattato. Se exc_info è un’istanza di BaseException, viene renderizzato il traceback di tale eccezione; altrimenti l’eccezione attiva viene consultata tramite sys.exc_info().

addHandler(handler: Handler) → None

Collega handler a questo logger.

hasHandlers() → bool

Restituisce True se a questo logger è collegato qualsiasi handler.

class logging.Handler(level: int = NOTSET)

Classe base per tutti gli handler. Le sottoclassi implementano emit().

level: int

Il livello di soglia dell’handler.

formatter: 'Formatter | None'

Il Formatter attivo, oppure None.

setLevel(level: int) → None

Imposta il livello di soglia dell’handler.

setFormatter(formatter: Formatter) → None

Collega formatter a questo handler.

format(record: LogRecord) → str

Renderizza record usando il formatter configurato.

close() → None

Rilascia le risorse detenute dall’handler. Chiamata da shutdown e da FileHandler quando viene chiuso.

class logging.StreamHandler(stream=None)

Handler che scrive i record formattati, seguiti da self.terminator ("\n" per impostazione predefinita), su stream. stream ha come valore predefinito sys.stderr.

stream

L’oggetto stream di destinazione.

terminator: str

Stringa accodata dopo ogni record formattato. Il valore predefinito è "\n".

emit(record: LogRecord) → None

Scrive record su stream se il suo livello soddisfa la soglia dell’handler.

close() → None

Esegue il flush dello stream sottostante quando questo espone un metodo flush.

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

Sottoclasse di StreamHandler che apre filename con i mode ed encoding indicati e vi scrive i record formattati. Il file sottostante viene chiuso con close().

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

Renderizza le istanze di LogRecord come stringhe.

fmt è un template in stile printf. Le chiavi riconosciute sono %(name)s, %(message)s, %(msecs)d, %(asctime)s e %(levelname)s. Quando non è impostato, il valore predefinito è "%(levelname)s:%(name)s:%(message)s".

datefmt è il template time.strftime usato per renderizzare %(asctime)s. Il valore predefinito è "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Restituisce True se il template di formato fa riferimento a asctime.

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

Formatta record.ct usando time.strftime e datefmt. Restituisce None sulle piattaforme dove time.strftime non è disponibile.

format(record: LogRecord) → str

Renderizza record. Se il template usa asctime, viene invocato prima formatTime() per popolare record.asctime.

class logging.LogRecord

Contenitore per i dati passati da un Logger ai suoi handler. Le istanze vengono popolate tramite set(); le implementazioni dei logger riutilizzano un singolo record per logger per ridurre le allocazioni.

name: str

Il nome del logger di origine.

levelno: int

Livello numerico di questo record.

levelname: str

Nome testuale del livello.

message: str

Il messaggio di log completamente formattato.

ct: float

Ora di creazione come restituita da time.time().

msecs: int

Componente in millisecondi di ct.

asctime: str | None

Timestamp leggibile dall’uomo; popolato in modo lazy da Formatter.

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

Inizializza il record con i valori indicati e cattura l’ora corrente.