[译]Python 和 TOML:新最好的朋友 (2) 使用Python操作TOML

简介: [译]Python 和 TOML:新最好的朋友 (2) 使用Python操作TOML

Python 和 TOML:新最好的朋友

原文:《Python and TOML: New Best Friends》

使用Python加载TOML

使用tomlitomlib加载TOML文档。

使用tomli 或 tomllib 读取TOML文档

在python3.11中,TOML支持已经内置在标准库中,tomllib模块可以读取和解析TOML文档。

如果你使用的是Python3.11及以后的版本,可以直接使用tomllib模块 替代tomli

我们先创建一个TOML文件tic_tac_toe.toml

# tic_tac_toe.toml

[user]
player_x.color = "blue"
player_o.color = "green"

[constant]
board_size = 3

[server]
url = "https://tictactoe.example.com"

用 pip 安装 tomli

python -m pip install tomli

tomli 模块仅公开两个函数:

  • load() :从文件对象加载 TOML
  • loads() :从字符串加载 TOML 文档。

首先用load()函数加载TOML文件:

import tomli
with open("tic_tac_toe.toml", mode="rb") as fp:
    config = tomli.load(fp)

然后可以查看config的内容:

>>> config
{'user': {'player_x': {'color': 'blue'}, 'player_o': {'color': 'green'}},
 'constant': {'board_size': 3},
 'server': {'url': 'https://tictactoe.example.com'}}

>>> config["user"]["player_o"]
{'color': 'green'}

>>> config["server"]["url"]
'https://tictactoe.example.com'

TOML 文档在 Python 中表示为字典。TOML 文件中的所有表和子表都显示为嵌套字典

如果已经将 TOML 文档表示为字符串,则可以使用 loads()代替 load()

>>> import tomli
>>> toml_str = """
... offset_date-time_utc = 2021-01-12 00:23:45Z
... potpourri = ["flower", 1749, { symbol = "X", color = "blue" }, 1994-02-14]
... """

>>> tomli.loads(toml_str)
{'offset_date-time_utc': datetime.datetime(2021, 1, 12, 0, 23, 45,
                                           tzinfo=datetime.timezone.utc),
 'potpourri': ['flower',
               1749,
               {'symbol': 'X', 'color': 'blue'},
               datetime.date(1994, 2, 14)]}

注意,TOML 时间和日期类型由 Python datetime 的类型表示


load()和 loads()之间的一个区别是,当您使用loads()时,您使用的是常规字符串而不是字节。在这种情况下, tomli 假设您已正确处理编码。


如果你希望自动设置tomli和tomllib。如果Python版本是3.11及以后的版本,则直接使用tomllib模块,否则安装并使用tomli模块。

requirements.txt写入:

tomli >= 1.1.0 ; python_version < "3.11"

在导入模块时:

try:
    import tomllib
except ModuleNotFoundError:
    import tomli as tomllib

比较TOML类型和Python类型

  • TOML 文件必须是有效的 UTF-8 编码的 Unicode 文档。
  • 任意 64 位有符号整数(从 −2^63 到 2^63−1)应被接受并无损处理。
  • 浮点数应实现为 IEEE 754 binary64 值。

一般来说,TOML的需求与Python对相应类型的实现非常匹配。Python 在处理文件时通常默认使用 UTF-8,而 Python float 遵循 IEEE 754。Python 的 int 类实现了任意精度的整数,这些整数可以处理所需的范围和更大的数字。


对于像 和 tomllib 这样的 tomli 基本库,TOML 的数据类型和 Python 的数据类型之间的映射是很自然的。您可以在tomllib 文档中找到以下转换表:

TOML Python
string str
integer int
float float
boolean bool
table dict
offset date-time datetime.datetime (.tzinfo是datetime.timezone是实例)
local date-time datetime.datetime(.tzinfo是None)
local date datetime.date
local time datetime.time
array list

load() 和 loads() 函数有一个参数 parse_float ,指定应如何分析浮点数。


默认实现满足使用 64 位浮点数的要求,通常精确到大约 16 位有效数字。大部分情况下这个精度足够了,但是如果您需要更高的精度,您可以使用 Decimal 类型。

