Loguru 文档导读与快速上手一份开箱即用的 Python 日志库使用指南【免费下载链接】loguruPython logging made (stupidly) simple项目地址: https://gitcode.com/gh_mirrors/lo/loguru本文以 Loguru 官方文档入口 docs/index.rst 为核心骨架带你快速理解这个以Python logging made (stupidly) simple为定位的日志库的项目理念、安装方式、文档组织结构和开箱即用的核心能力并辅以仓库源码佐证其默认行为与底层实现。读完本文你将能按图索骥地在 docs 目录中快速定位所需的 API 参考、使用教程与排障指南并用 3 行代码完成第一次日志输出。项目定位为什么需要 LoguruLoguru 是一个旨在让 Python 日志变得愉快的库。正如 docs/index.rst 引入的 README.md 开头所述开发者常常因为懒得配置 logger而改用print()但日志对每个应用都至关重要、是调试的基本手段。Loguru 想解决的核心痛点是——用 Loguru你没有任何理由不从一开始就使用日志简单到只需一行from loguru import logger同时这个库致力于缓解标准库logging的一些固有缺陷如繁琐的 Handler/Formatter/Filter 配置、时间格式不直观、线程异常丢失等把记录日志变成一件既愉悦又强大的事。当前仓库版本为 0.7.3见 loguru/init.py仅暴露一个模块级对象logger见 loguru/init.py这也是 Loguru 最核心的设计理念只有一个logger它是一个将日志消息分发给已注册 handlersink的接口。Loguru 官方演示动画来自文档静态资源 docs/_static/img/demo.gifREADME 亦在文档首页使用它展示实际输出效果安装与第一个日志根据 README 的安装章节通过 pip 一键安装即可pip install loguru从 pyproject.toml 可以看出项目要求 Python 3.5支持 CPython 与 PyPy运行时依赖极小——仅在 Windows 平台需要colorama0.3.4和win32-setctime1.0.0Python 3.7 时额外需要aiocontextvars0.2.0其余场景零第三方依赖。安装完成后日志立即可用无需任何配置from loguru import logger logger.debug(Thats it, beautiful and simple logging!)这就是 Loguru 与标准库最大的不同开箱即用零样板代码。默认情况下logger已预配置好并输出到stderr当然这完全可配置。文档结构docs 目录的四大部分docs/index.rst 本身是 Sphinx 文档的入口页它通过.. include::指令引入 README 的项目介绍部分并通过.. toctree::组织出完整的文档导航树。理解这份结构你就能迅速在仓库中找到任何所需资料目录节点对应文件内容Overview概览docs/overview.rst引入 README 的功能导览章节逐一讲解 17 项核心特性API ReferenceAPI 参考docs/api.rst以automodule方式生成Logger类的完整 API 文档Help Guides帮助与指南docs/resources.rst迁移指南、故障排查、实用食谱三份深度文档Project Information项目信息docs/project.rst贡献指南、开源协议、版本更新日志Overview功能导览docs/overview.rst 通过:start-after: / :end-before:两个标记截取 README 的 feature tour 部分是了解 Loguru 全部能力的最佳入口。它的核心特性清单包括开箱即用、一个add()函数搞定 sink/format/filter、文件日志的 rotation/retention/compression、花括号风格格式化、线程与主线程异常捕获、彩色日志、异步/线程安全/多进程安全、完整异常诊断、结构化日志、惰性求值、自定义级别、更好的时间处理、脚本与库双场景适配、与标准 logging 完全兼容、环境变量定制默认值、便捷的日志解析器、通知集成等。这些特性在下一节特性速览中会给出关键代码与对应文档位置。API ReferenceLogger 全量 APIdocs/api.rst 通过 Sphinx 的automodule/autoclass指令从源码生成文档主体是loguru._logger.Logger类的全部成员方法其索引直接列在 api 页面中add、remove、complete、catch、opt、bind、contextualize、patch、level、disable、enable、configure、reinstall、parse以及trace/debug/info/success/warning/error/critical/log/exception等日志方法。API 文档还交叉引用了 sink、message、levels、record、time、file、color、env 等概念标签:ref:引用并配套 docs/api/type_hints.rst 提供类型提示说明类型存根实现位于 loguru/init.pyi。Help Guides 与 Project Information帮助与指南docs/resources.rst下挂三份实战文档迁移指南、故障排查、实用食谱含使用 Loguru 的安全注意事项等主题仓库对应的内容文件位于 docs/resources 目录。项目信息docs/project.rst下挂贡献指南、MIT 许可证见 LICENSE与 CHANGELOG.rst 更新日志。如需本地构建这套文档可使用 docs/Makefile 配合 pyproject.toml 中dev可选依赖Sphinx、sphinx-rtd-theme、myst-parser进行。从源码看默认行为预配置的 logger 与启动流程文档首页强调 logger已预配置、输出到 stderr这在 loguru/init.py 中有非常直白的实现logger _Logger( core_Core(), exceptionNone, depth0, recordFalse, lazyFalse, colorsFalse, rawFalse, captureTrue, patchers[], extra{}, ) if _defaults.LOGURU_AUTOINIT and _sys.stderr: logger.add(_sys.stderr) _atexit.register(logger.remove)这段代码揭示了三点关键事实单例 logger模块导入时即构造一个全局logger实例暴露于__all__ [logger]自动初始化若环境变量LOGURU_AUTOINIT为真默认开启且存在stderr则自动注册 stderr sink这正是开箱即用的机制来源退出清理通过atexit在解释器退出时调用logger.remove()安全回收所有 handler。环境变量的默认值集中定义在 loguru/_defaults.py例如默认格式LOGURU_FORMAT含时间、级别、模块名、函数名、行号与消息的完整模板、默认级别LOGURU_LEVELDEBUG、LOGURU_BACKTRACETrue与LOGURU_DIAGNOSETrue以及每个内置级别TRACE/DEBUG/INFO/SUCCESS/WARNING/ERROR/CRITICAL的数值no、ANSIcolor与icon。这解释了文档中通过环境变量个性化默认值一节的实现基础。特性速览文档首页之外的核心能力作为文档入口的导读这里把 docs/overview.rstREADME feature tour中最常用、也最值得深入查阅的几项能力快速过一遍详细参数请以 docs/api/logger.rst 的add()文档为准。一个 add() 函数统一管理 sink / format / filter / level如何添加 handler如何设置格式如何过滤消息如何设置级别答案只有一个add()函数。sink 可以是普通函数、文件路径字符串、类文件对象、协程函数或标准库 Handler每条消息会以record字典的形式上下文化后分发给它logger.add(sys.stderr, format{time} {level} {message}, filtermy_module, levelINFO)add()会返回一个 handler 标识符可用remove()按需移除例如调用logger.remove()无参数即可清空默认的 stderr handler、重新开始。文件日志rotation / retention / compression 一行搞定以字符串路径作为 sink 即可写入文件并支持按大小、时间、周期自动轮转按时间清理旧文件以及在关闭时压缩归档对应实现见 loguru/_file_sink.py 中的Rotation、Retention、Compression三个类logger.add(file_1.log, rotation500 MB) # 文件超过 500 MB 自动轮转 logger.add(file_2.log, rotation12:00) # 每天中午 12 点创建新文件 logger.add(file_3.log, rotation1 week) # 文件过旧即轮转 logger.add(file_X.log, retention10 days) # 10 天后清理旧日志 logger.add(file_Y.log, compressionzip) # 关闭时压缩为 zip 节省空间文件名中的{time}占位符会被格式化为创建时间默认格式%Y-%m-%d_%H-%M-%S_%f见 loguru/_file_sink.py同名冲突时自动追加计数器后缀。格式化、异常捕获与彩色输出Loguru 采用更优雅的{}花括号风格等价于str.format()而非标准库的%logger.info(We discovered {} is the answer to {question}, 42, questioneverything)对于线程或主线程中悄悄崩溃、日志里什么也没有的场景可用catch()装饰器/上下文管理器保证任何错误都被记录logger.catch def my_function(x, y, z): # 出错了照样会被捕获记录 return 1 / (x y z)终端兼容时 Loguru 会自动为日志加色也可用 markup 标签自定义样式logger.add(sys.stdout, colorizeTrue, formatgreen{time}/green level{message}/level)异步、线程安全、多进程安全与结构化日志所有 sink 默认线程安全若需多进程安全或异步写日志给add()传enqueueTrue即可协程 sink 可用complete()等待其完成logger.add(somefile.log, enqueueTrue)结构化日志方面serializeTrue将每条消息序列化为 JSONbind()通过extra属性附加上下文如 IP、用户contextualize()可在with块内临时注入上下文patch()则能为每条新消息动态附加字段结合filter甚至能实现按上下文路由到不同 sink 的精细化控制logger.add(special.log, filterlambda record: special in record[extra]) logger.bind(specialTrue).info(This message, though, is logged to the file!)opt()惰性求值与逐条消息级控制opt()是 Loguru 非常灵活的方法可为单条日志开启诸多能力比如惰性求值昂贵的表达式以及临时叠加异常栈、颜色、原始输出、调用深度等相关实现见 loguru/_logger.py 附近logger.opt(lazyTrue).debug(如果 sink 级别 DEBUG 才执行: {x}, xlambda: expensive_function(2**64)) logger.opt(exceptionTrue).info(为这条消息附加异常堆栈也接受元组) logger.opt(colorsTrue).info(本条消息内使用 blue颜色/blue) logger.opt(recordTrue).info(读取 record 字段如 {record[thread]}) logger.opt(depth1).info(使用父级栈帧上下文适合包装函数)自定义级别与脚本/库双场景除内置标准级别外Loguru 额外提供了trace()与success()还可用level()创建任意新级别new_level logger.level(SNAKY, no38, coloryellow, icon) logger.log(SNAKY, Here we go!)脚本场景下可用configure()一次性配置多 handler库场景下则绝不调用add()而是用disable()让日志函数变为 no-op交由使用方enable()按需开启# 脚本 logger.configure(handlers[{sink: sys.stdout, format: {time} - {message}}]) # 库内应使用库的 __name__ logger.disable(my_library) # 应用中恢复 logger.enable(my_library)与标准 logging 兼容及更多Loguru 可以与标准库 logging 双向打通标准库 Handler 可直接作为 sink也可自定义PropagateHandler把 Loguru 消息转发到标准 logging或用InterceptHandler反向拦截标准库日志流入 Loguru sink。此外parse()可用带命名分组正则从日志文件中提取结构化数据对应实现见 loguru/_logger.py还可配合 apprise 等通知库在程序异常时发送邮件、Discord 等通知。继续深入从文档到源码的路径围绕本文涉及的各项能力仓库中可直接对照的资料如下文档结构入口 docs/index.rst概览 docs/overview.rstAPI docs/api.rst 与 docs/api/logger.rst核心实现logger 定义 loguru/_logger.py模块入口与默认 handler loguru/init.py默认环境变量 loguru/_defaults.py文件 sink轮转/保留/压缩loguru/_file_sink.py测试验证仓库 tests 目录下按功能拆分了大量测试例如文件轮转 tests/test_filesink_rotation.py、保留 tests/test_filesink_retention.py、压缩 tests/test_filesink_compression.py以及结构化日志 tests/test_bind.py、异常格式化 tests/test_exceptions_formatting.py 等可作为理解各参数实际行为的活文档总而言之Loguru 的文档体系与源码高度自洽入口页负责一句话讲清定位概览页负责特性逐一演示API 页负责参数精确说明而_logger.py、_defaults.py、_file_sink.py等源码文件则让文档中的每个承诺都能落实到具体实现上。无论你是想快速接入日志、还是深入定制日志行为都可以从这份文档结构出发快速定位到所需的全部信息。【免费下载链接】loguruPython logging made (stupidly) simple项目地址: https://gitcode.com/gh_mirrors/lo/loguru创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考