- Home
- Get it
- Docs
- Extend/Develop

# Logging API

`sphinx.util.logging.``getLogger`(name)

  Returns a logger wrapped by `SphinxLoggerAdapter` with the specified name.

  Example usage:

      from sphinx.util import logging  # Load on top of python's logging module

      logger = logging.getLogger(__name__)
      logger.info('Hello, this is an extension!')

class `SphinxLoggerAdapter`(logging.LoggerAdapter)
  `error`(level, msg, *args, **kwargs)
  `critical`(level, msg, *args, **kwargs)
  `warning`(level, 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, warning level logs are colored as `"darkred"`. The others are not colored.
  `log`(level, msg, *args, **kwargs)
  `info`(level, msg, *args, **kwargs)
  `verbose`(level, msg, *args, **kwargs)
  `debug`(level, 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`.
    color
      The color of logs. By default, debug level logs are colored as `"darkgray"`, and debug2 level ones are `"lightgray"`. The others are not colored.

`pending_logging`()

  Marks all logs as pending:

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

      # the warning is flushed here

`pending_warnings`()

  Marks warning logs as pending. Similar to `pending_logging()`.