>>> import tomli
>>> from decimal import Decimal
>>> ts = tomli.loads(
...     "ts = 2_459_772.084027777777778",
...     parse_float=Decimal,
... )["ts"]
>>> ts
Decimal('2459772.084027777777778')

>>> seconds = (ts - int(ts)) * 86_400
>>> seconds
Decimal('7260.000000000019200')

>>> seconds - 7260
Decimal('1.9200E-11')

在项目中使用配置文件

我们希望配置文件只读取一次,然后各个地方的代码都可以使用这个配置。

实际上,Python的import机制可以帮助我们实现这一点。import模块时,会缓存模块的内容,所以只有第一次import时会读取配置文件。

下面看一个具体的例子。

我们的配置文件为tic_tac_toe.toml

# tic_tac_toe.toml

[user]
player_x.color = "blue"
player_o.color = "green"

[constant]
board_size = 3

[server]
url = "https://tictactoe.example.com"

创建config/目录:

config/
├── __init__.py
└── tic_tac_toe.toml

名为 __init__.py 的文件在 Python 中扮演着特殊的角色。它们将包含目录标记为包。此外, __init__.py 定义的名称通过包公开。

下面我们在__init__.py读取配置文件:

# __init__.py

import pathlib
import tomli

path = pathlib.Path(__file__).parent / "tic_tac_toe.toml"
with path.open(mode="rb") as fp:
    tic_tac_toe = tomli.load(fp)

在config目录下启动解释器:

>>> import config
>>> config.path
PosixPath('/home/realpython/config/tic_tac_toe.toml')

>>> config.tic_tac_toe
{'user': {'player_x': {'color': 'blue'}, 'player_o': {'color': 'green'}},
 'constant': {'board_size': 3},
 'server': {'url': 'https://tictactoe.example.com'}}

现在,您可以通过将 config/ 目录复制到项目中并将井字游戏配置替换为您自己的设置,将配置集成到现有项目中。

在代码文件中,您可能希望为配置导入添加别名,以便更方便地访问您的设置:

>>> from config import tic_tac_toe as CFG

>>> CFG["user"]["player_x"]["color"]
'blue'

将Python对象转换为TOML

TOML 文档通常是手写的,因为它们主要用作配置。不过,有时您可能需要将嵌套字典转换为 TOML 文档。

将字典转换为 TOML

{
    "user": {
        "player_x": {"symbol": "X", "color": "blue", "ai": True},
        "player_o": {"symbol": "O", "color": "green", "ai": False},
        "ai_skill": 0.85,
    },
    "board_size": 3,
    "server": {"url": "https://tictactoe.example.com"},
}

在本小节中,您将编写一个简化的 TOML 编写器,该编写器能够将此字典编写为 TOML 文档。

创建一个新文件to_toml.py

首先,编写一个名为_dumps_value() 的辅助函数。此函数将获取某个值,并根据值类型返回其 TOML 表示形式。

# to_toml.py

def _dumps_value(value):
    if isinstance(value, bool):
        return "true" if value else "false"
    elif isinstance(value, (int, float)):
        return str(value)
    elif isinstance(value, str):
        return f'"{value}"'
    elif isinstance(value, list):
        return f"[{', '.join(_dumps_value(v) for v in value)}]"
    else:
        raise TypeError(f"{type(value).__name__} {value!r} is not supported")

接下来,您将添加处理表的代码。main 函数遍历字典,并将每个项目转换为键值对。如果该值恰好是字典,则您将添加一个表头并递归填写该表:

# to_toml.py

# ...

def dumps(toml_dict, table=""):
    toml = []
    for key, value in toml_dict.items():
        if isinstance(value, dict):
            table_key = f"{table}.{key}" if table else key
            toml.append(f"\n[{table_key}]\n{dumps(value, table_key)}")
        else:
            toml.append(f"{key} = {_dumps_value(value)}")
    return "\n".join(toml)

这在处理嵌套时会出现顺序问题,我们进行排序来修复这个问题。

# to_toml.py

