pyproject.toml 完全指南：Python 项目配置的现代化之路

Ne0inhk

— 10 min read
pyproject.toml 完全指南：Python 项目配置的现代化之路

pyproject.toml 完全指南：Python 项目配置的现代化之路

在这里插入图片描述

前言

如果你刚接触 Python 项目开发，可能会发现很多开源项目的根目录下都有一个 pyproject.toml 文件。它是什么？为什么需要它？本文将从零开始，带你全面了解这个 Python 生态中的"配置中枢"。

一、什么是 pyproject.toml？

1.1 定义

pyproject.toml 是 Python 项目的标准化配置文件，采用 TOML (Tom’s Obvious Minimal Language) 格式编写。它在 2016 年通过 PEP 518 被引入 Python 生态。

1.2 为什么需要它？

在 pyproject.toml 出现之前，Python 项目的配置非常混乱：

文件名作用问题
setup.py定义包的安装配置代码形式，容易出错
setup.cfgsetup.py 的配置版本格式陈旧
requirements.txt列出依赖无法表达复杂依赖关系
MANIFEST.in指定打包文件额外文件
tox.ini测试配置专用文件
.flake8代码检查配置专用文件

问题总结：

  • 配置文件分散，难以管理
  • 格式不统一（INI、Python 代码、纯文本）
  • 缺乏标准化

pyproject.toml 的解决方案：

  • ✅ 一个文件统一管理
  • ✅ 现代化的 TOML 格式
  • ✅ Python 官方标准

二、TOML 格式速成

在深入 pyproject.toml 之前，先了解 TOML 的基本语法：

# 这是注释 # 键值对 name = "my-project" version = "1.0.0" # 数组 dependencies = [ "requests>=2.28.0", "numpy>=1.20.0" ] # 表（类似于字典/对象） [tool.black] line-length = 88 target-version = ['py38'] # 嵌套表 [project.optional-dependencies] dev = ["pytest>=7.0", "black>=22.0"] docs = ["sphinx>=4.0"]

特点：

  • 简洁易读
  • 支持注释
  • 类型明确（字符串、数字、布尔值、数组、表）

三、pyproject.toml 的核心结构

一个完整的 pyproject.toml 通常包含以下几个部分：

[build-system] # 构建系统配置 [project] # 项目元数据 [project.optional-dependencies] # 可选依赖 [tool.xxx] # 各种工具的配置

让我们逐一解析。

四、详细解析各个部分

4.1 [build-system] - 构建系统配置

这是 pyproject.toml 的必需部分，告诉 Python 如何构建你的项目。

[build-system] requires = ["setuptools>=45", "wheel"] build-backend = "setuptools.build_meta"

字段说明：

字段说明示例
requires构建项目所需的依赖包["setuptools>=45", "wheel"]
build-backend指定使用哪个构建后端setuptools.build_meta

常见构建后端：

hatchling（新兴工具）

[build-system] requires = ["hatchling"] build-backend = "hatchling.build"

flit（轻量级）

[build-system] requires = ["flit_core >=3.2,<4"] build-backend = "flit_core.buildapi"

poetry（现代化工具）

[build-system] requires = ["poetry-core>=1.0.0"] build-backend = "poetry.core.masonry.api"

setuptools（传统方式）

[build-system] requires = ["setuptools>=45", "wheel"] build-backend = "setuptools.build_meta"

4.2 [project] - 项目元数据

定义项目的基本信息和依赖关系。

