⚡

Python代码风格与文档Skill python-code-style

这个技能专注于Python代码风格、linting、格式化、命名约定和文档标准，帮助开发者编写可维护和协作的代码。适用于项目设置、代码审查、文档编写和自动化工具配置。关键词：Python代码风格, linting, 格式化, 命名约定, 文档标准, 自动化工具, 代码审查, 可维护代码, 协作开发。

其他 0 次安装 0 次浏览 更新于 3/22/2026

name: python-code-style description: Python代码风格、linting、格式化、命名约定和文档标准。在编写新代码、审查风格、配置linter、编写docstrings或建立项目标准时使用。

Python代码风格与文档

一致的代码风格和清晰的文档使代码库可维护和可协作。本技能涵盖现代Python工具、命名约定和文档标准。

何时使用此技能

  • 为新项目设置linting和格式化
  • 编写或审查docstrings
  • 建立团队编码标准
  • 配置ruff、mypy或pyright
  • 审查代码以保持风格一致性
  • 创建项目文档

核心概念

1. 自动化格式化

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

2. 一致的命名

遵循PEP 8约定，使用有意义、描述性的名称。

3. 文档即代码

Docstrings应与其描述的代码一起维护。

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作为一体化的linter和格式化工具。它用单个快速工具替代了flake8、isort和black。

# pyproject.toml
[tool.ruff]
line-length = 120
target-version = "py312"  # 根据项目最低Python版本调整

[tool.ruff.lint]
select = [
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "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 .  # Lint并自动修复
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风格Docstrings

为所有公共类、方法和函数编写docstrings。

简单函数：

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"Processed {len(result.succeeded)} items")
    """
    ...

类Docstring：

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"Failed to process user {user_id}: "
    f"received status {response.status_code} "
    f"with body {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格式（保持变更日志）：

# 变更日志

## [未发布]

### 新增
- 新功能X

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

### 修复
- Z中的错误

最佳实践总结

  1. 使用ruff - 用于linting和格式化的单一工具
  2. 启用严格mypy - 在运行时前捕获类型错误
  3. 120字符行 - 现代可读性标准
  4. 描述性名称 - 清晰性优于简洁性
  5. 绝对导入 - 比相对导入更可维护
  6. Google风格docstrings - 一致、可读的文档
  7. 文档化公共API - 每个公共函数都需要docstring
  8. 保持文档更新 - 将文档视为代码
  9. 在CI中自动化 - 每次提交运行linter
  10. 目标Python 3.10+ - 对于新项目，推荐Python 3.12+以利用现代语言特性