# ...

def dumps(toml_dict, table=""):
    def tables_at_end(item):
        _, value = item
        return isinstance(value, dict)

    toml = []
    for key, value in sorted(toml_dict.items(), key=tables_at_end):
        if isinstance(value, dict):
            table_key = f"{table}.{key}" if table else key
            toml.append(f"\n[{table_key}]\n{dumps(value, table_key)}")
        else:
            toml.append(f"{key} = {_dumps_value(value)}")
    return "\n".join(toml)

通过tomli_w 写TOML文档

tomli_w有两个函数: dump()dumps()

类似于tomliload()loads()dump()写入文件,dumps()写入字符串。

Python 3.11 中的新 tomllib 库不包括 dump() 和 dumps()

需要安装tomli_w

python -m pip install tomli_w

现在我们可以容易地将字典导出为TOML文档。

>>> import tomli_w
>>> config = {
...     "user": {
...         "player_x": {"symbol": "X", "color": "blue", "ai": True},
...         "player_o": {"symbol": "O", "color": "green", "ai": False},
...         "ai_skill": 0.85,
...     },
...     "board_size": 3,
...     "server": {"url": "https://tictactoe.example.com"},
... }

>>> print(tomli_w.dumps(config))
board_size = 3

[user]
ai_skill = 0.85

[user.player_x]
symbol = "X"
color = "blue"
ai = true

[user.player_o]
symbol = "O"
color = "green"
ai = false

[server]
url = "https://tictactoe.example.com"

可以使用 dump() 将配置写入文件:

>>> with open("tic-tac-toe-config.toml", mode="wb") as fp:
...     tomli_w.dump(config, fp)
...


创建新的TOML文件

在本节中,您将首先探索如何设置 TOML 文档的格式,以使其更易于用户使用。然后,您将尝试另一个名为 tomlkit 的库,您可以使用它来完全控制 TOML 文档。

格式和样式

通常,TOML 文件中会忽略空格。您可以利用这一点使配置文件井井有条、可读且直观。

此外, # 符号将该行的其余部分标记为注释。


从某种意义上说,TOML 文档没有样式指南,因为 PEP 8 是 Python 代码的样式指南。但是,该规范确实包含一些建议,同时保留了一些样式方面供您选择。


为了保持一致性,您可以在项目中使用像 Taplo 这样的格式化程序,并将其配置文件包含在版本控制中。您也可以将其集成到编辑器中。

tomlkit 从头开始创建 TOML

TOML Kit 最初是为 Poetry 项目构建的。作为依赖项管理的一部分,Poetry 会操作 pyproject.toml 该文件。但是,由于此文件用于多种用途,因此 Poetry 必须保留文件中的样式和注释。


首先通过pip安装tomlkit:

python -m pip install tomlkit

然后,我们确认tomlkit可以保留样式和注释:

>>> import tomlkit
>>> toml_data = """
... [nested]  # Not necessary
...
...     [nested.table]
...     string       = "Hello, TOML!"
...     weird_string = '''Literal
...         Multiline'''
... """
>>> print(tomlkit.dumps(tomlkit.loads(toml_data)))

[nested]  # Not necessary

    [nested.table]
    string       = "Hello, TOML!"
    weird_string = '''Literal
        Multiline'''

>>> tomlkit.dumps(tomlkit.loads(toml_data)) == toml_data
True

下面我们使用tomlkit创建一个新的TOML文件:

>>> from tomlkit import comment, document, nl, table

>>> toml = document()
>>> toml.add(comment("Written by TOML Kit"))
>>> toml.add(nl())
>>> toml.add("board_size", 3)

调用 document()创建一个 TOML 文档实例。然后,您可以使用 .add() 向此文档添加不同的对象,例如注释、换行符、键值对和表。


您可以使用 dump() 或 dumps() 如上所述 toml 转换为实际的 TOML 文档,也可以使用.as_string() 方法:

>>> print(toml.as_string())
# Written by TOML Kit

board_size = 3
>>> player_x = table()
>>> player_x.add("symbol", "X")
>>> player_x.add("color", "blue")
>>> player_x.comment("Start player")
>>> toml.add("player_x", player_x)

