Python 项目里经常会出现 pyproject.toml、ruff.toml、config.toml。它们的文件名不同,但都使用 TOML 语法。
pyproject.toml
ruff.toml
config.toml
TOML 是一种配置文件格式。它的目标把一组有相对比较复杂的数据保存下来,让程序或开发工具读取。例如,一个 FastAPI 服务可能需要这些配置:
1[app] 2name = "FastAPI LangChain" 3debug = true 4 5[server] 6host = "127.0.0.1" 7port = 8000
从人的视角看,这份文件分成了应用和服务器两组配置;从 Python 的视角看,它最终会变成一层层字典:
01{ 02 "app": { 03 "name": "FastAPI LangChain", 04 "debug": True, 05 }, 06 "server": { 07 "host": "127.0.0.1", 08 "port": 8000, 09 }, 10}
因此,学习 TOML 时可以始终抓住一个核心:TOML 正在描述一棵由键、值、字典和列表组成的数据结构。
首先,我们要了解的是项目是如何读取 .toml 配置文件的
.toml
[project]
[tool.fastapi]
fastapi dev
fastapi run
tomllib
默认的 fastapi 项目中,有一个叫做 pyproject.toml 的配置文件:
fastapi
1[tool.fastapi] 2entrypoint = "app.main:app"
当我们执行下面的命令时,FastAPI CLI 会读取这段配置,找到 app/main.py 导出的 app 对象:
app/main.py
app
1uv run fastapi dev
至于 .env 配置,我们之前已经在 app/core/config.py 中接入了 .env:
.env
app/core/config.py
01from functools import lru_cache 02 03from pydantic_settings import BaseSettings, SettingsConfigDict 04 05 06class Settings(BaseSettings): 07 model_config = SettingsConfigDict( 08 env_file=".env", 09 env_file_encoding="utf-8", 10 extra="ignore", 11 ) 12 13 app_name: str = "FastAPI LangChain" 14 deepseek_model: str = "deepseek-v4-flash" 15 16 17@lru_cache 18def get_settings() -> Settings: 19 return Settings()
这里不是 FastAPI 自动读取 .env,而是创建 Settings() 时,Pydantic Settings 根据 env_file 读取文件并校验字段。@lru_cache 让同一进程复用配置对象,避免每个请求都重新读取。
Settings()
env_file
@lru_cache
如果我们新增一个位于项目根目录的 config.toml,最直接的接入方式是标准库 tomllib:
01from pathlib import Path 02from typing import Any 03import tomllib 04 05PROJECT_ROOT = Path(__file__).resolve().parents[2] 06CONFIG_PATH = PROJECT_ROOT / "config.toml" 07 08 09def load_config() -> dict[str, Any]: 10 with CONFIG_PATH.open("rb") as file: 11 return tomllib.load(file)
然后在创建应用时主动调用它:
01from fastapi import FastAPI 02 03from app.core.config_loader import load_config 04 05config = load_config() 06app_config = config["app"] 07 08app = FastAPI( 09 title=app_config["name"], 10 debug=app_config["debug"], 11)
这段代码能说明读取过程,但直接操作多层字典不适合大型项目。后面的“应用配置”和“环境”两篇会把 TOML 接入 Pydantic Settings:由 TomlConfigSettingsSource 负责读取,再由 Pydantic 校验字段和类型。它仍然需要我们显式配置,只是不必自己维护解析和类型转换逻辑。
TomlConfigSettingsSource
tomllib 从 Python 3.11 开始进入标准库。原文的本机项目使用 Python 3.13,可以直接导入,无需安装依赖;在线实验的浏览器解释器由共享 Pyodide 提供,下载实验项目的最低版本为 Python 3.12,同样支持 tomllib。Python 3.13 的 tomllib 解析 TOML 1.0.0,读取文件时必须使用二进制模式 rb。仍在使用 Python 3.10 的项目可以安装兼容包 tomli,但当前项目不需要。
rb
tomli
读取已经在内存中的 TOML 字符串时,使用 loads():
loads()
1import tomllib 2 3content = """ 4[server] 5port = 8000 6""" 7 8config = tomllib.loads(content) 9print(config["server"]["port"])
load() 接收文件对象,loads() 接收字符串,这与 json.load() 和 json.loads() 的区别相似。
load()
json.load()
json.loads()
解析失败时,tomllib 会抛出 TOMLDecodeError:
TOMLDecodeError
01from pathlib import Path 02from typing import Any 03import tomllib 04 05 06def load_config(path: Path) -> dict[str, Any]: 07 try: 08 with path.open("rb") as file: 09 return tomllib.load(file) 10 except FileNotFoundError as error: 11 raise RuntimeError(f"配置文件不存在:{path}") from error 12 except tomllib.TOMLDecodeError as error: 13 raise RuntimeError(f"TOML 语法错误:{error}") from error
标准库 tomllib 只负责读取,不提供写入功能。需要生成 TOML 时可以使用 tomli-w;需要在修改文件时保留注释和排版,可以使用 tomlkit。FastAPI 服务通常在启动时读取配置,而不是在运行过程中反复改写配置文件,所以只读能力已经覆盖大多数场景。
tomli-w
tomlkit
TOML 最基本的写法是 键 = 值。等号左侧是配置名称,右侧是配置内容:
键 = 值
1title = "FastAPI LangChain" 2port = 8000 3temperature = 0.7 4debug = false
键名区分大小写。model 和 MODEL 是两个不同的键,不建议在同一个项目中混用大小写风格。
model
MODEL
不加引号的键只能使用英文字母、数字、下划线和连字符。键名包含空格、点号等特殊字符时,需要加引号:
1model_name = "deepseek-v4-flash" 2"request timeout" = 30 3"api.example.com" = "enabled"
引号只是键名语法的一部分。"api.example.com" 是一个完整键;不加引号的 api.example.com 则是点号键,会创建嵌套结构。
"api.example.com"
api.example.com
常用值可以对应到下面这些 Python 类型:
model = "deepseek-v4-flash"
str
port = 8000
int
temperature = 0.7
float
debug = true
bool
released_at = 2026-08-27T10:30:00Z
datetime
release_date = 2026-08-27
date
start_at = 10:30:00
time
origins = ["http://localhost:3019"]
list
[server]
dict
字符串
双引号字符串支持 \n、\t 等转义字符;单引号字符串更接近「原样保存」,适合正则表达式或 Windows 路径:
\n
\t
1message = "第一行\n第二行" 2pattern = '^/api/v1/' 3windows_path = 'C:\projects\fastapi-langchain'
多行文本可以使用三个双引号或三个单引号。配置中只有确实存在较长文本时才需要这样做,普通模型名称、URL 和文件路径使用单行字符串更容易阅读。
数字与布尔值
整数和浮点数不加引号。加上引号后,它们就会变成字符串:
1port = 8000 2port_text = "8000" 3temperature = 0.7 4enabled = true
TOML 的布尔值只能写成小写的 true 或 false。True、FALSE、yes 都不是合法布尔值。
true
false
True
FALSE
yes
TOML 没有 null。一个字段如果没有值,通常有三种处理方式:不写该字段、提供明确默认值,或者使用业务约定的空字符串。不要写成 api_key = null,解析器会直接报错。
null
api_key = null
数组用方括号表示,元素之间使用逗号分隔:
1allow_methods = ["GET", "POST", "OPTIONS"] 2retry_delays = [0.5, 1.0, 2.0]
数组可以分成多行,并允许最后一个元素后保留逗号。这种写法更适合依赖列表和较长的域名列表:
1allow_origins = [ 2 "http://localhost:3019", 3 "https://langchainpy.usehook.cn", 4]
TOML 1.0 允许数组包含不同类型,但应用配置中通常不建议这样做。保持同一个数组元素类型一致,更容易交给 Pydantic 校验,也更方便读者理解字段含义。
表使用 [名称] 声明。它相当于 Python 字典中的一层键:
[名称]
1[server] 2host = "127.0.0.1" 3port = 8000 4 5[server.cors] 6allow_credentials = false 7allow_origins = ["http://localhost:3019"]
解析后,cors 会成为 server 下面的子字典:
cors
server
01{ 02 "server": { 03 "host": "127.0.0.1", 04 "port": 8000, 05 "cors": { 06 "allow_credentials": False, 07 "allow_origins": ["http://localhost:3019"], 08 }, 09 }, 10}
点号键也可以创建嵌套结构:
1server.host = "127.0.0.1" 2server.port = 8000
它与 [server] 表达的结果相同,但一个文件中最好采用一致的组织方式。配置较多时,使用表通常更清晰。
内联表
少量、紧密相关的数据可以写成内联表:
1database = { host = "localhost", port = 5432, name = "agent" }
内联表必须在一行内写完,也不能在末尾保留多余逗号。如果内容开始变长,应改成普通表。
表数组
双层方括号 [[...]] 表示「由多个表组成的数组」。例如配置多个模型:
[[...]]
1[[models]] 2name = "deepseek-v4-flash" 3provider = "openai" 4 5[[models]] 6name = "deepseek-v4-pro" 7provider = "openai"
解析结果是一个字典,其中 models 对应一个列表,列表中的每一项都是字典。这种结构适合真正需要配置多份同类对象的场景。如果应用永远只使用一个默认模型,普通的 [model] 表更简单。
models
[model]
TOML、JSON、YAML 和 .env 都能保存配置,但它们解决的问题并不完全相同:
在我们的 FastAPI + LangChain 项目中,会采用这样的分工:
uv.lock
配置格式不是越统一越好。把 API Key 写入 pyproject.toml,或把几十项嵌套配置压成 .env 字符串,都会让职责变得更混乱。
初学 TOML 时,最常见的错误不是字段含义,而是把其他格式的习惯带进来。
重复定义
同一个键或表不能定义两次:
1# 错误示例 2[server] 3port = 8000 4 5[server] 6host = "127.0.0.1"
应把字段写进同一个 [server] 中。
缺少引号
普通字符串必须加引号:
1# 错误示例 2model = deepseek-v4-flash
deepseek-v4-flash 不是数字、布尔值或日期,解析器无法判断它是什么。
deepseek-v4-flash
错误注释
TOML 只使用 # 注释,不使用 JavaScript 的 //:
#
//
1# 这是合法注释 2port = 8000 # 行尾也可以注释
路径与当前目录
Path("config.toml") 是相对于进程当前工作目录,而不是相对于 config.py 文件。开发环境从项目根目录启动时可能正常,测试或部署切换工作目录后就可能找不到文件。后续文章会使用明确的项目根路径解决这个问题。
Path("config.toml")
config.py
配置不是自动生效的
即使 TOML 能成功解析,拼错字段名也不一定立即报错。直接读取字典时,错误可能一直拖到业务代码访问该字段才出现。生产项目应使用 Pydantic 模型校验配置的字段、类型和范围。
从项目中的 lesson.toml 读取真实配置,观察整数、布尔值、日期和表数组分别变成什么 Python 对象。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
1from fastapi import FastAPI 2 3from toml_basics import router 4 5app = FastAPI(title="TOML 基础") 6app.include_router(router) 7
01from pathlib import Path 02import tomllib 03 04from fastapi import APIRouter, HTTPException 05from fastapi.encoders import jsonable_encoder 06 07router = APIRouter() 08 09@router.get("/config") 10async def config() -> dict[str, object]: 11 path = Path(__file__).with_name("lesson.toml") 12 try: 13 with path.open("rb") as file: 14 data = tomllib.load(file) 15 except (FileNotFoundError, tomllib.TOMLDecodeError) as error: 16 raise HTTPException(status_code=400, detail=str(error)) from error 17 return {"data": jsonable_encoder(data), 18 "types": {name: type(value).__name__ for name, value in data.items()}, 19 "port_type": type(data["server"]["port"]).__name__} 20
01title = "FastAPI LangChain" 02debug = true 03released_at = 2026-08-27 04 05[server] 06host = "127.0.0.1" 07port = 8000 08 09[[models]] 10name = "teaching-model-a" 11provider = "example" 12 13[[models]] 14name = "teaching-model-b" 15provider = "example" 16
打开在线案例,点击运行,等待环境就绪,再发送默认 GET /config。本篇不需要模型密钥或外部服务。
GET /config
port_type 为 int,types 中 debug 为 bool、released_at 为 date、models 为 list。JSON 响应里的日期显示为 ISO 字符串,这是输出时的转换,不是 tomllib 把日期解析成了字符串。
修改 lesson.toml 后重新运行,再发送请求。把整数写成引号包裹的字符串,会改变对应 Python 类型;重复定义表、写入 null 或不合法布尔值会得到 400。这里每次请求读文件便于观察,真实应用通常在启动时读取一次。
下载项目后,在项目目录执行:
1uv run fastapi dev main.py
再通过 http://127.0.0.1:8000/docs 发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。
http://127.0.0.1:8000/docs
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. TOML
Python 项目里经常会出现
pyproject.toml、ruff.toml、config.toml。它们的文件名不同,但都使用 TOML 语法。TOML 是一种配置文件格式。它的目标把一组有相对比较复杂的数据保存下来,让程序或开发工具读取。例如,一个 FastAPI 服务可能需要这些配置:
从人的视角看,这份文件分成了应用和服务器两组配置;从 Python 的视角看,它最终会变成一层层字典:
因此,学习 TOML 时可以始终抓住一个核心:TOML 正在描述一棵由键、值、字典和列表组成的数据结构。
2. 读取
首先,我们要了解的是项目是如何读取
.toml配置文件的pyproject.toml中的[project]pyproject.toml中的[tool.fastapi]fastapi dev或fastapi run时读取config.tomltomllib或配置库显式接入默认的
fastapi项目中,有一个叫做pyproject.toml的配置文件:当我们执行下面的命令时,FastAPI CLI 会读取这段配置,找到
app/main.py导出的app对象:至于
.env配置,我们之前已经在app/core/config.py中接入了.env:这里不是 FastAPI 自动读取
.env,而是创建Settings()时,Pydantic Settings 根据env_file读取文件并校验字段。@lru_cache让同一进程复用配置对象,避免每个请求都重新读取。如果我们新增一个位于项目根目录的
config.toml,最直接的接入方式是标准库tomllib:然后在创建应用时主动调用它:
这段代码能说明读取过程,但直接操作多层字典不适合大型项目。后面的“应用配置”和“环境”两篇会把 TOML 接入 Pydantic Settings:由
TomlConfigSettingsSource负责读取,再由 Pydantic 校验字段和类型。它仍然需要我们显式配置,只是不必自己维护解析和类型转换逻辑。tomllib从 Python 3.11 开始进入标准库。原文的本机项目使用 Python 3.13,可以直接导入,无需安装依赖;在线实验的浏览器解释器由共享 Pyodide 提供,下载实验项目的最低版本为 Python 3.12,同样支持 tomllib。Python 3.13 的tomllib解析 TOML 1.0.0,读取文件时必须使用二进制模式rb。仍在使用 Python 3.10 的项目可以安装兼容包tomli,但当前项目不需要。读取已经在内存中的 TOML 字符串时,使用
loads():load()接收文件对象,loads()接收字符串,这与json.load()和json.loads()的区别相似。解析失败时,
tomllib会抛出TOMLDecodeError:标准库
tomllib只负责读取,不提供写入功能。需要生成 TOML 时可以使用tomli-w;需要在修改文件时保留注释和排版,可以使用tomlkit。FastAPI 服务通常在启动时读取配置,而不是在运行过程中反复改写配置文件,所以只读能力已经覆盖大多数场景。3. 基础值
TOML 最基本的写法是
键 = 值。等号左侧是配置名称,右侧是配置内容:键名区分大小写。
model和MODEL是两个不同的键,不建议在同一个项目中混用大小写风格。不加引号的键只能使用英文字母、数字、下划线和连字符。键名包含空格、点号等特殊字符时,需要加引号:
引号只是键名语法的一部分。
"api.example.com"是一个完整键;不加引号的api.example.com则是点号键,会创建嵌套结构。常用值可以对应到下面这些 Python 类型:
model = "deepseek-v4-flash"strport = 8000inttemperature = 0.7floatdebug = trueboolreleased_at = 2026-08-27T10:30:00Zdatetimerelease_date = 2026-08-27datestart_at = 10:30:00timeorigins = ["http://localhost:3019"]list[server]dict字符串
双引号字符串支持
\n、\t等转义字符;单引号字符串更接近「原样保存」,适合正则表达式或 Windows 路径:多行文本可以使用三个双引号或三个单引号。配置中只有确实存在较长文本时才需要这样做,普通模型名称、URL 和文件路径使用单行字符串更容易阅读。
数字与布尔值
整数和浮点数不加引号。加上引号后,它们就会变成字符串:
TOML 的布尔值只能写成小写的
true或false。True、FALSE、yes都不是合法布尔值。TOML 没有
null。一个字段如果没有值,通常有三种处理方式:不写该字段、提供明确默认值,或者使用业务约定的空字符串。不要写成api_key = null,解析器会直接报错。4. 数组与表
数组用方括号表示,元素之间使用逗号分隔:
数组可以分成多行,并允许最后一个元素后保留逗号。这种写法更适合依赖列表和较长的域名列表:
TOML 1.0 允许数组包含不同类型,但应用配置中通常不建议这样做。保持同一个数组元素类型一致,更容易交给 Pydantic 校验,也更方便读者理解字段含义。
表使用
[名称]声明。它相当于 Python 字典中的一层键:解析后,
cors会成为server下面的子字典:点号键也可以创建嵌套结构:
它与
[server]表达的结果相同,但一个文件中最好采用一致的组织方式。配置较多时,使用表通常更清晰。内联表
少量、紧密相关的数据可以写成内联表:
内联表必须在一行内写完,也不能在末尾保留多余逗号。如果内容开始变长,应改成普通表。
表数组
双层方括号
[[...]]表示「由多个表组成的数组」。例如配置多个模型:解析结果是一个字典,其中
models对应一个列表,列表中的每一项都是字典。这种结构适合真正需要配置多份同类对象的场景。如果应用永远只使用一个默认模型,普通的[model]表更简单。5. 选择
TOML、JSON、YAML 和
.env都能保存配置,但它们解决的问题并不完全相同:null,复杂数据能力有限.env在我们的 FastAPI + LangChain 项目中,会采用这样的分工:
pyproject.toml保存项目元数据、依赖和工具配置;config.toml保存可以提交到仓库的应用默认配置;.env保存本机或部署环境提供的密钥与覆盖值;uv.lock保存 uv 解析出的精确依赖版本,由 uv 自动维护。配置格式不是越统一越好。把 API Key 写入
pyproject.toml,或把几十项嵌套配置压成.env字符串,都会让职责变得更混乱。6. 错误
初学 TOML 时,最常见的错误不是字段含义,而是把其他格式的习惯带进来。
重复定义
同一个键或表不能定义两次:
应把字段写进同一个
[server]中。缺少引号
普通字符串必须加引号:
deepseek-v4-flash不是数字、布尔值或日期,解析器无法判断它是什么。错误注释
TOML 只使用
#注释,不使用 JavaScript 的//:路径与当前目录
Path("config.toml")是相对于进程当前工作目录,而不是相对于config.py文件。开发环境从项目根目录启动时可能正常,测试或部署切换工作目录后就可能找不到文件。后续文章会使用明确的项目根路径解决这个问题。配置不是自动生效的
即使 TOML 能成功解析,拼错字段名也不一定立即报错。直接读取字典时,错误可能一直拖到业务代码访问该字段才出现。生产项目应使用 Pydantic 模型校验配置的字段、类型和范围。
7. 在线实验
从项目中的 lesson.toml 读取真实配置,观察整数、布尔值、日期和表数组分别变成什么 Python 对象。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
打开在线案例,点击运行,等待环境就绪,再发送默认
GET /config。本篇不需要模型密钥或外部服务。port_type 为 int,types 中 debug 为 bool、released_at 为 date、models 为 list。JSON 响应里的日期显示为 ISO 字符串,这是输出时的转换,不是 tomllib 把日期解析成了字符串。
修改 lesson.toml 后重新运行,再发送请求。把整数写成引号包裹的字符串,会改变对应 Python 类型;重复定义表、写入 null 或不合法布尔值会得到 400。这里每次请求读文件便于观察,真实应用通常在启动时读取一次。
下载项目后,在项目目录执行:
再通过
http://127.0.0.1:8000/docs发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。