logging — journalisation d’événements

Ce module fournit un sous-ensemble léger du paquet logging standard de Python, adapté à MicroPython. Il prend en charge la journalisation par niveaux via des objets Logger à noms hiérarchiques, un petit ensemble de gestionnaires (StreamHandler, FileHandler), le formatage de style printf via Formatter, ainsi que des fonctions utilitaires au niveau du module équivalentes à celles opérant sur le logger racine.

Le module suit l’API familière de CPython d’assez près pour que des applications simples écrites pour la bibliothèque standard fonctionnent sans modification. Les filtres, le verrouillage multi-processus, le format de fichier de configuration et la plupart des classes de gestionnaires ne sont pas fournis.

Constantes de niveau

logging.CRITICAL: int

Valeur numérique 50. Utilisée pour les erreurs irrécupérables.

logging.ERROR: int

Valeur numérique 40. Utilisée pour les problèmes graves.

logging.WARNING: int

Valeur numérique 30. Niveau par défaut d’un logger racine fraîchement configuré.

logging.INFO: int

Valeur numérique 20. Utilisée pour les messages de confirmation.

logging.DEBUG: int

Valeur numérique 10. Utilisée pour la sortie de diagnostic fine.

logging.NOTSET: int

Valeur numérique 0. Indique un logger sans niveau configuré (le niveau effectif est alors hérité du logger racine ou de WARNING).

Fonctions

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

Renvoie le Logger enregistré sous name, en le créant lors de la première utilisation. Si name est None, le logger racine est renvoyé. Le premier appel avec name="root" (ou avec name non défini) invoque implicitement basicConfig pour attacher un StreamHandler par défaut écrivant vers sys.stderr.

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

Journalise un message au niveau level sur le logger racine. Les args sont interpolés dans msg à l’aide du formatage de style printf % ; un unique argument dict est utilisé comme correspondance.

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

Équivalent à getLogger().debug(msg, *args).

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

Équivalent à getLogger().info(msg, *args).

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

Équivalent à getLogger().warning(msg, *args).

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

Équivalent à getLogger().error(msg, *args).

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

Équivalent à getLogger().critical(msg, *args).

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

Équivalent à getLogger().exception(msg, *args, exc_info=exc_info). Journalise le message au niveau ERROR et formate en plus la trace de la pile de l’exception active lorsque exc_info est vrai. Si exc_info est lui-même une BaseException, c’est la trace de cette exception qui est utilisée ; sinon sys.exc_info() est consulté lorsque c’est possible.

logging.shutdown() → None

Ferme tous les gestionnaires attachés à tous les loggers connus et oublie les loggers. Enregistré automatiquement via sys.atexit lorsque ce point d’ancrage est disponible.

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

