日志 API¶

sphinx.util.logging.getLogger(name)[source]¶

获取由 sphinx.util.logging.SphinxLoggerAdapter 封装的 logger。

Sphinx logger 始终使用 sphinx.* 命名空间，以独立于根 logger 的设置。这确保了日志记录的一致性，即使第三方扩展或导入的应用程序重置了 logger 设置。

用法示例

>>> 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)[source]¶

LoggerAdapter 允许 type 和 subtype 关键字。

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

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

warning(msg, *args, **kwargs)[source]¶

使用指定的级别在此 logger 上记录消息。基本上，参数与 python 的 logging 模块相同。

此外，Sphinx logger 支持以下关键字参数

type, *subtype*

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

location

警告发生的位置。它用于在每个日志中包含路径和行号。它允许 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)

color

日志的颜色。默认情况下，错误级别日志着色为 "darkred"，严重级别日志不着色，警告级别日志着色为 "red"。

log(level, msg, *args, **kwargs)[source]¶

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

verbose(msg, *args, **kwargs)[source]¶

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

使用指定的级别向此 logger 记录消息。基本上，参数与 python 的 logging 模块相同。

此外，Sphinx logger 支持以下关键字参数

nonl: 如果为 true，则 logger 不会在日志消息末尾折叠行。默认值为 False。
location: 消息发出的位置。有关更多详细信息，请参阅 SphinxLoggerAdapter.warning()。
color: 日志的颜色。默认情况下，info 和 verbose 级别日志不着色，debug 级别日志着色为 "darkgray"。

sphinx.util.logging.pending_logging()[source]¶

用于临时推迟记录所有日志的上下文管理器。

例如

>>> 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()[source]¶

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

类似于 pending_logging()。

sphinx.util.logging.prefixed_warnings()[source]¶

用于临时将前缀添加到所有警告日志记录的上下文管理器。

例如

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

在版本 2.0 中添加。