Python TOML

在本教程中，我们将学习 TOML，即 Tom 的明显最小语言。它是一种相当新的配置文件格式，被 Python 社区广泛使用。我们将讨论 TOML 的语法，使用 tomli 和 tomllib 解析 TOML 文档，并使用 tomli_w 将数据结构写入为 TOML。

将 TOML 用作配置格式

TOML，即 Tom's Obvious Minimal Language（Tom 的明显最小语言），是一种以其创建者 Tom Preston-Werner 命名的配置文件格式。其设计目标是创建一种可以轻松解析为各种编程语言数据结构的格式。

配置和配置文件

配置在几乎每个应用程序或系统中都扮演着至关重要的角色，它可以在不修改源代码的情况下灵活地修改设置和行为。配置用于各种场景，例如指定连接到数据库或云存储等外部服务的基本详细信息。此外，配置设置有助于自定义项目中的用户体验，使S用户能够根据自己的偏好调整应用程序。

在项目中使用配置文件有几个好处，包括将代码与其设置分离。它促使您仔细识别系统的哪些方面应该真正可配置，提供一种为在源代码中会被认为是“魔法”的值分配有意义名称的方法。现在，让我们考虑在一个假想的井字游戏中使用配置文件。

配置文件

虽然标准的井字游戏传统上是在三乘三的网格上玩的，但棋盘尺寸的可配置性是不确定的。现有的逻辑可能与不同的棋盘尺寸不兼容。然而，将棋盘尺寸值包含在配置文件中仍然是有益的。这种方法有两个目的：为该值提供一个有意义的名称并使其可见，即使它在标准游戏中保持不变。

项目 URL 在部署应用程序时至关重要。虽然它对于普通用户来说可能不会改变，但高级用户可能需要能够在不同的服务器上重新部署游戏。

为了提供清晰度并适应不同的用例，相应地组织配置文件可能是有益的。一种流行的方法是将配置分成多个文件，每个文件处理一个不同的问题。或者，您可以将相关的配置值组合在一起以便更好地组织。以下是您的假想配置文件可能的一种重组方式

根据操作系统和具体要求，存在多种指定配置的方法。例如，Windows 传统上使用 INI 文件，这与前面提供的配置文件示例相似。在 Unix 系统上，通常使用纯文本配置文件，尽管具体格式可能因不同的服务而异。无论格式如何，通常都强调保持可读性和简单性，以便于理解和修改。

随着时间的推移，越来越多的应用程序采用定义明确的格式，如 XML、JSON 或 YAML，以满足其配置要求。这些格式最初是作为数据交换或序列化格式开发的，主要用于计算机通信目的。然而，由于它们的结构化特性和在各种编程语言中的广泛支持，它们也已用于表示配置设置。它们的采用简化了不同系统和编程语言之间的解析、操作和互操作性，使其成为配置文件格式的流行选择。

TOML - Tom 的明显最小语言

TOML 是一种相对较新的格式，其最初的规范（版本 0.1.0）于 2013 年发布。从一开始，TOML 就优先考虑成为一种最小且人类可读的配置文件格式。TOML 网站上概述的目标如下：

“TOML 旨在成为一种最小的配置文件格式，由于其明显的语义而易于阅读。TOML 旨在明确映射到哈希表。TOML 应该易于解析为各种语言的数据结构。（来源，强调已添加）”

让我们在 TOML 中定义上述文件。

TOML 在其语法上借鉴了传统配置文件。然而，它相对于 Windows INI 文件和 UNIX 配置文件的显著优势在于其定义明确的规范。与它的对应物不同，TOML 有一个全面的规范，精确地概述了 TOML 文档中允许的元素，并提供了关于如何解释不同值的清晰指南。该规范已经演变并达到了稳定和成熟，最终在 2021 年初发布了 1.0.0 版本。