Associe le nom textuel name au niveau numérique level de sorte que Formatter puisse le rendre via %(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

Configure le logger racine avec un unique gestionnaire.

Si filename est fourni, un FileHandler est créé en utilisant filemode et encoding ; sinon un StreamHandler écrivant vers stream (par défaut sys.stderr) est utilisé.

format et datefmt sont transmis à un nouveau Formatter.

level définit à la fois le niveau du gestionnaire et le niveau du logger racine.

Si le logger racine possède déjà des gestionnaires, cette fonction ne fait rien, sauf si force vaut True, auquel cas les gestionnaires existants sont fermés et remplacés.

Classes

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

Un logger nommé. Construisez les loggers via getLogger plutôt que directement, afin que getLogger puisse renvoyer la même instance pour un même nom.

name: str

Le nom pointé du logger.

level: int

Le niveau numérique configuré. 0 (NOTSET) signifie « hériter ».

handlers: list

La liste des instances Handler attachées à ce logger. Lorsqu’elle est vide, les messages sont distribués aux gestionnaires du logger racine.

setLevel(level: int) → None

Définit le niveau seuil du logger.

isEnabledFor(level: int) → bool

Renvoie True si un message de niveau level serait traité par ce logger.

getEffectiveLevel() → int

Renvoie le premier non nul parmi : le niveau de ce logger, le niveau du logger racine ou WARNING.

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

Journalise msg au niveau level. Les args sont interpolés dans msg avec l’opérateur % ; si le premier argument positionnel est un dict, il est utilisé comme correspondance.

debug(msg: str, *args) → None

Journalise msg au niveau DEBUG.

info(msg: str, *args) → None

Journalise msg au niveau INFO.

warning(msg: str, *args) → None

Journalise msg au niveau WARNING.

error(msg: str, *args) → None

Journalise msg au niveau ERROR.

critical(msg: str, *args) → None

Journalise msg au niveau CRITICAL.

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

Journalise msg au niveau ERROR et, lorsque exc_info est vrai, ajoute la trace de la pile formatée. Si exc_info est une instance de BaseException, c’est la trace de cette exception qui est rendue ; sinon l’exception active est consultée via sys.exc_info().

addHandler(handler: Handler) → None

Attache handler à ce logger.

hasHandlers() → bool

Renvoie True si au moins un gestionnaire est attaché à ce logger.

class logging.Handler(level: int = NOTSET)

Classe de base de tous les gestionnaires. Les sous-classes implémentent emit().

level: int

Le niveau seuil du gestionnaire.

formatter: 'Formatter | None'

Le Formatter actif, ou None.

setLevel(level: int) → None

Définit le niveau seuil du gestionnaire.

setFormatter(formatter: Formatter) → None

Attache formatter à ce gestionnaire.

format(record: LogRecord) → str

Rend record à l’aide du formateur configuré.

close() → None

Libère les ressources détenues par le gestionnaire. Appelé par shutdown et par FileHandler lors de sa fermeture.

class logging.StreamHandler(stream=None)

Gestionnaire qui écrit les enregistrements formatés, suivis de self.terminator ("\n" par défaut), vers stream. stream vaut par défaut sys.stderr.

stream

L’objet flux de destination.

terminator: str

Chaîne ajoutée après chaque enregistrement formaté. Vaut par défaut "\n".

emit(record: LogRecord) → None

Écrit record vers stream si son niveau atteint le seuil du gestionnaire.

close() → None

Vide le flux sous-jacent lorsqu’il expose une méthode flush.

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

Sous-classe de StreamHandler qui ouvre filename avec les mode et encoding donnés et y écrit les enregistrements formatés. Le fichier sous-jacent est fermé lors de l’appel à close().

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

Rend les instances de LogRecord sous forme de chaînes.

fmt est un modèle de style printf. Les clés reconnues sont %(name)s, %(message)s, %(msecs)d, %(asctime)s et %(levelname)s. Lorsqu’il n’est pas défini, il vaut par défaut "%(levelname)s:%(name)s:%(message)s".

datefmt est le modèle time.strftime utilisé pour rendre %(asctime)s. Vaut par défaut "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Renvoie True si le modèle de format fait référence à asctime.

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

Formate record.ct à l’aide de time.strftime et de datefmt. Renvoie None sur les plateformes où time.strftime n’est pas disponible.

format(record: LogRecord) → str

Rend record. Si le modèle utilise asctime, formatTime() est invoqué d’abord pour renseigner record.asctime.

class logging.LogRecord

Conteneur des données transmises par un Logger à ses gestionnaires. Les instances sont renseignées via set() ; les implémentations de logger réutilisent un unique enregistrement par logger afin de réduire les allocations.

name: str

Le nom du logger d’origine.

levelno: int

Le niveau numérique de cet enregistrement.

levelname: str

Le nom textuel du niveau.

message: str

Le message de journal entièrement formaté.

ct: float

L’instant de création tel que renvoyé par time.time().

msecs: int

La composante en millisecondes de ct.

asctime: str | None

Horodatage lisible par un humain ; renseigné paresseusement par Formatter.

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

Initialise l’enregistrement avec les valeurs données et capture l’instant courant.