uiritoml：Python 里处理 TOML 的老牌工具

uiri/toml：Python 里处理 TOML 的老牌工具

TOML 配置文件格式这几年越来越常见，Rust 的 Cargo、Python 的 pyproject.toml 都采用了这种格式。Python 3.11 把 tomli 内置进了标准库作为只读模块。但在此之前，uiri/toml 一直是 Python 开发者处理 TOML 的常用选择，目前在 GitHub 上积累了 1,142 个 Star。

这个库的定位很清晰：提供 TOML 数据的解析和生成功能。安装方式也简单，pip install toml 即可，不需要额外依赖。

核心 API 设计简洁

库提供了四个主要函数，命名和 Python 标准库的 json 模块保持一致：

toml.load 和 toml.loads 负责解析，把 TOML 文件或字符串转成 Python 字典。前者接收文件路径或文件对象，后者直接处理字符串。两个函数都支持通过 _dict 参数指定返回的字典类型，这个设计在需要自定义数据结构时很实用。

toml.dump 和 toml.dumps 则负责序列化，把 Python 字典转成 TOML 格式。dump 写入文件，dumps 返回字符串。都支持传入自定义的 encoder。

这种对称的 API 设计降低了学习成本，开发者基本看一眼就能用。错误处理也明确，解析失败会抛出 TomlDecodeError，而不是静默返回奇怪的结果。

通过官方测试套件

配置解析库的可靠性很难凭感觉判断。这个项目的一个硬指标是通过了 TOML 官方测试套件，说明对各种边界情况和语法规则的处理是经过验证的。

README 里提供了完整的代码示例，覆盖了嵌套表、数组、日期时间等常见 TOML 结构。示例展示了从字符串解析到字典，再从字典转回字符串的完整流程，输出结果和输入结构保持一致。

对 Numpy 的支持

这个库有个比较实用的细节：对 Numpy 用户提供了 TomlNumpyEncoder。默认情况下，np.floatX 类型的数组元素会被编码成字符串。用上这个 encoder 后，就能正确输出为浮点数。

这个设计考虑到了数据科学场景的需求。很多配置文件里会存储数值参数，如果一律转字符串，后续读取时还要再做类型转换，容易出错。encoder 机制也提供了扩展接口，你可以根据需要实现自己的编码逻辑。

适用场景

如果你在维护一个需要兼容 Python 3.10 及以下版本的项目，uiri/toml 是个稳妥的选择。它的 API 稳定，依赖干净，MIT 协议也足够宽松。

对于 Python 3.11 及以上版本，标准库内置的 tomllib 可以满足读取需求。但 tomllib 只提供读取功能，没有写入能力。如果你的项目需要把配置数据写回 TOML 文件，uiri/toml 仍然是个合理的选择。

另外，PyPI 上这个包的下载量一直比较稳定，说明它作为基础设施类库，在生产环境里是被广泛依赖的。很多项目的配置管理逻辑底层用的就是它。

总体来说，这是一个功能聚焦、接口干净的工具库。没有多余的功能，就是把 TOML 的读写做扎实了。对于需要程序化操作 TOML 文件的开发者，值得了解一下。

OML 的读写做扎实了。对于需要程序化操作 TOML 文件的开发者，值得了解一下。