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

时间:2024-10-19 09:38:47

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

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

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

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

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

Package(包), Module(模块), file(文件) 三者关系,
Package由模块组成
包含功能代码的.py 代码文件也称为 module 模块, 但不能把 , __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) 项目根目录与包目录的区分

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

2) 项目根目录

主要有几类文件:

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

3) 包目录

包目录下主要有:

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

4) test目录

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

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

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

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

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
    │
    └─tests
            test_main.py

说明:

  1. 子包目录的, __init__.py文件内容分别如下:
 # 文件
 def demo():
    return "this is a demo function"

# __init__.py 文件
from .sample import demo 
# 或者 from sample import * 
  1. 在myproject/中
from app_sample import *
def main():
    return "main test"

print(main())
print(demo())

输出为:
main test
this is a demo function

也可以这样导入 中demo函数

from app_sample.sample import demo

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

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

project_root_directory
├──   # 项目配置文件,或者使用 , 
├── ...   # 如 , license等
└── src/
    └── mypkg/
        ├── __init__.py
        ├── ...
        ├── 
        |---- data
        |   |----- 
        |   |----   
        ├── subpkg1/
        │   ├── __init__.py
        │   ├── ...
        │   └── 
        └── subpkg2/
            ├── __init__.py
            ├── ...
            └── 

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

[]
where = ["src"]

[-data]
"*" = ["*.txt"]
mypkg = ["*.json","*.xml"]

包含测试文件夹的项目结构
采用 setuptool 构建的项目,如果不打包测试文件,就将测试文件夹移到 src/ 之 外,通常项目根目录下添加 tests/ 子目录,如下

project_root_directory
├──   # 项目配置文件,或者使用 , 
├── ...             # 如 , license等
├── src/
├──       # pytest配置文件
└── tests/          # 保存项目测试文件
         |----   __init__.py 
         |----   test_mypkg_module1.py 
         |----   test_xxx.py 
  ...

为了在测试文件中可以搜索到各个package,应将 src/ 绝对路径添加到环境变量 PYTHONPATH中。

set PYTHONPATH=D:\roject_root_path\src
# linux 下:export PYTHONPATH='/project_root_path/src

6. 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

7. 机器学习项目结构

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

sample/
├── data/
│   ├── external/
│   ├── interim/
│   ├── processed/
│   └── raw/
├── models/
├── notebooks/
├── sample/
│   ├── data/
│   ├── features/
│   └── model/
├── tests/
├── .gitignore
├── LICENSE
├── 
├── 
└── 

8. FastAPI 项目结构

FastAPI 框架采用异步框架,与Flask项目结构还是有区别的,主要通常会将 dependencies 与Data Model 代码分别放在两个子目录中保存。


my_fastapi_app/
│
├── src/
│   ├── __init__.py
│   ├── 
│   ├── routes/
│   │   ├── __init__.py
│   │   ├── users
│   │   ├── 
│   │   ├── 
│   │ 
│   ├── core/
│   │   ├── __init__.py
│   │   ├── 
│   │   ├── 
│   │   ├── 
│   │
│   ├── dependencies/
│   │   ├── __init__.py
│   │   ├── 
│   │
│   ├── models/
│   │   ├── __init__.py
│   │   ├── 
│   │   ├── another_example.py
│   │
│   ├── tests/
│   │   ├── __init__.py
│   │   ├── test_example.py
│   │   ├── test_another_example.py
│   │
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── 
│   │
├── .env
├── Dockerfile
├── 
├── 

说明

  • src/routers : 各个API 按功能分为不同的文件,也可以分成子包。
  • src/dependencies: 用于保存FastAPI路径函数的依赖, 这是FastAPI术语,注意不是python的第3方库。
  • src/core: 用于保存DataBase API, 项目配置文件等。
  • src/Models: FastAPI定义的Data Model 放在此文件夹。

总结

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

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