commit f67cb7e9d20718ef1d734a6490c57b96195ce412 Author: wehub-skill-sync Date: Mon Jul 13 21:36:00 2026 +0800 chore: import zh skill python-code-style diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..24abd92 --- /dev/null +++ b/README.wehub.md @@ -0,0 +1,9 @@ +# WeHub 来源说明 + +- Skill 名称：`python-code-style` +- 中文类目：Python 源码风格 / lint / docstring / 类型注解 规范化审查 +- 上游仓库：`wshobson__agents` +- 上游路径：`plugins/python-development/skills/python-code-style/SKILL.md` +- 上游链接：https://github.com/wshobson/agents/blob/HEAD/plugins/python-development/skills/python-code-style/SKILL.md +- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理 +- 原作者、版权和许可证信息以上游仓库为准 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..b9e527f --- /dev/null +++ b/SKILL.md @@ -0,0 +1,359 @@ +--- +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+ 以获得现代语言特性