python3-development

注重实践的 Python 开发技能

现代 Python 3.11-3.14 模式的 Python 开发指南。

特定领域的技能路由

测试

在审查测试质量或执行测试审计（完整检查清单）时，加载 /python3-development:comprehensive-test-review。

在分析失败的测试或调试测试失败（均衡调查）时，加载 /python3-development:analyze-test-failures。

在调整处理测试失败的方式（以测试为规范的思维模式）时，加载 /python3-development:test-failure-mindset。

CLI 和 UI 库

使用 Typer 和 Rich 构建 CLI（集成、宽度处理、示例）时，加载 /python3-development:typer-and-rich。

使用 Typer 专属 CLI 模式（命令、参数、Typer 功能）时，加载 /python3-development:typer。

使用 Rich 输出（表格、面板、进度、树）时，加载 /python3-development:rich。

使用 Textual 构建终端 UI 时，加载 /python3-development:textual。

开发工作流

创建带有跟踪和阶段的结构化功能任务时，加载 /python3-development:create-feature-task。

通过模板工作流创建新的 Claude Code 技能时，加载 /python3-development:use-command-template。

代码质量

应用现代 Python 3.11+ 模式或现代化旧代码（以 PEP 为依据）时，加载 /python3-development:modernpython。

验证 shebang 或 PEP 723 内联脚本元数据时，加载 /python3-development:shebangpython。

执行渐进式质量改进（静态分析、类型检查、现代化计划、TDD 循环）时，加载 /python3-development:stinkysnake。

扩展工具矩阵

任务涉及 uv、Hatchling、ty、pre-commit、打包或上文未列出的其他专业工具时，加载 /python3-development:specialist-skill-routing（该技能内含完整触发条件映射）。

技能架构

打包的资源（本技能内含）

参考文档：

• references/python3-standards.md — 统一的 Python 3.11+ 标准、知识图谱、流程图以及如何修订它们（在执行适用于整个插件的规则时查阅）
• references/user-project-conventions.md — 生产项目中的惯例；在启动项目或匹配现有项目风格时查阅
• references/modern-modules.md - 50 多个库的指南，包含用法模式和最佳实践
• references/tool-library-registry.md - 用于 lint、测试和构建自动化的开发工具目录
• references/python-development-orchestration.md - TDD、添加功能、重构和代码审查的详细工作流模式

专业技能（路由命令——参见特定领域的技能路由）：

• 测试：comprehensive-test-review、analyze-test-failures、test-failure-mindset
• CLI/UI：typer-and-rich、typer、rich、textual
• 工作流：create-feature-task、use-command-template
• 质量：modernpython、shebangpython、stinkysnake
• 更多：specialist-skill-routing（uv、Hatchling、ty、打包，……）

脚本和资源：

• 演示各种模式的示例脚本
• 配置模板和样板代码

系统工具（通过包管理器或 uv 安装）：

• uv - Python 包和项目管理器（必需）
• ruff - Linter 和格式化工具
• ty - 主要静态类型检查器（Astral）；新项目默认使用——参见 /astral:ty
• mypy - 静态类型检查器；仅在项目已配置使用它时采用——不要强制迁离 mypy
• pyright / basedpyright - 在项目已将其作为标准时使用
• pytest - 测试框架
• pre-commit - Git 钩子框架
• mutmut - 变异测试（用于关键代码）
• bandit - 安全扫描器（用于关键代码）

安装说明：

• 使用 uv 技能获取全面的 uv 文档和包管理指南

核心概念

Python 开发标准

本技能为 Python 3.11+ 开发提供现代标准、质量门禁和参考文档。

应用以下通用规则时，请参阅 references/python3-standards.md：

• 架构标准（分层架构、关注点分离）
• Python 标准（原生类型提示、Google 风格文档字符串、快速失败错误处理）
• CLI 标准（Typer/Rich）
• 服务集成标准（Protocol 类）
• 测试标准（pytest-mock、80% 覆盖率）
• 标识符命名标准（在公开名称中展开缩写；参见 §1.5）

