当前位置：首页 > news >正文

Python .toml 安装文件介绍

news 2025/8/2 12:35:23

在这篇文章中，让我们来详细地讲解一下 Python 生态中非常重要的 .toml 文件。

什么是 .toml 文件？

.toml 文件是一种用于配置的文件格式。它的全称是 TOML (Tom’s Obvious, Minimal Language)，即 “汤姆的（创始人）显而易见的、最小化的语言”。

核心目标：

人类易于阅读：它的语法非常直观，就像一个初始化（.ini）文件，但功能更强大。
易于解析：计算机程序可以轻松地将其内容解析成统一的数据结构（通常是字典或哈希表）。
无歧义：一种 TOML 文件格式应该只对应一种解析后的数据结构，避免了像 YAML 那样可能出现的歧义。

在 Python 生态中，.toml 文件变得越来越重要，特别是在 PEP 518 之后，它被选为 pyproject.toml 文件的格式，用于定义项目的构建依赖和配置信息。这正在逐渐取代旧的 setup.py, setup.cfg, 和 requirements.txt 的部分功能。

TOML 文件的主要组成部分

一个 TOML 文件由以下几个核心部分构成：

键值对 (Key-Value Pairs)
这是 TOML 最基本的单元，格式为 key = value。
- 键（key）在 = 的左边，值（value）在右边。
- 键名只能包含 ASCII 字母、数字、下划线和短横线 (A-Za-z0-9_-)。
注释 (Comments)
使用井号 # 来添加注释，从 # 开始到行尾都属于注释。
数据类型 (Data Types)
TOML 支持丰富且明确的数据类型：
- 字符串 (String):
  - 基本字符串：用双引号 " 包围。可以包含转义字符，如 \n, \t。
  - 多行基本字符串：用三个双引号 """ 包围。
  - 字面量字符串：用单引号 ' 包围，其中的内容不会被转义。
  - 多行字面量字符串：用三个单引号 ''' 包围。
- 整数 (Integer): 123, -10。可以用下划线 _ 提高可读性，如 1_000_000。
- 浮点数 (Float): 3.14, -0.01, 1e6。
- 布尔值 (Boolean): 只能是 true 或 false (全小写)。
- 日期时间 (Datetime): 格式遵循 RFC 3339 标准。
  - 带时区偏移的日期时间：1979-05-27T07:32:00Z
  - 本地日期时间：1979-05-27T00:32:00.999999
  - 本地日期：1979-05-27
  - 本地时间：00:32:00
- 数组 (Array): 用方括号 [] 包围，元素用逗号 , 分隔。元素可以是不同类型。
- 表 (Table) / 字典: 这是 TOML 用于组织数据的核心结构，相当于 Python 中的字典。
  - 标准表: 用方括号 [table_name] 定义。它下面的所有键值对都属于这个表。
  - 内联表 (Inline Table): 用花括号 {} 定义，用于简单的、单行的表。
  - 表数组 (Array of Tables): 用双重方括号 [[table_array_name]] 定义，用于表示一个对象列表，非常强大。

如何编写自己的 .toml 文件 (一个实际的例子)

假设我们要为一个应用程序创建一个配置文件 config.toml，用于管理数据库连接、API密钥和一些基本信息。

第一步：规划结构
我们希望配置包含：

应用的顶层信息（如名称、版本）。
数据库连接信息（主机、端口、用户名、密码）。
外部服务的 API 密钥。
一系列用户信息（每个用户有名字和角色）。

第二步：编写 config.toml 文件

# 这是一个示例 TOML 配置文件 (config.toml)# 1. 顶层键值对 (应用的元数据)
title = "我的超酷应用"
version = "1.0.2"
is_production = false # 使用布尔值控制环境# 2. [database] 表 - 用于组织数据库相关配置
# 这会解析成一个名为 'database' 的字典
[database]
server_ip = "192.168.1.1"
ports = [ 8001, 8002, 8003 ] # 这是一个整数数组
connection_max = 5000
enabled = true
data = [ ["delta", "phi"], [3.14] ] # 数组中可以包含数组# 使用点语法创建嵌套表 (等同于 Python 的嵌套字典)
# 这会创建 database = { user = { ... } }
[database.user]
username = "admin"
password = "a_secret_password" # 最好从环境变量读取，这里仅作演示# 3. [api_keys] 表 - 用于存放 API 密钥
[api_keys]
google_maps = "YOUR_GOOGLE_MAPS_API_KEY"
# 使用字面量字符串，避免特殊字符被转义
aws_s3_path = 's3://my-bucket/data/raw/'# 4. [[users]] 表数组 - 用于定义一个用户列表
# 每出现一次 [[users]]，就会在 'users' 数组中添加一个新对象（字典）
[[users]]
name = "Alice"
email = "alice@example.com"
roles = ["admin", "editor"][[users]]
name = "Bob"
email = "bob@example.com"
roles = ["viewer"]# 5. 内联表示例
# 适用于简单、单行的表结构
owner = { name = "Tom Preston-Werner", dob = 1979-05-27T07:32:00Z }

如何在 Python 中使用 .toml 文件

从 Python 3.11 开始，标准库中内置了 tomllib 模块，可以直接解析 TOML 文件。

对于 Python 3.11+:

import tomllib  # 内置库，无需安装# 读取并解析 config.toml 文件
try:with open("config.toml", "rb") as f: # 注意要用二进制模式 "rb" 打开config = tomllib.load(f)
except FileNotFoundError:print("错误：找不到 config.toml 文件！")config = {}# 访问配置数据
if config:print(f"应用标题: {config['title']}")print(f"数据库服务器IP: {config['database']['server_ip']}")print(f"数据库用户名: {config['database']['user']['username']}")# 访问表数组print("\n所有用户信息:")for user in config['users']:print(f"  - 用户名: {user['name']}, 角色: {', '.join(user['roles'])}")# 访问内联表print(f"\n项目所有者: {config['owner']['name']}")

对于 Python < 3.11:

你需要安装一个第三方库，最推荐的是 tomli（tomllib 就是基于它开发的）。

安装 tomli:
```
pip install tomli
```

使用 tomli:
代码和 tomllib 几乎完全一样，只是导入的模块名不同。

import tomli # 使用第三方库 tomlitry:with open("config.toml", "rb") as f:config = tomli.load(f)
except FileNotFoundError:print("错误：找不到 config.toml 文件！")config = {}# 后续代码与上面的例子完全相同
# ...