告别setup.py：使用pyproject.toml打造现代Python包

1. 为什么我们需要告别setup.py

如果你用过Python开发项目，肯定对setup.py这个文件不陌生。这个文件就像是Python项目的"身份证"，里面定义了项目的名称、版本、依赖等信息。但说实话，每次写setup.py都让我头疼不已 - 那些复杂的参数、难以调试的语法，还有各种莫名其妙的错误。

我最近接手一个老项目，setup.py文件足足有200多行。光是理解里面的各种配置就花了我大半天时间。更糟的是，这个文件里还混入了不少业务逻辑代码，导致打包过程经常失败。这让我下定决心要寻找更好的解决方案。

好消息是，Python社区也意识到了这个问题。随着PEP 517和PEP 621标准的推出，pyproject.toml正在成为新的打包标准。这个文件采用TOML格式，比Python代码更易读、更结构化。我最近把所有项目都迁移到了pyproject.toml，打包过程变得简单多了。

2. pyproject.toml与传统setup.py的对比

2.1 格式差异

setup.py是一个Python脚本，里面调用setuptools.setup()函数来定义项目信息。这种方式虽然灵活，但也带来了不少问题：

from setuptools import setup setup( name="my_project", version="0.1", packages=find_packages(), install_requires=[ "requests>=2.25.0", "numpy>=1.20.0" ], # 还有几十个其他参数... )

而pyproject.toml采用TOML格式，结构更加清晰：

[project] name = "my_project" version = "0.1" dependencies = [ "requests>=2.25.0", "numpy>=1.20.0" ]

2.2 功能对比

pyproject.toml不仅替代了setup.py的功能，还带来了更多优势：

1. 声明式配置：不再需要执行Python代码，减少了出错可能
2. 统一标准：所有工具都使用同一个配置文件
3. 更丰富的元数据：支持更多项目信息的定义
4. 构建系统隔离：明确指定构建依赖，避免污染环境

我在迁移过程中发现，pyproject.toml的另一个巨大优势是工具兼容性。现在主流的Python工具如pip、build、poetry等都支持pyproject.toml，这意味着你不再需要为不同工具维护多个配置文件。

3. 如何创建pyproject.toml文件

3.1 基本结构

一个典型的pyproject.toml文件包含以下几个部分：

[build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my_project" version = "0.1.0" authors = [ {name = "John Doe", email = "john@example.com"} ] description = "A small example package" readme = "README.md" requires-python = ">=3.7" classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ] [project.urls] Homepage = "https://example.com" Bug_Tracker = "https://example.com/issues"

3.2 关键配置详解

build-system部分：

• requires：指定构建依赖，通常是setuptools和wheel
• build-backend：指定构建后端，setuptools是最常用的选择

project部分：

• name：项目名称，在PyPI上必须唯一
• version：项目版本，建议遵循语义化版本规范
• dependencies：项目运行时依赖
• optional-dependencies：可选依赖，可以分组定义

我建议至少包含这些基本信息，这样你的包才能正确发布到PyPI。对于更复杂的项目，你还可以添加：

• scripts：命令行工具入口点
• package-data：非Python文件资源
• entry-points：插件系统集成点

4. 从零开始构建Python包

4.1 项目结构

让我们通过一个实际例子来演示如何用pyproject.toml打包Python项目。假设我们要打包一个简单的数学工具库：

math_utils/ ├── src/ │ └── math_utils/ │ ├── __init__.py │ ├── basic.py │ └── advanced.py ├── tests/ │ └── test_math_utils.py ├── pyproject.toml ├── README.md └── LICENSE

4.2 编写pyproject.toml

[build-system] requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta" [project] name = "math-utils" version = "0.1.0" authors = [ {name = "Jane Smith", email = "jane@example.com"} ] description = "A collection of useful math functions" readme = "README.md" requires-python = ">=3.8" license = {text = "MIT"} classifiers = [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", ] [project.urls] Homepage = "https://github.com/username/math-utils" Documentation = "https://github.com/username/math-utils#readme" Bug_Tracker = "https://github.com/username/math-utils/issues" [tool.setuptools] package-dir = {"" = "src"}

4.3 构建和安装

现在我们可以构建并安装这个包了：

# 安装构建工具 pip install build # 构建项目 python -m build # 安装生成的wheel文件 pip install dist/math_utils-0.1.0-py3-none-any.whl

构建完成后，你会在dist目录下看到两个文件：

• .tar.gz源码分发
• .whl二进制分发

5. 高级配置技巧

5.1 处理依赖关系

pyproject.toml可以非常灵活地管理依赖：

[project] dependencies = [ "requests>=2.25.0", "numpy>=1.20.0; python_version>='3.8'", "pandas>=1.3.0; python_version>='3.8' and python_version<'3.11'" ] [project.optional-dependencies] test = [ "pytest>=6.0", "pytest-cov>=2.0" ] dev = [ "black", "flake8", "mypy" ]

安装可选依赖组：

pip install "math-utils[test,dev]"

5.2 包含非Python文件

如果你需要包含数据文件或文档，可以这样配置：

[tool.setuptools] include-package-data = true [tool.setuptools.package-data] math_utils = ["data/*.json", "templates/*.html"]

5.3 定义命令行工具

[project.scripts] math-cli = "math_utils.cli:main" [project.gui-scripts] math-gui = "math_utils.gui:main"

这会在安装包时创建math-cli和math-gui命令。

6. 常见问题与解决方案

在迁移到pyproject.toml的过程中，我遇到过不少问题，这里分享几个典型的：

问题1：构建时报错"invalid project name"

• 原因：项目名称不符合PyPI命名规范
• 解决：只使用字母、数字和连字符，且不能以数字开头

问题2：安装后无法导入包

• 原因：通常是因为包目录结构不正确
• 解决：确保在pyproject.toml中正确配置了package-dir

问题3：依赖项安装失败

• 原因：依赖声明格式错误
• 解决：检查dependencies中的包名和版本说明符格式

问题4：构建速度慢

• 原因：每次构建都重新安装构建依赖
• 解决：使用build的--isolated参数或预先安装构建依赖

7. 迁移现有项目的最佳实践

如果你有一个使用setup.py的老项目，可以按照以下步骤迁移：

1. 备份现有配置：复制setup.py中的重要配置
2. 创建pyproject.toml：将关键信息转换为TOML格式
3. 测试构建：确保能正确构建wheel文件
4. 验证安装：安装生成的wheel并测试功能
5. 更新文档：修改README等文档中的构建说明
6. 删除setup.py：确认一切正常后可以删除旧文件

我最近将一个中型项目从setup.py迁移到pyproject.toml，整个过程大约花了2小时。最大的挑战是处理一些复杂的自定义构建逻辑，但最终结果非常值得 - 构建时间缩短了30%，配置也更加清晰易维护。

8. 现代Python打包生态

pyproject.toml的出现改变了Python打包的生态系统。现在除了setuptools，你还可以选择其他构建后端：

• Poetry：专注于依赖管理和发布流程
• Flit：适合简单项目的轻量级工具
• Hatch：提供完整的项目生命周期管理
• PDM：支持PEP 582的现代工具

这些工具都使用pyproject.toml作为配置文件，但提供了不同的功能和用户体验。我建议根据项目需求选择合适的工具 - 对于大多数库项目，setuptools+pyproject.toml的组合已经足够好用了。