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