Python目录规范

Python目录规范
https://mp.weixin.qq.com/s/uJcdf2eTPB-NDFlLiYBQ9g

1. 概述

这目录规范分为两级：

• 一级目录是必须遵守的规范，像文档、代码、数据、配置、日志、工具、测试这 7 大类目录；
• 二级目录就灵活多了，根据实际情况调整。而且，代码目录（src）还能按功能复杂程度分为复杂项目和简单项目两种情况。

# 标准项目结构示例
project_root/
├── docs/            # 文档中心：项目说明、API文档
├── src/             # 核心代码区：业务逻辑主战场
│   ├── interface/   # 接口层
│   └── service/     # 服务层
│   └── ……
├── data/            # 数据仓库：原始数据与加工数据
├── conf/            # 配置中心：所有配置文件
├── logs/            # 运行日志：项目执行历史
├── tools/           # 工具库：数据运维脚本
└── test/            # 测试区：单元测试与验证

2. 一级目录介绍

2.1 docs 目录（文档目录）

这可是项目的说明书，得好好写。

• README.md ：项目门面担当，打开项目第一个看到的就是它。里面要简明扼要地写项目介绍、功能、运行环境、安装步骤、运行方法、测试报告位置等基本信息。比如：

# 项目名称：数据分析小助手
# 功能：实现数据清洗、分析和可视化
# 运行环境：Python 3.8+、pandas、matplotlib
# 安装步骤：pip install -r requirements.txt
# 运行方法：python main.py
# 测试报告位置：test/test_report.html

• 代码说明文档 ：详细记录每个模块的功能、类和方法的作用、输入输出等，方便后续维护和别人查看。比如对一个数据清洗模块的说明：

# 模块：data_cleaning
# 功能：对原始数据进行清洗，包括去除重复值、处理缺失值、异常值检测等
# 类：DataCleaner
# 方法：
#   __init__(data)：初始化，传入原始数据
#   remove_duplicates()：去除重复值
#   handle_missing_values(strategy)：处理缺失值，strategy 可选"删除"、"均值填充"、"中位数填充"等
#   detect_outliers(method)：异常值检测，method 可选"Z-Score"、"IQR"等

• 代码部署文档 ：写清楚如何将代码部署到生产环境，包括服务器环境配置、部署步骤、启动停止方法等。比如：

# 部署步骤：
# 1. 在服务器上创建项目目录：mkdir /data/analytics_project
# 2. 将代码拷贝到服务器：scp -r * username@server:/data/analytics_project
# 3. 安装项目依赖：cd /data/analytics_project && pip install -r requirements.txt
# 启动方法：python /data/analytics_project/main.py --env production
# 停止方法：通过任务管理器或进程 ID 停止 python 进程

2.2 src 目录（代码目录）

这可是放核心代码的地儿。

2.2.1 复杂项目中的目录结构

• interface ：接口处理层，负责接收外部请求、验证参数等。比如一个接口文件：

from flask import Flask, request, jsonify
app = Flask(__name__)

@app.route('/api/data_analysis', methods=['POST'])
def data_analysis_interface():
    # 验证请求参数
    ifnot request.json or'data'notin request.json:
        return jsonify({'error': 'Invalid request data'}), 400
    # 调用业务处理层
    from service.data_analysis_service import analyze_data
    result = analyze_data(request.json['data'])
    return jsonify({'result': result})

• service ：业务处理层，包含项目的核心业务逻辑。比如数据处理业务逻辑：

def analyze_data(data):
    # 数据分析业务逻辑
    # 示例：计算数据的平均值、最大值、最小值
    avg = sum(data) / len(data)
    max_val = max(data)
    min_val = min(data)
    return {'average': avg, 'max': max_val, 'min': min_val}

• module ：模块功能层，将相关的功能封装成模块。比如一个数据可视化模块：

import matplotlib.pyplot as plt

