Python能做大项目（4）项目布局与生成向导

1. 项目布局和项目生成向导

通过前三章的学习，我们了解了如何构建开发环境，并且也完成了一个最简单的 python 程序 —— Hello World。

您可能已经意识到，即使撇开其简陋的功能不说，在其它方面，它也有明显的不足：

1. 一般而言，程序的使用者会需要帮助文档，也需要了解关于版权、作者等信息，这些信息应该如何提供？
2. 没有任何程序能够避免 bug。您可能已经听说，要减少 bug，程序就必须经过系统和详尽的测试。那么测试代码应该应该如何编写和组织？
3. 程序应该以可安装包的形式发布出去，而不是以源代码的方式交付。Hello World 小程序显然也没有涉及到这一部分。

还有很多很多。一个完整的项目，除了提供最核心的程序功能之外，还必然涉及到产品质量控制（包括单元测试、代码风格控制等）、版权、发布历史、制作分发包等杂务，从而也就在实现功能的源代码之外，引入了许多其它文件。这些文件应该如何组织？有没有基本的命名规范？是否有工程模板可以套用，或者可以通过工具来生成？这一章将为您解答这些问题。

这一章将介绍规范的项目布局应该具有什么样的目录视图，并在最后介绍了一个遵循社区最新规范的、生成 Python 工程框架的向导工具。

项目文件布局必须遵循一定的规范。这有两方面的考虑，一是项目文件布局是项目给人的第一印象，一个布局混乱的项目，会吓跑潜在的用户和贡献者；遵循规范的项目文件布局，可以让他人更容易上手；二来，构建工具、测试工具等工具也依赖于一定的文件结构。如果文件结构没有一定的规范，则必然要对每个工具进行一定的配置，才能使其工作。过多的配置项往往会引起错误，增加学习成本。

在工程构建过程中，使用约定俗成的项目文件结构和规范的文件、文件夹名字，而不是通过繁琐的配置项目以允许过度自定义，这种原则被称为惯例优于配置 (convention over configuration)，这不仅仅是 Python, 也是许多其它语言遵循的原则。

1.1. 标准项目布局

首先，我们介绍一个经典的 Python 项目布局，由 Kenneth Reitz[^kenneth] 推荐。他是著名的 Python http 库request和pipenv的作者。

这个布局如下面所示：

├── sample
│   ├── AUTHORS.rst
│   ├── docs
|   |   ├── conf.py
│   │   └── index.rst
│   ├── HISTORY.rst
│   ├── LICENSE
│   ├── makefile
│   ├── MANIFEST.in
│   ├── README.rst
│   ├── requirements.txt
│   ├── sample
|   |   ├── app.py
│   │   └── helper.py
|   ├── setup.cfg
|   ├── setup.py
│   └── tests

下面我们来逐一解释。

1.1.1. 一般性文档

1.1.1.1. 项目说明文档

一般使用 README 作为文件名，大写。用来向本项目的使用者概括性地介绍这个项目的基本情况，比如主要功能、优势、版本计划等。这里文件的后缀是.rst，这是一种扩展标记文本格式，通过文档构建工具，可以生成富文本格式的文件。现在更流行的格式可能是 markdown，以.md 作为文件名后缀。我们会在文档构建那一章再详细介绍两者的区别。

1.1.1.2. 许可证文档

一般使用 LICENSE 作为文件名，大写。开源项目必须配置此文档。此文件一般为纯文本格式，不支持扩展标记。

1.1.1.3. 版本历史文档

一般使用 HISTORY 作为文件名，大写。

每一个版本发布，都可能引入新的功能、修复了一些 bug 和安全性问题，也可能带来一些行为变更，导致使用者必须也要做相应的修改才能使用。

如果没有一个清晰的版本说明，程序库的用户就不知道应该选用哪一个版本，或者是否应该升级到最新版本上。我们在使用其它人开发的程序库时，并不一定要选择最新的，有时候升级到最新的版本会导致程序无法运行。比如 SQLAlchemy 是一个应用十分广泛的 Python ORM 框架，它的 1.4 版本与前面的版本有较多不兼容的问题。如果您的程序不加修改就直接升级到 1.4，那么大概率程序会崩溃。因此，使用新的版本可能会有益处，但也可能因为兼容性问题，破坏现有的应用，所以，在升级新版本之前需要做很多测试的工作。

同 README 一样，可以使用.rst 的文件格式，也可以使用.md 的文件格式，后面我们不再特别提示。

1.1.1.4. 开发者介绍文档

一般使用 AUTHORS 作为文件名，大写。其目的是向他人介绍项目的开发者团队。

1.1.2. 帮助文档

一个优秀的项目，往往还会有比较详尽的帮助文档，来告诉使用者如何安装、配置和使用，甚至还会配有一些教程。这些文档在命名上就没有那么严格，最终，它们将通过文档生成工具转换成格式美观的在线文档，供使用者阅读。一般地，这些文档都放在 docs 目录下，由一个主控文档来串联。当然，具体如何做，取决于文档构建工具。

1.1.2.1. API 文档

还有一类比较特殊的文档，它们不直接出现在上述目录中，而是散落在源代码的各个部分，通过专门工具生成，与帮助文档一起使用。关于帮助文档和 API 文档，我们将在第 10 章，撰写技术文档中详细介绍。

1.1.3. 工程构建配置文件

不同的构建工具需要不同的配置文件。在 Python 工程中，主要有两种主流的构建工具，一是 Python setup tools, 另一种是符合 PEP517，PEP518 规范的新型构建工具，如 Poetry 等。

在上述目录示例中，使用的是基于 python setup tools 的构建工具，它需要的配置文件有 setup.py, MANIFEST.IN 等文件，还可能会有 requirements.txt 和 makefile；这也是为什么您会看到 setup.py 等文件的原因。如果是使用 Poetry, 则配置文件会简单许多，只需要一个 pyproject.toml 就够了。

当您开始新的项目时，应该只使用 Poetry，而不使用 python setup tools。Poetry 的依赖管理可以锁定程序的运行时，避免很多问题。但是，您可能依然要能看懂基于 setup tools 的老式工程配置，它们将可能在未来的一两年里还继续存在。

1.1.4. 代码目录

在其它开发语言