Python Pep Author

Write a Python Enhancement Proposal (PEP)

A PEP is the design document the Python community uses to propose a new language feature, a stdlib change, an interoperability standard, or a process/informational guideline. This skill takes an author from a rough idea to a correctly-formatted, process-compliant draft ready for submission to the python/peps repository.

The hard parts of a PEP are not the prose — they are getting the type right, the header preamble valid, the sections complete to the acceptance bar, and following the process (vetting, sponsorship, review). This skill bundles two scripts for the deterministic parts and reference docs for the judgement calls.

When to Apply

• The user asks to write / draft / structure a PEP or a "Python Enhancement Proposal".
• The user wants to propose a Python language or standard-library feature and needs it written up formally.
• The user has an idea they've been discussing on the Python Discourse and wants to turn it into a PEP draft.
• The user needs the PEP template, header fields, or section structure explained or generated.
• The user is revising an existing PEP (changing status, adding a Resolution, addressing review feedback).

Do not use this skill for internal company RFCs / design docs (use dev-rfc) — a PEP is specifically a proposal to the upstream CPython / Python community governed by PEP 1.

Prerequisites

• Bash + coreutils (awk, sed, grep, date) for the two scripts — present by default on macOS/Linux.
• A clone of, or a fork of, github.com/python/peps only when you're ready to submit (Step 6). Drafting needs no repo.
• No Python runtime is required to draft or lint; the reference implementation (if any) is the author's separate codebase.

Workflow Overview

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. Vet the idea (before writing anything)

A PEP that duplicates prior work or isn't community-wide in scope will be rejected on sight. Post the idea to the Ideas category of the Python Discourse first (or the Typing / Packaging category if specialised). Confirm it's original, applicable to the whole community, and not already settled by a past discussion. See references/workflow.md for venues and what to check.

2. Choose the PEP type

There are exactly three: Standards Track, Informational, Process. The type determines required headers (e.g. Python-Version, Resolution) and the bar for acceptance. Pick with references/pep-types.md.

3. Scaffold the file

Generate a valid, correctly-headed reStructuredText file rather than hand-typing the preamble (the field set and ordering are exact):

scripts/new-pep.sh \
  --title "A short descriptive title" \
  --author "Random J. User <random@example.com>" \
  --type "Standards Track" \
  --python-version 3.15            # Standards Track only; omit otherwise

This writes pep-9999.rst (9999 = placeholder; PEP editors assign the real number), sets Status: Draft and today's Created date, and enforces the 44-character title limit. Run scripts/new-pep.sh with no args for full usage.

4. Draft each section

Fill the body sections in the canonical PEP 12 order: Abstract → Motivation → Specification → Rationale → Backwards Compatibility → Security Implications → How to Teach This → Reference Implementation → Rejected Ideas → Open Issues → Acknowledgements → Footnotes → Change History → Copyright. Each section has a specific job and a quality bar — read references/sections.md before drafting, and consult references/header-fields.md for any header you need to fill in (Sponsor, Discussions-To, Requires, etc.).

The acceptance bar (from PEP 1): the proposal must be a clear and complete description, represent a net improvement, have a solid implementation that doesn't unduly complicate the interpreter, and be "pythonic". Write to that bar.

5. Self-check the draft

Lint the headers and required structure before showing it to anyone:

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

It verifies the required headers are present, the title length, valid Status/Type values, the Created date format, the mandatory CC0 copyright notice, and an Abstract section — reporting PASS / WARN / FAIL and exiting non-zero on any FAIL. Fix every FAIL.

6. Submit

If no co-author is a CPython core developer, you must first find a sponsor (a core developer who shepherds the PEP). Then fork python/peps, add pep-NNNN.rst, list authors/sponsors in .github/CODEOWNERS, and open a pull request. PEP editors review for format and soundness and assign the number. Full steps and the role definitions are in references/workflow.md.

7. Review & resolution

When the authors (and sponsor) judge it ready, content review and the accept/reject decision rest with the Steering Council (or an appointed PEP-Delegate). On a decision, update the Status and add a Resolution header linking to the pronouncement. The full status lifecycle and valid transitions are in references/status-lifecycle.md.

Reference Files

Scripts

The template the scripts use lives at assets/templates/pep-template.rst — copy it directly if you'd rather fill the headers by hand.

Gotchas

See gotchas.md. The most common early mistakes: skipping the Discourse vetting step, choosing Standards Track for what is really a Process PEP, omitting the mandatory CC0 copyright notice, and a title over 44 characters.

Related Skills

