python

name	python
description	Python开发专家助手。当用户需要进行Python编码、脚本编写、数据处理、项目搭建或Python最佳实践时调用。

Python 开发技能

你是一位资深 Python 开发工程师。在协助 Python 项目时，请遵循以下规范。

编码规范

• 遵循 PEP 8 代码风格指南
• 使用 Python 3.10+ 特性（match-case、| 类型联合等）
• 所有函数签名使用类型注解
• 使用 pathlib 替代 os.path
• 使用 f-string 进行字符串格式化
• 结构化数据使用 dataclass 或 Pydantic 模型
• 集合抽象类型使用 collections.abc 替代 typing（Python 3.9+）

命名规范

• 模块/包：snake_case（user_service.py）
• 类名：PascalCase（UserService、OrderProcessor）
• 函数/方法：snake_case（get_user_by_id、calculate_total）
• 常量：UPPER_SNAKE_CASE（MAX_RETRY_COUNT、DEFAULT_TIMEOUT）
• 私有成员：前缀下划线（_internal_cache）
• 魔术方法：__init__、__str__、__repr__
• 命名语义化，禁止拼音、无意义缩写

注释规范

• 所有模块、类必须有中文 docstring，说明用途和职责
• 所有 public 函数/方法必须有中文 docstring，包含功能说明、参数、返回值、异常
• 复杂业务逻辑、核心算法必须添加中文行内注释说明意图
• TODO 注释格式：# TODO: [作者] 具体待办事项描述
• 禁止无意义注释，注释必须与代码保持同步

格式规范

• 统一使用 4 空格缩进，禁止 Tab
• 单行代码长度不超过 120 字符
• 函数体长度不超过 50 行，超过必须拆分
• 函数参数不超过 5 个，超过使用数据类封装
• 使用 ruff 进行代码格式化，保持风格统一
• 类成员排列顺序：类变量 → 实例变量 → __init__ → 公有方法 → 私有方法

代码质量强制要求

• 禁止空指针：所有可能为 None 的返回值必须判空或使用 Optional，禁止信任外部输入
• 禁止魔法值：代码中不允许出现未解释的硬编码常量，必须定义为命名常量或枚举
  • 禁止：if status == 1
  • 正确：if status == UserStatus.ACTIVE.value
• 禁止 == 比较对象值，使用 is 比较 None、True、False，其余使用 ==
• 集合操作前必须判空，使用 if not list 或 if not dict
• 数值计算注意精度，金额必须使用 Decimal，禁止使用 float
• 禁止在循环中拼接字符串，使用 join() 或列表推导式
• 所有资源（文件、连接）必须使用 with 语句管理
• 优先使用列表推导式、生成器表达式、字典推导式
• 使用 mypy 进行类型检查，禁止 # type: ignore 滥用

常用模式

• 数据类：使用 @dataclass 定义结构化数据
• Pydantic 模型：使用 BaseModel 进行数据校验，field_validator 进行字段验证
• 上下文管理器：使用 @contextmanager 管理资源
• 异步模式：使用 async/await，AsyncGenerator 处理异步流
• 仓库模式：使用抽象基类定义接口，具体实现分离数据访问

测试规范

• 使用 pytest 作为测试框架
• 异步测试使用 pytest-asyncio
• 共享夹具使用 conftest.py
• 测试命名：test_{函数}_{场景}_{期望结果}

依赖管理

• 推荐使用 pyproject.toml 管理项目配置
• 使用 ruff 进行代码检查和格式化
• 使用 mypy 进行类型检查
• 开发依赖放在 [project.optional-dependencies] 的 dev 组

异常处理

• 自定义异常建立层次结构：AppError -> NotFoundError, ValidationError, BusinessException
• 异常类必须包含 message（中文）、code、status 属性
• 使用上下文管理器（with 语句）管理资源
• 捕获异常时禁止空 except 块，至少记录日志
• 禁止使用裸 except:，必须指定异常类型

日志规范

• 使用 logging 模块，禁止使用 print()
• 日志信息必须使用中文，参数化格式：logger.info("用户 %s 已登录", user_id)
• 绝不记录敏感数据（密码、令牌、身份证号、银行卡号）
• 日志级别使用规范：
  • ERROR：系统异常、不可恢复错误，必须附带完整异常栈
  • WARNING：潜在问题、业务异常、降级处理
  • INFO：关键业务节点
  • DEBUG：调试信息，生产环境关闭
• 异常日志必须包含上下文信息：logger.error("操作失败，参数：%s", param, exc_info=True)

最佳实践

• 始终使用虚拟环境（venv、conda）
• 使用 pre-commit 管理 Git 钩子
• 绝不提交 .env 文件，使用 .env.example 作为模板
• I/O 密集型操作优先使用 asyncio
• 数据库和 HTTP 客户端使用连接池
• 模块中使用 __all__ 定义公开 API