Python项目打包教程：setuptools与wheel详解

本文深入解析了Python项目打包的核心流程与关键技术，旨在帮助开发者高效地构建、分发和维护Python项目。文章强调了使用`pyproject.toml`文件定义项目元数据和依赖的重要性，并详细介绍了如何利用`setuptools`工具生成`wheel`格式的二进制分发包。通过清晰的项目结构组织、依赖管理和构建工具的运用，可以显著提升Python项目的可维护性、可重复性和协作效率。此外，文章还对比了`pyproject.toml`与`setup.py`的优劣，强烈推荐使用前者以实现更现代、更健壮的Python项目打包体验。掌握这些技巧，能让你的Python项目更易于部署、分享，并为开源社区做出贡献。

答案：Python项目打包需用pyproject.toml定义元数据和依赖，结合setuptools生成wheel包，实现代码分发、依赖管理与跨环境部署，提升可维护性和协作效率。

打包Python项目，核心在于将其代码、依赖和元数据组织成一个可分发的格式，最常见的就是使用setuptools来定义项目结构，并通过它生成wheel格式的二进制分发包（以及sdist源码分发包），以便其他人或系统能轻松安装和使用。这不仅仅是为了上传到PyPI，更是为了项目自身的模块化、可维护性和协作效率。

解决方案

说实话，刚开始接触Python打包时，我个人觉得这玩意儿有点玄乎，各种配置文件和概念堆在一起。但一旦你理解了核心逻辑，它其实非常直观。现代Python项目的打包流程，强烈推荐使用pyproject.toml结合build工具。

1. 项目结构准备： 一个典型的、推荐的项目结构会是这样：

   my_project/
   ├── src/
   │   └── my_package/
   │       ├── __init__.py
   │       └── module_a.py
   ├── pyproject.toml
   ├── README.md
   ├── LICENSE
   ├── requirements.txt (可选，用于开发环境)
   └── .gitignore

   这里src/目录非常关键，它将你的包代码与项目根目录下的其他文件（如文档、测试、配置文件）清晰地分离。这避免了在开发模式下Python解释器意外地从项目根目录加载包的问题。

2. pyproject.toml 文件配置： 这是你的项目元数据和构建系统定义的核心文件。它遵循TOML格式，比传统的setup.py更声明式，更易于理解和维护。

   [build-system]
   requires = ["setuptools>=61.0", "wheel"]
   build-backend = "setuptools.build_meta"
   
   [project]
   name = "my-awesome-package"
   version = "0.1.0"
   description = "一个超棒的Python项目，解决你的所有烦恼。"
   readme = "README.md"
   requires-python = ">=3.8"
   license = { file = "LICENSE" }
   keywords = ["awesome", "utility", "python"]
   authors = [
       { name = "你的名字", email = "你的邮箱@example.com" },
   ]
   maintainers = [
       { name = "另一个贡献者", email = "另一个邮箱@example.com" },
   ]
   classifiers = [
       "Programming Language :: Python :: 3",
       "License :: OSI Approved :: MIT License",
       "Operating System :: OS Independent",
   ]
   dependencies = [
       "requests>=2.28.1",
       "numpy",
       # 更多依赖...
   ]
   
   [project.urls]
   "Homepage" = "https://github.com/你的用户名/my_project"
   "Bug Tracker" = "https://github.com/你的用户名/my_project/issues"
   "Documentation" = "https://my_project.readthedocs.io/"
   
   [tool.setuptools.packages.find]
   where = ["src"] # 告诉setuptools在src目录下查找包

   这里我们定义了构建系统（使用setuptools作为后端），然后是项目的基本信息、依赖、作者、许可证等。[tool.setuptools.packages.find]部分是告诉setuptools去src目录下找你的Python包。

3. 安装构建工具： 你需要安装build工具来执行打包操作。

   pip install build

4. 执行打包： 在你的项目根目录（pyproject.toml所在的目录）下运行：

   python -m build

   这个命令会执行构建过程，通常会在项目根目录下生成一个dist/目录。里面会包含两个文件：

   • my_awesome_package-0.1.0-py3-none-any.whl (Wheel 文件，二进制分发包)
   • my_awesome_package-0.1.0.tar.gz (Source Distribution，源码分发包)

现在，你就可以用pip install dist/my_awesome_package-0.1.0-py3-none-any.whl来安装你的包了，或者将其上传到PyPI。

为什么我的Python项目需要打包？

老实说，一开始我只是写脚本，本地跑跑，根本没想过打包这回事。但随着项目代码量上去，或者需要给别人用，甚至只是自己换台机器部署，就会发现不打包简直是自找麻烦。

核心原因在于：可重复性、可维护性和协作效率。

想想看，如果你写了一个工具，里面用到了requests、pandas这些库。如果只是把代码文件扔给别人，他们怎么知道要安装哪些依赖？版本对不对？打包就解决了这个问题。它把你的代码、依赖信息、版本号、作者、许可证等所有元数据都封装在一起，形成一个标准的、可安装的单元。