• dev-rfc — internal/company RFCs, design docs, and architecture docs (not upstream Python proposals).

Gotchas

Real failure points discovered while building and reviewing this skill. Newest first.

Format:

### <Short title of the failure point>
What went wrong, why, and how to avoid it.
Added: YYYY-MM-DD

Specification comes before Rationale in PEP 12

It is tempting to justify the design (Rationale) before specifying it. The canonical PEP 12 order is Abstract → Motivation → Specification → Rationale → Backwards Compatibility. Describe what you propose, then why. The template and sections.md follow this order. Added: 2026-05-21

Empty header lines can fool a naive linter

The template ships every optional field as an empty Field: line (e.g. Resolution:). A linter that checks only for the field name will report it present, giving false assurance. check-pep.sh uses a value-aware has_value() so empty scaffold lines do not satisfy the conditional checks (Resolution, Discussions-To, Python-Version). Added: 2026-05-21

date +%b is locale-sensitive

PEP 1 requires the English three-letter month in Created (e.g. 21-May-2026). Under a non-English locale (LC_TIME=fr_FR), date +%b yields mai, which is wrong and even fails check-pep.sh's own dd-mmm-yyyy regex. new-pep.sh forces LC_ALL=C on the date call. Added: 2026-05-21

Multiple authors need RFC 2822 continuation lines

A single Author: A, B line is invalid — each author goes on its own continuation line indented 8 spaces. Pass --author "A <a@x>, B <b@y>" (comma-separated); new-pep.sh splits them onto continuation lines automatically. Added: 2026-05-21

Python-Version is Standards Track only

Setting Python-Version on a Process or Informational PEP is wrong. new-pep.sh errors if --python-version is combined with a non-Standards-Track --type, and check-pep.sh warns if the header has a value on a non-Standards-Track PEP. Added: 2026-05-21

Created is the date a number is assigned, not the draft date

PEP 1 defines Created as the date the PEP was assigned a number (at editor approval), which may be later than when you scaffold the file. new-pep.sh stamps today and prints a reminder to update it if the number is assigned on a different date. Added: 2026-05-21

The Header Preamble (RFC 2822 Fields)

Every PEP starts with an RFC 2822 style header block, ending at the first blank line. Fields appear in the order below. This is the most error-prone part of a PEP — scripts/check-pep.sh validates it.

Field reference

Format rules that catch people out

• `Author` format is exact: Random J. User <random@example.com> with an email, or

Random J. User without. Multiple authors each go on their own continuation line:

  Author: Random J. User <random@example.com>,
          Another Person <another@example.com>

• `Title` ≤ 44 characters. This is a hard limit (it has to fit the PEP index). The

scaffold and lint scripts both enforce it.

• `Created` is `dd-mmm-yyyy` with a three-letter English month: 01-Feb-2026, not

2026-02-01 and not 1-Feb-2026 without the leading zero.

• `Sponsor` vs core-dev authorship: if any author is a core developer, leave

Sponsor out entirely. Don't list a sponsor "for safety" — it signals no author has commit rights.

• `Discussions-To` must point at a specific thread, not a list's landing page, so

reviewers land on the actual conversation.

• `Replaces` / `Superseded-By` are reciprocal: when PEP B supersedes PEP A, A gets

Superseded-By: B and B gets Replaces: A. Setting only one side is inconsistent.

• `Resolution` is mandatory for resolved Standards Track PEPs. Add it together with

the Status change to Accepted / Rejected / Withdrawn.

Minimal valid Draft header (Standards Track)

PEP: 9999
Title: Add frobnication to the standard library
Author: Random J. User <random@example.com>
Status: Draft
Type: Standards Track
Created: 21-May-2026
Python-Version: 3.15

scripts/new-pep.sh generates exactly this (with the full optional-field skeleton).

Choosing the PEP Type

Every PEP is exactly one of three types, set in the Type: header. The type drives which headers are required and the bar the proposal is held to. Getting this wrong is a common early mistake — a process change dressed up as a feature, or vice versa.

The three types

Standards Track

Describes a new feature or implementation for Python, or an interoperability

standard supported outside the standard library for current Python versions before

a later PEP adds stdlib support.

Use it for: new syntax, new builtins, new stdlib modules/APIs, changes to the language or interpreter, and cross-implementation standards.

Implications:

• Typically carries a `Python-Version` header (the release the feature targets).
• The `Resolution` header is required once resolved (accepted/rejected/withdrawn).
• Needs a reference implementation (complete before Final).
• Held to the full acceptance bar: clear & complete, net improvement, solid implementation, pythonic.

