一、Python一般项目结构

Python项目的目录结构是一种以文件夹为基本单元的树形结构，按照一定的标准，把不同的文件和文件夹分类放在合适的位置，用于定义和组织代码，以便能够轻松地定位和索引相关代码。其有助于我们存储、开发和发布代码库，保证开发过程顺利进行，同时便于我们运行、测试和部署代码。下面我们简单介绍一下Python项目的目录结构。

通常情况下，Python项目的目录结构包含以下几个文件夹：

- config: 一般存放项目需要的配置文件；
- data: 一般存储该Python项目测试数据；
- src: 主要用于存放源代码。它包含所有的.py文件；
- docs: 存放项目相关文档；
- tests: 用于存放测试脚本；
- utils: 常用工具类包，读写文件、配置、简单数据处理等工具函数；
- scripts: 存储一些shell脚本或工具；
- README.md: 项目介绍，一般包括使用的环境，安装的方法，软件的基本原理、测试数据及常见问题等，越详细越好；
- requirements.txt: 记录项目依赖的软件包及对应的版本号，明确项目使用了哪些Python包，可以使用命令安装所有的依赖包pip install -r requirements.txt，具体requirements.txt文件生成，详见下一小节；
- setup.py: 安装、部署、打包的脚本，python打包工具setuptools。

如果项目是开源项目，则可能还会包括下面几个文件

- LICENSE: 协议文件，可参考开源许可协议
- ChangeLog.txt: 记录版本发布的release note
- .gitignore: 项目代码管理工具git的过滤文件，表明上传代码时要忽略的文件；

当然，以上目录也并不是绝对一成不变的，只是一个建议，另外，除了以上项目目录，可能还会包含一些可选的目录，例如lib，api等等，这里不再赘述。下面给出一个具体项目目录结构，如图1所示

二、项目依赖自动生成

一个Python项目，多多少少都会依赖一些外部的包，本节我们就介绍一下Python项目如何自动生成项目的依赖文件requirements.txt以及其使用方式。项目依赖文件requirements.txt，主要有两种生成方法，一种是依赖python自带的包管理工具pip的方式；一种是依赖第三方库pipreqs的方式。下面分别介绍一下这两种方法。

pip freeze方法

pip freeze > requirements.txt

在项目根目录下，运行上面这条命令，会在当前目录下生成一个requirements.txt文件。但这里要强调一点，使用此种方式生成的requirements.txt文件，包括了当前整个Python环境的包，某些包也包含了@file路径。这时，如果我们使用下面的命令

pip install -r requirements.txt

安装包时，就会遇到如下的错误：

此时，我们可以利用下面的命令生成不包含@file路径的requirements.txt文件，具体命令如下所示 ：

pip list --format=freeze > requirements.txt

然后，我们可以进一步使用下面的命令，具体地排除某个包，命令如下：

pip freeze --exclude 包名 > requirements.txt 或
pip list --format=freeze --exclude 报名 > requirements.txt

我们可以看到，通过以上命令，我们得到的是当前Python环境安装的所有的包，不仅包括了项目需要依赖的包，还包括了项目不需要依赖的包。那么，有没有方法，可以精准地得到就是当前项目依赖的包文件呢？答案是，必须滴！具体方法见下文。

pipreqs方法

这是一个Python第三方的库，这个工具的优点就是可以对项目目录进行扫描，自动发现当前项目使用了哪些类库或包，生成项目依赖清单。但是也有缺点，就是生成的依赖清单可能存在偏差，需要自己手动修改下。我们使用下面的命令来安装pipreqs

pip install pipreqs

然后，我们可以使用下面的命令，来生成项目依赖清单

pipreqs 当前项目根目录 --encoding=utf-8 --force

pipreqs用法说明

options：
--use-local 仅使用本地包信息而不查询 PyPI
--pypi-server <url> 使用自定义的 PyPi 服务器
--proxy <url> 使用代理，参数将被传递给 requests 库。您也可以在终端中设置环境参数：
$ export HTTP_PROXY=&#;http://:&#;
$ export HTTPS_PROXY=&#;https://:&#;
--debug 打印调试信息
--ignore <dirs>... 忽略额外的目录，每个目录之间用逗号分隔
--no-follow-links 不跟随项目中的符号链接
--encoding <charset> 使用文件打开的编码参数
--savepath <file> 将要求列表保存到指定的文件中
--print 将要求列表输出到标准输出
--force 覆盖现有的 requirements.txt 文件
--diff <file> 将 requirements.txt 文件中的模块与项目导入的模块进行比较
--clean <file> 清理 requirements.txt 文件，删除项目中未导入的模块
--mode <scheme> 启用 <compat>、<gt> 或 <non-pin> 方案的动态版本控制

依赖文件使用方式

在生成了项目依赖清单文件之后，我们可以利用下面的方式来一键安装所有依赖包或库

pip install -r requirements.txt

以上我们就介绍完了Python的一般项目目录结构，以及Python项目自动生成项目依赖清单文件requirements.txt的方法。

Reference

[1]. https://pip.pypa.io/en/stable/cli/pip_freeze/

[2]. https://github.com/bndr/pipreqs