对于个人项目，打包意味着你可以轻松地在不同环境（比如开发机、测试服务器、生产环境）部署你的代码，确保依赖的一致性。对于团队协作，它提供了一个清晰的接口，让团队成员能够像使用任何第三方库一样使用你开发的模块，而不需要深入了解其内部结构。更重要的是，它为你的项目走向公开（比如发布到PyPI）铺平了道路，让全世界都能轻松地使用你的劳动成果。这不仅仅是技术上的必要，更是一种代码工程化和专业化的体现。

setuptools 与 wheel：它们到底是什么关系？

理解setuptools和wheel的关系，就好比理解建筑师和预制板的关系。

setuptools，你可以把它看作是项目的“建筑师”和“施工方”。它定义了你的项目应该如何被构建。它负责：

• 元数据管理：读取pyproject.toml（或setup.py）中定义的项目名称、版本、作者、依赖等信息。
• 包发现：根据你的配置（比如where = ["src"]），找到项目中实际的Python模块和包。
• 资源包含：确保像配置文件、数据文件等非Python代码也能被打包进去。
• 依赖解析：处理你项目所依赖的其他库。
• 构建指令：最终，它会执行一系列操作，将你的源代码和所有相关信息转换成可分发的格式。

简单来说，setuptools是那个知道如何把你的散乱代码和配置变成一个有组织的、可安装的“东西”的引擎。

而 wheel，则是这个“东西”的最终“预制件”。它是一种二进制分发格式。想象一下，如果setuptools把你的项目“盖”好了，那么wheel就是那个已经打包好的、可以直接搬到工地上（你的Python环境里）安装的“预制房屋”。

它的特点是：

• 预编译：如果你的项目包含C扩展（例如numpy），wheel文件通常会包含这些预编译好的二进制文件，省去了用户在安装时进行编译的步骤，大大加快了安装速度。
• 平台特定：一个wheel文件可能只适用于特定的Python版本和操作系统架构（尽管很多纯Python包是any，即通用）。
• 安装快速：pip可以直接解压wheel文件并将其内容放置到正确的位置，无需执行任何构建步骤。

所以，它们的关系是：setuptools（作为构建后端）使用wheel格式来生成最终的可分发包。setuptools负责“制造”这个“预制件”，而wheel本身就是这个“预制件”的标准格式。当你运行python -m build时，setuptools会按照pyproject.toml的指示，最终输出.whl（以及.tar.gz）文件。

pyproject.toml vs setup.py：我该选择哪一个？

这个问题，在我看来，几乎没有争议：强烈推荐使用 pyproject.toml。

过去，setup.py是Python项目打包的黄金标准。它是一个Python脚本，这意味着你可以用Python的全部灵活性来定义你的打包逻辑。你可以编写复杂的条件语句，动态地生成元数据，或者执行一些自定义的构建步骤。

# 示例：setup.py (不推荐，但了解一下)
from setuptools import setup, find_packages

setup(
    name="my_legacy_package",
    version="0.1.0",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    install_requires=[
        "requests>=2.28.1",
        "numpy",
    ],
    # ... 更多配置
)

然而，这种灵活性也带来了问题。setup.py需要被执行才能获取到项目的元数据，这使得工具链（比如pip）在处理它时变得复杂。它可能引入副作用，或者依赖于特定的Python环境才能正确运行。这导致了所谓的“构建隔离”问题，即构建工具本身可能需要依赖项目本身的依赖才能运行，形成循环依赖。

而 pyproject.toml，则是Python打包生态系统迈向现代化的关键一步（通过PEP 517和PEP 518）。它是一个声明式的配置文件，用TOML格式编写。这意味着：

• 元数据是静态的：工具可以在不执行任何Python代码的情况下，直接解析pyproject.toml来获取项目的元数据。这大大简化了构建工具的工作。
• 构建系统隔离：pyproject.toml明确定义了构建项目所需的工具（如setuptools和wheel），这些工具会在一个隔离的环境中安装和运行，避免了与项目运行时依赖的冲突。
• 标准化：它提供了一个统一的入口点，不仅setuptools可以使用，像Poetry、Flit这样的替代构建工具也可以使用。
• 更清晰：TOML格式本身就比Python脚本更适合表达配置，结构清晰，易于阅读和维护。

尽管setup.py仍然被大量遗留项目使用，并且在某些极度复杂的定制化构建场景下可能仍有其用武之地，但对于绝大多数新项目和现有项目的迁移，pyproject.toml都是毫无疑问的最佳选择。它代表了Python打包的未来，提供了更健壮、更可预测、更易于管理的构建体验。我的建议是，从一开始就拥抱pyproject.toml，你会省去很多不必要的麻烦。

以上就是《Python项目打包教程：setuptools与wheel详解》的详细内容，更多关于依赖管理,setuptools,wheel,Python项目打包,pyproject.toml的资料请关注golang学习网公众号！