《Python高手之路（第3版）》——1.2 项目布局

本节书摘来自异步社区《python高手之路（第3版）》一书中的第1章，第1.2节，作者［法］julien danjou，王飞龙 译，更多章节内容可以访问云栖社区“异步社区”公众号查看。

项目结构应该保持简单，审慎地使用包和层次结构：过深的层次结构在目录导航时将如同梦魇，但过平的层次结构则会让项目变得臃肿。

一个常犯的错误是将单元测试放在包目录的外面。这些测试实际上应该被包含在软件的子包中，以便：

不会偶尔被setuptools（或者其他打包库）作为tests顶层模块自动安装；

能够被安装，且被其他包用于构建自己的单元测试。

图1-1展示了一个项目的标准文件层次结构。

<code>setup.py</code>是python安装脚本的标准名称。在安装时，它会通过python分发工具（distutils）进行包的安装。也可以通过<code>readme.rst</code>（或者<code>readme.txt</code>或其他合适的名字）为用户提供重要信息。<code>requirements.txt</code>应该包含python包所需要的依赖包，也就是说，所有这些包都会预先通过<code>pip</code>这样的工具进行安装，以保证你的包能正常工作。还可以包含<code>test-requirements.txt</code>，它只列出运行测试套件所需要的依赖包。最后，<code>docs</code>文件夹应该包括<code>restructuredtext</code>格式的文档，以便能够被sphinx处理（参见5.1节）。

包中还经常需要包含一些额外的数据，如图片、shell脚本等。不过，关于这类文件如何保存并没有一个统一的标准。因此放到任何觉得合适的地方都可以。

下面这些顶层目录也经常出现。

<code>etc</code>用来存放配置文件的样例。

<code>tools</code>用来存放与工具有关的shell脚本。

<code>bin</code>用来存放将被<code>setup.py</code>安装的二进制脚本。

<code>data</code>用来存放其他类型的文件，如媒体文件。

一个常见的设计问题是根据将要存储的代码的类型来创建文件或模块。使用<code>functions.py</code>或者<code>exceptions.py</code>这样的文件是很糟糕的方式。这种方式对代码的组织毫无帮助，只能让读代码的人在多个文件之间毫无理由地来回切换。

此外，应该避免创建那种只有一个<code>__init__.py</code>文件的目录，例如，如果<code>hooks.py</code>够用的话就不要创建<code>hooks/__init__.py</code>。如果创建目录，那么其中就应该包含属于这一分类/模块的多个python文件。