Back to Details

python-coding-standards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python 编码规范

Python Coding Standards

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

Unified baseline for Python code implementation phase, covering requirements for types, logging, naming and structure.

⚠️ 核心强制要求

⚠️ Core Mandatory Requirements

1. 类型提示

1. Type Hints

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

缺值返回使用
```
-> None
```
公共 API 必须提供完整 docstring（参数、返回值、异常）

All functions, methods, and class declarations must complete type hints.

Use
```
-> None
```
for return values with no data
Public APIs must provide complete docstrings (parameters, return values, exceptions)

2. 日志规范

2. Logging Specifications

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

测试示例代码除外
错误路径必须使用
```
logger.error
```
或
```
logger.exception
```

Business code must uniformly obtain logger through
src.logger.setup_logger
, and
print
is prohibited.

Except for test sample code
Error paths must use
```
logger.error
```
or
```
logger.exception
```

AI Agent 行为要求

AI Agent Behavior Requirements

创建新文件时

When Creating New Files

必须添加类型提示
必须使用 logger（禁止 print）

Must add type hints
Must use logger (print is prohibited)

修改现有文件时

When Modifying Existing Files

新增代码必须符合类型提示要求
新增日志必须使用 logger

Newly added code must comply with type hint requirements
Newly added logs must use logger

代码审查时

During Code Review

检查类型提示完整性
检查是否使用了 print

Check completeness of type hints
Check if print is used

验收标准

Acceptance Criteria

所有函数、方法、类有类型提示
公共 API 有完整 docstring
关键模块的日志覆盖正常运行与异常分支

All functions, methods, and classes have type hints
Public APIs have complete docstrings
Logs of key modules cover normal operation and exception branches

参考资料

Reference Materials

```
references/type-hints.md
```
- 类型提示详细规范
```
references/logging.md
```
- 日志规范详细说明
```
references/naming-conventions.md
```
- 命名约定详细说明
```
references/code-structure.md
```
- 代码结构详细说明

```
references/type-hints.md
```
- Detailed specifications for type hints
```
references/logging.md
```
- Detailed explanation of logging specifications
```
references/naming-conventions.md
```
- Detailed explanation of naming conventions
```
references/code-structure.md
```
- Detailed explanation of code structure