python-pep-author

编写 Python 增强提案（PEP）

PEP 是 Python 社区用来提议新语言特性、标准库变更、互操作标准或流程／信息指南的设计文档。这项技能将作者从初步构想引导至格式正确、符合流程要求、可提交到 python/peps 仓库的草稿。

PEP 的难点不在于措辞，而在于选对类型、确保头部前言有效、让章节完整到达到验收标准，并遵循流程（审查、赞助、评审）。这项技能包含两个脚本，用于处理确定性任务；同时提供参考文档，帮助处理需要判断的事项。

适用场景

• 用户要求撰写／起草／组织 PEP，或“Python 增强提案”。
• 用户想要提议一项 Python 语言或标准库特性，并需要正式撰写提案。
• 用户一直在 Python Discourse 上讨论某个想法，现在想将其整理成 PEP 草稿。
• 用户需要了解或生成 PEP 模板、头部字段或章节结构。
• 用户正在修订现有 PEP（更改状态、添加 Resolution、处理评审反馈）。

不要将此技能用于公司内部 RFC／设计文档（请使用 dev-rfc）——PEP 专指由 PEP 1 管理、面向上游 CPython／Python 社区的提案。

前提条件

• 用于运行两个脚本的 Bash + coreutils（awk、sed、grep、date）——macOS/Linux 默认已提供。
• 只有准备好提交时（第 6 步），才需要克隆或复刻 github.com/python/peps。起草无需仓库。
• 起草或检查无需 Python 运行时；参考实现（如有）是作者单独维护的代码库。

工作流概览

1. Vet the idea ────► 2. Choose the type ────► 3. Scaffold the file
   (is it PEP-able?)     (Standards/Info/Process)   (scripts/new-pep.sh)
                                                          │
   6. Submit ◄──── 5. Self-check ◄──── 4. Draft each section
   (sponsor, PR)      (scripts/check-pep.sh)   (to the acceptance bar)
        │
        ▼
   7. Review & resolution ──► update Status + Resolution header

1. 审查想法（动笔之前）

重复已有工作或不属于整个社区范围的 PEP，一经发现就会被拒绝。请先将想法发布到 Python Discourse 的 Ideas 类别（如果属于专业领域，则发布到 Typing／Packaging 类别）。确认想法具有原创性、适用于整个社区，并且过去的讨论尚未对此作出定论。有关讨论场所及检查事项，请参阅 references/workflow.md。

2. 选择 PEP 类型

PEP 类型恰好有三种：标准轨道（Standards Track）、信息类（Informational）、流程类（Process）。类型决定必填头部字段（例如 Python-Version、Resolution）和验收标准。请参阅 references/pep-types.md 进行选择。

3. 搭建文件框架

请生成有效且头部格式正确的 reStructuredText 文件，不要手动输入前言（字段集合及其顺序都有严格要求）：

scripts/new-pep.sh \
  --title "A short descriptive title" \
  --author "Random J. User <[email protected]>" \
  --type "Standards Track" \
  --python-version 3.15            # Standards Track only; omit otherwise

这会创建 pep-9999.rst（9999 是占位符；PEP 编辑者会分配实际编号），设置 Status: Draft 和当天的 Created 日期，并确保标题不超过 44 个字符。不带参数运行 scripts/new-pep.sh 可查看完整用法。

4. 起草各个章节

按照 PEP 12 的标准顺序填写正文各章节：摘要 → 动机 → 规范 → 原理 → 向后兼容性 → 安全影响 → 如何讲授 → 参考实现 → 被否决的想法 → 未决问题 → 致谢 → 脚注 → 变更历史 → 版权。 每个章节都有特定职责和质量标准——起草前请阅读 references/sections.md，并参阅 references/header-fields.md，了解需要填写的头部字段（Sponsor、Discussions-To、Requires 等）。

验收标准（摘自 PEP 1）：提案必须有清晰且完整的描述，代表净改进，实现方案必须可靠，且不会给解释器带来不必要的复杂性，同时还要符合 “Pythonic” 原则。请按此标准撰写。

5. 自检草稿

在展示给任何人之前，先检查标题和必需的结构：

scripts/check-pep.sh pep-9999.rst

此脚本会验证必需的标题是否齐全、标题长度、有效的 Status/Type 值、Created 日期格式、强制要求的 CC0 版权声明，以及 Abstract 部分；同时报告 PASS / WARN / FAIL，并在出现任何 FAIL 时以非零状态码退出。 修复所有 FAIL。

6. 提交

如果没有共同作者是 CPython 核心开发者，你必须先找到一位赞助人（负责指导该 PEP 的核心开发者）。然后 fork python/peps，添加 pep-NNNN.rst，在 .github/CODEOWNERS 中列出作者/赞助人，并发起拉取请求。PEP 编辑会审核格式和合理性，并分配编号。完整步骤和角色定义见 references/workflow.md。

7. 审核与决议

当作者（和赞助人）认为内容已准备就绪时，内容审核以及接受/拒绝的决定由 Steering Council（或指定的 PEP-Delegate）负责。作出决定后，更新 Status，并添加一个链接到公告的 Resolution 标题。完整的状态生命周期和有效转换见 references/status-lifecycle.md。

参考文件

文件	阅读时机
references/workflow.md	审查、寻找赞助人、提交、审核流程、角色、转移所有权
references/pep-types.md	在 Standards Track / Informational / Process 之间进行选择
references/header-fields.md	填写任何前言字段时——格式、必填项与可选项、示例
references/status-lifecycle.md	设置或更改 Status、了解有效转换、Resolution 标题
references/sections.md	起草正文——每个部分必须包含的内容、RST 约定、接受标准

脚本

脚本	功能
scripts/new-pep.sh	根据模板生成有效的 pep-NNNN.rst，替换标题字段并强制执行标题长度限制
scripts/check-pep.sh	根据 PEP 1 / PEP 12 规则检查 PEP 草稿（标题、状态/类型、日期格式、版权、摘要）

脚本使用的模板位于 assets/templates/pep-template.rst——如果你更愿意手动填写标题字段，也可以直接复制它。

注意事项

参见 gotchas.md。最常见的初期错误包括：跳过 Discourse 审查步骤、将实际属于 Process 的 PEP 误选为 Standards Track、遗漏强制要求的 CC0 版权声明，以及标题超过 44 个字符。

相关技能

• dev-rfc — 用于内部/公司 RFC、设计文档和架构文档（不适用于上游 Python 提案）。