logging --- 事件記錄

此模組提供標準 Python logging 套件的輕量化子集，並針對 MicroPython 進行調整。它透過階層式命名的 Logger 物件支援分級記錄、提供一小組處理常式（StreamHandler、FileHandler）、透過 Formatter 進行 printf 風格的格式化，以及與作用於根記錄器之函式等效的模組層級便利函式。

此模組對 CPython API 的遵循程度足夠高，因此為標準函式庫撰寫的簡單應用程式應可直接運作而無需修改。本模組不提供篩選器、多行程鎖定、組態檔格式以及大多數處理常式類別。

等級常數

logging.CRITICAL: int

數值 50。用於無法復原的錯誤。

logging.ERROR: int

數值 40。用於嚴重問題。

logging.WARNING: int

數值 30。剛完成組態的根記錄器之預設等級。

logging.INFO: int

數值 20。用於確認訊息。

logging.DEBUG: int

數值 10。用於細部診斷輸出。

logging.NOTSET: int

數值 0。表示記錄器未設定等級（此時有效等級會從根記錄器或 WARNING 繼承而來）。

函式

logging.getLogger(name: str | None = None) → Logger

傳回以 name 註冊的 Logger，並在首次使用時建立它。若 name 為 None，則傳回根記錄器。第一次以 name="root"（或未設定 name）呼叫時，會隱式呼叫 basicConfig 以附加一個寫入 sys.stderr 的預設 StreamHandler。

logging.log(level: int, msg: str, *args) → None

在根記錄器上以 level 等級記錄一則訊息。args 會使用 printf 風格的 % 格式化插入 msg；單一字典引數會被當作對應表使用。

logging.debug(msg: str, *args) → None

等效於 getLogger().debug(msg, *args)。

logging.info(msg: str, *args) → None

等效於 getLogger().info(msg, *args)。

logging.warning(msg: str, *args) → None

等效於 getLogger().warning(msg, *args)。

logging.error(msg: str, *args) → None

等效於 getLogger().error(msg, *args)。

logging.critical(msg: str, *args) → None

等效於 getLogger().critical(msg, *args)。

logging.exception(msg: str, *args, exc_info: bool | BaseException = True) → None

等效於 getLogger().exception(msg, *args, exc_info=exc_info)。以 ERROR 等級記錄訊息，並在 exc_info 為真值時額外格式化目前作用中例外的回溯記錄。若 exc_info 本身是 BaseException，則使用該例外的回溯記錄；否則會在可用時查詢 sys.exc_info()。

logging.shutdown() → None

關閉附加至每個已知記錄器的所有處理常式並遺忘這些記錄器。當 sys.atexit 鉤點可用時，會透過它自動註冊此函式。

logging.addLevelName(level: int, name: str) → None

將文字 name 與數值 level 建立關聯，如此 Formatter 即可透過 %(levelname)s 呈現它。

logging.basicConfig(filename: str | None = None, filemode: str = 'a', format: str | None = None, datefmt: str | None = None, level: int = WARNING, stream=None, encoding: str = 'UTF-8', force: bool = False) → None

以單一處理常式設定根記錄器。

若提供了 filename，則會使用 filemode 與 encoding 建立一個 FileHandler；否則會使用一個寫入 stream（預設為 sys.stderr）的 StreamHandler。

format 與 datefmt 會傳遞給新的 Formatter。

level 同時設定處理常式的等級與根記錄器的等級。

若根記錄器已有處理常式，則此函式不執行任何動作，除非 force 為 True，此時現有的處理常式會被關閉並取代。

類別

class logging.Logger(name: str, level: int = NOTSET)

具名的記錄器。請透過 getLogger 建構記錄器，而非直接建構，如此 getLogger 才能為相同名稱傳回相同的實例。

name: str

記錄器的點分隔名稱。

level: int

已設定的數值等級。0（NOTSET）表示「繼承」。

handlers: list

附加至此記錄器的 Handler 實例清單。當為空時，訊息會分派給根記錄器的處理常式。

setLevel(level: int) → None

設定記錄器的閾值等級。

isEnabledFor(level: int) → bool

