日志 API

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

获取由 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)[source]

LoggerAdapter 允许使用 typesubtype 关键字。

error(msg, *args, **kwargs)
critical(msg, *args, **kwargs)
warning(msg, *args, **kwargs)[source]

在此日志记录器上以指定的级别记录消息。基本上,参数与 Python 的日志记录模块相同。

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

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)

在此日志记录器上以指定的级别记录消息。基本上,参数与 Python 的日志记录模块相同。

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

nonl

如果为真,则日志记录器不会在日志消息末尾折叠行。默认值为 False

location

消息发出位置。有关更多详细信息,请参阅 SphinxLoggerAdapter.warning()

color

日志的颜色。默认情况下,信息和详细级别的日志不带颜色,调试级别的日志颜色为 "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 中新增。