TOML

语法

官方文档

1. 大小写敏感的
2. UTF-8 编码的 Unicode 文档
3. 空白的意思是 Tab（0x09）或空格（0x20）
4. 换行的意思是 LF（0x0A）或 CRLF（0x0D0A）
5. 仅支持单行注释，井号将此行剩下的部分标记为注释。
6. KEY 为裸键时仅支持（A-Za-z0-9_-）

KEY

name = "Tom" # 裸键
name_key = "Tom" # 带下划线的裸键
name-key = "Tom" # 带连字符的裸键
"名字" = "Tom" # 带引号的键
1234 = "Tom" # 数字key
'你的"name"' = "Tom" # 带引号的键

使用点号来表示层级关系

user.name = "Tom"
user.age = 18

在 json 中

{
  "user": {
    "name": "Tom",
    "age": 18
  }
}

支持的数据类型

1. 字符串

   • name = "Tom" # 双引号
     name_key = 'C:\Users\nodejs\templates' # 单引号，无法转义
     name-key = """
     T
     o
     m""" # 双引号多行，保留空白
     

2. 空类型

   • name = nan
     

3. 日期和时间

   • birth = 1999-02-21 07:32:00Z
     death = 1979-05-27T00:32:00.999999-07:00
     

4. 整数

   • age = +18
     coin = -3_873
     

5. 浮点数

   • number = 18.5
     

6. 布尔值

   • gender = true
     

7. 数组

   • class_name = [ "Tom", "Jerry" ]
     

8. 行内表

   • table = { user = "曹操", Dynasty = "曹魏" }
     

     和下面相等

9. 表

   •    [table]
        user = "曹操"
        Dynasty = "曹魏"
     

   • {
       "table": {
         "user": "曹操",
         "Dynasty": "曹魏"
       }
     }
     

10. 表数组

    • nest = [ { age = 18, gender = true }, { age = 19, gender = false } ]
      

    • {
        "nest": [
          {
            "age": 18,
            "gender": true
          },
          {
            "age": 19,
            "gender": false
          }
        ]
      }
      

11. 表嵌套

    • [[fruit]]
      name = "apple"
      
      [fruit.physical]
      color = "red"
      shape = "round"
      
      [[fruit.variety]]
      name = "red delicious"
      
      [[fruit.variety]]
      name = "granny smith"
      
      [[fruit]]
      name = "banana"
      
      [[fruit.variety]]
      name = "plantain"
      

    • {
        "fruit": [
          {
            "name": "apple",
            "physical": {
              "color": "red",
              "shape": "round"
            },
            "variety": [{ "name": "red delicious" }, { "name": "granny smith" }]
          },
          {
            "name": "banana",
            "variety": [{ "name": "plantain" }]
          }
        ]
      }
      

pyproject.toml

学完语法了就要开始上实战了

官方文档

一个通用示例，这是一个几乎包含全部内容的 pyproject.toml 文件，平常使用可以根据需要添加。

[build-system] # 构建系统配置
requires = ["uv_build>=0.7.19,<0.9.0"] # 构成依赖及版本约束
build-backend = "uv_build" # 构建后端入口

