Sphinx

# 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!

  Added in version 2.0.