melobot.log¶
在 3.2.0 版本，日志系统进行了重构，现在推荐通过“域”规则设置和获取日志器。依据“域”来获取日志代理对象，可使用 get_logger()，或使用上下文变量 logger。日志代理对象是通用日志器的子类，它将会内含一个有效的日志器或单纯包含空，包含空时自动丢弃所有日志记录
域总共有三层：顶级域、bot 域和模块域。顶级域只存在一个日志器，bot 域依据 bot 上下文构建，模块域依据文件路径树构建
当获取“当前域”的日志代理对象时，首先沿本模块对应的文件/目录结点向上查找存在日志器的路径结点。查找到的第一个不为 None 的日志器，将会提供给日志代理对象使用。如果向上查找到根路径都没有可用日志器，则开始查找 bot 域可用的日志器。当前调用点的 bot 上下文中，如果有可用 bot 存在（例如调用点在处理流中）且 bot 日志器不为空，此时就使用该 bot 的日志器。否则继续尝试顶级域日志器，如果依然为空，那么最终日志代理对象内含空，丢弃日志
设置顶级域的日志器使用
set_global_logger()方法，设置 bot 域的日志器在初始化 bot 时进行，设置模块域的日志器使用set_module_logger()方法值得注意的是：melobot 会默认设置顶级日志器，保证其存在且不为空，当然你也可以随时替换。另外
Bot初始化方法的 enable_log 参数已经移除
一些实际例子：
# 使用日志器的一方，例如 xxx.py
from melobot.log import logger
# 定义日志器的一方，一般是 bot 程序的主入口脚本处：
from melobot.log import set_module_logger, Logger, NullLogger
# 为 melobot 核心模块对应路径结点设置一个日志器
set_module_logger("melobot", Logger(...))
# 设置 melobot.bot.dispatch 模块对应路径结点的日志器为 NullLogger
# 这样就会停止向上继续查找，从而屏蔽这个模块的日志
set_module_logger("melobot.bot.dispatch", NullLogger())
# 再为插件目录下的所有插件设置一个单独的日志器
set_module_logger("./plugin_dir", Logger(...))
另外 3.2.0 版本开始，提供 log_exc() 方法用于向 melobot 核心模块报告异常信息，并体现在日志或异常回溯栈信息中。
该方法所在模块为：melobot.log.report，此信息可用于调整被报告异常日志输出时使用的日志器。
注意：通过依赖注入获取 logger 的方式依旧可用，并且该特性计划长期支持：
from melobot.log import GenericLogger
async def _(logger: GenericLogger) -> None:
# 通过依赖注入获取的 logger，永远是当前 bot 上下文中的 bot 的日志器
# 按照依赖注入规则，如果日志器为空：
# 对于事件处理方法，就不会被执行
# 对于 hook 方法，就会发出一个“依赖不匹配”异常
...
内置日志部件¶
- class melobot.log.Logger[源代码]¶
基类：
Logger,GenericLoggermelobot 内置日志器
推荐使用的日志器。实现了
GenericLogger接口，因此可以用于 melobot 内部日志记录debug, info, warning, error, critical, exception 等接口与
logging.Logger用法完全一致- __init__(name: str = '[default]', level: LogLevel = LogLevel.INFO, file_level: LogLevel = LogLevel.DEBUG, to_console: bool = True, to_dir: str | None = None, add_tag: bool = True, legacy: bool = False, yellow_warn: bool = True, red_error: bool = True, two_stream: bool = False, is_parellel: bool = False) None[源代码]¶
初始化日志器
- 参数:
name (str) -- 日志器的名称（唯一）
level (LogLevel) -- 日志等级
file_level (LogLevel) -- 日志文件的日志等级
to_console (bool) -- 是否输出到控制台
to_dir (str | None) -- 保存日志文件的目录，为空则不保存文件
add_tag (bool) -- 记录日志时是否标识日志器名称
legacy (bool) -- 记录日志时是否使用传统样式（不对日志内容进行自动高亮，而是使用日志等级的五色）
yellow_warn (bool) -- 记录 LogLevel.WARN 级别时，是否将日志内容着色为黄色。 legacy 选项为 True 时此参数无效
red_error (bool) -- 记录 LogLevel.ERROR 及以上级别时，是否将日志内容着色为红色。 legacy 选项为 True 时此参数无效
two_stream (bool) -- 当使用记录到文件功能时，是否分离“常规日志”和“问题日志”（warning, error, critical）到不同的文件
is_parellel (bool) -- 日志渲染是否启用并行优化（可能导致日志小范围行间乱序）
- 返回类型:
None
- set_level(level: LogLevel) None[源代码]¶
设置日志等级
日志等级自动应用于包含的所有 handler（但输出日志到文件的 handler 除外）
- 参数:
level (LogLevel) -- 日志等级
- 返回类型:
None
- generic_lazy(msg: str, *arg_getters: Callable[[], str], level: LogLevel, with_exc: bool = False, stacklevel: int = 1) None[源代码]¶
懒惰日志方法
通用日志部件与通用修补¶
- class melobot.log.GenericLogger[源代码]¶
基类：
BetterABC通用日志器抽象类
任何日志器实现本类接口，或通过
logger_patch()修补后， 即可兼容 melobot 内部所有日志操作（也就可以用于 bot 初始化Bot.()）
- melobot.log.logger_patch(logger: Any, lazy_meth: LazyLogMethod) GenericLogger[源代码]¶
对指定的日志器进行修补操作，使其可以被用于 melobot 内部的日志记录
- 参数:
logger (Any) -- 任意已经实现 debug, info, warning, error, critical, exception 接口的日志器
lazy_meth (LazyLogMethod) -- 修补方法
- 返回类型:
- class melobot.log.StandardPatch[源代码]¶
-
用于修补 logging.Logger 的日志修补
上下文操作与变量¶
- melobot.log.logger¶
当前域对应的日志器，满足
GenericLogger的接口
- melobot.log.get_logger() GenericLogger[源代码]¶
获取当前域下可用的日志器
- 返回:
日志器
- 返回类型:
获取当前域对应的日志器的方法，与上面的上下文变量行为一致
- melobot.log.set_global_logger(logger: GenericLogger | None) None[源代码]¶
设置顶级域对应的日志器
- 参数:
logger (GenericLogger | None) -- 日志器，可以为空
- 返回类型:
None
- melobot.log.set_module_logger(module: str | PathLike[str] | ModuleType, logger: GenericLogger | None) None[源代码]¶
设置模块域对应的日志器
- 参数:
module (str | PathLike[str] | ModuleType) -- 模块名、模块相对或绝对路径、模块对象
logger (GenericLogger | None) -- 日志器，可以为空
- 返回类型:
None
- melobot.log.log_exc(exc: BaseException, msg: str, obj: Any | None = None) None[源代码]¶
使用 melobot 内部的异常报告日志器报告异常
- 参数:
exc (BaseException) -- 异常对象
msg (str) -- 日志消息
obj (Any | None) -- 需要打印的相关变量，为空时不打印
- 返回类型:
None