Logging API¶

sphinx.util.logging.getLogger(name)[源代码]¶

获取由 sphinx.util.logging.SphinxLoggerAdapter 包装的记录器.

Sphinx 记录器总是使用 sphinx.* 命名空间,以独立于根记录器的设置.这确保了即使第三方扩展或导入的应用程序重置记录器设置,日志记录也是一致的.

示例用法:

>>> 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 允许 type 和 subtype 关键字.

error(msg, *args, **kwargs)¶

critical(msg, *args, **kwargs)¶

warning(msg, *args, **kwargs)[源代码]¶

在此记录器上以指定级别记录消息.基本上,参数与python的logging模块相同.

此外,Sphinx 记录器支持以下关键字参数:

类型, *子类型*

警告日志的类别.它用于通过 suppress_warnings 设置来抑制警告.

位置

警告发生的地方.它用于在每个日志中包含路径和行号.它允许 docname、docname 和行号的元组以及节点:

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)

颜色

日志的颜色.默认情况下,错误级别的日志颜色为 "darkred",关键级别的日志不带颜色,警告级别的日志颜色为 "red".

log(level, msg, *args, **kwargs)[源代码]¶

info(msg, *args, **kwargs)¶

verbose(msg, *args, **kwargs)[源代码]¶

debug(msg, *args, **kwargs)¶

使用指定的级别记录消息到此记录器.基本上,参数与Python的logging模块相同.

此外,Sphinx 记录器支持以下关键字参数:

nonl: 如果为真,记录器不会在日志消息的末尾折叠行.默认值是 False.
位置: 消息发出的地方.更多详情,请参见 SphinxLoggerAdapter.warning().
颜色: 日志的颜色.默认情况下,信息和详细级别的日志不带颜色,而调试级别的日志颜色为 "darkgray".

sphinx.util.logging.pending_logging()[源代码]¶

上下文管理器暂时推迟所有日志记录.

例如:

>>> 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()[源代码]¶

用于临时推迟记录日志警告的上下文管理器.

类似于 pending_logging().

sphinx.util.logging.prefixed_warnings()[源代码]¶

上下文管理器,用于临时在所有警告日志记录前添加前缀.

例如:

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

Added in version 2.0.