Python3实现读取TOML配置文件
作者：曾阿伦
在 Python 项目开发中,配置管理是核心环节,TOML是一种专为配置文件设计的极简格式,相比ini/json/yaml具有语法清晰、支持注释和层级结构等优势,下面我们就来看看如何使用Python3实现读取TOML配置文件吧
前言
在 Python 项目开发中，配置管理是核心环节。传统的 ini 不支持复杂结构、json 无法写注释、yaml 缩进严格易报错，而 TOML 作为专为配置文件设计的格式，凭借语法清晰、支持注释、层级结构、类型安全等优势，成为 Python 项目的首选配置格式。
Python 3.11+ 已内置 TOML 解析器，低版本也可通过第三方库快速支持。
一、TOML 配置文件简介
TOML（Tom’s Obvious, Minimal Language）是极简、语义化的配置格式，核心优势：
- 语法和
ini相似，极易读写 - 支持单行注释（
#开头） - 天然支持层级结构（表 / 嵌套表）
- 支持字符串、数字、布尔、数组、时间等数据类型
- 无缩进依赖，不会因格式错误导致解析失败
- 被 Poetry、Pydantic、Rust 等主流工具 / 语言广泛采用
标准 TOML 示例：
# 项目通用配置 [project] name = "python-toml-demo" version = "1.0.0" debug = true port = 8000 # 数据库配置 [database] host = "127.0.0.1" port = 3306 username = "root" password = "root123" db_name = "test" timeout = 30 # 日志配置 [log] level = "INFO" file_path = "./logs/app.log" max_size = 10485760
二、Python 解析 TOML 的两种方式
1、Python 3.11+ 内置库
Python 3.11 及以上版本自带 ****tomllib，无需安装任何依赖：
import tomllib
2、低版本 Python（≤3.10）第三方库
低版本使用 toml 库，先安装：
pip install toml
import toml
本文以 Python 3.11+ 内置 tomllib 为主，同时兼容低版本写法。
三、Python3 读取 TOML 文件
1. 创建配置文件
在项目根目录新建 config.toml，写入测试配置：
# config.toml [app] name = "TOML测试项目" env = "development" port = 9000 [mysql] host = "localhost" user = "root" password = "123456" database = "demo"
2. 读取并解析 TOML
# read_toml_demo.py
import tomllib
# 1. 读取配置文件
with open("config.toml", "rb") as f:
config = tomllib.load(f)
# 2. 直接使用配置
print("项目名称：", config["app"]["name"])
print("运行环境：", config["app"]["env"])
print("MySQL 地址：", config["mysql"]["host"])
3. 运行结果
项目名称： TOML测试项目
运行环境： development
MySQL 地址： localhost
4. 低版本 Python 兼容写法
import toml
config = toml.load("config.toml")
print(config["app"]["name"])
四、支持所有 TOML 数据类型
TOML 支持丰富的数据类型，Python 可直接解析为对应类型：
TOML 配置
# 基本类型 str_val = "字符串" int_val = 100 float_val = 3.14 bool_val = true # 数组 array_val = [1, 2, 3, 4] # 层级表 [server] ip = "192.168.1.100" port = 8080
Python 读取
with open("config.toml", "rb") as f:
config = tomllib.load(f)
print(type(config["bool_val"])) # <class 'bool'>
print(type(config["array_val"])) # <class 'list'>
print(config["server"]["ip"]) # 192.168.1.100
五、全局配置工具类
封装一个配置类，实现：
- 全局唯一配置实例
- 自动加载配置
- 优雅获取配置项
- 异常捕获
完整封装代码
# config.py
import tomllib
from pathlib import Path
class TomlConfig:
"""TOML 配置文件管理类"""
_instance = None
_config = None
def __new__(cls, config_path="config.toml"):
if cls._instance is None:
cls._instance = super().__new__(cls)
cls._load_config(config_path)
return cls._instance
@classmethod
def _load_config(cls, config_path):
"""加载配置文件"""
path = Path(config_path)
if not path.exists():
raise FileNotFoundError(f"配置文件不存在：{config_path}")
try:
with open(path, "rb") as f:
cls._config = tomllib.load(f)
except tomllib.TOMLDecodeError as e:
raise ValueError(f"TOML 格式错误：{e}")
def get(self, key: str, default=None):
"""
获取配置（支持层级写法：app.name）
示例：get("app.port")
"""
keys = key.split(".")
data = self._config
for k in keys:
if isinstance(data, dict) and k in data:
data = data[k]
else:
return default
return data
# 初始化全局配置
config = TomlConfig()
使用方式
from config import config
# 直接获取配置
app_name = config.get("app.name")
mysql_host = config.get("mysql.host", "127.0.0.1") # 带默认值
print(app_name)
print(mysql_host)
六、常见问题与解决方案
1. 报错：ModuleNotFoundError: No module named 'tomllib'
原因：Python 版本 < 3.11
解决：安装第三方库
pip install toml
并将代码改为：
import toml
config = toml.load("config.toml")
2. 报错：TOMLDecodeError: Invalid statement
原因：TOML 语法错误（如字符串未加引号、括号不匹配）
解决：检查配置文件格式，TOML 字符串必须用双引号。
3. 如何读取多级嵌套 TOML？
TOML：
[redis.cluster.node1] host = "127.0.0.1" port = 6379
Python：
config.get("redis.cluster.node1.host")
到此这篇关于Python3实现读取TOML配置文件的文章就介绍到这了,更多相关Python读取TOML配置文件内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！