Python3实现读取TOML配置文件

 更新时间:2026年05月22日 08:24:00   作者:曾阿伦  
在 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配置文件内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

相关文章

  • 基于python的Tkinter编写登陆注册界面

    基于python的Tkinter编写登陆注册界面

    这篇文章主要为大家详细介绍了基于python的Tkinter编写登陆注册界面,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2017-06-06
  • 详解修改Anaconda中的Jupyter Notebook默认工作路径的三种方式

    详解修改Anaconda中的Jupyter Notebook默认工作路径的三种方式

    这篇文章主要介绍了详解修改Anaconda中的Jupyter Notebook默认工作路径的三种方式,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2021-01-01
  • Python Flask 搭建微信小程序后台详解

    Python Flask 搭建微信小程序后台详解

    这篇文章主要介绍了Python Flask 搭建微信小程序后台,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2019-05-05
  • python简单区块链模拟详解

    python简单区块链模拟详解

    这篇文章主要介绍了python简单区块链模拟详解,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
    2019-07-07
  • 对python3中pathlib库的Path类的使用详解

    对python3中pathlib库的Path类的使用详解

    今天小编就为大家分享一篇对python3中pathlib库的Path类的使用详解,具有很好的参考价值,希望对大家有所帮助。一起跟随小编过来看看吧
    2018-10-10
  • Python3使用tracemalloc实现追踪mmap内存变化

    Python3使用tracemalloc实现追踪mmap内存变化

    这篇文章主要为大家详细介绍了在Python3中如何使用tracemalloc实现追踪mmap内存变化,文中的示例代码讲解详细,感兴趣的可以了解一下
    2023-03-03
  • Python3 常用数据标准化方法详解

    Python3 常用数据标准化方法详解

    这篇文章主要介绍了Python3 常用数据标准化方法详解,具有很好的参考价值,希望对大家有所帮助。一起跟随小编过来看看吧
    2021-03-03
  • python解析xml文件实例分享

    python解析xml文件实例分享

    这篇文章主要介绍了python解析XML文件的方法,大家参考使用吧
    2013-12-12
  • matplotlib.subplot()画子图并共享y坐标轴的方法

    matplotlib.subplot()画子图并共享y坐标轴的方法

    Matplotlib的可以把很多张图画到一个显示界面,本文主要介绍matplotlib.subplot()画子图并共享y坐标轴的方法,需要的朋友们下面随着小编来一起学习学习吧
    2021-05-05
  • Python利用正则表达式从字符串提取数字

    Python利用正则表达式从字符串提取数字

    正则表达式是一个特殊的字符序列,它能帮助你方便的检查一个字符串是否与某种模式匹配,下面这篇文章主要给大家介绍了关于Python利用正则表达式从字符串提取数字的相关资料,需要的朋友可以参考下
    2022-02-02

最新评论