>>> player_o = table()
>>> player_o.update({"symbol": "O", "color": "green"})
>>> toml["player_o"] = player_o

您可以通过调用 table()创建表并向其添加内容。

可以通过.add()添加键和值,也可以使用 .update() 直接从字典添加键和值。

更新现有的TOML文件

将 TOML 表示为 tomlkit 对象

下面仔细研究一下如何用ttomlki表示 TOML 文档。

首先,创建tic-tac-toe-config.toml :

# tic-tac-toe-config.toml

board_size = 3

[user]
ai_skill = 0.85  # A number between 0 (random) and 1 (expert)

    [user.player_x]
    symbol = "X"
    color = "blue"
    ai = true

    [user.player_o]
    symbol = "O"
    color = "green"
    ai = false

# Settings used when deploying the application
[server]
url = "https://tictactoe.example.com"

打开 REPL 会话并使用以下命令 tomlkit 加载此文档:

>>> import tomlkit
>>> with open("tic-tac-toe-config.toml", mode="rt", encoding="utf-8") as fp:
...     config = tomlkit.load(fp)
...
>>> config
{'board_size': 3, 'user': {'ai_skill': 0.85, 'player_x': { ... }}}

>>> type(config)
<class 'tomlkit.toml_document.TOMLDocument'>

load() 用于从文件加载 TOML 文档。 config 看起来像一个字典。然而,深入挖掘,你会发现它是TOMLDocument 类型。

我们可以用[]访问:

>>> config["user"]["player_o"]["color"]
'green'

>>> type(config["user"]["player_o"]["color"])
<class 'tomlkit.items.String'>

>>> config["user"]["player_o"]["color"].upper()
'GREEN'

发现其中的值也是特殊的tomlkit数据类型。不过我们可以像普通的Python对象一样使用它们。例如,可以使用 .upper() 字符串方法。

特殊数据类型的一个优点是,它们允许您访问有关文档的元信息,包括注释和缩进:

>>> config["user"]["ai_skill"]
0.85

>>> config["user"]["ai_skill"].trivia.comment
'# A number between 0 (random) and 1 (expert)'

>>> config["user"]["player_x"].trivia.indent
'    '

如上所述,您通常可以将这些特殊对象视为原生 Python 对象。事实上,它们继承自相应的Python对象。但是,如果你真的需要,你可以用 .unwrap() 它们转换为普通的 Python:

>>> config["board_size"] ** 2
9

>>> isinstance(config["board_size"], int)
True

>>> config["board_size"].unwrap()
3

>>> type(config["board_size"].unwrap())
<class 'int'>

无损读取和写入 TOML

在本小节中,您将加载现有的 TOML 文件,并在将其写回磁盘之前对其进行一些更改。

首先加载您在上一小节中使用的相同 TOML 文件:

>>> import tomlkit
>>> with open("tic-tac-toe-config.toml", mode="rt", encoding="utf-8") as fp:
...     config = tomlkit.load(fp)
...

现在,你可以用.add()添加新元素,但无法用.add()更新现有key的值。

>>> config.add("app_name", "Tic-Tac-Toe")
{'board_size': 3, 'app_name': 'Tic-Tac-Toe', 'user': { ... }}

>>> config["user"].add("ai_skill", 0.6)
Traceback (most recent call last):
  ...
KeyAlreadyPresent: Key "ai_skill" already exists.

不过,我们可以像字典一样:

>>> config["user"]["ai_skill"] = 0.6
>>> print(config["user"].as_string())
ai_skill = 0.6  # A number between 0 (random) and 1 (expert)

    [user.player_x]
    symbol = "X"
    color = "blue"
    ai = true

    [user.player_o]
    symbol = "O"
    color = "green"
    ai = false

当您更新这样的值时, tomlkit 仍然会保留样式和注释。如您所见,关于 ai_skill 的注释保持不变。

部分 tomlkit 支持所谓的 Fluent 接口(链式调用)。在实践中,这意味着返回更新的对象

