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垃圾回收机制

    谈谈python垃圾回收机制

    这篇文章主要介绍了python垃圾回收机制的相关资料,帮助大家更好的理解和使用python,感兴趣的朋友可以了解下
    2020-09-09
  • Python Json序列化与反序列化的示例

    Python Json序列化与反序列化的示例

    这篇文章主要介绍了Python Json序列化与反序列化的示例,小编觉得挺不错的,现在分享给大家,也给大家做个参考。一起跟随小编过来看看吧
    2018-01-01
  • Python基本文件操作实用指南

    Python基本文件操作实用指南

    文件操作是我们开发中必不可少的一项需求,下面这篇文章主要给大家介绍了关于Python基本文件操作的相关资料,文中通过实例代码介绍的非常详细,需要的朋友可以参考下
    2022-06-06
  • python实现定时同步本机与北京时间的方法

    python实现定时同步本机与北京时间的方法

    这篇文章主要介绍了python实现定时同步本机与北京时间的方法,涉及Python针对时间的操作技巧,具有一定参考借鉴价值,需要的朋友可以参考下
    2015-03-03
  • python3+PyQt5+Qt Designer实现界面可视化

    python3+PyQt5+Qt Designer实现界面可视化

    本文主要介绍了python3+PyQt5+Qt Designer实现界面可视化,Qt Designer,用鼠标拖拖就能完成窗体设计,感兴趣的可以了解一下
    2021-06-06
  • python实现Adapter模式实例代码

    python实现Adapter模式实例代码

    这篇文章主要介绍了python实现Adapter模式实例代码,分享了相关代码示例,小编觉得还是挺不错的,具有一定借鉴价值,需要的朋友可以参考下
    2018-02-02
  • Python的索引与切片原来该这样理解

    Python的索引与切片原来该这样理解

    这篇文章主要为大家详细介绍了Python的索引与切片,文中示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下,希望能够给你带来帮助
    2022-02-02
  • pandas使用QGraphicsView自动排列项目的实现

    pandas使用QGraphicsView自动排列项目的实现

    本文主要介绍了pandas使用QGraphicsView自动排列项目的实现,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2025-04-04
  • python 爬虫请求模块requests详解

    python 爬虫请求模块requests详解

    这篇文章主要介绍了python 爬虫请求模块requests详解,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
    2020-12-12
  • 云原生Docker部署Django和mysql项目全过程

    云原生Docker部署Django和mysql项目全过程

    最近在学习用docker部署Django项目,经过百折不挠的鼓捣,终于将项目部署成功,下面这篇文章主要给大家介绍了关于云原生Docker部署Django和mysql项目的相关资料,文中通过图文介绍的非常详细,需要的朋友可以参考下
    2022-12-12

最新评论