logging — Ereignisprotokollierung

Dieses Modul stellt eine schlanke Teilmenge des Standard-Python-Pakets logging bereit, angepasst für MicroPython. Es unterstützt stufenbasierte Protokollierung über hierarchisch benannte Logger-Objekte, eine kleine Auswahl an Handlern (StreamHandler, FileHandler), Formatierung im printf-Stil über Formatter sowie Komfortfunktionen auf Modulebene, die denen entsprechen, die auf dem Root-Logger arbeiten.

Das Modul orientiert sich so eng an der vertrauten CPython-API, dass einfache Anwendungen, die für die Standardbibliothek geschrieben wurden, unverändert funktionieren sollten. Filter, Mehrprozess-Sperren, das Format der Konfigurationsdatei und die meisten Handler-Klassen werden nicht bereitgestellt.

Stufenkonstanten

logging.CRITICAL: int

Numerischer Wert 50. Wird für nicht behebbare Fehler verwendet.

logging.ERROR: int

Numerischer Wert 40. Wird für schwerwiegende Probleme verwendet.

logging.WARNING: int

Numerischer Wert 30. Standardstufe für einen frisch konfigurierten Root-Logger.

logging.INFO: int

Numerischer Wert 20. Wird für Bestätigungsmeldungen verwendet.

logging.DEBUG: int

Numerischer Wert 10. Wird für feingranulare Diagnoseausgaben verwendet.

logging.NOTSET: int

Numerischer Wert 0. Zeigt einen Logger ohne konfigurierte Stufe an (die effektive Stufe wird dann vom Root-Logger oder von WARNING geerbt).

Funktionen

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

Gibt den unter name registrierten Logger zurück und erstellt ihn bei der ersten Verwendung. Wenn name gleich None ist, wird der Root-Logger zurückgegeben. Der erste Aufruf mit name="root" (oder ohne gesetzten name) ruft implizit basicConfig auf, um einen Standard-StreamHandler anzuhängen, der nach sys.stderr schreibt.

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

Protokolliert eine Meldung auf der Stufe level auf dem Root-Logger. args werden mittels printf-artiger %-Formatierung in msg eingesetzt; ein einzelnes dict-Argument wird als Mapping verwendet.

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

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

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

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

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

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

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

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

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

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

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

Entspricht getLogger().exception(msg, *args, exc_info=exc_info). Protokolliert die Meldung auf ERROR und formatiert zusätzlich den Traceback der aktiven Ausnahme, wenn exc_info wahr ist. Wenn exc_info selbst eine BaseException ist, wird der Traceback dieser Ausnahme verwendet; andernfalls wird sys.exc_info() herangezogen, sofern verfügbar.

logging.shutdown() → None

Schließt jeden Handler, der an jeden bekannten Logger angehängt ist, und verwirft die Logger. Wird automatisch über sys.atexit registriert, wenn dieser Hook verfügbar ist.

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

Verknüpft den textuellen name mit der numerischen Stufe level, sodass Formatter sie über %(levelname)s darstellen kann.

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

Konfiguriert den Root-Logger mit einem einzelnen Handler.

Wenn filename angegeben ist, wird ein FileHandler unter Verwendung von filemode und encoding erstellt; andernfalls wird ein StreamHandler verwendet, der nach stream (standardmäßig sys.stderr) schreibt.

format und datefmt werden an einen neuen Formatter durchgereicht.

level setzt sowohl die Stufe des Handlers als auch die Stufe des Root-Loggers.

Wenn der Root-Logger bereits Handler besitzt, ist diese Funktion ein No-Op, es sei denn, force ist True; in diesem Fall werden die vorhandenen Handler geschlossen und ersetzt.

Klassen

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

Ein benannter Logger. Erstellen Sie Logger über getLogger statt direkt, damit getLogger für denselben Namen dieselbe Instanz zurückgeben kann.

name: str

Der punktnotierte Name des Loggers.

level: int

Die konfigurierte numerische Stufe. 0 (NOTSET) bedeutet „erben“.

handlers: list

Die Liste der Handler-Instanzen, die an diesen Logger angehängt sind. Wenn sie leer ist, werden Meldungen an die Handler des Root-Loggers weitergeleitet.

setLevel(level: int) → None

Setzt die Schwellenstufe des Loggers.

isEnabledFor(level: int) → bool

Gibt True zurück, wenn eine Meldung der Stufe level von diesem Logger verarbeitet würde.