若 level 等級的訊息會被此記錄器處理，則傳回 True。

getEffectiveLevel() → int

傳回下列各項中第一個非零值：此記錄器的等級、根記錄器的等級，或 WARNING。

log(level: int, msg: str, *args) → None

以 level 等級記錄 msg。args 會以 % 運算子插入 msg；若第一個位置引數為字典，則會將其當作對應表使用。

debug(msg: str, *args) → None

以 DEBUG 等級記錄 msg。

info(msg: str, *args) → None

以 INFO 等級記錄 msg。

warning(msg: str, *args) → None

以 WARNING 等級記錄 msg。

error(msg: str, *args) → None

以 ERROR 等級記錄 msg。

critical(msg: str, *args) → None

以 CRITICAL 等級記錄 msg。

exception(msg: str, *args, exc_info: bool | BaseException = True) → None

以 ERROR 等級記錄 msg，並在 exc_info 為真值時附加格式化後的回溯記錄。若 exc_info 是 BaseException 實例，則呈現該例外的回溯記錄；否則會透過 sys.exc_info() 查詢目前作用中的例外。

addHandler(handler: Handler) → None

將 handler 附加至此記錄器。

hasHandlers() → bool

若此記錄器附加了任何處理常式，則傳回 True。

class logging.Handler(level: int = NOTSET)

所有處理常式的基底類別。子類別實作 emit()。

level: int

處理常式的閾值等級。

formatter: 'Formatter | None'

作用中的 Formatter，或 None。

setLevel(level: int) → None

設定處理常式的閾值等級。

setFormatter(formatter: Formatter) → None

將 formatter 附加至此處理常式。

format(record: LogRecord) → str

使用已設定的格式器呈現 record。

close() → None

釋放處理常式所持有的資源。由 shutdown 以及 FileHandler 在關閉時呼叫。

class logging.StreamHandler(stream=None)

將格式化後的記錄寫入 stream，後面接著 self.terminator（預設為 "\n"）。stream 預設為 sys.stderr。

stream

目標串流物件。

terminator: str

附加在每筆格式化記錄之後的字串。預設為 "\n"。

emit(record: LogRecord) → None

若 record 的等級達到處理常式的閾值，則將其寫入 stream。

close() → None

當底層串流提供 flush 方法時，沖刷該串流。

class logging.FileHandler(filename: str, mode: str = 'a', encoding: str = 'UTF-8')

StreamHandler 子類別，它以指定的 mode 與 encoding 開啟 filename 並將格式化後的記錄寫入其中。底層檔案會在 close() 時關閉。

class logging.Formatter(fmt: str | None = None, datefmt: str | None = None)

將 LogRecord 實例呈現為字串。

fmt 是 printf 風格的範本。可辨識的鍵為 %(name)s、%(message)s、%(msecs)d、%(asctime)s 以及 %(levelname)s。未設定時預設為 "%(levelname)s:%(name)s:%(message)s"。

datefmt 是用於呈現 %(asctime)s 的 time.strftime 範本。預設為 "%Y-%m-%d %H:%M:%S"。

usesTime() → bool

若格式範本引用了 asctime，則傳回 True。

formatTime(datefmt: str, record: LogRecord) → str | None

使用 time.strftime 與 datefmt 格式化 record.ct。在 time.strftime 不可用的平台上傳回 None。

format(record: LogRecord) → str

呈現 record。若範本使用了 asctime，則會先呼叫 formatTime() 以填入 record.asctime。

class logging.LogRecord

用於存放從 Logger 傳遞至其處理常式之資料的容器。實例透過 set() 填入；記錄器實作會為每個記錄器重複使用單一記錄，以減少配置。

name: str

源發記錄器的名稱。

levelno: int

此記錄的數值等級。

levelname: str

文字形式的等級名稱。

message: str

完整格式化後的記錄訊息。

ct: float

time.time() 所傳回的建立時間。

msecs: int

ct 的毫秒部分。

asctime: str | None

人類可讀的時間戳記；由 Formatter 延遲填入。

set(name: str, level: int, message: str) → None

以指定的值初始化此記錄並擷取目前時間。