Logging API¶

sphinx.util.logging.getLogger(name)[原始碼]¶

取得由 sphinx.util.logging.SphinxLoggerAdapter 包裝的 logger。

Sphinx logger 總是使用 sphinx.* 命名空間，以獨立於 root logger 的設定。它確保即使第三方擴充功能或匯入的應用程式重設 logger 設定，logging 仍然保持一致。

使用範例

>>> 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)[原始碼]¶

使用指定的層級在此 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)[原始碼]¶

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

verbose(msg, *args, **kwargs)[原始碼]¶

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()[原始碼]¶

暫時延後記錄所有日誌的上下文管理器。

例如

>>> 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!

在 2.0 版本中新增。