class DataVisualizer:
    def __init__(self, data):
        self.data = data

    def plot_line_chart(self):
        # 绘制折线图
        plt.plot(self.data)
        plt.title('Data Trend')
        plt.xlabel('Index')
        plt.ylabel('Value')
        plt.savefig('line_chart.png')
        plt.close()

• common ：通用工具层，放一些通用的工具函数或类。比如常用的数据处理工具：

def is_valid_data(value):
    # 判断数据是否有效（非空、非异常值等）
    return value isnotNoneandnot isinstance(value, (str, bool)) and abs(value) < 1e10

def format_date(date_str):
    # 格式化日期字符串
    from datetime import datetime
    try:
        return datetime.strptime(date_str, '%Y-%m-%d').strftime('%Y-%m-%d')
    except ValueError:
        returnNone

• utils ：第三方工具层，放一些对第三方库的封装或工具类。比如对 pandas 的封装工具：

import pandas as pd

def read_csv_with_encoding(file_path, encoding='utf-8'):
    # 尝试用不同编码读取 CSV 文件
    encodings = ['utf-8', 'gbk', 'latin-1']
    for enc in encodings:
        try:
            return pd.read_csv(file_path, encoding=enc)
        except UnicodeDecodeError:
            continue
    return pd.DataFrame()

2.2.2 简单模型中的目录结构

• predict ：模型预测相关的代码。比如一个简单的预测脚本：

import pickle
import numpy as np

# 加载训练好的模型
with open('model.pkl', 'rb') as f:
    model = pickle.load(f)

def predict(data):
    # 预测函数
    data_array = np.array(data).reshape(1, -1)
    prediction = model.predict(data_array)
    return prediction[0]

• train ：模型训练相关的代码。比如训练脚本：

from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
import pickle

# 生成模拟数据
X, y = make_classification(n_samples=1000, n_features=20, n_classes=2)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

# 训练模型
model = RandomForestClassifier()
model.fit(X_train, y_train)

# 保存模型
with open('model.pkl', 'wb') as f:
    pickle.dump(model, f)

2.3 data 目录（数据目录）

存放项目所需的基础数据，比如 POI 词典数据等。数据文件可以是 CSV、Excel 等格式。

比如一个 POI 词典数据文件（poi_dict.csv）：

id,poi_type,name
1,餐饮,"麦当劳"
2,餐饮,"肯德基"
3,酒店,"如家酒店"
4,酒店,"汉庭酒店"

2.4 conf 目录（配置目录）

• config.py ：代码配置文件，放一些项目的配置参数。比如：

# 数据库配置
DB_CONFIG = {
    'host': 'localhost',
    'port': 3306,
    'user': 'root',
    'password': 'password',
    'database': 'analytics_db'
}

# 模型超参数
MODEL_PARAMS = {
    'n_estimators': 100,
    'max_depth': 10,
    'learning_rate': 0.1
}

• logging.conf ：日志配置文件，可以配置日志的输出格式、级别、文件路径等。比如：

[loggers]
keys=root

[handlers]
keys=consoleHandler,fileHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=DEBUG
handlers=consoleHandler,fileHandler

[handler_consoleHandler]
class=StreamHandler
level=INFO
formatter=simpleFormatter
args=(sys.stdout,)

[handler_fileHandler]
class=FileHandler
level=DEBUG
formatter=simpleFormatter
args=('app.log', 'a')

