Logging API

sphinx.util.logging.getLogger(name)

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)

LoggerAdapter allowing type and subtype 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)

info(msg, *args, **kwargs)

verbose(msg, *args, **kwargs)

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()

Context manager to postpone logging all logs temporarily.

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()

Context manager to postpone logging warnings temporarily.

Similar to pending_logging().

sphinx.util.logging.prefixed_warnings()

Context manager to prepend prefix to all warning log records temporarily.

For example:

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

2.0 新版功能.