Logging API
Logging API
- sphinx.util.logging.getLogger(name)[source]
Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
Sphinx logger always uses
sphinx.*
namespace to be independent from settings of root logger. It ensures logging is consistent even if a third-party extension or imported application resets logger settings.Example usage:
>>> 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)[source]
LoggerAdapter allowing
type
andsubtype
keywords.- error(msg, *args, **kwargs)
- critical(msg, *args, **kwargs)
- warning(msg, *args, **kwargs)
Logs a message on this logger with the specified level. Basically, the arguments are as with python’s logging module.
In addition, Sphinx logger supports following keyword arguments:
- type, *subtype*
Categories of warning logs. It is used to suppress warnings by suppress_warnings setting.
- location
Where the warning happened. It is used to include the path and line number in each log. It allows docname, tuple of docname and line number and nodes:
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
The color of logs. By default, error level logs are colored as
"darkred"
, critical level ones is not colored, and warning level ones are colored as"red"
.
- log(level, msg, *args, **kwargs)[source]
- info(msg, *args, **kwargs)
- verbose(msg, *args, **kwargs)[source]
- debug(msg, *args, **kwargs)
Logs a message to this logger with the specified level. Basically, the arguments are as with python’s logging module.
In addition, Sphinx logger supports following keyword arguments:
- nonl
If true, the logger does not fold lines at the end of the log message. The default is
False
.- location
Where the message emitted. For more detail, see SphinxLoggerAdapter.warning().
- color
The color of logs. By default, info and verbose level logs are not colored, and debug level ones are colored as
"darkgray"
.
- sphinx.util.logging.pending_logging()[source]
Contextmanager to pend logging all logs temporary.
For example:
>>> 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()[source]
Contextmanager to pend logging warnings temporary.
Similar to pending_logging().
- sphinx.util.logging.prefixed_warnings()[source]
Prepend prefix to all records for a while.
For example:
>>> with prefixed_warnings("prefix:"): >>> logger.warning('Warning message!') # => prefix: Warning message!
New in version 2.0.