Python 开发流程图

规范开发生命周期请参阅 references/python3-standards.md（第 3 节）。

文档字符串标准：Google 风格（Args/Returns/Raises 部分）。ruff 的 pydocstyle 配置（convention = "google"）请参阅 references/user-project-conventions.md。

Pyproject.toml 模板变量

所有 pyproject.toml 示例都使用明确的模板变量（例如 {{project_name_from_directory_or_git_remote}}），而非通用占位符。写入文件前，请将每个模板变量替换为实际值。变量参考、取值方法和验证步骤请参阅 references/tool-library-registry.md#18-pyprojecttoml-template-variable-reference。

命令用法

/python3-development:modernpython

用途：Python 3.11+ 模式的综合参考指南，附有官方 PEP 引用

适用场景：

• 编写新代码时用作参考指南
• 学习现代 Python 3.11–3.14 功能和模式
• 了解官方 PEP（585、604、695 等）
• 识别应避免的旧式模式
• 为旧代码寻找现代替代方案

注意：这是一份供阅读的参考文档，并非自动化验证工具。请用它指导实现方案的选择。

用法：

/python3-development:modernpython
→ Loads comprehensive reference guide
→ Provides Python 3.11+ pattern examples
→ Includes PEP citations with research tool guidance (prefer MCP tools: Ref/exa over WebFetch)
→ Shows legacy patterns to avoid
→ Shows modern alternatives to use
→ Framework-specific guides (Typer, Rich, pytest)

Research tool preference for PEP documentation:
1. mcp__Ref__ref_search_documentation(query="PEP {number} Python enhancement proposal")
2. mcp__exa__get_code_context_exa(query="PEP {number} implementation examples")
3. WebFetch as fallback

> [Web resource access, definitive guide for getting accurate data for high quality results](./references/accessing_online_resources.md)

带文件路径参数：

/python3-development:modernpython src/mymodule.py
→ Loads guide for reference while working on specified file
→ Use guide to manually identify and refactor legacy patterns

/python3-development:shebangpython

用途：根据依赖项和执行上下文，验证所有 Python 脚本的 shebang 是否正确

适用场景：

• 创建任何独立的可执行 Python 脚本
• 验证脚本 shebang 是否正确
• 确保脚本具有适当的执行配置

适用于：所有可执行 Python 脚本（验证 shebang 是否与脚本类型匹配）

验证内容：

• 仅使用标准库的脚本：#!/usr/bin/env python3（无需 PEP 723；没有需要声明的内容）
• 包含依赖项的脚本：#!/usr/bin/env -S uv run --quiet --script + 声明这些依赖项的 PEP 723 元数据
• 包可执行文件：#!/usr/bin/env python3（依赖项通过包管理器提供）
• 库模块：不需要 shebang（不可直接执行）

参见：内联脚本元数据的详情请参阅 references/PEP723.md

模式：

/python3-development:shebangpython scripts/deploy.py
→ Analyzes imports to determine dependency type
→ **Corrects shebang** to match script type (edits file if wrong)
→ **Adds PEP 723 metadata** if external dependencies detected (edits file)
→ **Removes PEP 723 metadata** if stdlib-only (edits file)
→ Sets execute bit if needed
→ Provides detailed verification report

质量门禁

如需执行强制质量门禁流程（lint、类型检查、测试、完整文件审查、shebang 验证），请启用 /python3-development:python-cli-architect 技能。

诊断规则

error[unresolved-import]: Cannot resolve imported module 'X' — 将包含模块 X 的目录添加到 pyproject.toml 中的 [tool.ty.environment] extra-paths；运行 uv run ty check <path> 进行验证；若错误仍然存在，请确认 ty 读取的是 pyproject.toml 配置（项目根目录中的 ty.toml 优先级更高，且会导致 pyproject.toml 被忽略）。

标准项目结构

项目目录布局、Hatchling 配置和包命名规则请启用 /python3-development:python-cli-architect 技能。

