Python PEP 编写

概述

本技能专用于需遵循官方 python/peps 仓库规范的 Python 增强提案（PEP）工作，不适用于通用 Python 代码风格指导。涵盖 PEP 起草、PEP 审阅、元数据/头部校验、reStructuredText 格式化、仓库检查及贡献流程支持。

所附参考文档汇总了截至 2026-06-28 提交哈希 63b05773e2b5e8355910df520e8cf319f70944be 的官方 python/peps 仓库状态。若当前已检出 github.com/python/peps 仓库，请优先使用本地文件而非这些摘要内容。

工作流

1. 对请求进行分类：
   • 新建 PEP 草案或模板创建；
   • 对已有 PEP 草案进行审阅；
   • 修改已有 PEP；
   • 为仓库提交 PR 做准备、处理 lint 失败或渲染问题。
2. 在做出具体判断前，先阅读相关参考文档：
   • references/process-and-policy.md：涵盖 PEP 工作流、状态定义、作者权责、赞助人机制、审阅流程与维护规则；
   • references/header-and-rst-rules.md：涵盖 PEP 12 规定的头部字段顺序、元数据格式、PEP 章节模板及 reStructuredText（reST）书写规则；
   • references/repo-validation.md：涵盖 python/peps 仓库检出命令、check-peps.py 工具用法、pre-commit 配置、拼写检查与 HTML 渲染流程。
3. 若存在可访问的本地 python/peps 检出副本，请在编辑前先查阅以下源文件：
   • peps/pep-0001.rst
   • peps/pep-0012.rst
   • peps/pep-0012/pep-NNNN.rst
   • CONTRIBUTING.rst
   • README.rst
   • check-peps.py
   • .pre-commit-config.yaml
4. 对于新 PEP，须确保草案满足以下要求：仅聚焦单一提案、指定一名 champion（主要推动者）、选择正确的 PEP 类型、设置 Status: Draft、按需指定 sponsor（赞助人）、提供有效的讨论计划，并严格采用 PEP 12 规定的模板结构。
5. 修改已有 PEP 前，须首先核查其当前状态。处于 Draft 状态的 PEP 允许开放讨论与修订建议；而 Accepted、Final、Rejected、Withdrawn 和 Superseded 状态的 PEP 主要作为历史文档存在，除非有明确流程依据，否则不应进行重大内容变更。
6. 开展审阅时，应优先报告可复现的具体问题，并在可能时注明文件路径与行号。将问题分类为：流程阻塞项（process blockers）、元数据/头部缺陷（metadata/header defects）、reST/渲染缺陷（reST/rendering defects）以及编辑/内容类关切（editorial/content concerns）。
7. 处理仓库相关任务时，应优先运行粒度最细且有意义的校验命令：对单个 PEP 推荐执行 python check-peps.py peps/pep-NNNN.rst；随后视需要运行 make lint、make spellcheck 及 make html 或 python build.py。

新 PEP 草案

当被要求创建或修订新 PEP 时，请遵守以下规范：

• 若本地存在官方仓库，则以 peps/pep-0012/pep-NNNN.rst 为源模板；切勿使用渲染后的 HTML 页面作为模板。
• 文件名应为 peps/pep-NNNN.rst，其中编号须补零对齐；但头部字段 PEP: 后的编号本身无需补零。
• 默认使用下一个未被已发布或已提交 PR 占用的 PEP 编号，除非 PEP 编辑已另行指定。
• 严格按 PEP 12 规定的顺序包含必需头部字段，并移除所有不适用的可选头部字段。
• 对于 Standards Track 类型的 PEP，若该特性面向特定 Python 版本发布，则必须包含 Python-Version 字段；若为最初独立于标准库之外的互操作性标准，则可省略该字段。
• 仅当尚无权威讨论线程时，才填写 Discussions-To: Pending 与 Post-History: Pending；在线程创建后须及时更新这两项。
• 必须包含双许可声明文本：“This PEP is dedicated to the public domain. Alternatively, it is licensed under the Creative Commons Zero v1.0 Universal license.”（即公有领域 + CC0-1.0-Universal 许可）。
• 若该 PEP 存在具备 python/peps 仓库写入权限的共同作者或 sponsor，请同步更新 .github/CODEOWNERS 文件。

审阅输出格式

请按如下结构组织 PEP 审阅意见：

Findings
- [P1] Missing sponsor for non-core authors - peps/pep-NNNN.rst:4
  Explain the official rule, why it blocks or weakens the PEP, and the smallest fix.

Open Questions
- Mention only questions that affect process, metadata, or content readiness.

Validation
- List commands run and whether rendering/linting passed.

请统一使用如下优先级标识：

• P0：直接导致渲染失败、校验失败或仓库拒绝接收的问题；
• P1：可能阻碍 PEP 编辑批准的流程或元数据问题；
• P2：明确违反 PEP 1 / PEP 12 / 仓库规则的问题，应予以修复；
• P3：属于文字润色、表述清晰度提升或非强制性优化项。

若未发现任何问题，请明确说明，并指出尚未执行的校验项。

源链接

• 官方仓库地址：https://github.com/python/peps
• PEP 索引页：https://peps.python.org/
• PEP 1 文档：https://peps.python.org/pep-0001/
• PEP 12 文档：https://peps.python.org/pep-0012/