python

🐍 Python 开发规则

版本: v4.3.0 | 最后更新: 2026-01-15 | 作者: wangqiqi (https://github.com/wangqiqi)

🎯 适用场景

• Django/Flask/FastAPI Web 应用开发
• 数据科学和机器学习项目
• 自动化脚本和工具开发
• API 服务和微服务架构

🏗️ 项目结构

推荐的项目布局

my_project/
├── src/                    # 源代码目录
│   ├── __init__.py
│   ├── main.py            # 应用入口
│   └── my_module/         # 功能模块
│       ├── __init__.py
│       ├── models.py      # 数据模型
│       ├── views.py       # 视图/控制器
│       ├── services.py    # 业务逻辑
│       └── utils.py       # 工具函数
├── tests/                 # 测试目录
│   ├── __init__.py
│   ├── test_models.py
│   └── test_services.py
├── docs/                  # 文档
├── requirements.txt       # 依赖管理
├── pyproject.toml         # 项目配置 (现代)
├── setup.py              # 包安装配置
├── .env                  # 环境变量
├── .gitignore
└── README.md

📝 编码规范

PEP 8 合规

• 行长度: 最多79个字符（Docstring 72个字符）
• 缩进: 4个空格，无Tab
• 命名: snake_case for 函数和变量，CamelCase for 类

# ✅ 推荐的命名和结构
class UserService:
    """用户服务类，处理用户相关的业务逻辑。"""

    def __init__(self, db_connection):
        self.db = db_connection
        self._cache = {}

    def get_user_by_id(self, user_id: int) -> Optional[User]:
        """根据用户ID获取用户信息。

        Args:
            user_id: 用户的唯一标识符

        Returns:
            用户对象，如果不存在则返回None

        Raises:
            ValueError: 当user_id无效时
        """
        if not isinstance(user_id, int) or user_id <= 0:
            raise ValueError("用户ID必须是正整数")

        # 检查缓存
        if user_id in self._cache:
            return self._cache[user_id]

        # 查询数据库
        user = self.db.query("SELECT * FROM users WHERE id = ?", user_id)

        # 更新缓存
        if user:
            self._cache[user_id] = user

        return user

类型注解 (Python 3.5+)

from typing import List, Dict, Optional, Union
from dataclasses import dataclass

@dataclass
class User:
    id: int
    name: str
    email: str
    is_active: bool = True

def process_users(users: List[User]) -> Dict[str, int]:
    """处理用户列表，返回统计信息。"""
    stats = {"total": 0, "active": 0}

    for user in users:
        stats["total"] += 1
        if user.is_active:
            stats["active"] += 1

    return stats