一篇文章搞懂Python项目结构和打包!

你是否曾经为Python项目的结构而头疼？还在使用那个古老的setup.py？每次打包都感觉像是在踩地雷？

在Python世界中，项目结构和打包一直是让很多开发者头疼的问题。好在随着社区的发展，我们现在有了更现代、更标准化的解决方案。

从setup.py到pyproject.toml：Python打包的演进之路

回想过去，我们要打包一个Python项目，通常需要编写那个“神秘”的setup.py文件。这个文件虽然功能强大，但对于新手来说却不太友好，很多时候我们都不知道应该怎么正确配置。

随着Python社区的发展，情况已经有了很大改变。PEP 518和PEP 621的引入，为我们带来了pyproject.toml这个标准的配置文件格式。这个文件采用静态TOML格式，明确区分了构建系统需求和项目元数据，让Python打包变得标准化和可预测。

Hatchling：现代化的Python构建后端

那么，什么是Hatchling呢？

简单来说，Hatchling是一个现代化的、符合标准的Python构建后端，它取代了传统的setuptools。Hatchling是Hatch项目使用的构建后端，它提供了清晰的pyproject.toml配置方式、智能的默认设置，以及通过钩子和插件的可扩展性。

你可能会问，为什么我们要从setuptools转向Hatchling？原因很充分：Hatchling比setuptools快3倍，更简单，错误信息也更加友好。在2025年的今天，setuptools在现代特性上已经没有任何优势，只留下了20年的历史负担。

build工具：简单正确的构建前端

除了构建后端，我们还需要一个构建前端。这就是python3-build工具的用武之地。

build是一个简单、正确的基于pyproject.toml的构建前端，它会调用构建后端的钩子函数来构建发行包。与其他工具不同，build专注于构建功能，不执行任何依赖管理任务。

如何使用Hatchling打包你的Python项目

那么如何使用Hatchling来打包项目呢？操作其实很简单：

首先，在你的项目根目录下创建pyproject.toml文件，在里面定义[project]表，包含项目的名称、版本、依赖等元数据。

然后，指定构建后端为Hatchling：

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

接着，使用构建前端工具（如build工具或uv）来构建你的包。

如果你使用uv进行包管理，uv init命令会自动配置Hatchling作为默认的构建后端。

为什么Hatchling如此受欢迎？

Hatchling的简洁性和标准化让它受到了越来越多开发者的青睐。

不论是uv这样的现代包管理器，还是其他需要构建Python包的工具，很多都默认采用了Hatchling作为构建后端。这主要是因为Hatchling提供了一个现代化、符合标准、依赖最小的选项。

对于大多数项目来说，Hatchling都是个绝佳选择——它在速度、可配置性和可扩展性之间取得了很好的平衡。Hatchling默认会包含所有版本控制下的文件到发行版中，让整个构建过程更加便利。如果你只是需要一个标准兼容且体积很小的构建后端，Hatchling是极好的选择。

从setup.py过渡到pyproject.toml：平滑迁移

虽然setup.py和setuptools构建的包仍然是有效的，仍然可以被PyPI生态系统的所有安装程序使用，但我们还是应该考虑向现代化标准迁移。

在实际迁移中，你会发现pyproject.toml已经覆盖了setup.py的核心功能：项目元信息（名称、版本、作者、依赖）和构建依赖声明。

这对于那些还在犹豫要不要迁移的项目来说，是个很好的消息——迁移过程并不复杂，却能带来长期的收益。

总结

Python打包工具链的演进，反映了整个Python社区对标准化和易用性的追求。

从最初的自定义构建脚本，到setuptools的生态系统，再到现在的pyproject.toml国际标准，Python在不断变得更好用、更规范。

而Hatchling正是这种演进的最新成果。它简洁、高效、符合标准，将成为未来Python项目打包的主流选择。

如果你还没有尝试过这种新的打包方式，强烈推荐大家观看这期B站视频，花15分钟时间了解一下。相信你一定会发现，原来Python打包可以如此简单！

你平时用哪种方式打包Python项目呢？

如果你正在学习python，这些Python资料、数据分析、Python从入门到实践第三版pdf书籍、Python+Pycharm安装包&永久激活插件、直播课程，可以在这里免费领取哈👇