Files

T

wehub-skill-sync f67cb7e9d2 chore: import zh skill python-code-style

2026-07-13 21:36:00 +08:00

7.6 KiB

Raw Permalink Blame History

name, description

name	description
python-code-style	Python 代码风格、代码检查、格式化、命名规范与文档标准。适用于编写新代码、审查风格、配置代码检查工具、编写文档字符串或制定项目标准。

Python 代码风格与文档

一致的代码风格和清晰的文档可以让代码库更易于维护和协作。本技能涵盖现代 Python 工具链、命名规范与文档标准。

何时使用本技能

为新项目配置代码检查和格式化工具
编写或审查文档字符串
制定团队编码标准
配置 ruff、mypy 或 pyright
审查代码的风格一致性
创建项目文档

核心概念

1. 自动化格式化

让工具来处理格式争论。一次配置，自动执行。

2. 一致的命名

遵循 PEP 8 规范，使用有意义且描述清晰的名称。

3. 文档即代码

文档字符串应与其所描述的代码保持同步维护。

4. 类型注解

现代 Python 代码中，所有公开 API 都应包含类型提示。

快速开始

# 安装现代工具链
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。

# 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"

运行方式：

ruff check --fix .  # 代码检查并自动修复
ruff format .       # 格式化代码

模式 2：类型检查配置

为生产代码配置严格模式的类型检查。

# 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 以获得更快的检查速度。

[tool.pyright]
pythonVersion = "3.12"
typeCheckingMode = "strict"

模式 3：命名规范

遵循 PEP 8，以清晰性优先于简洁性。

文件和模块：

# 好：描述性的 snake_case
user_repository.py
order_processing.py
http_client.py

# 避免：缩写
usr_repo.py
ord_proc.py
http_cli.py

类和函数：

# 类：PascalCase
class UserRepository:
    pass

class HTTPClientFactory:  # 缩写保持大写
    pass

# 函数和变量：snake_case
def get_user_by_email(email: str) -> User | None:
    retry_count = 3
    max_connections = 100

常量：

# 模块级常量：SCREAMING_SNAKE_CASE
MAX_RETRY_ATTEMPTS = 3
DEFAULT_TIMEOUT_SECONDS = 30
API_BASE_URL = "https://api.example.com"

模式 4：导入组织

按一致的顺序分组导入：标准库、第三方库、本地模块。

# 标准库
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

始终使用绝对导入：

# 推荐
from myproject.utils import retry_decorator

# 避免相对导入
from ..utils import retry_decorator

进阶模式

模式 5：Google 风格的文档字符串

为所有公开的类、方法和函数编写文档字符串。

简单函数：

def get_user(user_id: str) -> User:
    """根据唯一标识符获取用户。"""
    ...

复杂函数：

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)} 个任务")
    """
    ...

类的文档字符串：

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 个字符，同时保持可读性。

# 好：可读的换行
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 结构：

# 项目名称

简要描述项目的功能。

## 安装

\`\`\`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）：

# 更新日志

## [未发布]

### 新增
- 新功能 X

### 变更
- 修改了 Y 的行为

### 修复
- 修复了 Z 中的 Bug

最佳实践总结

使用 ruff —— 用于代码检查和格式化的单一工具
启用 strict mypy —— 在运行时之前捕获类型错误
120 字符行长度 —— 现代可读性标准
描述性命名 —— 清晰性优于简洁性
绝对导入 —— 比相对导入更易于维护
Google 风格的文档字符串 —— 一致、可读的文档
记录公开 API —— 每个公开函数都需要文档字符串
保持文档更新 —— 将文档视为代码
在 CI 中自动化 —— 每次提交都运行代码检查
目标 Python 3.10+ —— 对于新项目，建议使用 Python 3.12+ 以获得现代语言特性

7.6 KiB Raw Permalink Blame History Unescape Escape