python-conventions

Python 约定

当 Python 是主要工作流时，遵循这些约定。

调度

$ARGUMENTS	操作
Active（Python 是主要工作流时自动调用）	应用下方的操作规范
Empty	显示约定摘要和路由指南
check	仅验证工具合规性

参考文件索引

文件	用途
references/tooling-contract.md	安装、运行、Lint、类型检查和测试流程所需的命令顺序
references/redirection-boundaries.md	Python 约定应何时让位于 shell、JS/TS 或特定领域技能
references/exceptions.md	何时打破约定（旧项目、企业环境）
references/library-preferences.md	新 Python 工作的引导式库默认选择
references/performance-tips.md	性能分析工具、优化模式速查
references/testing-patterns.md	Fixture 作用域、标记、conftest 骨架

操作规范

Active

1. 仅当 Python 文件、Python 工具或 pyproject.toml 是任务的主要内容时，才应用此技能。
2. 当 Python 与 shell、JS/TS 或其他主要工作流并存时，阅读 references/redirection-boundaries.md。
3. 对包管理、命令执行、Lint、类型检查和测试，强制遵守 references/tooling-contract.md 中的硬性要求。
4. 建议采用任何旧项目或受限环境的偏离做法前，先查看 references/exceptions.md。
5. 仅在为新的 Python 工作选择库时，阅读 references/library-preferences.md。

Empty / Help

1. 概述硬性要求：uv、uv run、uv add、ty、ruff、pytest 和 pyproject.toml。
2. 说明硬性要求与引导式偏好之间的区别。
3. 指明工具、例外、库、测试、性能和混合语言路由对应的准确参考文件。

check

1. 仅验证工具合规性；除非用户提出要求，否则不要扩展为完整的实现建议。
2. 报告项目是否按预期方式使用 uv、uv run、ty、ruff、pytest 和 pyproject.toml。
3. 标记旧项目或例外路径的偏离，并要求其理由符合 references/exceptions.md。
4. 拒绝使用 mypy、pip install 或裸 python 替代仓库要求的工具的建议。

硬性要求

• 包管理器：所有 Python 包操作均使用 uv
• 依赖项：酌情使用 uv add、uv add --group dev、uv remove 和 uv lock --upgrade-package <pkg>
• 可复现安装：验证现有锁文件工作流时，使用 uv sync --locked
• 项目配置：将 Python 项目配置保存在 pyproject.toml 中
• 类型检查：使用 uv run ty check，而非 mypy
• Lint：使用 uv run ruff check 和 uv run ruff format
• 测试：使用 uv run pytest
• 任务运行：执行 Python 命令时使用 uv run <command>

虚拟环境

• 让 uv 自动管理虚拟环境
• 切勿手动创建或激活 .venv 目录
• 使用 uv run 在项目环境中执行命令

引导式偏好

仅当开始新的 Python 工作且没有更强的本地约束时，才应用引导式库偏好。建议替换现有技术栈前，请阅读 references/library-preferences.md。

项目结构

• 使用 pyproject.toml 保存所有项目元数据和依赖项
• 将源代码放在与项目名称匹配的包目录中
• 在单体仓库中使用 uv 工作区成员管理子包
• 在认为 Python 工作已完成前，按照 references/tooling-contract.md 执行所需的 Lint、格式化、类型检查和测试流程

性能规范

1. 先分析性能，再进行优化。
2. 使用 references/performance-tips.md 快速了解 Python 性能分析和优化模式。
3. 将广泛的性能分析、回归分析或性能调查任务交给 performance-profiler。

测试规范

1. 使用 pytest 编写 Python 测试，并在 pyproject.toml 中配置项目测试默认设置。
2. 使用 references/testing-patterns.md 了解 fixture、标记、tmp_path、monkeypatch、参数化和覆盖率策略。
3. 将测试策略、测试套件设计、fixture 架构或跨语言测试计划交给 test-architect。

验证约定

在声明更改完成前，从此技能目录运行：

python scripts/check.py
git diff --check

完成标准：

1. scripts/check.py 以状态码 0 退出。
2. git diff --check 以状态码 0 退出。
3. 此技能目录下不再存在可移植 CLI 违规项。

更改技能定义、公开描述、参考文件或评估行为后，如果 docs-steward 可用，请调用它。

关键规则

1. 如果任务不属于明确批准的例外路径，请拒绝使用 pip install、uv pip install 或裸 python 的 Python 环境设置建议。
2. 运行时依赖必须使用 uv add，仅用于开发的依赖必须使用 uv add --group dev，除非 references/exceptions.md 说明了合理的旧版方案或受限环境偏离情况。
3. 类型检查必须使用 uv run ty check；不要将 mypy 或裸 ty check 作为此仓库的默认方案。
4. 对于 Python 更改，默认完成门槛为 uv run ruff check、uv run ruff format、uv run ty check 和 uv run pytest，除非有记录在案的例外。
5. 不要手动编辑 uv.lock；请使用 uv lock、uv sync 或依赖管理命令。
6. 不要将指导性的库选择偏好说成是必须替换已有本地技术栈的要求。
7. 批准旧版工具链、其他环境管理器或其他库方案前，请先阅读 references/exceptions.md。
8. 对于混合语言或非 Python 为主的工作，请通过 references/redirection-boundaries.md 转交，不要强行将整个任务套用到此技能上。

规范术语（请严格照此使用）：

• uv -- 必需的包管理器和任务运行器
• ty -- 必需的类型检查器（不是 mypy）
• uv run ty check -- 必需的类型检查命令
• ruff -- 必需的代码检查和格式化工具
• pyproject.toml -- 项目配置的唯一来源
• uv run -- 所有 Python 命令执行时的前缀
• uv sync --locked -- 基于锁文件的工作流中默认的可复现安装检查

扩展策略

• 更广泛的非 Python 任务中偶尔涉及 Python 文件：仅强制执行涉及 Python 负责范围的硬性要求，然后通过 references/redirection-boundaries.md 转交混合工作流相关问题。
• 以 Python 为主的功能开发或重构：应用完整的操作约定，包括相关的工具、测试和指导性偏好。
• 仓库范围的 Python 工具或迁移工作：使用 check、references/tooling-contract.md 和 references/exceptions.md，区分硬性违规与有文档记录的过渡方案。

渐进式披露

• 默认不要加载所有参考资料。
• 有关命令顺序的问题，先阅读 references/tooling-contract.md。
• 请求中涉及 shell、JS/TS、CI 或特定框架的工作时，阅读 references/redirection-boundaries.md。
• 只有在任务似乎需要旧版方案、企业环境或受限环境例外时，才阅读 references/exceptions.md。
• 只有在为新的 Python 工作选择库时，才阅读 references/library-preferences.md。
• 只有在当前任务实际涉及性能或测试时，才阅读相应的参考资料。

范围边界

适用于： Python 工具约定、命令选择、依赖管理规则、类型检查／代码检查／测试门槛，以及考虑异常情况的仓库指南。

不适用于： JS/TS 约定、Shell 约定、CI 流水线设计、性能分析调查、测试架构，或特定于框架／领域的实现策略。