Logging API¶

sphinx.util.logging.getLogger(name)[Quelle]¶

Holt den Logger, der von sphinx.util.logging.SphinxLoggerAdapter umschlossen wird.

Der Sphinx-Logger verwendet immer den Namensraum sphinx.*, um unabhängig von den Einstellungen des Root-Loggers zu sein. Dies stellt sicher, dass die Protokollierung konsistent ist, auch wenn eine Drittanbietererweiterung oder eine importierte Anwendung die Logger-Einstellungen zurücksetzt.

Beispielverwendung

>>> from sphinx.util import logging
>>> logger = logging.getLogger(__name__)
>>> logger.info('Hello, this is an extension!')
Hello, this is an extension!

class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)[Quelle]¶

LoggerAdapter, der die Schlüsselwörter type und subtype zulässt.

error(msg, *args, **kwargs)¶

critical(msg, *args, **kwargs)¶

warning(msg, *args, **kwargs)[Quelle]¶

Protokolliert eine Nachricht mit dem angegebenen Level in diesem Logger. Grundsätzlich sind die Argumente wie im Python-Logging-Modul.

Darüber hinaus unterstützt der Sphinx-Logger folgende Schlüsselwortargumente:

type, *subtype*

Kategorien von Warnprotokollen. Sie werden verwendet, um Warnungen gemäß der Einstellung suppress_warnings zu unterdrücken.

location

Wo die Warnung aufgetreten ist. Sie wird verwendet, um den Pfad und die Zeilennummer in jedem Protokoll einzuschließen. Sie erlaubt docname, ein Tupel aus docname und Zeilennummer sowie Knoten.

logger = sphinx.util.logging.getLogger(__name__)
logger.warning('Warning happened!', location='index')
logger.warning('Warning happened!', location=('chapter1/index', 10))
logger.warning('Warning happened!', location=some_node)

color

Die Farbe der Protokolle. Standardmäßig werden Fehlermeldungen in "darkred" gefärbt, kritische Meldungen nicht gefärbt und Warnmeldungen in "red".

log(level, msg, *args, **kwargs)[Quelle]¶

info(msg, *args, **kwargs)¶

verbose(msg, *args, **kwargs)[Quelle]¶

debug(msg, *args, **kwargs)¶

Protokolliert eine Nachricht mit dem angegebenen Level in diesem Logger. Grundsätzlich sind die Argumente wie im Python-Logging-Modul.

Darüber hinaus unterstützt der Sphinx-Logger folgende Schlüsselwortargumente:

nonl: Wenn wahr, faltet der Logger Zeilen am Ende der Protokollnachricht nicht um. Der Standardwert ist False.
location: Wo die Nachricht ausgegeben wurde. Für weitere Details siehe SphinxLoggerAdapter.warning().
color: Die Farbe der Protokolle. Standardmäßig werden Info- und Verbose-Level-Protokolle nicht gefärbt, Debug-Level-Protokolle werden als "darkgray" gefärbt.

sphinx.util.logging.pending_logging()[Quelle]¶

Kontextmanager zum vorübergehenden Aufschieben aller Protokolle.

Zum Beispiel

>>> with pending_logging():
>>>     logger.warning('Warning message!')  # not flushed yet
>>>     some_long_process()
>>>
Warning message!  # the warning is flushed here

sphinx.util.logging.pending_warnings()[Quelle]¶

Kontextmanager zum vorübergehenden Aufschieben der Protokollierung von Warnungen.

Ähnlich wie pending_logging().

sphinx.util.logging.prefixed_warnings()[Quelle]¶

Kontextmanager zum vorübergehenden Hinzufügen eines Präfixes zu allen Warnprotokoll-Datensätzen.

Zum Beispiel

>>> with prefixed_warnings("prefix:"):
>>>     logger.warning('Warning message!')  # => prefix: Warning message!

Hinzugefügt in Version 2.0.