wehub-skill-sync
360 lines
7.6 KiB
Markdown
360 lines
7.6 KiB
Markdown
---
|
||
name: python-code-style
|
||
description: Python 代码风格、代码检查、格式化、命名规范与文档标准。适用于编写新代码、审查风格、配置代码检查工具、编写文档字符串或制定项目标准。
|
||
---
|
||
|
||
# Python 代码风格与文档
|
||
|
||
一致的代码风格和清晰的文档可以让代码库更易于维护和协作。本技能涵盖现代 Python 工具链、命名规范与文档标准。
|
||
|
||
## 何时使用本技能
|
||
|
||
- 为新项目配置代码检查和格式化工具
|
||
- 编写或审查文档字符串
|
||
- 制定团队编码标准
|
||
- 配置 ruff、mypy 或 pyright
|
||
- 审查代码的风格一致性
|
||
- 创建项目文档
|
||
|
||
## 核心概念
|
||
|
||
### 1. 自动化格式化
|
||
|
||
让工具来处理格式争论。一次配置，自动执行。
|
||
|
||
### 2. 一致的命名
|
||
|
||
遵循 PEP 8 规范，使用有意义且描述清晰的名称。
|
||
|
||
### 3. 文档即代码
|
||
|
||
文档字符串应与其所描述的代码保持同步维护。
|
||
|
||
### 4. 类型注解
|
||
|
||
现代 Python 代码中，所有公开 API 都应包含类型提示。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 安装现代工具链
|
||
pip install ruff mypy
|
||
|
||
# 在 pyproject.toml 中配置
|
||
[tool.ruff]
|
||
line-length = 120
|
||
target-version = "py312" # 根据项目的最低 Python 版本调整
|
||
|
||
[tool.mypy]
|
||
strict = true
|
||
```
|
||
|
||
## 基本模式
|
||
|
||
### 模式 1：现代 Python 工具链
|
||
|
||
使用 `ruff` 作为集代码检查与格式化为一体的一站式工具。它用一个快速工具取代了 flake8、isort 和 black。
|
||
|
||
```toml
|
||
# pyproject.toml
|
||
[tool.ruff]
|
||
line-length = 120
|
||
target-version = "py312" # 根据项目的最低 Python 版本调整
|
||
|
||
[tool.ruff.lint]
|
||
select = [
|
||
"E", # pycodestyle 错误
|
||
"W", # pycodestyle 警告
|
||
"F", # pyflakes
|
||
"I", # isort
|
||
"B", # flake8-bugbear
|
||
"C4", # flake8-comprehensions
|
||
"UP", # pyupgrade
|
||
"SIM", # flake8-simplify
|
||
]
|
||
ignore = ["E501"] # 行长度由格式化工具处理
|
||
|
||
[tool.ruff.format]
|
||
quote-style = "double"
|
||
indent-style = "space"
|
||
```
|
||
|
||
运行方式：
|
||
|
||
```bash
|
||
ruff check --fix . # 代码检查并自动修复
|
||
ruff format . # 格式化代码
|
||
```
|
||
|
||
### 模式 2：类型检查配置
|
||
|
||
为生产代码配置严格模式的类型检查。
|
||
|
||
```toml
|
||
# pyproject.toml
|
||
[tool.mypy]
|
||
python_version = "3.12"
|
||
strict = true
|
||
warn_return_any = true
|
||
warn_unused_ignores = true
|
||
disallow_untyped_defs = true
|
||
disallow_incomplete_defs = true
|
||
|
||
[[tool.mypy.overrides]]
|
||
module = "tests.*"
|
||
disallow_untyped_defs = false
|
||
```
|
||
|
||
备选方案：使用 `pyright` 以获得更快的检查速度。
|
||
|
||
```toml
|
||
[tool.pyright]
|
||
pythonVersion = "3.12"
|
||
typeCheckingMode = "strict"
|
||
```
|
||
|
||
### 模式 3：命名规范
|
||
|
||
遵循 PEP 8，以清晰性优先于简洁性。
|
||
|
||
**文件和模块：**
|
||
|
||
```python
|
||
# 好：描述性的 snake_case
|
||
user_repository.py
|
||
order_processing.py
|
||
http_client.py
|
||
|
||
# 避免：缩写
|
||
usr_repo.py
|
||
ord_proc.py
|
||
http_cli.py
|
||
```
|
||
|
||
**类和函数：**
|
||
|
||
```python
|
||
# 类：PascalCase
|
||
class UserRepository:
|
||
pass
|
||
|
||
class HTTPClientFactory: # 缩写保持大写
|
||
pass
|
||
|
||
# 函数和变量：snake_case
|
||
def get_user_by_email(email: str) -> User | None:
|
||
retry_count = 3
|
||
max_connections = 100
|
||
```
|
||
|
||
**常量：**
|
||
|
||
```python
|
||
# 模块级常量：SCREAMING_SNAKE_CASE
|
||
MAX_RETRY_ATTEMPTS = 3
|
||
DEFAULT_TIMEOUT_SECONDS = 30
|
||
API_BASE_URL = "https://api.example.com"
|
||
```
|
||
|
||
### 模式 4：导入组织
|
||
|
||
按一致的顺序分组导入：标准库、第三方库、本地模块。
|
||
|
||
```python
|
||
# 标准库
|
||
import os
|
||
from collections.abc import Callable
|
||
from typing import Any
|
||
|
||
# 第三方包
|
||
import httpx
|
||
from pydantic import BaseModel
|
||
from sqlalchemy import Column
|
||
|
||
# 本地导入
|
||
from myproject.models import User
|
||
from myproject.services import UserService
|
||
```
|
||
|
||
始终使用绝对导入：
|
||
|
||
```python
|
||
# 推荐
|
||
from myproject.utils import retry_decorator
|
||
|
||
# 避免相对导入
|
||
from ..utils import retry_decorator
|
||
```
|
||
|
||
## 进阶模式
|
||
|
||
### 模式 5：Google 风格的文档字符串
|
||
|
||
为所有公开的类、方法和函数编写文档字符串。
|
||
|
||
**简单函数：**
|
||
|
||
```python
|
||
def get_user(user_id: str) -> User:
|
||
"""根据唯一标识符获取用户。"""
|
||
...
|
||
```
|
||
|
||
**复杂函数：**
|
||
|
||
```python
|
||
def process_batch(
|
||
items: list[Item],
|
||
max_workers: int = 4,
|
||
on_progress: Callable[[int, int], None] | None = None,
|
||
) -> BatchResult:
|
||
"""使用工作池并发处理任务。
|
||
|
||
使用配置的工作线程数处理批次中的每个任务。
|
||
可通过可选的回调函数监控处理进度。
|
||
|
||
Args:
|
||
items: 待处理的任务列表。不能为空。
|
||
max_workers: 最大并发工作线程数。默认为 4。
|
||
on_progress: 可选回调函数，接收 (已完成数, 总数) 参数。
|
||
|
||
Returns:
|
||
BatchResult，包含处理成功的任务以及失败任务及其对应的异常信息。
|
||
|
||
Raises:
|
||
ValueError: 如果 items 为空。
|
||
ProcessingError: 如果批次无法处理。
|
||
|
||
Example:
|
||
>>> result = process_batch(items, max_workers=8)
|
||
>>> print(f"已处理 {len(result.succeeded)} 个任务")
|
||
"""
|
||
...
|
||
```
|
||
|
||
**类的文档字符串：**
|
||
|
||
```python
|
||
class UserService:
|
||
"""用户操作管理服务。
|
||
|
||
提供创建、获取、更新和删除用户的方法，
|
||
并包含适当的验证和错误处理。
|
||
|
||
Attributes:
|
||
repository: 用户持久化的数据访问层。
|
||
logger: 操作跟踪的日志记录器实例。
|
||
|
||
Example:
|
||
>>> service = UserService(repository, logger)
|
||
>>> user = service.create_user(CreateUserInput(...))
|
||
"""
|
||
|
||
def __init__(self, repository: UserRepository, logger: Logger) -> None:
|
||
"""初始化用户服务。
|
||
|
||
Args:
|
||
repository: 用户的数据访问层。
|
||
logger: 用于跟踪操作的日志记录器。
|
||
"""
|
||
self.repository = repository
|
||
self.logger = logger
|
||
```
|
||
|
||
### 模式 6：行长度与格式化
|
||
|
||
对于现代显示器，将行长度设置为 120 个字符，同时保持可读性。
|
||
|
||
```python
|
||
# 好：可读的换行
|
||
def create_user(
|
||
email: str,
|
||
name: str,
|
||
role: UserRole = UserRole.MEMBER,
|
||
notify: bool = True,
|
||
) -> User:
|
||
...
|
||
|
||
# 好：清晰的链式方法调用
|
||
result = (
|
||
db.query(User)
|
||
.filter(User.active == True)
|
||
.order_by(User.created_at.desc())
|
||
.limit(10)
|
||
.all()
|
||
)
|
||
|
||
# 好：格式化长字符串
|
||
error_message = (
|
||
f"处理用户 {user_id} 失败："
|
||
f"收到状态码 {response.status_code}，"
|
||
f"响应体为 {response.text[:100]}"
|
||
)
|
||
```
|
||
|
||
### 模式 7：项目文档
|
||
|
||
**README 结构：**
|
||
|
||
```markdown
|
||
# 项目名称
|
||
|
||
简要描述项目的功能。
|
||
|
||
## 安装
|
||
|
||
\`\`\`bash
|
||
pip install myproject
|
||
\`\`\`
|
||
|
||
## 快速开始
|
||
|
||
\`\`\`python
|
||
from myproject import Client
|
||
|
||
client = Client(api_key="...")
|
||
result = client.process(data)
|
||
\`\`\`
|
||
|
||
## 配置
|
||
|
||
说明环境变量和配置选项。
|
||
|
||
## 开发
|
||
|
||
\`\`\`bash
|
||
pip install -e ".[dev]"
|
||
pytest
|
||
\`\`\`
|
||
```
|
||
|
||
**CHANGELOG 格式（遵循 Keep a Changelog）：**
|
||
|
||
```markdown
|
||
# 更新日志
|
||
|
||
## [未发布]
|
||
|
||
### 新增
|
||
- 新功能 X
|
||
|
||
### 变更
|
||
- 修改了 Y 的行为
|
||
|
||
### 修复
|
||
- 修复了 Z 中的 Bug
|
||
```
|
||
|
||
## 最佳实践总结
|
||
|
||
1. **使用 ruff** —— 用于代码检查和格式化的单一工具
|
||
2. **启用 strict mypy** —— 在运行时之前捕获类型错误
|
||
3. **120 字符行长度** —— 现代可读性标准
|
||
4. **描述性命名** —— 清晰性优于简洁性
|
||
5. **绝对导入** —— 比相对导入更易于维护
|
||
6. **Google 风格的文档字符串** —— 一致、可读的文档
|
||
7. **记录公开 API** —— 每个公开函数都需要文档字符串
|
||
8. **保持文档更新** —— 将文档视为代码
|
||
9. **在 CI 中自动化** —— 每次提交都运行代码检查
|
||
10. **目标 Python 3.10+** —— 对于新项目，建议使用 Python 3.12+ 以获得现代语言特性
|