logging --- 事件日志

本模块为 MicroPython 提供了标准 Python logging 包的一个轻量级子集。它通过分层命名的 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 中；单个 dict 参数会被用作映射。

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，否则此函数不执行任何操作；在 force 为真值的情况下，现有的处理器会被关闭并替换。

类

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 中；如果第一个位置参数是 dict，则将其用作映射。

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

用给定的值初始化记录并捕获当前时间。