如何在Python中处理TOML文件

TOML（Tom’s Obvious Minimal Language）已成为Python项目中配置文件的现代标准。它比INI文件更具表现力，比JSON或YAML更简洁。

自Python 3.11起，标准库包含了用于读取和解析TOML文件的tomllib模块。TOML相比其他配置格式具有多个优势。它支持复杂数据类型（如数组和嵌套表），同时保持人类可读性。许多Python项目，包括Poetry和setuptools，都使用pyproject.toml进行配置。

在本教程中，我们将学习如何在Python中解析TOML文件。

🔗 代码在GitHub上。

先决条件

要跟随本教程，您需要：

Python 3.11或更高版本：tomllib模块从Python 3.11开始成为标准库的一部分
基础Python知识：熟悉字典、文件I/O和基本语法
文本编辑器或IDE：用于创建和编辑TOML和Python文件的任何编辑器

理解TOML格式

TOML文件将数据组织成表（类似于INI部分），但具有更强大的功能。让我们创建一个示例配置来理解语法。

创建config.toml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


# 应用程序配置
title = "My Application"
version = "1.0.0"

[database]
host = "localhost"
port = 5432
username = "app_user"
password = "secure_password"
databases = ["myapp_db", "myapp_cache"]
pool_size = 10
ssl_enabled = true

[server]
host = "0.0.0.0"
port = 8000
debug = false
allowed_hosts = ["localhost", "127.0.0.1", "example.com"]

[logging]
level = "INFO"
format = "%(asctime)s - %(levelname)s - %(message)s"
handlers = ["console", "file"]

[cache]
enabled = true
ttl = 3600
max_size = 1000

[features]
enable_api = true
enable_webhooks = false
rate_limit = 100

此TOML文件展示了关键特性：简单的键值对、表（括号中的部分）、数组（方括号中的逗号分隔值）以及不同的数据类型，包括字符串、整数、布尔值和数组。

如何使用tomllib读取TOML文件

tomllib模块从版本3.11开始成为Python标准库的一部分。它提供了一个简单的接口来加载TOML文件，如下所示：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


import tomllib

with open('config.toml', 'rb') as f:
    config = tomllib.load(f)

# 访问值
app_title = config['title']
db_host = config['database']['host']
db_port = config['database']['port']

print(f"Application: {app_title}")
print(f"Database: {db_host}:{db_port}")
print(f"Config keys: {config.keys()}")

输出：

1
2
3


Application: My Application
Database: localhost:5432
Config keys: dict_keys(['title', 'version', 'database', 'server', 'logging', 'cache', 'features'])

请注意，tomllib需要以二进制模式（‘rb’）打开文件。load()函数解析TOML文件并返回一个常规的Python字典。

值会自动转换为适当的Python类型：字符串保持为字符串，整数变为int，布尔值变为True/False，数组变为列表。接下来，让我们更仔细地看看如何处理不同的数据类型。

如何处理TOML数据类型

TOML的类型系统清晰地映射到Python的内置类型。以下是处理不同值类型的方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


import tomllib

with open('config.toml', 'rb') as f:
    config = tomllib.load(f)

# 字符串
app_title = config['title']

# 整数
db_port = config['database']['port']
cache_ttl = config['cache']['ttl']

# 布尔值
debug_mode = config['server']['debug']
cache_enabled = config['cache']['enabled']

# 数组（变为Python列表）
databases = config['database']['databases']
allowed_hosts = config['server']['allowed_hosts']

print(f"Databases: {databases}")
print(f"Type of databases: {type(databases)}")
print(f"Debug mode: {debug_mode}, type: {type(debug_mode)}")

使用tomllib，您不需要像ConfigParser那样的特殊getter方法。返回的字典包含正确类型的Python对象，可以直接使用，如下所示：

1
2
3


Databases: ['myapp_db', 'myapp_cache']
Type of databases: <class 'list'>
Debug mode: False, type: <class 'bool'>

如何构建TOML配置管理器

对于生产应用程序，将TOML加载包装在配置类中可提供更好的错误处理和验证。以下是您可以做到的方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


import tomllib
from pathlib import Path

class TOMLConfig:
    def __init__(self, config_file='config.toml'):
        self.config_file = Path(config_file)

        if not self.config_file.exists():
            raise FileNotFoundError(f"Config file not found: {config_file}")

        with open(self.config_file, 'rb') as f:
            self.config = tomllib.load(f)

    def get(self, key, default=None):
        """获取顶级配置值"""
        return self.config.get(key, default)

    def get_section(self, section):
        """获取整个配置部分"""
        if section not in self.config:
            raise ValueError(f"Section '{section}' not found")
        return self.config[section]

您可以这样使用TOMLConfig类：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


config = TOMLConfig('config.toml')

# 获取顶级值
app_title = config.get('title')
version = config.get('version')

# 获取整个部分
db_config = config.get_section('database')
server_config = config.get_section('server')

print(f"{app_title} v{version}")
print(f"Database config: {db_config}")

此配置类为您的TOML文件提供了一个干净的接口。它在尝试解析之前验证文件是否存在，并提供了安全访问配置值的方法。

运行上述代码会得到以下输出：

1
2


My Application v1.0.0
Database config: {'host': 'localhost', 'port': 5432, 'username': 'app_user', 'password': 'secure_password', 'databases': ['myapp_db', 'myapp_cache'], 'pool_size': 10, 'ssl_enabled': True}

如何安全处理缺失值

您的代码需要优雅地处理缺失的配置。以下是如何提供默认值和验证必需值的方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


import tomllib

def load_config_safe(config_file='config.toml'):
    try:
        with open(config_file, 'rb') as f:
            return tomllib.load(f)
    except FileNotFoundError:
        print(f"Config file {config_file} not found, using defaults")
        return {}
    except tomllib.TOMLDecodeError as e:
        print(f"Error parsing TOML: {e}")
        raise

config = load_config_safe('config.toml')

# 使用默认值获取
db_host = config.get('database', {}).get('host', 'localhost')
db_port = config.get('database', {}).get('port', 5432)
debug = config.get('server', {}).get('debug', False)

print(f"Database: {db_host}:{db_port}")
print(f"Debug: {debug}")

输出：

1
2


Database: localhost:5432
Debug: False

此模式使用带有默认值的链式.get()调用。如果某个部分或键不存在，您将获得默认值而不是KeyError。

结论

在Python中处理TOML文件时，请遵循以下准则：

始终以二进制模式打开：tomllib模块在打开文件时需要二进制模式（‘rb’）
使用嵌套表进行组织：利用TOML嵌套表的能力来处理复杂配置
为可选设置提供默认值：使用带有默认值的.get()使您的应用程序更加灵活

考虑在新项目中使用TOML。如果您从头开始，TOML是Python配置的绝佳选择。编码愉快！

Python中TOML文件操作完全指南

本文详细介绍如何在Python中处理TOML配置文件，包括使用tomllib模块读取解析文件、处理不同数据类型、构建配置管理类以及安全处理缺失值的方法。