rtoml

一个用 rust 实现的 python TOML 库。

为什么使用 rtoml

• 正确性：rtoml 基于广泛使用且非常稳定的 toml-rs 库，它通过了所有 标准 TOML 测试，并且对 python 代码拥有 100% 的覆盖率。我尝试过的其他 python TOML 库都无法解析某些有效的 TOML。
• 性能：参见 github.com/pwwang/toml-bench - 在撰写本文时，rtoml 是最快的 Python TOML 库。
• None-值处理：rtoml 对 None 值具有灵活的支持，而不是简单地忽略它们。

安装

需要 python>=3.10，Linux、macOS 和 Windows 的二进制文件可从 PyPI 获取， 参见 此处。

pip install rtoml

如果 pypi 上没有适用于你系统配置的二进制文件；你需要先安装 rust stable，然后才能安装 rtoml。

用法

load

def load(toml: Union[str, Path, TextIO], *, none_value: Optional[str] = None) -> Dict[str, Any]: ...

通过字符串或文件解析 TOML，并返回一个 python 字典。

• toml: 一个 str、Path 或来自 open() 的文件对象。
• none_value: 控制 toml 中的哪个值在 python 中作为 None 加载。默认情况下，none_value 为 None，这意味着没有值作为 None 加载

loads

def loads(toml: str, *, none_value: Optional[str] = None) -> Dict[str, Any]: ...

解析 TOML 字符串并返回一个 python 字典。（提供此函数以匹配 json 及类似库的接口）

• toml: 包含 TOML 的 str。
• none_value: 控制 toml 中的哪个值在 python 中作为 None 加载。默认情况下，none_value 为 None，这意味着没有值作为 None 加载

dumps

def dumps(obj: Any, *, pretty: bool = False, none_value: Optional[str] = "null") -> str: ...

将 python 对象序列化为 TOML。

• obj: 要序列化的 python 对象。
• pretty: 如果为 True，则输出采用更“美观”的格式。
• none_value: 控制 obj 中 None 值的序列化方式。none_value=None 表示忽略 None 值。

dump

def dump(
    obj: Any, file: Union[Path, TextIO], *, pretty: bool = False, none_value: Optional[str] = "null"
) -> int: ...

将 python 对象序列化为 TOML 并写入文件。

• obj: 要序列化的 python 对象。
• file: 一个 Path 或来自 open() 的文件对象。
• pretty: 如果为 True，则输出采用更“美观”的格式。
• none_value: 控制 obj 中 None 值的序列化方式。none_value=None 表示忽略 None 值。

示例

from datetime import datetime, timezone, timedelta
import rtoml

obj = {
    'title': 'TOML Example',
    'owner': {
        'dob': datetime(1979, 5, 27, 7, 32, tzinfo=timezone(timedelta(hours=-8))),
        'name': 'Tom Preston-Werner',
    },
    'database': {
        'connection_max': 5000,
        'enabled': True,
        'ports': [8001, 8001, 8002],
        'server': '192.168.1.1',
    },
}

loaded_obj = rtoml.load("""\
# This is a TOML document.

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # First class dates

[database]
server = "192.168.1.1"
ports = [8001, 8001, 8002]
connection_max = 5000
enabled = true
""")

assert loaded_obj == obj

assert rtoml.dumps(obj) == """\
title = "TOML Example"

[owner]
dob = 1979-05-27T07:32:00-08:00
name = "Tom Preston-Werner"

[database]
connection_max = 5000
enabled = true
server = "192.168.1.1"
ports = [8001, 8001, 8002]
"""

None 值处理的示例：

obj = {
    'a': None,
    'b': 1,
    'c': [1, 2, None, 3],
}

# Ignore None values
assert rtoml.dumps(obj, none_value=None) == """\
b = 1
c = [1, 2, 3]
"""

# Serialize None values as '@None'
assert rtoml.dumps(obj, none_value='@None') == """\
a = "@None"
b = 1
c = [1, 2, "@None", 3]
"""

# Deserialize '@None' back to None
assert rtoml.load("""\
a = "@None"
b = 1
c = [1, 2, "@None", 3]
""", none_value='@None') == obj