Python PEP Authoring

Overview

Use this skill for Python Enhancement Proposal work that needs to follow the official python/peps repository, not generic Python code style. It covers PEP drafting, PEP review, metadata/header validation, reStructuredText formatting, repository checks, and contribution workflow.

The bundled references summarize the official python/peps repository at commit 63b05773e2b5e8355910df520e8cf319f70944be from 2026-06-28. When working inside a current checkout of github.com/python/peps, prefer the checkout's local files over these summaries.

Workflow

1. Classify the request:
   • New PEP draft or template creation.
   • Review of an existing PEP draft.
   • Change to an existing PEP.
   • Repository PR preparation, lint failure, or rendering issue.
2. Read the relevant reference before making detailed claims:
   • references/process-and-policy.md for PEP workflow, statuses, authorship, sponsors, review, and maintenance.
   • references/header-and-rst-rules.md for PEP 12 header order, metadata formats, PEP section template, and reST rules.
   • references/repo-validation.md for python/peps checkout commands, check-peps.py, pre-commit, spelling, and rendering.
3. If a live python/peps checkout is available, inspect local source files before editing:
   • 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. For a new PEP, make sure the draft has one focused proposal, a champion, the correct PEP type, Status: Draft, a sponsor if required, a valid discussion plan, and the PEP 12 template structure.
5. For edits to existing PEPs, check the status first. Draft PEPs are open to discussion and proposed modification; Accepted, Final, Rejected, Withdrawn, and Superseded PEPs are mainly historical documents and should not receive major content changes without a process reason.
6. For reviews, report concrete issues first with file/line references when available. Separate process blockers, metadata/header defects, reST/rendering defects, and editorial/content concerns.
7. For repository work, run the narrowest meaningful validation command available. Prefer python check-peps.py peps/pep-NNNN.rst for a single PEP, then make lint, make spellcheck, and make html or python build.py when appropriate.

New PEP Drafts

When asked to create or revise a new PEP:

• Use peps/pep-0012/pep-NNNN.rst as the source template if the official repo is present. Do not use rendered HTML as a template.
• Name the file peps/pep-NNNN.rst with zero padding. The PEP: header itself is not zero-padded.
• Use the next available PEP number not used by a published or in-PR PEP unless a PEP editor assigns a number.
• Include required headers in PEP 12 order and remove optional headers that do not apply.
• For Standards Track PEPs, include Python-Version when the feature targets a Python release; omit it for interoperability standards that initially live outside the stdlib.
• Add Discussions-To: Pending and Post-History: Pending only when the canonical thread does not exist yet; update them after the thread is created.
• Include the dual public domain / CC0-1.0-Universal copyright/license text.
• If the PEP has co-authors or sponsors with write access to python/peps, update .github/CODEOWNERS.

Review Output

Use this structure for PEP reviews:

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.

Use priorities consistently:

• P0: would break rendering, validation, or repository acceptance outright.
• P1: process or metadata issue likely to block PEP editor approval.
• P2: clear PEP 1/PEP 12/repo-rule issue that should be fixed.
• P3: editorial polish, clarity, or optional improvement.

If there are no findings, say that directly and mention any validation not run.

Source Links

• Official repository: https://github.com/python/peps
• PEP index: https://peps.python.org/
• PEP 1: https://peps.python.org/pep-0001/
• PEP 12: https://peps.python.org/pep-0012/