各类Python项目的项目结构及代码组织最佳实践

1. 了解Python项目文件组织结构非常重要

为什么要掌握python项目结构？

• 优秀的程序员都使用规范的项目代码结构，了解这些好的习惯方式，有助于快速读懂代码
• 如果项目是几个人合作开发，好的代码结构，便于分工，减少混乱，使项目开发过程更顺畅。
• 采用规范的项目结构，也便于项目打包、编译、在社区共享。

本文将为您介绍： 项目结构预备知识，基本项目结构 ，带多个子包的项目结构，Flask项目结构，机器学习项目结构等常见类型的项目结构，有疑问，欢迎留言

预备知识：Package包, Module模块与 fiile文件的关系

Package(包), Module(模块), file(文件） 三者关系，
Package由模块组成
包含功能代码的.py 代码文件也称为 module 模块， 但不能把 config.py , __init__.py称为模块。

预备知识： 包与目录的关系

虽然在形式上，可以把1个包理解为1个目录，但并非是包含代码的目录都是包，

二者区分的关键是， 包目录包含 __init__.py 文件，不包含此文件的不能称之为包目录。

2. 应用最广泛的 python 项目结构的基本形式

本文介绍的python项目结构适合于中小型项目， 应用非常广泛，初学者应该养成好习惯，一开始就用这种方式来组织自己的代码。

假设新建项目的名称为 myproject, 可以在windows或 linux终端， 创建如下项目结构

└─myproject │ .gitignore │ LICENSE │ readme.md │ requirements.txt │ setup.py │ ├─myproject │ main.py │ util.py │ __init__.py │ └─test test_main.py

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15

说明如下：

1) 项目根目录与包目录的区分

第1层 myproject 是项目根目录，第2级 myproject 才是包目录，为什么这样组织，主要是基于好的实践经验，项目根目录主要用于存放配置，手册，启动文件等。 而主要功能都放在package包中，Pythton包的具体组织形式就是1个子目录，由于是基本项目，功能不多，只有1个包，因此用项目同名做为包名，所有实现代码放在 ·myproject/myproject· 目录下。

2) 项目根目录

主要有几类文件：

• setup.py 文件，或者 pyproject.toml, 这是要项目打包配置文件
• readme.md , 或 readme.rst，项目说明书
• requirements.txt， 第3方依赖库列表
• License， 许可说明文件
• .gitignore 如果使用git 做为仓库，这个文件说明哪些文件不上传

3) 包目录

包目录下主要有:

1. 包目录下还必须有1个__init__.py文件，（参考 Python项目中的 init.py的作用及内容 )n
2. python实现代码 .py文件。

4) test目录

主要保存测试文件，都是test开头文件。

3. 再简化：命令行式项目的结构

对于1个非常简单的程序 ，还可以简化为如下形式

sample/ ├── .gitignore ├── LICENSE ├── README.rst ├── requirements.txt ├── sample.py ├── setup.py └── test_sample.py

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8

4. 带子应用的项目结构

如果项目功能较多，有几个开发者，可以把项目拆分，分成几个子包来开发。在 myproject的主包目录下创建子包目录

└─myproject │ .gitignore │ LICENSE │ readme.md │ requirements.txt │ setup.py │ ├─myproject │ │ main.py │ │ util.py │ │ __init__.py │ │ │ ├─app_sample │ │ │ sample.py │ │ │ __init__.py │ │ │ │ │ └─__pycache__ │ │ sample.cpython-39.pyc │ │ __init__.cpython-39.pyc │ │ │ └─__pycache__ │ main.cpython-39.pyc │ __init__.cpython-39.pyc │ └─test test_main.py

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19
• 20
• 21
• 22
• 23
• 24
• 25
• 26
• 27

说明:

1. 子包目录的sample.py, __init__.py文件内容分别如下：

# sample.py文件 def demo(): return "this is a demo function" # __init__.py 文件 from .sample import demo # 或者 from sample import *

• 1
• 2
• 3
• 4
• 5
• 6
• 7

2. 在myproject/main.py中

from app_sample import * def main(): return "main test" print(main()) print(demo())

• 1
• 2
• 3
• 4
• 5
• 6
• 7

输出为：
main test
this is a demo function

也可以这样导入 sameple.py 中demo函数

from app_sample.sample import demo

• 1

4. 适用于 setuptools 构建工具的项目结构

python包管理工具，setuptools 已取代distutils，当然也可以使用 Poetry ，python建议使用 pyproject.toml 做为打包配置文件，下面给出了1个流行的项目结构，适用于商业化Python项目。

project_root_directory ├── pyproject.toml # 项目配置文件，或者使用 setup.cfg, setup.py ├── ... # 如 readme.rst, license等 └── src/ └── mypkg/ ├── __init__.py ├── ... ├── module.py |---- data | |----- data1.json | |---- data2.xml ├── subpkg1/ │ ├── __init__.py │ ├── ... │ └── module1.py └── subpkg2/ ├── __init__.py ├── ... └── module2.py

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19
• 20

上述结构中，mypkg下还包含1个data文件夹，包含了项目使用的数据文件，当然也可以添加更多公共文件夹，如 static/,/meida/, log/ 等.
可以在pyproject.toml 添加模块搜索路径以及数据文件配置

[tool.setuptools.packages.find] where = ["src"] [tool.setuptools.package-data] "*" = ["*.txt"] mypkg = ["*.json","*.xml"]

• 1
• 2
• 3
• 4
• 5
• 6

5. Flask 项目结构

与django不同， django-admin startproject 可自动生成项目结构，而Flask项目结构需要自己来构建，1个结构良好的项目结构形式，要考虑子应用隔离，模型，模板文件、静态文件等路径，
下面是推荐的 Flask项目结构:

flaskr-tutorial/ ├── flaskr/ │ ├── ___init__.py │ ├── db.py │ ├── schema.sql │ ├── auth.py │ ├── blog.py │ ├── templates/ │ │ ├── base.html │ │ ├── auth/ │ │ │ ├── login.html │ │ │ └── register.html │ │ └── blog/ │ │ ├── create.html │ │ ├── index.html │ │ └── update.html │ └── static/ │ └── style.css ├── tests/ │ ├── data.sql │ ├── test_auth.py │ ├── test_blog.py │ ├── test_conf.py │ ├── test_db.py │ └── test_factory.py ├── venv/ ├── .gitignore ├── setup.py └── MANIFEST.in

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19
• 20
• 21
• 22
• 23
• 24
• 25
• 26
• 27
• 28
• 29

6. 机器学习项目结构

机器学习项目是python应用的重要方向，此类项目的特点是，需要有源数据、算法模型目录（注意不是django, flask 的模型)，生产环境通常还需要集成 Flask 提供web服务，典型的项目结构如下：

sample/ ├── data/ │ ├── external/ │ ├── interim/ │ ├── processed/ │ └── raw/ ├── models/ ├── notebooks/ ├── sample/ │ ├── data/ │ ├── features/ │ └── model/ ├── tests/ ├── .gitignore ├── LICENSE ├── README.rst ├── requirements.txt └── setup.py

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18

总结

本文描述的python最流行的基本项目结构形式，后续继续给大家介绍，多应用项目，web项目，AI类应用项目结构的建议。

关于项目打包与部署相关知识, 可参考本博主其它文章：
Python项目打包与部署(三)：打包与部署的实际操作流程