Python 项目布局

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

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

• 不会偶尔被 setuptools（或者其他打包库）作为 tests 顶层模块自动安装；
• 能够被安装，且被其他包用于构建自己的单元测试。

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

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

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

常用的还有： setup.cfg、MANIFEST.in、LICENSE.txt

• setup.cfg： 包含 setup.py 默认命令选项的 ini 文件
• MANIFEST.in：当需要打包源码中不自动包含的附加文件时使用
• LICENSE.txt： 发行许可文件

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

• etc 用来存放配置文件的样例
• tools 用来存放与工具有关的shell脚本
• bin 用来存放将被setup.py安装的二进制脚本
• data 用来存放其他类型的文件，如媒体文件

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

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

---

快速生成项目结构

这里介绍两款工具： hatch、cookiecutter

hatch

创建项目（不带虚拟环境）

C:\Users\acer\Desktop>hatch new myapp -ne  
Unable to locate config file; try `hatch config --restore`. The default project structure will be used.
Created project `myapp`

C:\Users\acer\Desktop>tree myapp /f
C:\USERS\ACER\DESKTOP\MYAPP
│ .coveragerc        # coverage 代码覆盖率配置文件
│ .gitattributes
│ .gitignore
│ LICENSE-APACHE
│ LICENSE-MIT
│ MANIFEST.in
│ pyproject.toml    # PEP 518 用于处理构建系统的依赖关系
│ README.rst
│ requirements.txt
│ setup.py
│ tox.ini        # tox（python标准化测试）配置文件
│
├─myapp
│ __init__.py
│
└─tests
        __init__.py

cookiecutter
选择一个模板（这里选择 python 通用模板）

cookiecutter https://github.com/audreyr/cookiecutter-pypackage.git

C:\Users\acer\Desktop>tree python_boilerplate /f
C:\USERS\ACER\DESKTOP\PYTHON_BOILERPLATE
│ .editorconfig
│ .gitignore
│ .travis.yml
│ AUTHORS.rst
│ CONTRIBUTING.rst
│ HISTORY.rst
│ LICENSE
│ Makefile
│ MANIFEST.in
│ README.rst
│ requirements_dev.txt
│ setup.cfg
│ setup.py
│ tox.ini
│
├─.github
│ ISSUE_TEMPLATE.md
│
├─docs
│ .gitignore
│ authors.rst
│ conf.py
│ contributing.rst
│ history.rst
│ index.rst
│ installation.rst
│ make.bat
│ Makefile
│ readme.rst
│ usage.rst
│
├─python_boilerplate
│ cli.py
│ python_boilerplate.py
│ __init__.py
│
└─tests
        test_python_boilerplate.py
        __init__.py