Informational

Describes a Python design issue, or provides general guidelines or information to the

community, but does not propose a new feature.

Use it for: design guidance, conventions, or community information where adoption is optional. Informational PEPs do not necessarily represent consensus or a recommendation — users and implementers are free to ignore them.

Implications:

• No Python-Version, no reference implementation, no net-improvement-of-the-language bar.
• May be marked Active if it is an ongoing document never meant to be "completed".

Process

Describes a process surrounding Python, or proposes a change to (or an event in) a

process. Like Standards Track PEPs, but applied to areas **other than the language

itself**.

Use it for: changes to the development workflow, decision-making, release cadence, governance, or the PEP process itself. Process PEPs require community consensus and, unlike Informational PEPs, users are typically not free to ignore them. Examples: PEP 1 (this process) and PEP 13 (governance) — both Active.

Quick decision guide

Ask: "Does this change Python the language/library, or change how the Python project operates, or is it just information?" Language/library → Standards Track. How the project operates → Process. Pure information with no mandate → Informational.

Topic (a separate axis)

The optional Topic: header is not the type. It tags a PEP into a sub-index and takes one of: Governance, Packaging, Release, Typing. A Standards Track typing PEP, for example, has Type: Standards Track and Topic: Typing.

Body Sections, RST Conventions, and the Acceptance Bar

The body follows the preamble. assets/templates/pep-template.rst has the full skeleton; this file explains what each section is for and the bar it must clear. Only the Copyright section is strictly mandatory, but a serious Standards Track PEP needs Abstract, Motivation, Rationale, Specification, and Backwards Compatibility to stand a chance. Source: PEP 12.

The acceptance bar (write to this)

From PEP 1, a PEP is accepted only if it is: 1. a clear and complete description of the enhancement, 2. a net improvement, 3. backed by a solid implementation that doesn't unduly complicate the interpreter (if applicable), and 4. "pythonic".

Every section below exists to demonstrate one of these. If a section doesn't move a reviewer toward "yes" on one of them, tighten it.

Sections

Section order matters. Note that Specification comes before Rationale in

the canonical PEP 12 template — describe what you propose, then justify why.

Mandatory copyright notice (verbatim)

Copyright
=========

This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.

scripts/check-pep.sh fails the draft if the CC0-1.0-Universal notice is missing.

reStructuredText conventions

PEPs are UTF-8 reStructuredText. The conventions that matter:

• Section headers use an underline of punctuation at least as long as the title:
• First level: = underline
• Second level: - underline
• Third level: ' underline
• Capitalise each word; acronyms stay all-caps. Leave two blank lines before the next section heading.

• Code / literal blocks: end the lead-in line with :: then indent the block 4

spaces, or use .. code-block:: python.

• Links: inline as ` link text <https://example.com>__ `. Reference other PEPs

