Python 编码规范

Python 代码实现阶段的统一基线，覆盖类型、日志、命名与结构要求。

⚠️ 核心强制要求

1. 类型提示

所有函数、方法、类声明必须补全类型提示。

• 缺值返回使用 -> None

• 公共 API 必须提供完整 docstring（参数、返回值、异常）

2. 日志规范

业务代码统一通过 src.logger.setup_logger 获取 logger，禁止使用 print 。

• 测试示例代码除外

• 错误路径必须使用 logger.error 或 logger.exception

AI Agent 行为要求

创建新文件时

• 必须添加类型提示

• 必须使用 logger（禁止 print）

修改现有文件时

• 新增代码必须符合类型提示要求

• 新增日志必须使用 logger

代码审查时

• 检查类型提示完整性

• 检查是否使用了 print

验收标准

• 所有函数、方法、类有类型提示

• 公共 API 有完整 docstring

• 关键模块的日志覆盖正常运行与异常分支

参考资料

• references/type-hints.md

• 类型提示详细规范

• references/logging.md

• 日志规范详细说明

• references/naming-conventions.md

• 命名约定详细说明

• references/code-structure.md

• 代码结构详细说明