mirror of https://github.com/python/peps
845 lines
59 KiB
HTML
845 lines
59 KiB
HTML
|
||
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="color-scheme" content="light dark">
|
||
<title>PEP 1 – PEP Purpose and Guidelines | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0001/">
|
||
<link rel="stylesheet" href="../_static/style.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/mq.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light">
|
||
<link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark">
|
||
<link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss">
|
||
<meta property="og:title" content='PEP 1 – PEP Purpose and Guidelines | peps.python.org'>
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0001/">
|
||
<meta property="og:site_name" content="Python Enhancement Proposals (PEPs)">
|
||
<meta property="og:image" content="https://peps.python.org/_static/og-image.png">
|
||
<meta property="og:image:alt" content="Python PEPs">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="description" content="Python Enhancement Proposals (PEPs)">
|
||
<meta name="theme-color" content="#3776ab">
|
||
</head>
|
||
<body>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
|
||
<symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Following system colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="9"></circle>
|
||
<path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected dark colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
|
||
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected light colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="5"></circle>
|
||
<line x1="12" y1="1" x2="12" y2="3"></line>
|
||
<line x1="12" y1="21" x2="12" y2="23"></line>
|
||
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
|
||
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
|
||
<line x1="1" y1="12" x2="3" y2="12"></line>
|
||
<line x1="21" y1="12" x2="23" y2="12"></line>
|
||
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
|
||
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
|
||
</svg>
|
||
</symbol>
|
||
</svg>
|
||
<script>
|
||
|
||
document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto"
|
||
</script>
|
||
<section id="pep-page-section">
|
||
<header>
|
||
<h1>Python Enhancement Proposals</h1>
|
||
<ul class="breadcrumbs">
|
||
<li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li>
|
||
<li><a href="../pep-0000/">PEP Index</a> » </li>
|
||
<li>PEP 1</li>
|
||
</ul>
|
||
<button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())">
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
<span class="visually-hidden">Toggle light / dark / auto colour theme</span>
|
||
</button>
|
||
</header>
|
||
<article>
|
||
<section id="pep-content">
|
||
<h1 class="page-title">PEP 1 – PEP Purpose and Guidelines</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Barry Warsaw, Jeremy Hylton, David Goodger, Alyssa Coghlan</dd>
|
||
<dt class="field-even">Status<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Currently valid informational guidance, or an in-use process">Active</abbr></dd>
|
||
<dt class="field-odd">Type<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Normative PEP describing or proposing a change to a Python community process, workflow or governance">Process</abbr></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">13-Jun-2000</dd>
|
||
<dt class="field-odd">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-odd">21-Mar-2001, 29-Jul-2002, 03-May-2003, 05-May-2012,
|
||
07-Apr-2013</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<section id="contents">
|
||
<details><summary>Table of Contents</summary><ul class="simple">
|
||
<li><a class="reference internal" href="#what-is-a-pep">What is a PEP?</a></li>
|
||
<li><a class="reference internal" href="#pep-audience">PEP Audience</a></li>
|
||
<li><a class="reference internal" href="#pep-types">PEP Types</a></li>
|
||
<li><a class="reference internal" href="#pep-workflow">PEP Workflow</a><ul>
|
||
<li><a class="reference internal" href="#python-s-steering-council">Python’s Steering Council</a></li>
|
||
<li><a class="reference internal" href="#python-s-core-developers">Python’s Core Developers</a></li>
|
||
<li><a class="reference internal" href="#python-s-bdfl">Python’s BDFL</a></li>
|
||
<li><a class="reference internal" href="#pep-editors">PEP Editors</a></li>
|
||
<li><a class="reference internal" href="#start-with-an-idea-for-python">Start with an idea for Python</a></li>
|
||
<li><a class="reference internal" href="#submitting-a-pep">Submitting a PEP</a></li>
|
||
<li><a class="reference internal" href="#discussing-a-pep">Discussing a PEP</a></li>
|
||
<li><a class="reference internal" href="#pep-review-resolution">PEP Review & Resolution</a></li>
|
||
<li><a class="reference internal" href="#pep-maintenance">PEP Maintenance</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#what-belongs-in-a-successful-pep">What belongs in a successful PEP?</a></li>
|
||
<li><a class="reference internal" href="#pep-formats-and-templates">PEP Formats and Templates</a></li>
|
||
<li><a class="reference internal" href="#pep-header-preamble">PEP Header Preamble</a></li>
|
||
<li><a class="reference internal" href="#auxiliary-files">Auxiliary Files</a></li>
|
||
<li><a class="reference internal" href="#changing-existing-peps">Changing Existing PEPs</a></li>
|
||
<li><a class="reference internal" href="#transferring-pep-ownership">Transferring PEP Ownership</a></li>
|
||
<li><a class="reference internal" href="#pep-editor-responsibilities-workflow">PEP Editor Responsibilities & Workflow</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<section id="what-is-a-pep">
|
||
<h2><a class="toc-backref" href="#what-is-a-pep" role="doc-backlink">What is a PEP?</a></h2>
|
||
<p>PEP stands for Python Enhancement Proposal. A PEP is a design
|
||
document providing information to the Python community, or describing
|
||
a new feature for Python or its processes or environment. The PEP
|
||
should provide a concise technical specification of the feature and a
|
||
rationale for the feature.</p>
|
||
<p>We intend PEPs to be the primary mechanisms for proposing major new
|
||
features, for collecting community input on an issue, and for
|
||
documenting the design decisions that have gone into Python. The PEP
|
||
author is responsible for building consensus within the community and
|
||
documenting dissenting opinions.</p>
|
||
<p>Because the PEPs are maintained as text files in a versioned
|
||
repository, their revision history is the historical record of the
|
||
feature proposal. This historical record is available by the normal git
|
||
commands for retrieving older revisions, and can also be browsed
|
||
<a class="reference external" href="https://github.com/python/peps">on GitHub</a>.</p>
|
||
</section>
|
||
<section id="pep-audience">
|
||
<h2><a class="toc-backref" href="#pep-audience" role="doc-backlink">PEP Audience</a></h2>
|
||
<p>The typical primary audience for PEPs are the core developers of the CPython
|
||
reference interpreter and their elected Steering Council, as well as developers
|
||
of other implementations of the Python language specification.</p>
|
||
<p>However, other parts of the Python community may also choose to use the process
|
||
(particularly for Informational PEPs) to document expected API conventions and
|
||
to manage complex design coordination problems that require collaboration across
|
||
multiple projects.</p>
|
||
</section>
|
||
<section id="pep-types">
|
||
<h2><a class="toc-backref" href="#pep-types" role="doc-backlink">PEP Types</a></h2>
|
||
<p>There are three kinds of PEP:</p>
|
||
<ol class="arabic simple">
|
||
<li>A <strong>Standards Track</strong> PEP describes a new feature or implementation
|
||
for Python. It may also describe an interoperability standard that will
|
||
be supported outside the standard library for current Python versions
|
||
before a subsequent PEP adds standard library support in a future
|
||
version.</li>
|
||
<li>An <strong>Informational</strong> PEP describes a Python design issue, or
|
||
provides general guidelines or information to the Python community,
|
||
but does not propose a new feature. Informational PEPs do not
|
||
necessarily represent a Python community consensus or
|
||
recommendation, so users and implementers are free to ignore
|
||
Informational PEPs or follow their advice.</li>
|
||
<li>A <strong>Process</strong> PEP describes a process surrounding Python, or
|
||
proposes a change to (or an event in) a process. Process PEPs are
|
||
like Standards Track PEPs but apply to areas other than the Python
|
||
language itself. They may propose an implementation, but not to
|
||
Python’s codebase; they often require community consensus; unlike
|
||
Informational PEPs, they are more than recommendations, and users
|
||
are typically not free to ignore them. Examples include
|
||
procedures, guidelines, changes to the decision-making process, and
|
||
changes to the tools or environment used in Python development.
|
||
Any meta-PEP is also considered a Process PEP.</li>
|
||
</ol>
|
||
</section>
|
||
<section id="pep-workflow">
|
||
<h2><a class="toc-backref" href="#pep-workflow" role="doc-backlink">PEP Workflow</a></h2>
|
||
<section id="python-s-steering-council">
|
||
<h3><a class="toc-backref" href="#python-s-steering-council" role="doc-backlink">Python’s Steering Council</a></h3>
|
||
<p>There are several references in this PEP to the “Steering Council” or “Council”.
|
||
This refers to the current members of the elected Steering Council described
|
||
in <a class="pep reference internal" href="../pep-0013/" title="PEP 13 – Python Language Governance">PEP 13</a>, in their role as the final authorities on whether or not PEPs
|
||
will be accepted or rejected.</p>
|
||
</section>
|
||
<section id="python-s-core-developers">
|
||
<h3><a class="toc-backref" href="#python-s-core-developers" role="doc-backlink">Python’s Core Developers</a></h3>
|
||
<p>There are several references in this PEP to “core developers”. This refers to
|
||
the currently active Python core team members described in <a class="pep reference internal" href="../pep-0013/" title="PEP 13 – Python Language Governance">PEP 13</a>.</p>
|
||
</section>
|
||
<section id="python-s-bdfl">
|
||
<h3><a class="toc-backref" href="#python-s-bdfl" role="doc-backlink">Python’s BDFL</a></h3>
|
||
<p>Previous versions of this PEP used the title “BDFL-Delegate” for PEP decision
|
||
makers. This was a historical reference to Python’s previous governance model,
|
||
where all design authority ultimately derived from Guido van Rossum, the
|
||
original creator of the Python programming language. By contrast, the Steering
|
||
Council’s design authority derives from their election by the currently active
|
||
core developers. Now, PEP-Delegate is used in place of BDFL-Delegate.</p>
|
||
</section>
|
||
<section id="pep-editors">
|
||
<h3><a class="toc-backref" href="#pep-editors" role="doc-backlink">PEP Editors</a></h3>
|
||
<p>The PEP editors are individuals responsible for managing the administrative
|
||
and editorial aspects of the PEP workflow (e.g. assigning PEP numbers and
|
||
changing their status). See <a class="reference internal" href="#pep-editor-responsibilities-workflow">PEP Editor Responsibilities & Workflow</a> for
|
||
details.</p>
|
||
<p>PEP editorship is by invitation of the current editors, and they can be
|
||
contacted by mentioning <code class="docutils literal notranslate"><span class="pre">@python/pep-editors</span></code> on GitHub. All of the PEP
|
||
workflow can be conducted via the GitHub <a class="reference external" href="https://github.com/python/peps">PEP repository</a> issues and pull
|
||
requests.</p>
|
||
</section>
|
||
<section id="start-with-an-idea-for-python">
|
||
<h3><a class="toc-backref" href="#start-with-an-idea-for-python" role="doc-backlink">Start with an idea for Python</a></h3>
|
||
<p>The PEP process begins with a new idea for Python. It is highly
|
||
recommended that a single PEP contain a single key proposal or new
|
||
idea; the more focused the PEP, the more successful it tends to be.
|
||
Most enhancements and bug fixes don’t need a PEP and
|
||
can be submitted directly to the <a class="reference external" href="https://github.com/python/cpython/issues">Python issue tracker</a>.
|
||
The PEP editors reserve the
|
||
right to reject PEP proposals if they appear too unfocused or too
|
||
broad. If in doubt, split your PEP into several well-focused ones.</p>
|
||
<p>Each PEP must have a champion – someone who writes the PEP using the style
|
||
and format described below, shepherds the discussions in the appropriate
|
||
forums, and attempts to build community consensus around the idea. The PEP
|
||
champion (a.k.a. Author) should first attempt to ascertain whether the idea is
|
||
PEP-able. Posting to the <a class="reference external" href="https://discuss.python.org/c/ideas/">Ideas category</a> of the <a class="reference external" href="https://discuss.python.org/">Python Discourse</a> is usually
|
||
the best way to go about this, unless a more specialized venue is appropriate,
|
||
such as the <a class="reference external" href="https://discuss.python.org/c/typing/">Typing category</a> (for static typing ideas)
|
||
or <a class="reference external" href="https://discuss.python.org/c/packaging/">Packaging category</a> (for packaging ideas) on the Python Discourse.</p>
|
||
<p>Vetting an idea publicly before going as far as writing a PEP is meant
|
||
to save the potential author time. Many ideas have been brought
|
||
forward for changing Python that have been rejected for various
|
||
reasons. Asking the Python community first if an idea is original
|
||
helps prevent too much time being spent on something that is
|
||
guaranteed to be rejected based on prior discussions (searching
|
||
the internet does not always do the trick). It also helps to make sure
|
||
the idea is applicable to the entire community and not just the author.
|
||
Just because an idea sounds good to the author does not
|
||
mean it will work for most people in most areas where Python is used.</p>
|
||
<p>Once the champion has asked the Python community as to whether an
|
||
idea has any chance of acceptance, a draft PEP should be presented to
|
||
the appropriate venue mentioned above.
|
||
This gives the author a chance to flesh out the draft
|
||
PEP to make properly formatted, of high quality, and to address
|
||
initial concerns about the proposal.</p>
|
||
</section>
|
||
<section id="submitting-a-pep">
|
||
<h3><a class="toc-backref" href="#submitting-a-pep" role="doc-backlink">Submitting a PEP</a></h3>
|
||
<p>Following the above initial discussion, the workflow varies based on whether
|
||
any of the PEP’s co-authors are core developers. If one or more of the PEP’s
|
||
co-authors are core developers, they are responsible for following the process
|
||
outlined below. Otherwise (i.e. none of the co-authors are core developers),
|
||
then the PEP author(s) will need to find a sponsor for the PEP.</p>
|
||
<p>Ideally, a core developer sponsor is identified, but non-core sponsors may also
|
||
be selected with the approval of the Steering Council. Members of the GitHub
|
||
“PEP editors” team and members of the Typing Council (<a class="pep reference internal" href="../pep-0729/" title="PEP 729 – Typing governance process">PEP 729</a>) are
|
||
pre-approved to be sponsors. The sponsor’s job is to
|
||
provide guidance to the PEP author to help them through the logistics of the
|
||
PEP process (somewhat acting like a mentor). Being a sponsor does <strong>not</strong>
|
||
disqualify that person from becoming a co-author or PEP-Delegate later on (but
|
||
not both). The sponsor of a PEP is recorded in the “Sponsor:” field of the
|
||
header.</p>
|
||
<p>Once the sponsor or the core developer(s) co-authoring the PEP deem the PEP
|
||
ready for submission, the proposal should be submitted as a draft PEP via a
|
||
<a class="reference external" href="https://github.com/python/peps/pulls">GitHub pull request</a>. The draft must be written in PEP style as described
|
||
below, else it will fail review immediately (although minor errors may be
|
||
corrected by the editors).</p>
|
||
<p>The standard PEP workflow is:</p>
|
||
<ul>
|
||
<li>You, the PEP author, fork the <a class="reference external" href="https://github.com/python/peps">PEP repository</a>, and create a file named
|
||
<code class="file docutils literal notranslate"><span class="pre">pep-</span><em><span class="pre">NNNN</span></em><span class="pre">.rst</span></code> that contains your new PEP. <code class="samp docutils literal notranslate"><em><span class="pre">NNNN</span></em></code> should be the next
|
||
available PEP number not used by a published or in-PR PEP.</li>
|
||
<li>In the “PEP:” header field, enter the PEP number that matches your filename
|
||
as your draft PEP number.</li>
|
||
<li>In the “Type:” header field, enter “Standards Track”,
|
||
“Informational”, or “Process” as appropriate, and for the “Status:”
|
||
field enter “Draft”. For full details, see <a class="reference internal" href="#pep-header-preamble">PEP Header Preamble</a>.</li>
|
||
<li>Update <a class="reference external" href="https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners">.github/CODEOWNERS</a> such that any co-author(s) or sponsors
|
||
with write access to the <a class="reference external" href="https://github.com/python/peps">PEP repository</a> are listed for your new file.
|
||
This ensures any future pull requests changing the file will be assigned
|
||
to them.</li>
|
||
<li>Push this to your GitHub fork and submit a pull request.</li>
|
||
<li>The PEP editors review your PR for structure, formatting, and other
|
||
errors. For a reST-formatted PEP, <a class="pep reference internal" href="../pep-0012/" title="PEP 12 – Sample reStructuredText PEP Template">PEP 12</a> is provided as a template.
|
||
It also provides a complete introduction to reST markup that is used
|
||
in PEPs. Approval criteria are:<ul class="simple">
|
||
<li>It is sound and complete. The ideas must make technical sense. The
|
||
editors do not consider whether they seem likely to be accepted.</li>
|
||
<li>The title accurately describes the content.</li>
|
||
<li>The PEP’s language (spelling, grammar, sentence structure, etc.)
|
||
and code style (examples should match <a class="pep reference internal" href="../pep-0007/" title="PEP 7 – Style Guide for C Code">PEP 7</a> & <a class="pep reference internal" href="../pep-0008/" title="PEP 8 – Style Guide for Python Code">PEP 8</a>) should be
|
||
correct and conformant. The PEP text will be automatically checked for
|
||
correct reStructuredText formatting when the pull request is submitted.
|
||
PEPs with invalid reST markup will not be approved.</li>
|
||
</ul>
|
||
<p>Editors are generally quite lenient about this initial review,
|
||
expecting that problems will be corrected by the reviewing process.
|
||
<strong>Note:</strong> Approval of the PEP is no guarantee that there are no
|
||
embarrassing mistakes! Correctness is the responsibility of authors
|
||
and reviewers, not the editors.</p>
|
||
<p>If the PEP isn’t ready for approval, an editor will send it back to
|
||
the author for revision, with specific instructions.</p>
|
||
</li>
|
||
<li>Once approved, they will assign your PEP a number.</li>
|
||
</ul>
|
||
<p>Once the review process is complete, and the PEP editors approve it (note that
|
||
this is <em>not</em> the same as accepting your PEP!), they will squash commit your
|
||
pull request onto main.</p>
|
||
<p>The PEP editors will not unreasonably deny publication of a PEP. Reasons for
|
||
denying PEP status include duplication of effort, being technically unsound,
|
||
not providing proper motivation or addressing backwards compatibility, or not
|
||
in keeping with the Python philosophy. The Steering Council can be consulted
|
||
during the approval phase, and are the final arbiter of a draft’s PEP-ability.</p>
|
||
<p>Developers with write access to the <a class="reference external" href="https://github.com/python/peps">PEP repository</a> may claim PEP
|
||
numbers directly by creating and committing a new PEP. When doing so, the
|
||
developer must handle the tasks that would normally be taken care of by the
|
||
PEP editors (see <a class="reference internal" href="#pep-editor-responsibilities-workflow">PEP Editor Responsibilities & Workflow</a>). This includes
|
||
ensuring the initial version meets the expected standards for submitting a
|
||
PEP. Alternately, even developers should submit PEPs via pull request.
|
||
When doing so, you are generally expected to handle the process yourself;
|
||
if you need assistance from PEP editors, mention <code class="docutils literal notranslate"><span class="pre">@python/pep-editors</span></code>
|
||
on GitHub.</p>
|
||
<p>As updates are necessary, the PEP author can check in new versions if they
|
||
(or a collaborating developer) have write access to the <a class="reference external" href="https://github.com/python/peps">PEP repository</a>.
|
||
Getting a PEP number assigned early can be useful for ease of
|
||
reference, especially when multiple draft PEPs are being considered at the
|
||
same time.</p>
|
||
<p>Standards Track PEPs consist of two parts, a design document and a
|
||
reference implementation. It is generally recommended that at least a
|
||
prototype implementation be co-developed with the PEP, as ideas that sound
|
||
good in principle sometimes turn out to be impractical when subjected to the
|
||
test of implementation.</p>
|
||
</section>
|
||
<section id="discussing-a-pep">
|
||
<h3><a class="toc-backref" href="#discussing-a-pep" role="doc-backlink">Discussing a PEP</a></h3>
|
||
<p>As soon as a PEP number has been assigned
|
||
and the draft PEP is committed to the <a class="reference external" href="https://github.com/python/peps">PEP repository</a>,
|
||
a discussion thread for the PEP should be created
|
||
to provide a central place to discuss and review its contents, and the
|
||
PEP should be updated so that the <code class="docutils literal notranslate"><span class="pre">Discussions-To</span></code> header links to it.</p>
|
||
<p>The PEP authors (or sponsor, if applicable) may select any reasonable venue
|
||
for the discussion, so long as the the following criteria are met:</p>
|
||
<ul class="simple">
|
||
<li>The forum is appropriate to the PEP’s topic.</li>
|
||
<li>The thread is publicly available on the web so that all interested parties
|
||
can participate.</li>
|
||
<li>The discussion is subject to the <a class="reference external" href="https://www.python.org/psf/conduct/">Python Community Code of Conduct</a>.</li>
|
||
<li>A direct link to the current discussion thread is provided in the PEP
|
||
under the <code class="docutils literal notranslate"><span class="pre">Discussions-To</span></code> header.</li>
|
||
</ul>
|
||
<p>The <a class="reference external" href="https://discuss.python.org/c/peps/">PEPs category</a> of the <a class="reference external" href="https://discuss.python.org/">Python Discourse</a>
|
||
is the preferred choice for most new PEPs,
|
||
whereas historically the <a class="reference external" href="https://mail.python.org/mailman3/lists/python-dev.python.org/">Python-Dev</a> mailing list was commonly used.
|
||
Some specialized topics have specific venues, such as
|
||
the <a class="reference external" href="https://discuss.python.org/c/typing/">Typing category</a> and the <a class="reference external" href="https://discuss.python.org/c/packaging/">Packaging category</a> on the Python
|
||
Discourse for typing and packaging PEPs, respectively.
|
||
If the PEP authors are unsure of the best venue,
|
||
the PEP Sponsor and PEP editors can advise them accordingly.</p>
|
||
<p>If a PEP undergoes a significant re-write or other major, substantive
|
||
changes to its proposed specification, a new thread should typically be created
|
||
in the chosen venue to solicit additional feedback. If this occurs, the
|
||
<code class="docutils literal notranslate"><span class="pre">Discussions-To</span></code> link must be updated and a new <code class="docutils literal notranslate"><span class="pre">Post-History</span></code> entry added
|
||
pointing to this new thread.</p>
|
||
<p>If it is not chosen as the discussion venue,
|
||
a brief announcement post should be made to the <a class="reference external" href="https://discuss.python.org/c/peps/">PEPs category</a>
|
||
with at least a link to the rendered PEP and the <code class="docutils literal notranslate"><span class="pre">Discussions-To</span></code> thread
|
||
when the draft PEP is committed to the repository
|
||
and if a major-enough change is made to trigger a new thread.</p>
|
||
<p>PEP authors are responsible for collecting community feedback on a PEP
|
||
before submitting it for review. However, to avoid long-winded and
|
||
open-ended discussions, strategies such as soliciting private or more
|
||
narrowly-tailored feedback in the early design phase,
|
||
collaborating with other community members with expertise in the PEP’s
|
||
subject matter, and picking an appropriately-specialized discussion for the
|
||
PEP’s topic (if applicable) should be considered.
|
||
PEP authors should use their discretion here.</p>
|
||
<p>Once the PEP is assigned a number and committed to the PEP repository,
|
||
substantive issues should generally be discussed on the canonical public
|
||
thread, as opposed to private channels, GitHub pull request reviews or
|
||
unrelated venues. This ensures everyone can follow and contribute,
|
||
avoids fragmenting the discussion,
|
||
and makes sure it is fully considered as part of the PEP review process.
|
||
Comments, support, concerns and other feedback on this designated thread
|
||
are a critical part of what the Steering Council or PEP-Delegate will
|
||
consider when reviewing the PEP.</p>
|
||
</section>
|
||
<section id="pep-review-resolution">
|
||
<h3><a class="toc-backref" href="#pep-review-resolution" role="doc-backlink">PEP Review & Resolution</a></h3>
|
||
<p>Once the authors have completed a PEP, they may request a review for
|
||
style and consistency from the PEP editors.
|
||
However, content review and acceptance of the PEP is ultimately the
|
||
responsibility of the Steering Council, which is formally initiated by
|
||
opening a <a class="reference external" href="https://github.com/python/steering-council/issues/new/choose">Steering Council issue</a> once the authors (and sponsor, if any)
|
||
determine the PEP is ready for final review and resolution.</p>
|
||
<p>To expedite the process in selected cases (e.g. when a change is clearly
|
||
beneficial and ready to be accepted, but the PEP hasn’t been formally submitted
|
||
for review yet), the Steering Council may also initiate a PEP review, first
|
||
notifying the PEP author(s) and giving them a chance to make revisions.</p>
|
||
<p>The final authority for PEP approval is the Steering Council. However, whenever
|
||
a new PEP is put forward, any core developer who believes they are suitably
|
||
experienced to make the final decision on that PEP may offer to serve as its
|
||
PEP-Delegate by <a class="reference external" href="https://github.com/python/steering-council/issues/new/choose">notifying the Steering Council</a>
|
||
of their intent. If the Steering Council approves their offer,
|
||
the PEP-Delegate will then have the authority to approve or reject that PEP.
|
||
For PEPs related to the Python type system, the Typing Council (<a class="pep reference internal" href="../pep-0729/" title="PEP 729 – Typing governance process">PEP 729</a>)
|
||
provides a recommendation to the Steering Council. To request such a
|
||
recommendation, open an issue on the <a class="reference external" href="https://github.com/python/typing-council/issues">Typing Council issue tracker</a>.</p>
|
||
<p>The term “PEP-Delegate” is used under the Steering Council governance model
|
||
for the PEP’s designated decision maker,
|
||
who is recorded in the “PEP-Delegate” field in the PEP’s header.
|
||
The term “BDFL-Delegate” is a deprecated alias for PEP-Delegate, a legacy of
|
||
the time when when Python was led by <a class="reference internal" href="#python-s-bdfl">a BDFL</a>.
|
||
Any legacy references to “BDFL-Delegate” should be treated as equivalent to
|
||
“PEP-Delegate”.</p>
|
||
<p>An individual offering to nominate themselves as a PEP-Delegate must notify
|
||
the relevant authors and (when present) the sponsor for the PEP, and submit
|
||
their request to the Steering Council
|
||
(which can be done via a <a class="reference external" href="https://github.com/python/steering-council/issues/new/choose">new issue</a> ).
|
||
Those taking on this responsibility are free to seek
|
||
additional guidance from the Steering Council at any time, and are also expected
|
||
to take the advice and perspectives of other core developers into account.</p>
|
||
<p>The Steering Council will generally approve such self-nominations by default,
|
||
but may choose to decline them.
|
||
Possible reasons for the Steering Council declining a
|
||
self-nomination as PEP-Delegate include, but are not limited to, perceptions of
|
||
a potential conflict of interest (e.g. working for the same organisation as the
|
||
PEP submitter), or simply considering another potential PEP-Delegate to be
|
||
more appropriate. If core developers (or other community members) have concerns
|
||
regarding the suitability of a PEP-Delegate for any given PEP, they may ask
|
||
the Steering Council to review the delegation.</p>
|
||
<p>If no volunteer steps forward, then the Steering Council will approach core
|
||
developers (and potentially other Python community members) with relevant
|
||
expertise, in an attempt to identify a candidate that is willing to serve as
|
||
PEP-Delegate for that PEP. If no suitable candidate can be found, then the
|
||
PEP will be marked as Deferred until one is available.</p>
|
||
<p>Previously appointed PEP-Delegates may choose to step down, or be asked to step
|
||
down by the Council, in which case a new PEP-Delegate will be appointed in the
|
||
same manner as for a new PEP (including deferral of the PEP if no suitable
|
||
replacement can be found). In the event that a PEP-Delegate is asked to step
|
||
down, this will overrule any prior acceptance or rejection of the PEP, and it
|
||
will revert to Draft status.</p>
|
||
<p>When such standing delegations are put in place, the Steering Council will
|
||
maintain sufficient public records to allow subsequent Councils, the core
|
||
developers, and the wider Python community to understand the delegations that
|
||
currently exist, why they were put in place, and the circumstances under which
|
||
they may no longer be needed.</p>
|
||
<p>For a PEP to be accepted it must meet certain minimum criteria. It
|
||
must be a clear and complete description of the proposed enhancement.
|
||
The enhancement must represent a net improvement. The proposed
|
||
implementation, if applicable, must be solid and must not complicate
|
||
the interpreter unduly. Finally, a proposed enhancement must be
|
||
“pythonic” in order to be accepted by the Steering Council. (However,
|
||
“pythonic” is an imprecise term; it may be defined as whatever is acceptable to
|
||
the Steering Council. This logic is intentionally circular.) See <a class="pep reference internal" href="../pep-0002/" title="PEP 2 – Procedure for Adding New Modules">PEP 2</a>
|
||
for standard library module acceptance criteria.</p>
|
||
<p>Except where otherwise approved by the Steering Council,
|
||
pronouncements of PEP resolution will be posted to the
|
||
<a class="reference external" href="https://discuss.python.org/c/peps/">PEPs category</a> on the <a class="reference external" href="https://discuss.python.org/">Python Discourse</a>.</p>
|
||
<p>Once a PEP has been accepted, the reference implementation must be
|
||
completed. When the reference implementation is complete and incorporated
|
||
into the main source code repository, the status will be changed to “Final”.</p>
|
||
<p>To allow gathering of additional design and interface feedback before committing
|
||
to long term stability for a language feature or standard library API, a PEP
|
||
may also be marked as “Provisional”. This is short for “Provisionally Accepted”,
|
||
and indicates that the proposal has been accepted for inclusion in the reference
|
||
implementation, but additional user feedback is needed before the full design
|
||
can be considered “Final”. Unlike regular accepted PEPs, provisionally accepted
|
||
PEPs may still be Rejected or Withdrawn <em>even after the related changes have
|
||
been included in a Python release</em>.</p>
|
||
<p>Wherever possible, it is considered preferable to reduce the scope of a proposal
|
||
to avoid the need to rely on the “Provisional” status (e.g. by deferring some
|
||
features to later PEPs), as this status can lead to version compatibility
|
||
challenges in the wider Python ecosystem. <a class="pep reference internal" href="../pep-0411/" title="PEP 411 – Provisional packages in the Python standard library">PEP 411</a> provides additional details
|
||
on potential use cases for the Provisional status.</p>
|
||
<p>A PEP can also be assigned the status “Deferred”. The PEP author or an
|
||
editor can assign the PEP this status when no progress is being made
|
||
on the PEP. Once a PEP is deferred, a PEP editor can reassign it
|
||
to draft status.</p>
|
||
<p>A PEP can also be “Rejected”. Perhaps after all is said and done it
|
||
was not a good idea. It is still important to have a record of this
|
||
fact. The “Withdrawn” status is similar - it means that the PEP author
|
||
themselves has decided that the PEP is actually a bad idea, or has
|
||
accepted that a competing proposal is a better alternative.</p>
|
||
<p>When a PEP is Accepted, Rejected or Withdrawn, the PEP should be updated
|
||
accordingly. In addition to updating the Status field, at the very least
|
||
the Resolution header should be added with a direct link
|
||
to the relevant post making a decision on the PEP.</p>
|
||
<p>PEPs can also be superseded by a different PEP, rendering the original
|
||
obsolete. This is intended for Informational PEPs, where version 2 of
|
||
an API can replace version 1.</p>
|
||
<p>The possible paths of the status of PEPs are as follows:</p>
|
||
<img alt="PEP process flow diagram" class="invert-in-dark-mode" src="../_images/process_flow.svg" /><p>While not shown in the diagram, “Accepted” PEPs may technically move to
|
||
“Rejected” or “Withdrawn” even after acceptance. This will only occur if
|
||
the implementation process reveals fundamental flaws in the design that were
|
||
not noticed prior to acceptance of the PEP. Unlike Provisional PEPs, these
|
||
transitions are only permitted if the accepted proposal has <em>not</em> been included
|
||
in a Python release - released changes must instead go through the regular
|
||
deprecation process (which may require a new PEP providing the rationale for
|
||
the deprecation).</p>
|
||
<p>Some Informational and Process PEPs may also have a status of “Active”
|
||
if they are never meant to be completed. E.g. <a class="pep reference internal" href="../pep-0001/" title="PEP 1 – PEP Purpose and Guidelines">PEP 1</a> (this PEP).</p>
|
||
</section>
|
||
<section id="pep-maintenance">
|
||
<h3><a class="toc-backref" href="#pep-maintenance" role="doc-backlink">PEP Maintenance</a></h3>
|
||
<p>In general, PEPs are no longer substantially modified after they have reached
|
||
the Accepted, Final, Rejected or Superseded state. Once resolution is reached,
|
||
a PEP is considered a historical document rather than a living specification.
|
||
Formal documentation of the expected behavior should be maintained elsewhere,
|
||
such as the <a class="reference external" href="https://docs.python.org/3/reference/index.html">Language Reference</a> for core features, the <a class="reference external" href="https://docs.python.org/3/library/index.html">Library Reference</a>
|
||
for standard library modules or the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/">PyPA Specifications</a> for packaging.</p>
|
||
<p>If changes based on implementation experience and user feedback are made to
|
||
Standards track PEPs while in the Provisional or (with SC approval) Accepted
|
||
state, they should be noted in the PEP, such that the PEP accurately describes
|
||
the implementation at the point where it is marked Final.</p>
|
||
<p>Active (Informational and Process) PEPs may be updated over time to reflect
|
||
changes to development practices and other details. The precise process
|
||
followed in these cases will depend on the nature and purpose of the PEP
|
||
in question.</p>
|
||
<p>Occasionally, a Deferred or even a Withdrawn PEP may be resurrected
|
||
with major updates, but it is often better to just propose a new one.</p>
|
||
</section>
|
||
</section>
|
||
<section id="what-belongs-in-a-successful-pep">
|
||
<h2><a class="toc-backref" href="#what-belongs-in-a-successful-pep" role="doc-backlink">What belongs in a successful PEP?</a></h2>
|
||
<p>Each PEP should have the following parts/sections:</p>
|
||
<ol class="arabic">
|
||
<li>Preamble – <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2822.html"><strong>RFC 2822</strong></a> style headers containing meta-data about the
|
||
PEP, including the PEP number, a short descriptive title (limited
|
||
to a maximum of 44 characters), the names, and optionally the
|
||
contact info for each author, etc.</li>
|
||
<li>Abstract – a short (~200 word) description of the technical issue
|
||
being addressed.</li>
|
||
<li>Motivation – The motivation is critical for PEPs that want to
|
||
change the Python language, library, or ecosystem. It should
|
||
clearly explain why the existing language specification is
|
||
inadequate to address the problem that the PEP solves. This can
|
||
include collecting documented support for the PEP from important
|
||
projects in the Python ecosystem. PEP submissions without
|
||
sufficient motivation may be rejected.</li>
|
||
<li>Rationale – The rationale fleshes out the specification by
|
||
describing why particular design decisions were made. It should
|
||
describe alternate designs that were considered and related work,
|
||
e.g. how the feature is supported in other languages.<p>The rationale should provide evidence of consensus within the
|
||
community and discuss important objections or concerns raised
|
||
during discussion.</p>
|
||
</li>
|
||
<li>Specification – The technical specification should describe the
|
||
syntax and semantics of any new language feature. The
|
||
specification should be detailed enough to allow competing,
|
||
interoperable implementations for at least the current major Python
|
||
platforms (CPython, Jython, IronPython, PyPy).</li>
|
||
<li>Backwards Compatibility – All PEPs that introduce backwards
|
||
incompatibilities must include a section describing these
|
||
incompatibilities and their severity. The PEP must explain how the
|
||
author proposes to deal with these incompatibilities. PEP
|
||
submissions without a sufficient backwards compatibility treatise
|
||
may be rejected outright.</li>
|
||
<li>Security Implications – If there are security concerns in relation
|
||
to the PEP, those concerns should be explicitly written out to make
|
||
sure reviewers of the PEP are aware of them.</li>
|
||
<li>How to Teach This – For a PEP that adds new functionality or changes
|
||
language behavior, it is helpful to include a section on how to
|
||
teach users, new and experienced, how to apply the PEP to their
|
||
work.<p>This section may include key points and recommended documentation
|
||
changes that would help users adopt a new feature or migrate their
|
||
code to use a language change.</p>
|
||
</li>
|
||
<li>Reference Implementation – The reference implementation must be
|
||
completed before any PEP is given status “Final”, but it need not
|
||
be completed before the PEP is accepted. While there is merit
|
||
to the approach of reaching consensus on the specification and
|
||
rationale before writing code, the principle of “rough consensus
|
||
and running code” is still useful when it comes to resolving many
|
||
discussions of API details.<p>The final implementation must include test code and documentation
|
||
appropriate for either the Python language reference or the
|
||
standard library reference.</p>
|
||
</li>
|
||
<li>Rejected Ideas – Throughout the discussion of a PEP, various ideas
|
||
will be proposed which are not accepted. Those rejected ideas should
|
||
be recorded along with the reasoning as to why they were rejected.
|
||
This both helps record the thought process behind the final version
|
||
of the PEP as well as preventing people from bringing up the same
|
||
rejected idea again in subsequent discussions.<p>In a way this section can be thought of as a breakout section of the
|
||
Rationale section that is focused specifically on why certain ideas
|
||
were not ultimately pursued.</p>
|
||
</li>
|
||
<li>Open Issues – While a PEP is in draft, ideas can come up which
|
||
warrant further discussion. Those ideas should be recorded so people
|
||
know that they are being thought about but do not have a concrete
|
||
resolution. This helps make sure all issues required for the PEP to be
|
||
ready for consideration are complete and reduces people duplicating
|
||
prior discussion.</li>
|
||
<li>Footnotes – A collection of footnotes cited in the PEP, and
|
||
a place to list non-inline hyperlink targets.</li>
|
||
<li>Copyright/license – Each new PEP must be placed under a dual license of
|
||
public domain and <a class="reference external" href="https://choosealicense.com/licenses/cc0-1.0/">CC0-1.0-Universal</a> (see this PEP for an example).</li>
|
||
</ol>
|
||
</section>
|
||
<section id="pep-formats-and-templates">
|
||
<h2><a class="toc-backref" href="#pep-formats-and-templates" role="doc-backlink">PEP Formats and Templates</a></h2>
|
||
<p>PEPs are UTF-8 encoded text files using the <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html">reStructuredText</a> format.
|
||
reStructuredText allows for rich markup that is still quite easy to
|
||
read, but also results in good-looking and functional HTML. <a class="pep reference internal" href="../pep-0012/" title="PEP 12 – Sample reStructuredText PEP Template">PEP 12</a>
|
||
contains instructions and a <a class="pep reference internal" href="../pep-0012/#suggested-sections" title="PEP 12 – Sample reStructuredText PEP Template § Suggested Sections">PEP template</a>.</p>
|
||
<p>The PEP text files are automatically
|
||
<a class="reference external" href="https://peps.python.org/docs/rendering_system/">converted to HTML</a>
|
||
(via a <a class="reference external" href="https://www.sphinx-doc.org/">Sphinx</a>-based <a class="pep reference internal" href="../pep-0676/" title="PEP 676 – PEP Infrastructure Process">build system</a>)
|
||
for easier <a class="reference external" href="https://peps.python.org/">online reading</a>.</p>
|
||
</section>
|
||
<section id="pep-header-preamble">
|
||
<h2><a class="toc-backref" href="#pep-header-preamble" role="doc-backlink">PEP Header Preamble</a></h2>
|
||
<p>Each PEP must begin with an <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2822.html"><strong>RFC 2822</strong></a> style header preamble. The headers
|
||
must appear in the following order. Headers marked with “*” are
|
||
optional and are described below. All other headers are required.</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span> PEP: <pep number>
|
||
Title: <pep title>
|
||
Author: <list of authors' real names and optionally, email addrs>
|
||
* Sponsor: <real name of sponsor>
|
||
* PEP-Delegate: <PEP delegate's real name>
|
||
Discussions-To: <URL of current canonical discussion thread>
|
||
Status: <Draft | Active | Accepted | Provisional | Deferred | Rejected |
|
||
Withdrawn | Final | Superseded>
|
||
Type: <Standards Track | Informational | Process>
|
||
* Topic: <Governance | Packaging | Release | Typing>
|
||
* Requires: <pep numbers>
|
||
Created: <date created on, in dd-mmm-yyyy format>
|
||
* Python-Version: <version number>
|
||
Post-History: <dates, in dd-mmm-yyyy format,
|
||
inline-linked to PEP discussion threads>
|
||
* Replaces: <pep number>
|
||
* Superseded-By: <pep number>
|
||
* Resolution: <url>
|
||
</pre></div>
|
||
</div>
|
||
<p>The Author header lists the names, and optionally the email addresses
|
||
of all the authors/owners of the PEP. The format of the Author header
|
||
values must be:</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Random J. User <random@example.com>
|
||
</pre></div>
|
||
</div>
|
||
<p>if the email address is included, and just:</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Random J. User
|
||
</pre></div>
|
||
</div>
|
||
<p>if the address is not given.</p>
|
||
<p>If there are multiple authors, each should be on a separate line
|
||
following <span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2822.html"><strong>RFC 2822</strong></a> continuation line conventions. Note that personal
|
||
email addresses in PEPs will be obscured as a defense against spam
|
||
harvesters.</p>
|
||
<p>The Sponsor field records which developer (core, or otherwise approved by the
|
||
Steering Council) is sponsoring the PEP. If one of the authors of the PEP is a
|
||
core developer then no sponsor is necessary and thus this field should be left
|
||
out.</p>
|
||
<p>The PEP-Delegate field is used to record the individual appointed by the
|
||
Steering Council to make the final decision on whether or not to approve or
|
||
reject a PEP.</p>
|
||
<p><em>Note: The Resolution header is required for Standards Track PEPs
|
||
only. It contains a URL that should point to an email message or
|
||
other web resource where the pronouncement about
|
||
(i.e. approval or rejection of) the PEP is made.</em></p>
|
||
<p>The Discussions-To header provides the URL to the current
|
||
canonical discussion thread for the PEP.
|
||
For email lists, this should be a direct link to the thread in the list’s
|
||
archives, rather than just a mailto: or hyperlink to the list itself.</p>
|
||
<p>The Type header specifies the type of PEP: Standards Track,
|
||
Informational, or Process.</p>
|
||
<p>The optional Topic header lists the special topic, if any,
|
||
the PEP belongs under.
|
||
See the <a class="reference internal" href="../topic/#topic-index"><span class="std std-ref">Topic Index</span></a> for the existing topics.</p>
|
||
<p>The Created header records the date that the PEP was assigned a
|
||
number, while Post-History is used to record the dates of and corresponding
|
||
URLs to the Discussions-To threads for the PEP, with the former as the
|
||
linked text, and the latter as the link target.
|
||
Both sets of dates should be in <code class="docutils literal notranslate"><span class="pre">dd-mmm-yyyy</span></code> format, e.g. <code class="docutils literal notranslate"><span class="pre">14-Aug-2001</span></code>.</p>
|
||
<p>Standards Track PEPs will typically have a Python-Version header which
|
||
indicates the version of Python that the feature will be released with.
|
||
Standards Track PEPs without a Python-Version header indicate
|
||
interoperability standards that will initially be supported through
|
||
external libraries and tools, and then potentially supplemented by a later PEP
|
||
to add support to the standard library. Informational and Process PEPs do
|
||
not need a Python-Version header.</p>
|
||
<p>PEPs may have a Requires header, indicating the PEP numbers that this
|
||
PEP depends on.</p>
|
||
<p>PEPs may also have a Superseded-By header indicating that a PEP has
|
||
been rendered obsolete by a later document; the value is the number of
|
||
the PEP that replaces the current document. The newer PEP must have a
|
||
Replaces header containing the number of the PEP that it rendered
|
||
obsolete.</p>
|
||
</section>
|
||
<section id="auxiliary-files">
|
||
<h2><a class="toc-backref" href="#auxiliary-files" role="doc-backlink">Auxiliary Files</a></h2>
|
||
<p>PEPs may include auxiliary files such as diagrams. Such files should be
|
||
named <code class="docutils literal notranslate"><span class="pre">pep-XXXX-Y.ext</span></code>, where “XXXX” is the PEP number, “Y” is a
|
||
serial number (starting at 1), and “ext” is replaced by the actual
|
||
file extension (e.g. “png”).</p>
|
||
<p>Alternatively, all support files may be placed in a subdirectory called
|
||
<code class="docutils literal notranslate"><span class="pre">pep-XXXX</span></code>, where “XXXX” is the PEP number. When using a subdirectory, there
|
||
are no constraints on the names used in files.</p>
|
||
</section>
|
||
<section id="changing-existing-peps">
|
||
<h2><a class="toc-backref" href="#changing-existing-peps" role="doc-backlink">Changing Existing PEPs</a></h2>
|
||
<p>Draft PEPs are freely open for discussion and proposed modification, at the
|
||
discretion of the authors, until submitted to the Steering Council or
|
||
PEP-Delegate for review and resolution. Substantive content changes should
|
||
generally be first proposed on the PEP’s discussion thread listed in its
|
||
<code class="docutils literal notranslate"><span class="pre">Discussions-To</span></code> header, while copyedits and corrections can be submitted
|
||
as a <a class="reference external" href="https://github.com/python/peps/issues">GitHub issue</a> or <a class="reference external" href="https://github.com/python/peps/pulls">GitHub pull request</a>.
|
||
PEP authors with write access to the PEP repository can update the PEPs
|
||
themselves by using <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> or a GitHub PR to submit their changes.
|
||
For guidance on modifying other PEPs, consult the <a class="reference internal" href="#pep-maintenance">PEP Maintenance</a> section.</p>
|
||
<p>See the <a class="reference external" href="https://github.com/python/peps/blob/main/CONTRIBUTING.rst">Contributing Guide</a> for additional details, and when in doubt,
|
||
please check first with the PEP author and/or a PEP editor.</p>
|
||
</section>
|
||
<section id="transferring-pep-ownership">
|
||
<h2><a class="toc-backref" href="#transferring-pep-ownership" role="doc-backlink">Transferring PEP Ownership</a></h2>
|
||
<p>It occasionally becomes necessary to transfer ownership of PEPs to a
|
||
new champion. In general, it is preferable to retain the original author as
|
||
a co-author of the transferred PEP, but that’s really up to the
|
||
original author. A good reason to transfer ownership is because the
|
||
original author no longer has the time or interest in updating it or
|
||
following through with the PEP process, or has fallen off the face of
|
||
the ‘net (i.e. is unreachable or not responding to email). A bad
|
||
reason to transfer ownership is because the author doesn’t agree with the
|
||
direction of the PEP. One aim of the PEP process is to try to build
|
||
consensus around a PEP, but if that’s not possible, an author can always
|
||
submit a competing PEP.</p>
|
||
<p>If you are interested in assuming ownership of a PEP, you can also do this via
|
||
pull request. Fork the <a class="reference external" href="https://github.com/python/peps">PEP repository</a>, make your ownership modification,
|
||
and submit a pull request. You should mention both the original author and
|
||
<code class="docutils literal notranslate"><span class="pre">@python/pep-editors</span></code> in a comment on the pull request. (If the original
|
||
author’s GitHub username is unknown, use email.) If the original author
|
||
doesn’t respond in a timely manner, the PEP editors will make a
|
||
unilateral decision (it’s not like such decisions can’t be reversed :).</p>
|
||
</section>
|
||
<section id="pep-editor-responsibilities-workflow">
|
||
<h2><a class="toc-backref" href="#pep-editor-responsibilities-workflow" role="doc-backlink">PEP Editor Responsibilities & Workflow</a></h2>
|
||
<p>A PEP editor must be added to the <code class="docutils literal notranslate"><span class="pre">@python/pep-editors</span></code> group on GitHub and
|
||
must watch the <a class="reference external" href="https://github.com/python/peps">PEP repository</a>.</p>
|
||
<p>Note that developers with write access to the <a class="reference external" href="https://github.com/python/peps">PEP repository</a> may
|
||
handle the tasks that would normally be taken care of by the PEP editors.
|
||
Alternately, even developers may request assistance from PEP editors by
|
||
mentioning <code class="docutils literal notranslate"><span class="pre">@python/pep-editors</span></code> on GitHub.</p>
|
||
<p>For each new PEP that comes in an editor does the following:</p>
|
||
<ul class="simple">
|
||
<li>Make sure that the PEP is either co-authored by a core developer, has a core
|
||
developer as a sponsor, or has a sponsor specifically approved for this PEP
|
||
by the Steering Council.</li>
|
||
<li>Read the PEP to check if it is ready: sound and complete. The ideas
|
||
must make technical sense, even if they don’t seem likely to be
|
||
accepted.</li>
|
||
<li>The title should accurately describe the content.</li>
|
||
<li>The file name extension is correct (i.e. <code class="docutils literal notranslate"><span class="pre">.rst</span></code>).</li>
|
||
<li>Ensure that everyone listed as a sponsor or co-author of the PEP who has write
|
||
access to the <a class="reference external" href="https://github.com/python/peps">PEP repository</a> is added to <a class="reference external" href="https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners">.github/CODEOWNERS</a>.</li>
|
||
<li>Skim the PEP for obvious defects in language (spelling, grammar,
|
||
sentence structure, etc.), and code style (examples should conform to
|
||
<a class="pep reference internal" href="../pep-0007/" title="PEP 7 – Style Guide for C Code">PEP 7</a> & <a class="pep reference internal" href="../pep-0008/" title="PEP 8 – Style Guide for Python Code">PEP 8</a>). Editors may correct problems themselves, but are
|
||
not required to do so (reStructuredText syntax is checked by the repo’s CI).</li>
|
||
<li>If a project is portrayed as benefiting from or supporting the PEP, make sure
|
||
there is some direct indication from the project included to make the support
|
||
clear. This is to avoid a PEP accidentally portraying a project as supporting
|
||
a PEP when in fact the support is based on conjecture.</li>
|
||
</ul>
|
||
<p>If the PEP isn’t ready, an editor will send it back to the author for
|
||
revision, with specific instructions. If reST formatting is a
|
||
problem, ask the author(s) to use <a class="pep reference internal" href="../pep-0012/" title="PEP 12 – Sample reStructuredText PEP Template">PEP 12</a> as a template and resubmit.</p>
|
||
<p>Once the PEP is ready for the repository, a PEP editor will:</p>
|
||
<ul>
|
||
<li>Check that the author has selected a valid PEP number or assign them a
|
||
number if they have not (almost always just the next available number, but
|
||
sometimes it’s a special/joke number, like 666 or 3141).<p>Remember that numbers below 100 are meta-PEPs.</p>
|
||
</li>
|
||
<li>Check that the author has correctly labeled the PEP’s type
|
||
(“Standards Track”, “Informational”, or “Process”), and marked its
|
||
status as “Draft”.</li>
|
||
<li>Ensure all CI build and lint checks pass without errors,
|
||
and there are no obvious issues in the rendered preview output.</li>
|
||
<li>Merge the new (or updated) PEP.</li>
|
||
<li>Inform the author of the next steps (open a discussion thread and
|
||
update the PEP with it, post an announcement, etc).</li>
|
||
</ul>
|
||
<p>Updates to existing PEPs should be submitted as a <a class="reference external" href="https://github.com/python/peps/pulls">GitHub pull request</a>.</p>
|
||
<p>Many PEPs are written and maintained by developers with write access
|
||
to the Python codebase. The PEP editors monitor the PEP repository
|
||
for changes, and correct any structure, grammar, spelling, or
|
||
markup mistakes they see.</p>
|
||
<p>PEP editors don’t pass judgment on PEPs. They merely do the
|
||
administrative & editorial part (which is generally a low volume task).</p>
|
||
<p>Resources:</p>
|
||
<ul class="simple">
|
||
<li><a class="reference external" href="https://peps.python.org/">Index of Python Enhancement Proposals</a></li>
|
||
<li><a class="reference external" href="https://devguide.python.org/communication/">Following Python’s Development</a></li>
|
||
<li><a class="reference external" href="https://devguide.python.org/">Python Developer’s Guide</a></li>
|
||
</ul>
|
||
</section>
|
||
<section id="copyright">
|
||
<h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2>
|
||
<p>This document is placed in the public domain or under the
|
||
CC0-1.0-Universal license, whichever is more permissive.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0001.rst">https://github.com/python/peps/blob/main/peps/pep-0001.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0001.rst">2024-01-12 20:31:04 GMT</a></p>
|
||
|
||
</article>
|
||
<nav id="pep-sidebar">
|
||
<h2>Contents</h2>
|
||
<ul>
|
||
<li><a class="reference internal" href="#what-is-a-pep">What is a PEP?</a></li>
|
||
<li><a class="reference internal" href="#pep-audience">PEP Audience</a></li>
|
||
<li><a class="reference internal" href="#pep-types">PEP Types</a></li>
|
||
<li><a class="reference internal" href="#pep-workflow">PEP Workflow</a><ul>
|
||
<li><a class="reference internal" href="#python-s-steering-council">Python’s Steering Council</a></li>
|
||
<li><a class="reference internal" href="#python-s-core-developers">Python’s Core Developers</a></li>
|
||
<li><a class="reference internal" href="#python-s-bdfl">Python’s BDFL</a></li>
|
||
<li><a class="reference internal" href="#pep-editors">PEP Editors</a></li>
|
||
<li><a class="reference internal" href="#start-with-an-idea-for-python">Start with an idea for Python</a></li>
|
||
<li><a class="reference internal" href="#submitting-a-pep">Submitting a PEP</a></li>
|
||
<li><a class="reference internal" href="#discussing-a-pep">Discussing a PEP</a></li>
|
||
<li><a class="reference internal" href="#pep-review-resolution">PEP Review & Resolution</a></li>
|
||
<li><a class="reference internal" href="#pep-maintenance">PEP Maintenance</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#what-belongs-in-a-successful-pep">What belongs in a successful PEP?</a></li>
|
||
<li><a class="reference internal" href="#pep-formats-and-templates">PEP Formats and Templates</a></li>
|
||
<li><a class="reference internal" href="#pep-header-preamble">PEP Header Preamble</a></li>
|
||
<li><a class="reference internal" href="#auxiliary-files">Auxiliary Files</a></li>
|
||
<li><a class="reference internal" href="#changing-existing-peps">Changing Existing PEPs</a></li>
|
||
<li><a class="reference internal" href="#transferring-pep-ownership">Transferring PEP Ownership</a></li>
|
||
<li><a class="reference internal" href="#pep-editor-responsibilities-workflow">PEP Editor Responsibilities & Workflow</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
|
||
<br>
|
||
<a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0001.rst">Page Source (GitHub)</a>
|
||
</nav>
|
||
</section>
|
||
<script src="../_static/colour_scheme.js"></script>
|
||
<script src="../_static/wrap_tables.js"></script>
|
||
<script src="../_static/sticky_banner.js"></script>
|
||
</body>
|
||
</html> |