[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
datefmt=%Y-%m-%d %H:%M:%S

2.5 logs 目录（日志目录）

• 业务应用日志 ：记录项目运行过程中的业务相关操作和信息。比如：

import logging
from logging.config import fileConfig

fileConfig('conf/logging.conf')
logger = logging.getLogger()

def process_order(order_id):
    logger.info(f"Processing order {order_id}")
    # 业务逻辑处理
    logger.debug(f"Order {order_id} details: ...")
    logger.info(f"Order {order_id} processed successfully")

• 底层框架日志 ：记录底层框架（如 Flask、Django 等）的日志信息。比如 Flask 的日志：

from flask import Flask
app = Flask(__name__)

@app.route('/')
def home():
    app.logger.info("Home page accessed")
    return "Welcome to Analytics Project"

2.6 tools 目录（工具目录）

• data_operation.sh ：数据运维工具，比如用来补数据的脚本。比如：

#!/bin/bash
# 补数据脚本
echo "Starting data backfill..."
python src/data_backfill.py --start_date 2024-01-01 --end_date 2024-01-31
echo "Data backfill completed"

• perf_analysis.sh ：性能分析工具。比如：

#!/bin/bash
# 性能分析脚本
echo "Starting performance analysis..."
python -m cProfile src/main.py > perf_analysis.log
echo "Performance analysis completed, results saved to perf_analysis.log"

• log_analysis.sh ：日志分析工具。比如：

#!/bin/bash
# 日志分析脚本
echo "Starting log analysis..."
grep "ERROR" logs/app.log | awk '{print $1, $2, $NF}' > error_log_analysis.log
echo "Log analysis completed, error logs saved to error_log_analysis.log"

2.7 test 目录（测试目录）

包含测试报告、测试数据、测试脚本等。比如一个测试脚本（test_data_cleaning.py）：

import unittest
from src.module.data_cleaning import DataCleaner

class TestDataCleaning(unittest.TestCase):
    def setUp(self):
        self.raw_data = [1, 2, None, 4, 5, 'invalid', 10000000000]
        self.cleaner = DataCleaner(self.raw_data)

    def test_remove_duplicates(self):
        cleaned_data = self.cleaner.remove_duplicates()
        self.assertEqual(len(cleaned_data), len(set(cleaned_data)))

    def test_handle_missing_values(self):
        handled_data = self.cleaner.handle_missing_values(strategy="均值填充")
        self.assertFalse(Nonein handled_data)

    def test_detect_outliers(self):
        outliers = self.cleaner.detect_outliers(method="Z-Score")
        self.assertIn(10000000000, outliers)

if __name__ == '__main__':
    unittest.main()

3. 目录规范的应用场景和示例

3.1 项目开发中的目录规范应用

在开发一个数据分析项目时，严格按照目录规范来操作。

1. 先在 docs 目录写好 README.md ，介绍项目的基本信息。
2. 把核心代码按照业务逻辑、模块功能等分别放在 src/interface 、src/service 、src/module 等子目录。
3. 准备好项目需要的数据文件，放到 data 目录。
4. 在 conf 目录配置好数据库、模型参数等配置文件。
5. 开启项目后，日志会自动输出到 logs 目录。
6. 编写好数据处理、性能分析等工具脚本，放到 tools 目录。
7. 项目开发过程中，不断补充和完善 docs 目录中的代码说明文档。
8. 最后，在 test 目录编写测试脚本，对项目进行全面测试。

3.2 团队协作中的目录规范重要性

当多个小伙伴一起开发一个项目时，目录规范就像团队的 “暗号”，让大家能快速明白彼此的代码结构。

• 代码交接 ：新来的小伙伴只要熟悉了目录规范，就能快速上手，找到需要修改或添加功能的代码位置。比如，想修改接口参数验证规则，就直接去 src/interface 目录找对应的接口文件。
• 协同开发 ：不同小伙伴负责不同模块的开发，按照目录规范，大家各司其职，避免了代码混乱和重复劳动。比如，A 同事负责业务逻辑层（src/service ）的开发，B 同事负责通用工具层（src/common ）的开发，大家互不干扰。

4. 最后

内容有点多，不好掌握？

不用担心，按照上面的规范进行第一个项目时，可能会觉得比较约束比较多，但是只要做了几个项目后，就会发现代码目录井井有条，工作极其高效，妥妥的专业范儿！