getEffectiveLevel() → int

Gibt den ersten von null verschiedenen Wert zurück: die Stufe dieses Loggers, die Stufe des Root-Loggers oder WARNING.

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

Protokolliert msg auf der Stufe level. args werden mit dem %-Operator in msg eingesetzt; wenn das erste Positionsargument ein dict ist, wird es als Mapping verwendet.

debug(msg: str, *args) → None

Protokolliert msg auf DEBUG.

info(msg: str, *args) → None

Protokolliert msg auf INFO.

warning(msg: str, *args) → None

Protokolliert msg auf WARNING.

error(msg: str, *args) → None

Protokolliert msg auf ERROR.

critical(msg: str, *args) → None

Protokolliert msg auf CRITICAL.

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

Protokolliert msg auf ERROR und hängt, wenn exc_info wahr ist, den formatierten Traceback an. Wenn exc_info eine BaseException-Instanz ist, wird der Traceback dieser Ausnahme dargestellt; andernfalls wird die aktive Ausnahme über sys.exc_info() herangezogen.

addHandler(handler: Handler) → None

Hängt handler an diesen Logger an.

hasHandlers() → bool

Gibt True zurück, wenn an diesen Logger irgendwelche Handler angehängt sind.

class logging.Handler(level: int = NOTSET)

Basisklasse für alle Handler. Unterklassen implementieren emit().

level: int

Die Schwellenstufe des Handlers.

formatter: 'Formatter | None'

Der aktive Formatter oder None.

setLevel(level: int) → None

Setzt die Schwellenstufe des Handlers.

setFormatter(formatter: Formatter) → None

Hängt formatter an diesen Handler an.

format(record: LogRecord) → str

Stellt record unter Verwendung des konfigurierten Formatters dar.

close() → None

Gibt vom Handler gehaltene Ressourcen frei. Wird von shutdown und von FileHandler aufgerufen, wenn dieser geschlossen wird.

class logging.StreamHandler(stream=None)

Handler, der formatierte Einträge, gefolgt von self.terminator (standardmäßig "\n"), nach stream schreibt. stream ist standardmäßig sys.stderr.

stream

Das Ziel-Stream-Objekt.

terminator: str

Zeichenkette, die nach jedem formatierten Eintrag angehängt wird. Standardmäßig "\n".

emit(record: LogRecord) → None

Schreibt record nach stream, wenn seine Stufe die Schwelle des Handlers erreicht.

close() → None

Leert den zugrunde liegenden Stream, wenn er eine flush-Methode bereitstellt.

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

StreamHandler-Unterklasse, die filename mit dem angegebenen mode und encoding öffnet und formatierte Einträge dorthin schreibt. Die zugrunde liegende Datei wird bei close() geschlossen.

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

Stellt LogRecord-Instanzen als Zeichenketten dar.

fmt ist eine Vorlage im printf-Stil. Erkannte Schlüssel sind %(name)s, %(message)s, %(msecs)d, %(asctime)s und %(levelname)s. Ohne Angabe wird standardmäßig "%(levelname)s:%(name)s:%(message)s" verwendet.

datefmt ist die time.strftime-Vorlage, die zur Darstellung von %(asctime)s verwendet wird. Standardmäßig "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Gibt True zurück, wenn die Formatvorlage auf asctime verweist.

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

Formatiert record.ct mit time.strftime und datefmt. Gibt None zurück auf Plattformen, auf denen time.strftime nicht verfügbar ist.

format(record: LogRecord) → str

Stellt record dar. Wenn die Vorlage asctime verwendet, wird zuerst formatTime() aufgerufen, um record.asctime zu füllen.

class logging.LogRecord

Container für die Daten, die von einem Logger an seine Handler übergeben werden. Instanzen werden über set() befüllt; Logger-Implementierungen verwenden einen einzelnen Record pro Logger wieder, um Allokationen zu reduzieren.

name: str

Der Name des ursprünglichen Loggers.

levelno: int

Numerische Stufe dieses Records.

levelname: str

Textueller Stufenname.

message: str

Die vollständig formatierte Protokollmeldung.

ct: float

Erstellungszeit, wie von time.time() zurückgegeben.

msecs: int

Millisekundenanteil von ct.

asctime: str | None

Menschenlesbarer Zeitstempel; wird von Formatter verzögert (lazy) befüllt.

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

Initialisiert den Record mit den angegebenen Werten und erfasst die aktuelle Zeit.