【Python】Python 项目目录结构

对于一个代码项目，好的目录结构是必不可少的。

我们为什么需要设计好的目录结构？

好的目录结构，意味着好的 可读性 和 可维护性，

可读性好：刚接触项目的人，一眼就能看懂目录结构，知道哪里是源码，哪里是 配置文件，哪里是文档，从而能够非常快速的了解这个项目
可维护性好：维护者能够很明确地知道，新增的文件跟代码应该放到什么目录，随着时间的推移，代码/配置的规模增加，项目结构不会混乱，仍然能够组织良好。

我们应该如何对项目目录合理地进行组织？

组织一个良好的项目目录其实不难。你并不需要从零开始造轮子，已经有人总结出了一些不错的目录结构并得到了大家的广泛共识，你只要能够理解其思想，会使用就够了。

项目目录结构的简单模板

假设你的项目名为foo，推荐的、比较方便的目录结构可以是这样，

Foo/
|-- bin/
|   |-- foo
|
|-- foo/
|   |-- tests/
|   |   |-- __init__.py
|   |   |-- test_main.py
|   |
|   |-- __init__.py
|   |-- main.py
|
|-- docs/
|   |-- conf.py
|   |-- abc.rst
|
|-- setup.py
|-- requirements.txt
|-- README

其中，

bin/: 存放项目的一些可执行文件，当然你可以起名script/之类的也行。
foo/: 存放项目的所有源代码。(1) 源代码中的所有模块、包都应该放在此目录。不要置于顶层目录。(2) 其子目录tests/存放单元测试代码； (3) 程序的入口最好命名为main.py。
docs/: 存放一些文档。
setup.py: 安装、部署、打包的脚本。
requirements.txt: 存放软件依赖的外部Python包列表。
README: 项目说明文件。

除此之外，有一些方案给出了更加多的内容。比如LICENSE.txt,ChangeLog.txt文件等，这里没有列出，因为这些东西主要是项目开源的时候需要用到。

项目说明 README

README每个项目都应该有的一个文件，作用是能够 简要描述该项目的信息，让读者快速了解这个项目。

它最好能够说明以下几个事项:

软件定位，软件的基本功能。
运行代码的方法: 安装环境、启动命令等。
简要的使用说明。
代码目录结构说明，更详细点可以说明软件的基本原理。
常见问题说明。

可以参考Redis源码中Readme的写法，这里面简洁但是清晰的描述了Redis功能和源码结构。

https://github.com/antirez/redis#what-is-redis

依赖包 requirements.txt 和 setup.py

配置文件 config

很多项目对配置文件的使用做法是:

配置文件写在一个或多个python文件中，比如此处的conf.py。
项目中哪个模块用到这个配置文件就直接通过import conf这种形式来在代码中使用配置。

实例解读

以流行的YOLOv3XmlGenerator的项目为例，大致的文件目录如下图所示

其中

README.md 项目介绍，一般包括使用的环境，安装的方法，软件的基本原理、测试数据及常见问题等，越详细越好
requirements.txt 记录依赖的软件包及对应的版本号，方便读者明确项目使用了哪些Python包，可以使用命令安装所有的依赖包pip install -r requirements.txt，另外，可以使用pipreqs这个工具来生成requirements.txt
setup.py，安装、部署、打包的脚本。
docs 文档目录，项目配置文件通常也放在这里，关于项目配置文件，可以看看这篇文章，讲的比较全 https://martin-thoma.com/configuration-files-in-python/
extras 有时候会使用到一些C/C++库，一般放在这个文件夹里
scripts 存放脚本文件，比如代码仓库不适合存放很大的二进制文件，这时候可以写个脚本去拉取
yolov3xmlgenerator 项目源码文件夹，入口文件建议命名为main.py，再配上__init__.py文件，另外，单元测试的代码也放在这块

下面的东西主要是项目开源的时候需要用到

LICENSE 协议文件，可以参考这篇文章 https://www.jianshu.com/p/a57c13631d5e，讲的很详细
ChangeLog.txt 记录版本发布的release note
.gitignore 如果使用的是git代码管理工具，表明上传时忽略的文件，如果您使用的是svn，请忽略

参考：

python 软件目录结构规范

Python工程目录结构

[3] 结构化您的工程

5.1. 代码结构 |《Python 最佳实践指南 2018 2018》| Python 技术论坛