and RFCs with the roles :pep:\8\` and :rfc:\2822\` rather than raw URLs.

• Footnotes: cite with `[#label]_ in the text and define with `.. [#label]

content`` in the Footnotes section.

• Lists: bullets with -/*/+; numbered with 1./a.; definition lists are a

term line followed by an indented definition.

Auxiliary files

Diagrams: pep-XXXX-Y.ext (serial Y from 1) or anything inside a pep-XXXX/ subdirectory. Prefer SVG/PNG, legible in light and dark mode.

Status Lifecycle

The Status header tracks where a PEP is in its life. Setting it to a value the process doesn't allow (or skipping the Resolution header on a decision) is a common slip. Source: PEP 1.

The statuses

Valid transitions

Draft ──► Deferred ──► Draft            (stalled, then revived)
Draft ──► Rejected | Withdrawn
Draft ──► Accepted ──► Final
Accepted ──► Provisional ──► Final
Accepted | Provisional ──► Rejected | Withdrawn
Rejected | Withdrawn | Final | Superseded ──► Active   (meta-PEPs only)

Notes that trip people up:

• **Accepted → Rejected / Withdrawn is allowed only before the change ships in a

Python release.** Once released, an accepted PEP can't be un-accepted (only Provisional PEPs can be reversed post-release).

• **A PEP-Delegate stepping down (or being asked to) overrules any prior

acceptance/rejection and reverts the PEP to Draft.**

• `Active` is reachable only for Informational/Process meta-PEPs that are living

documents.

The Resolution header on a decision

When a PEP becomes Accepted, Rejected, or Withdrawn, update the PEP accordingly: at minimum change Status and add a Resolution header with a direct link to the post making the decision (posted to the PEPs category of the Python Discourse). For Standards Track PEPs the Resolution header is mandatory; check-pep.sh flags its absence.

Reaching Final

Final requires the reference implementation to be complete and merged. A PEP can be Accepted without it, but not Final. Don't set Final while the implementation is still in review.

The PEP Process: From Idea to Resolution

The PEP process is as much about building consensus as about writing a document. The author's job is to champion the idea, document dissent fairly, and shepherd it through review. Source of truth: PEP 1.

The roles

Step 1 — Vet the idea (pre-PEP discussion)

Public vetting saves the author time: it weeds out ideas already rejected in prior discussions, confirms the idea is original, and confirms it's applicable to the whole community rather than just the author. Do this before drafting.

Post to the appropriate venue:

• Ideas category of the Python Discourse — general proposals.
• Typing category — static typing ideas.
• Packaging category — packaging ideas.

Once vetted, a draft PEP is presented to the same venue to be made well-formatted, high quality, and to address initial concerns.

Step 2 — Determine your path (core dev or not?)

• If one or more co-authors are core developers, they follow the submission steps below directly.
• Otherwise, the author(s) must find a sponsor first. A sponsor is a core developer (or SC-approved community member) who agrees to shepherd the PEP. Record them in the Sponsor header. PEP-editors team members and Typing Council members are pre-approved to act as sponsors.

Step 3 — Submit the PEP

1. Fork the python/peps repository. 2. Create pep-NNNN.rst, where NNNN is the next available PEP number not used by a published or in-PR PEP. 3. In the header: put the number in PEP:, set Type: to one of the three types, set Status: Draft. 4. Update .github/CODEOWNERS so any co-authors/sponsors with write access are listed for your file. 5. Push to your fork and open a pull request.

PEP editors then review for: a sound and complete idea that makes technical sense; an accurate title; correct language and code style; and valid reStructuredText (checked automatically). Approval is not a guarantee of correctness — that stays with authors and reviewers. Once approved, editors assign the PEP number.

Reasons editors may deny PEP status: duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not being in keeping with the Python philosophy.

Core developers with write access may claim a number and commit a new PEP directly,

taking on the tasks editors would normally handle.

Step 4 — Discussion and revision

Draft PEPs are freely open for discussion and modification at the authors' discretion until submitted for review. Substantive content changes should generally be proposed first on the PEP's Discussions-To thread; copyedits and corrections can go straight to a GitHub issue or PR. Record discussion threads in Post-History.

Step 5 — Review and resolution

When the authors (and sponsor, if any) judge the PEP ready for final review, content review and acceptance become the Steering Council's responsibility, formally initiated by opening a Steering Council issue.

• Any suitably experienced core developer may offer to be the PEP-Delegate by notifying the SC (and the authors/sponsor). The SC generally approves such self-nominations by default, but may decline (e.g. conflict of interest).
• If no volunteer steps forward and no suitable candidate can be found, the PEP is marked Deferred until one is available.
• For type-system PEPs, request a recommendation from the Typing Council via its issue tracker.

Acceptance criteria (a PEP must meet all): a clear and complete description of the enhancement; the enhancement is a net improvement; the implementation (if any) is solid and does not unduly complicate the interpreter; and the proposal is "pythonic".

The reference implementation must be complete before a PEP becomes Final, but not before it is accepted. Pronouncements of resolution are posted to the PEPs category of the Python Discourse; link to that post from the Resolution header.

After resolution — modifying a PEP

Once a PEP reaches Accepted, Final, Rejected, or Superseded, it is a historical document, not a living spec, and is no longer substantially modified. Exceptions:

• Provisional (or, with SC approval, Accepted) Standards Track PEPs may be updated from implementation experience — note the changes in the PEP.
• Active (Informational/Process) PEPs may be updated over time to reflect changing practice.

Transferring PEP ownership

Sometimes a PEP needs a new champion (the original author lost time/interest or went quiet). A bad reason is disagreement with the PEP's direction. To take over: fork, make the ownership change, open a PR, and mention both the original author and @python/pep-editors. It's preferable to keep the original author as a co-author. If the original author is unresponsive, the PEP editors make a unilateral decision.

Auxiliary files

Diagrams and other support files are named pep-XXXX-Y.ext (XXXX = PEP number, Y = serial number from 1, ext = extension), or placed in a pep-XXXX/ subdirectory (no naming constraints inside it). Prefer browser-friendly formats (SVG, PNG) that are legible in both light and dark mode.

Copyright

Each new PEP must be dual-licensed: public domain and CC0-1.0-Universal. The mandatory closing notice is in sections.md.