是否应仅使用pyproject.toml？还是与setup.py、setup.cfg搭配使用？

核心结论 #

现代Python项目优先选择纯pyproject.toml，仅在需要动态逻辑或兼容旧代码时搭配其他文件。

1. 大多数场景：只用pyproject.toml #

PEP 621已经将pyproject.toml确立为Python项目元数据和构建配置的标准文件，它能覆盖绝大多数常规需求：

• 定义项目元数据（名称、版本、作者、许可证等）
• 声明依赖（运行时、开发时、可选依赖）
• 设置脚本/入口点（比如命令行工具）
• 指定构建后端（比如setuptools、poetry、flit）

示例片段：

[project]
name = "my-package"
version = "0.1.0"
authors = [{name = "Your Name", email = "your@email.com"}]
dependencies = ["requests>=2.25.0"]

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

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

这种方式完全是声明式的，清晰易读，没有执行代码的风险，是当前官方推荐的最佳实践。

2. 需要动态逻辑时：pyproject.toml + setup.py #

如果你的项目需要动态生成配置或执行自定义逻辑，就需要保留setup.py：

• 动态生成版本号（比如从Git标签自动获取）
• 编译C/C++扩展模块
• 安装过程中需要执行自定义操作（比如生成配置文件、下载额外资源）
• 兼容一些仅支持setup.py的老工具

此时pyproject.toml负责指定构建后端和基础配置，setup.py处理动态部分。示例setup.py片段：

from setuptools import setup

def get_version():
    # 从Git标签或其他动态源获取版本
    return "0.1.0-dev"

setup(
    version=get_version(),
    # 其他动态配置项
)

3. 过渡/复杂配置场景：pyproject.toml + setup.cfg #

如果你有一个用setup.cfg维护的旧项目，或者需要一些setuptools特有的复杂配置（比如精细的package_data规则），可以逐步将元数据迁移到pyproject.toml，同时保留setup.cfg处理剩余的setuptools专属配置。不过随着setuptools对pyproject.toml的支持越来越完善，这种场景会越来越少。

4. 不推荐的方式 #

• 单独使用setup.py：不符合现代打包标准，缺少build isolation的配置，容易导致构建环境问题。
• 单独使用setup.cfg：同样需要pyproject.toml来指定构建后端，否则无法正常构建。

内容的提问来源于stack exchange，提问作者paavoto