[project] name = "my-awesome-package" version = "1.0.0" description = "一个很棒的 Python 包" readme = "README.md" requires-python = ">=3.8" license = {text = "MIT"} authors = [ {name = "张三", email = "[email protected]"} ] maintainers = [ {name = "李四", email = "[email protected]"} ] keywords = ["web", "api", "framework"] classifiers = [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", ] dependencies = [ "requests>=2.28.0,<3.0.0", "click>=8.0.0", "pydantic>=2.0.0" ] [project.urls] Homepage = "https://github.com/username/my-awesome-package" Documentation = "https://my-awesome-package.readthedocs.io" Repository = "https://github.com/username/my-awesome-package" Changelog = "https://github.com/username/my-awesome-package/blob/main/CHANGELOG.md"

字段详解：

字段必需?说明
name✅包名（发布到 PyPI 的名称）
version✅版本号（遵循 SemVer 规范）
description❌简短描述
readme❌README 文件路径
requires-python❌支持的 Python 版本
license❌开源协议
authors❌作者列表
dependencies❌运行时依赖

4.3 [project.optional-dependencies] - 可选依赖

用于定义不同场景下的额外依赖，比如开发、测试、文档等。

[project.optional-dependencies] # 开发依赖 dev = [ "pytest>=7.0", "pytest-cov>=4.0", "black>=22.0", "ruff>=0.1.0", "mypy>=1.0" ] # 测试依赖 test = [ "pytest>=7.0", "pytest-asyncio>=0.21.0", "httpx>=0.24.0" ] # 文档依赖 docs = [ "sphinx>=4.0", "sphinx-rtd-theme>=1.0" ] # 所有依赖 all = [ "my-awesome-package[dev,test,docs]" ]

使用方式：

# 安装基础依赖 pip install my-awesome-package # 安装开发依赖 pip install my-awesome-package[dev]# 安装多个可选依赖组 pip install my-awesome-package[dev,test]# 安装所有依赖 pip install my-awesome-package[all]

4.4 [project.scripts] - 命令行入口

定义安装后可在命令行直接调用的命令。

[project.scripts] my-cli = "my_package.cli:main" my-tool = "my_package.tools:run"

示例场景：

假设你有以下代码结构：

my_package/ ├── __init__.py └── cli.py

cli.py 内容：

defmain():print("Hello from my-cli!")if __name__ =="__main__": main()

安装后，用户可以直接运行：

my-cli # 输出：Hello from my-cli!

4.5 [tool.*] - 工具配置

这是 pyproject.toml 最强大的功能之一：集中管理各种开发工具的配置。

4.5.1 pytest（测试框架）
[tool.pytest.ini_options] testpaths = ["tests"] python_files = ["test_*.py", "*_test.py"] python_classes = ["Test*"] python_functions = ["test_*"] addopts = [ "--cov=my_package", "--cov-report=html", "--cov-report=term-missing", "-v" ]
4.5.2 black（代码格式化）
[tool.black] line-length = 88 target-version = ['py38', 'py39', 'py310'] include = '\.pyi?$' extend-exclude = ''' /( # 排除的目录 \.eggs | \.git | \.venv | build | dist )/ '''
4.5.3 ruff（快速 Linter）
[tool.ruff] line-length = 88 target-version = "py38" [tool.ruff.lint] select = [ "E", # pycodestyle errors "W", # pycodestyle warnings "F", # pyflakes "I", # isort "B", # flake8-bugbear "C4", # flake8-comprehensions ] ignore = [ "E501", # 行过长（由 black 处理） "B008", # 函数调用中的参数默认值 ] [tool.ruff.lint.per-file-ignores] "__init__.py" = ["F401"] # 允许未使用的导入
4.5.4 mypy（类型检查）
[tool.mypy] python_version = "3.8" warn_return_any = true warn_unused_configs = true disallow_untyped_defs = true disallow_incomplete_defs = true check_untyped_defs = true no_implicit_optional = true [[tool.mypy.overrides]] module = "tests.*" disallow_untyped_defs = false
4.5.5 coverage（代码覆盖率）
[tool.coverage.run] source = ["my_package"] omit = [ "*/tests/*", "*/__init__.py" ] [tool.coverage.report] exclude_lines = [ "pragma: no cover", "def __repr__", "raise AssertionError", "raise NotImplementedError", "if __name__ == .__main__.:", ]

五、实战案例：完整的 pyproject.toml

下面是一个生产环境级别的完整示例：

[build-system] requires = ["setuptools>=68.0", "wheel"] build-backend = "setuptools.build_meta" [project] name = "data-processor" version = "2.3.1" description = "一个强大的数据处理库" readme = "README.md" requires-python = ">=3.8" license = {text = "MIT"} authors = [ {name = "数据团队", email = "[email protected]"} ] keywords = ["data", "processing", "etl", "pipeline"] classifiers = [ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Topic :: Software Development :: Libraries :: Python Modules", ] dependencies = [ "pandas>=2.0.0,<3.0.0", "numpy>=1.24.0", "sqlalchemy>=2.0.0", "pydantic>=2.0.0", "click>=8.0.0", ] [project.optional-dependencies] dev = [ "pytest>=7.4.0", "pytest-cov>=4.1.0", "pytest-asyncio>=0.21.0", "black>=23.0.0", "ruff>=0.1.0", "mypy>=1.5.0", "pre-commit>=3.3.0", ] postgres = [ "psycopg2-binary>=2.9.0", ] mysql = [ "pymysql>=1.1.0", ] all = [ "data-processor[dev,postgres,mysql]" ] [project.urls] Homepage = "https://github.com/company/data-processor" Documentation = "https://data-processor.readthedocs.io" Repository = "https://github.com/company/data-processor" Issues = "https://github.com/company/data-processor/issues" [project.scripts] dp = "data_processor.cli:main" # pytest 配置 [tool.pytest.ini_options] testpaths = ["tests"] addopts = [ "--cov=data_processor", "--cov-report=html", "--cov-report=term-missing:skip-covered", "-v", "--strict-markers", ] markers = [ "slow: 标记慢速测试", "integration: 集成测试", "unit: 单元测试", ] # black 配置 [tool.black] line-length = 100 target-version = ['py38', 'py39', 'py310', 'py311'] include = '\.pyi?$' # ruff 配置 [tool.ruff] line-length = 100 target-version = "py38" [tool.ruff.lint] select = ["E", "F", "I", "B", "C4", "UP"] ignore = ["E501"] [tool.ruff.lint.isort] known-first-party = ["data_processor"] # mypy 配置 [tool.mypy] python_version = "3.8" warn_return_any = true warn_unused_configs = true disallow_untyped_defs = true plugins = ["pydantic.mypy"] # coverage 配置 [tool.coverage.run] source = ["data_processor"] omit = ["*/tests/*", "*/__init__.py"] [tool.coverage.report] precision = 2 show_missing = true skip_covered = false

六、pyproject.toml vs 传统方式对比

6.1 依赖管理对比

传统方式（requirements.txt）：

requests>=2.28.0 numpy>=1.20.0 pandas>=2.0.0

问题：

  • 无法区分生产依赖和开发依赖
  • 不支持可选依赖组
  • 缺少项目元数据

现代方式（pyproject.toml）：

[project] dependencies = [ "requests>=2.28.0", "numpy>=1.20.0", "pandas>=2.0.0", ] [project.optional-dependencies] dev = ["pytest>=7.0", "black>=22.0"]

优势：

  • ✅ 清晰分类
  • ✅ 灵活安装
  • ✅ 完整的项目信息

6.2 工具配置对比

传统方式：

需要多个配置文件：

  • .flake8
  • pytest.ini
  • mypy.ini
  • tox.ini

现代方式：

一个 pyproject.toml 搞定：

[tool.pytest.ini_options] # pytest 配置 [tool.black] # black 配置 [tool.mypy] # mypy 配置

七、最佳实践

7.1 版本管理

使用语义化版本（SemVer）：

[project] version = "主版本.次版本.修订号" # 如 "2.3.1"
  • 主版本：不兼容的 API 修改
  • 次版本：向下兼容的功能新增
  • 修订号：向下兼容的问题修正

7.2 依赖版本约束

dependencies = [ "requests>=2.28.0,<3.0.0", # 推荐：指定范围 "numpy>=1.20.0", # 可以：仅指定最低版本 "pandas==2.0.0", # 避免：固定版本（除非必要） ]

7.3 项目结构建议

my_project/ ├── pyproject.toml # 项目配置 ├── README.md # 项目说明 ├── LICENSE # 开源协议 ├── .gitignore # Git 忽略文件 ├── src/ │ └── my_package/ # 源代码 │ ├── __init__.py │ └── ... └── tests/ # 测试代码 └── ...

7.4 使用 src 布局

在 pyproject.toml 中配置：

[tool.setuptools] package-dir = {"" = "src"} [tool.setuptools.packages.find] where = ["src"]

优势：

  • 避免测试时导入本地未安装的包
  • 确保测试的是安装后的版本

八、常见问题 FAQ

Q1: pyproject.toml 和 setup.py 可以共存吗？

答：可以，但不推荐。如果两者都存在，建议逐步迁移到 pyproject.toml。

Q2: 如何从 setup.py 迁移到 pyproject.toml？

答：

  1. 创建 pyproject.toml
  2. 将 setup() 中的参数转换为对应的 TOML 格式
  3. 测试构建：pip install -e .
  4. 确认无误后删除 setup.py

Q3: Poetry 和 setuptools 选哪个？

答：

  • Poetry：现代化，功能丰富，适合新项目
  • setuptools：传统，兼容性好，适合维护老项目

Q4: pyproject.toml 中的依赖和 requirements.txt 的关系？

答：

  • pyproject.toml：定义抽象依赖和项目元数据
  • requirements.txt：可选，用于锁定具体版本

推荐工作流：

# 从 pyproject.toml 生成 requirements.txt pip-compile pyproject.toml -o requirements.txt

九、工具推荐

9.1 Poetry

一站式项目管理工具，自动生成 pyproject.toml。

# 安装 pip install poetry # 初始化项目 poetry init # 添加依赖 poetry add requests # 安装依赖 poetry install

9.2 Flit

轻量级打包工具，配置简单。

# 安装 pip install flit # 发布到 PyPI flit publish

9.3 Hatch

现代化项目管理工具。

# 安装 pip install hatch # 创建项目 hatch new my-project

十、总结

pyproject.toml 是 Python 项目管理的未来趋势，它带来了：

✅ 统一配置：一个文件管理所有配置
✅ 标准化：Python 官方推荐的标准
✅ 现代化：更清晰的语法和更强大的功能
✅ 工具支持：主流工具都已支持

学习路径建议

  1. 初级：理解基本结构，能读懂常见配置
  2. 中级：为自己的项目编写 pyproject.toml
  3. 高级：掌握各种工具配置，优化项目管理流程

参考资源

最后的建议：如果你正在开始一个新的 Python 项目，从第一天就使用 pyproject.toml。它不仅让你的项目更专业，也为未来的维护和协作打下良好基础。

Happy Coding! 🐍

Read more

个人玩家新手必看｜使用扣子Coze搭建AI智能体（内含接口有效key）

个人玩家新手必看｜使用扣子Coze搭建AI智能体（内含接口有效key）

前言 大家好呀～ 我是超爱分享干货的学妹菲菲！😉今天给大家带来「Coze（扣子）AI 智能体搭建教程」，全程手把手拆解，每一步都讲得明明白白，新手也能轻松上手～学会的宝子别忘了点赞分享，让更多人 get 这项实用技能呀！ 进入教程👉 搭建AI智能体 1、进入扣子空间点击“项目开发”→点击“创建”→选择“创建智能体” 2、按照实际情况填写Bot信息，图标可以本地上传图片，也可以通过AI生成，填写完成后，点击“确认”按钮 3、编写提示词 4、进入 Bot 编辑页面后，左侧「编排」栏可配置两大核心参数：Bot 运行模式与大语言模型。 运行模式分为「单 Agent 模式」和「多 Agents

By Ne0inhk
【AI编程】Qoder AI 编程工具从部署到深度使用实战详解

【AI编程】Qoder AI 编程工具从部署到深度使用实战详解

目录 一、前言 二、AI编程工具介绍 2.1 什么是AI编程 2.1 AI编程核心功能 2.3 AI编程应用场景 1. 智能代码补全与生成 2. 自然语言生成代码 3. 代码解释与文档生成 4. 错误检测与自动修复 5. 单元测试与自动化测试生成 6. 代码重构与优化 7. 跨语言代码转换 8. 低代码/无代码平台增强 三、几种主流AI编程工具介绍 3.1 Cursor 3.1.1 Cursor 核心功能 3.1.1 Cursor 优势 3.2 GitHub Copilot

By Ne0inhk

AI设计代替UI的工具选择，有免费的使用额度！

AI直接生成UI 设计文件（Figma、Pixso、即时设计等格式）的工具已经很成熟了，作为一个没有ui设计的公司，用这些个工具就非常你测了，以下是主流且实用的选择，按国内 / 国外分类整理： 一、国内主流工具 1. Pixso AI（推荐） * 官网：https://ai.pixso.cn/ * 核心能力：输入文字描述，一键生成可编辑矢量 UI 设计稿，支持转为 Pixso 源文件，可导出 Figma 格式。 * 优势：中文语境优化好，内置 Ant Design、Material 等大厂组件库，生成后可直接编辑、协作，还能导出前端代码。 * 使用：注册后进入 AI 生成，输入需求（如 “设计极简风电商

By Ne0inhk

人工智能（AI）常见面试题及答案汇总（2025最新版）

一、AI基础概念与核心原理 1. 人工智能、机器学习、深度学习的关系？ 答案： 三者是包含与被包含的关系，核心聚焦“让机器具备智能”的不同实现层次： * 人工智能（AI）：广义是让机器模拟人类智能（如推理、学习、决策）的技术总称，涵盖机器学习、深度学习、专家系统、强化学习等多个分支，目标是解决“智能行为”问题； * 机器学习（ML）：AI的核心分支，是实现AI的一种手段，指机器通过数据学习规律（无需显式编程），并利用规律预测或决策。核心是“从数据中自动学习模型”，不依赖手动设计规则（如传统编程）； * 深度学习（DL）：机器学习的子集，以深度神经网络（DNN） 为核心，通过多层网络结构自动提取数据的层级特征（从底层像素/字符到高层语义），擅长处理海量高维数据（如图像、语音、文本）。 关系图示：

By Ne0inhk