[project] # 项目配置
name = "spam-eggs"  # 项目名称
version = "2020.0.0" # 项目版本
# dynamic = ["version", "authors"] # 动态版本 有的支持有的不支持
dependencies = [ # 核心依赖包
  "httpx",
  "gidgethub[httpx]>4.0.0",
  "django>2.1; os_name != 'nt'",
  "django>2.0; os_name == 'nt'",
]
requires-python = ">=3.10" # 项目支持的Python版本
authors = [ # 作者列表
  {name = "Pradyun Gedam", email = "pradyun@example.com"},
  {name = "Tzu-Ping Chung", email = "tzu-ping@example.com"},
  {name = "Another person"},
  {email = "different.person@example.com"},
]
maintainers = [ # 维护者
  {name = "Brett Cannon", email = "brett@example.com"}
]
description = "Lovely Spam! Wonderful Spam!" # 项目描述
# readme = "README.rst"
readme = {file = "README.txt", content-type = "text/markdown"} # 项目说明文档
license = "MIT"  # 项目许可证
license-files = ["LICEN[CS]E.*"] # 项目许可证文件
keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"] # 项目关键词PyPI搜索关键词
urls = { # 项目链接(显示在PyPI页面侧边栏)
  "Homepage" = "https://example.com",
  "Documentation" = "https://readthedocs.org",
  "Repository" = "https://github.com/me/spam.git",
  "Bug Tracker" = "https://github.com/me/spam/issues",
  "Changelog" = "https://github.com/me/spam/blob/master/CHANGELOG.md"
}
classifiers = [ # 项目分类
    "Development Status :: 3 - Alpha", # 项目开发状态,3-Alpha,4-Beta,5-Production/Stable
    "Intended Audience :: Developers", # 项目目标用户
    "Topic :: Software Development :: Build Tools", # 项目主题
    "License :: OSI Approved :: MIT License", # 项目许可证
    "Programming Language :: Python :: 3.10", # 项目支持的Python版本
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: Implementation :: CPython", # 项目支持的Python解释器
]

[project.optional-dependencies] # 可选依赖分组
gui = ["PyQt5"]  # GUI使用依赖Qt5
cli = [ # 命令行依赖
  "rich",
  "click",
]
dev = ["pytest", "pytest-cov"] # 开发依赖

[project.scripts] # 项目命令行脚本
spam-cli = "spam:main_cli"


[project.gui-scripts] # 项目GUI脚本
spam-gui = "spam:main_gui"

[project.entry-points."spam.magical"] # 插件接入入口
tomatoes = "spam:main_tomatoes"

[tool.uv] # uv_build配置
# 环境限制配置（仅解析指定平台/Python 版本的依赖）
environments = [
  "sys_platform == 'darwin'",  # 支持 macOS
  "sys_platform == 'linux' and platform_machine == 'x86_64'",  # 支持 Linux x86_64
  "sys_platform == 'win32' and python_version >= '3.10'",  # 仅 Windows 3.10+ 支持
]
# 必需环境（强制支持的平台，适用于预编译二进制包如 PyTorch）
required-environments = [
  "sys_platform == 'linux' and platform_machine == 'aarch64'"  # 必须支持 Linux ARM64
]
# 依赖冲突解决（声明不兼容的可选依赖/依赖组，避免解析失败）
conflicts = [
  # 冲突1：cli 和 old-cli 不能同时安装（old-cli 是旧版命令行，与新版冲突）
  [
    { extra = "cli" },
    { extra = "old-cli" }
  ],
  # 冲突2：dev 开发组与 production 生产组不能同时安装（开发依赖与生产依赖冲突）
  [
    { group = "dev" },
    { group = "production" }
  ]
]
# 构建隔离配置（禁用部分包的构建隔离，解决依赖问题）
no-build-isolation-package = [
  "flash-attn >= 2.6",  # 特殊包：需提前安装 torch 才能构建，禁用隔离
  "cchardet == 2.1.7"  # 旧版包：不兼容默认构建隔离，需手动处理依赖
]
# 预提供依赖元数据（解决 flash-attn 等包的解析阶段依赖问题）
[[tool.uv.dependency-metadata]]
name = "flash-attn"  # 包名
version = "2.6.3"  # 目标版本（可选：省略则适用于所有版本）
requires-dist = [  # 包的依赖声明（从 PyPI 或 METADATA 文件获取）
  "torch >= 2.0.0",
  "einops >= 0.6.1",
  "packaging >= 21.3"
]
# 6. 项目打包控制（强制/禁用项目构建安装）
package = true  # 强制构建项目并安装到虚拟环境（默认：根据 build-system 自动判断）
# 7. 依赖组配置（按场景分组，安装：uv sync --group production）
[dependency-groups]
production = [  # 生产环境依赖（精简，不含开发工具）
  "gunicorn >= 21.2",  # WSGI 服务器
  "prometheus-client >= 0.17"  # 监控指标暴露
]
test = [  # 测试环境依赖（扩展 dev 组）
  "pytest-cov >= 4.1",
  "pytest-mock >= 3.11"
]