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.

使用例:

>>> 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()[ソース]

Contextmanager to pend logging all logs temporary.

例えば:

>>> 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()[ソース]

Contextmanager to pend logging warnings temporary.

Similar to pending_logging().

sphinx.util.logging.prefixed_warnings()[ソース]

Prepend prefix to all records for a while.

例えば:

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

バージョン 2.0 で追加.