与 TOML 相反，INI 格式缺乏正式规范。相反，它由许多变体和方言组成，通常由特定的实现定义。例如，Python 通过 ConfigParser 在其标准库中包含了对读取 INI 文件的支持。尽管 ConfigParser 相当灵活，但它可能不支持所有 INI 文件变体。

TOML 与许多传统格式的另一个显著区别是 TOML 为其值分配了类型。在提供的示例中，“blue”被解释为字符串，而 3 被视为数字。对 TOML 的一个潜在批评是，人类作者在编写 TOML 文档时需要注意这些类型。在更简单的格式中，这种责任通常由解析配置文件的程序员来处理

TOML 模式验证

目前，TOML 不包含允许在 TOML 文档中指定必需和可选字段的模式语言。已经提出了各种添加此功能的提案，但目前尚不确定其中任何一个是否会在不久的将来被接受和实施。

在处理更复杂的 TOML 文档时，仅依靠 TOML 格式的方法可能无法有效扩展。此外，如果目标是提供信息丰富的错误消息，则需要额外的努力。一个更好的替代方案是利用 pydantic 等库，它利用类型注解在运行时执行数据验证。通过使用 pydantic，可以受益于其精确且有用的内置错误消息。这种方法不仅简化了数据验证，还增强了处理 TOML 配置的可伸缩性和可用性。

更多关于 TOML：键值对

TOML 以键值格式存储值。TOML 值具有不同的类型。一个值必须是以下类型之一。

• String
• Integer
• Float
• Boolean
• 带偏移量的日期时间
• 本地日期
• 本地时间
• Array
• 内联表

注意 - TOML 采用与 Python 相同的注释语法。通过使用哈希符号 (#)，您可以将一行的其余部分指定为注释。在配置文件中引入注释的目的是增强清晰度并方便您自己和您的用户理解。

键值对是 TOML 文档中的基本构建块。我们使用 key=value 语法提及它们，其中键与值用等号分隔。以下是带有一个键值对的 TOML 文档示例。

在 TOML 中，键始终被解释为字符串，无论它们是否被引号括起来。让我们考虑以下示例来说明这一点。

在 TOML 中，像“12”这样的键是有效的，但它将被解释为字符串而不是数字。通常，建议尽可能使用裸键。裸键由 ASCII 字母、数字、下划线和连字符组成。这些键可以不加引号书写，如前面提供的示例所示。通过使用裸键，您可以提高 TOML 配置文件的可读性和简单性。

TOML 文档必须采用 UTF-8 Unicode 编码，为表示值提供了极大的灵活性。虽然裸键存在限制，但在定义键时仍然可以使用 Unicode 字符。但是，使用 Unicode 键需要将其括在引号中。需要注意的是，使用 Unicode 键需要额外的引号来分隔它们。

在 TOML 中，点（.）在键中使用时具有特定的含义。虽然您可以在未加引号的键中包含点，但这样做会导致值的分组。带点的键将在每个点处拆分，从而在数据结构中创建嵌套分组。让我们考虑以下示例来说明这种行为。

在给定的示例中，有两个包含点的键。由于这两个键都以“match_x”开头，它们将分组在名为“match_x”的部分下。“symbol”和“color”键将嵌套在此部分中，从而实现相关数据的结构化组织。

字符串、数字和布尔值

TOML 使用与 Python 相似的数据类型。唯一的区别是布尔值为小写：true 和 false。在 TOML 中，通常使用双引号 (") 来定义字符串。在字符串中，您可以使用反斜杠来转义特殊字符。例如，“\u03c0 is less than four”包含转义序列 \u03c0，它表示 Unicode 字符码点 U+03c0，对应于希腊字母 π。解释时，此字符串将呈现为“π is less than four”。

在 TOML 中，另一种指定字符串的方法是使用单引号 (')。这些单引号字符串被称为字面字符串，其行为类似于 Python 中的原始字符串。在字面字符串中，不转义或解释任何字符，这意味着 '\u03c0 is the Unicode codepoint of π' 会将初始字符 '\u03c0' 视为字面值，而不是将其解释为 Unicode 转义序列。