Logging API¶
-
sphinx.util.logging.getLogger(name)¶ Returns a logger wrapped by
SphinxLoggerAdapterwith 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_warningssetting. - 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().