>>> from tomlkit import aot, comment, inline_table, nl, table
>>> player_data = [
...     {"user": "gah", "first_name": "Geir Arne", "last_name": "Hjelle"},
...     {"user": "tompw", "first_name": "Tom", "last_name": "Preston-Werner"},
... ]

>>> players = aot()
>>> for player in player_data:
...     players.append(
...         table()
...         .add("username", player["user"])
...         .add("name",
...             inline_table()
...             .add("first", player["first_name"])
...             .add("last", player["last_name"])
...         )
...     )
...
>>> config.add(nl()).add(comment("Players")).add("players", players)

完成对配置的更新后,现在可以将其写回同一文件:

>>> with open("tic-tac-toe-config.toml", mode="wt", encoding="utf-8") as fp:
...     tomlkit.dump(config, fp)

打开 tic-tac-toe-config.toml 并注意您的更新已包含在内。同时,保留了原有的风格。

总结

现在你已经了解TOML语法以及在Python中使用它的方式。当你需要一个配置文件时,推荐考虑使用TOML

相关文章
|
19小时前
|
索引 Python
Python的列表操作有哪些?
Python的列表操作非常丰富,包括列表的创建、元素的访问、修改、添加、删除、切片、排序等多个方面。
21 12
|
3天前
|
SQL 分布式计算 DataWorks
DataWorks操作报错合集之重新上传后只有SQL无法运行,而Python可以正常运行,是什么导致的
DataWorks是阿里云提供的一站式大数据开发与治理平台,支持数据集成、数据开发、数据服务、数据质量管理、数据安全管理等全流程数据处理。在使用DataWorks过程中,可能会遇到各种操作报错。以下是一些常见的报错情况及其可能的原因和解决方法。
|
8天前
|
Python
|
12天前
|
SQL 关系型数据库 MySQL
「Python入门」python操作MySQL和SqlServer
**摘要:** 了解如何使用Python的pymysql模块与MySQL数据库交互。首先,通过`pip install pymysql`安装模块。pymysql提供与MySQL的连接功能,例如创建数据库连接、执行SQL查询。在设置好MySQL环境后,使用`pymysql.connect()`建立连接,并通过游标执行SQL(如用户登录验证)。注意防止SQL注入,使用参数化查询。增删改操作需调用`conn.commit()`来保存更改。pymssql模块类似,但导入和连接对象创建略有不同。
15 0
「Python入门」python操作MySQL和SqlServer
|
17天前
|
API Python
Python学习日记(二:函数和逻辑操作)
Python中的函数和逻辑操作至关重要。函数包括可变和不可变参数。
|
20天前
|
SQL 分布式计算 DataWorks
DataWorks产品使用合集之对于Hologres的Python查询,该如何操作
DataWorks作为一站式的数据开发与治理平台,提供了从数据采集、清洗、开发、调度、服务化、质量监控到安全管理的全套解决方案,帮助企业构建高效、规范、安全的大数据处理体系。以下是对DataWorks产品使用合集的概述,涵盖数据处理的各个环节。
20 0
|
22天前
|
SQL Java 数据库连接
使用Python通过JDBC操作数据库(达梦数据库)
使用Python通过JDBC操作数据库(达梦数据库)
48 0
|
23天前
|
程序员 API 计算机视觉
技术经验解读:【python自动化】02.pywin32库自动操作键鼠(保姆级代码注释)
技术经验解读:【python自动化】02.pywin32库自动操作键鼠(保姆级代码注释)
17 0
|
24天前
python+Pycharm+selenium操作浏览器(Chorme或Edge)
python+Pycharm+selenium操作浏览器(Chorme或Edge)
34 1
|
25天前
|
jenkins 持续交付 API
使用Python操作Jenkins的过程详解
Python作为一种简洁、灵活且功能丰富的编程语言,可以与各种API轻松集成,Jenkins的API也不例外。借助于Python中的python-jenkins模块,我们可以轻松地编写脚本来连接到Jenkins服务器,并执行各种操作,如创建、删除、构建Jobs等。这种自动化的方式不仅提高了效率,还使得CI/CD流程更加灵活和可控。