集成

参考示例（随附）

完整可运行的示例（随附）：加载 Skill(skill="python3-development:typer-and-rich")，即可访问 python-cli-demo.py——一个展示所有推荐模式的完整 CLI 演示。

此参考实现展示了所有推荐模式：

• 带有正确 shebang 的 PEP 723 元数据
• Typer + Rich 集成
• 现代 Python 3.11+（StrEnum、Protocol、TypeVar、Generics）
• CLI 参数的 Annotated 语法
• 异步处理
• 完整的文档字符串

此文件随插件一同提供，确保工作流自包含。创建 CLI 工具时可将其用作参考。

使用资源模板

创建新的 Python 项目时，请从该技能的资源目录中复制标准配置文件，以确保遵循既定规范：

原因：模板实现了经过验证的模式，可节省设置时间。

资源目录位置（在插件中）：./assets/

可用模板：

1. version.py - 双模式版本管理（hatch-vcs + importlib.metadata 回退）

   cp "${CLAUDE_PLUGIN_ROOT}/skills/python3-development/assets/version.py" "packages/{package_name}/version.py"
   

2. hatch_build.py - 二进制文件/资源处理的构建钩子（仅在需要时使用）

   mkdir -p scripts/
   cp "${CLAUDE_PLUGIN_ROOT}/skills/python3-development/assets/hatch_build.py" "scripts/hatch_build.py"
   

3. .markdownlint.json - Markdown lint 配置

   cp "${CLAUDE_PLUGIN_ROOT}/skills/python3-development/assets/.markdownlint.json" "."
   

4. .pre-commit-config.yaml - 标准 git 钩子配置

   cp "${CLAUDE_PLUGIN_ROOT}/skills/python3-development/assets/example.pre-commit-config.yaml" ".pre-commit-config.yaml"
   
   # Install hooks using pre-commit or prek (whichever is available)
   # Both tools use the same configuration file and have identical interfaces
   uv run pre-commit install  # or: uv run prek install
   

5. .editorconfig - 编辑器格式设置

   cp "${CLAUDE_PLUGIN_ROOT}/skills/python3-development/assets/.editorconfig" "."
   

这些模板实现了 references/user-project-conventions.md 中记录的模式，并确保所有项目在版本管理、lint、格式化和构建配置方面遵循相同标准。

详细文档

参考文档

PEP 723 规范：references/PEP723.md - PEP 723 行内脚本元数据的易用指南，包含示例和迁移模式

异常处理和 Typer/Rich 示例：加载 Skill(skill="python3-development:typer-and-rich")——涵盖异常链预防、Typer 退出模式、Rich 非 TTY 显示解决方案，以及可运行的可执行示例，包括 typer_examples/ 脚本和 python-cli-demo.py。

模块参考：references/modern-modules.md - 50 多个现代 Python 库的综合指南，针对每个模块提供深入文档，包括用法模式和最佳实践

工具注册表：references/tool-library-registry.md - 开发工具目录，介绍其用途，以及用于 lint、测试和构建自动化的用法模式

浏览大型参考文档

要在 modern-modules.md 中查找特定模块：

grep -i "^### " references/modern-modules.md

要在 tool-library-registry.md 中按类别搜索工具：

grep -A 5 "^## " references/tool-library-registry.md

要在 python-development-orchestration.md 中查找工作流模式：

grep -i "^## " references/python-development-orchestration.md

外部命令

这些技能随插件一同提供，并可作为斜杠命令使用：

• ../modernpython/SKILL.md - Python 3.11+ 模式和 PEP 参考
• ../shebangpython/SKILL.md - PEP 723 验证和 shebang 标准

总结

• 现代 Python 3.11+ 标准和模式
• 质量门禁：ruff、ty（默认类型检查）、项目使用时的 mypy/pyright、pytest（覆盖率 >80%）
• 命令标准：/python3-development:modernpython、/python3-development:shebangpython
• 涵盖 50 多个现代 Python 模块的参考文档
• 工具和库注册表