• What is a PEP?
• PEP Audience
• PEP Types
• PEP Workflow
  • Python's Steering Council
  • Python's Core Developers
  • Python's BDFL
  • PEP Editors
  • Start with an idea for Python
  • Submitting a PEP
  • PEP Review & Resolution
  • PEP Maintenance
• What belongs in a successful PEP?
• PEP Formats and Templates
• PEP Header Preamble
• Auxiliary Files
• Reporting PEP Bugs, or Submitting PEP Updates
• Transferring PEP Ownership
• PEP Editor Responsibilities & Workflow
• References and Footnotes
• Copyright

What is a PEP?

PEP stands for Python Enhancement Proposal. A PEP is a designdocument providing information to the Python community, or describinga new feature for Python or its processes or environment. The PEPshould provide a concise technical specification of the feature and arationale for the feature.

We intend PEPs to be the primary mechanisms for proposing major newfeatures, for collecting community input on an issue, and fordocumenting the design decisions that have gone into Python. The PEPauthor is responsible for building consensus within the community anddocumenting dissenting opinions.

Because the PEPs are maintained as text files in a versionedrepository, their revision history is the historical record of thefeature proposal[1].

PEP Audience

The typical primary audience for PEPs are the core developers of the CPythonreference interpreter and their elected Steering Council, as well as developersof other implementations of the Python language specification.

However, other parts of the Python community may also choose to use the process(particularly for Informational PEPs) to document expected API conventions andto manage complex design coordination problems that require collaboration acrossmultiple projects.

PEP Types

There are three kinds of PEP:

1. AStandards Track PEP describes a new feature or implementationfor Python. It may also describe an interoperability standard that willbe supported outside the standard library for current Python versionsbefore a subsequent PEP adds standard library support in a futureversion.
2. AnInformational PEP describes a Python design issue, orprovides general guidelines or information to the Python community,but does not propose a new feature. Informational PEPs do notnecessarily represent a Python community consensus orrecommendation, so users and implementers are free to ignoreInformational PEPs or follow their advice.
3. AProcess PEP describes a process surrounding Python, orproposes a change to (or an event in) a process. Process PEPs arelike Standards Track PEPs but apply to areas other than the Pythonlanguage itself. They may propose an implementation, but not toPython's codebase; they often require community consensus; unlikeInformational PEPs, they are more than recommendations, and usersare typically not free to ignore them. Examples includeprocedures, guidelines, changes to the decision-making process, andchanges to the tools or environment used in Python development.Any meta-PEP is also considered a Process PEP.

PEP Workflow

PEP Review & Resolution

Once the authors have completed a PEP, they may request a review forstyle and consistency from the PEP editors.

However, content review and final acceptance of the PEP must be requested of thecore developers, usually via an email to the python-dev mailing list.

To expedite the process in selected cases (e.g. when a change is clearlybeneficial and ready to be accepted, but the PEP hasn't been formally submittedfor review yet), the Steering Council may also initiate a PEP review, firstnotifying the PEP author(s) and giving them a chance to make revisions.

The final authority for PEP approval is the Steering Council. However, whenevera new PEP is put forward, any core developer that believes they are suitablyexperienced to make the final decision on that PEP may offer to serve asthe BDFL-Delegate for that PEP, and they will then have the authority to approve(or reject) that PEP. Individuals taking on this responsibility are free to seekadditional guidance from the Steering Council at any time, and are also expectedto take the advice and perspectives of other core developers into account.

The designated decision maker for each PEP is recorded in the "BDFL-Delegate"header in the PEP.

Such self-nominations are accepted by default, but may be explicitly declined bythe Steering Council. Possible reasons for the Steering Council declining aself-nomination as BDFL-Delegate include, but are not limited to, perceptions ofa potential conflict of interest (e.g. working for the same organisation as thePEP submitter), or simply considering another potential BDFL-Delegate to bemore appropriate. If core developers (or other community members) have concernsregarding the suitability of a BDFL-Delegate for any given PEP, they may askthe Steering Council to review the delegation.

If no volunteer steps forward, then the Steering Council will approach coredevelopers (and potentially other Python community members) with relevantexpertise, in an attempt to identify a candidate that is willing to serve asBDFL-Delegate for that PEP. If no suitable candidate can be found, then thePEP will be marked as Deferred until one is available.

Previously appointed BDFL-Delegates may choose to step down, or be asked to stepdown by the Council, in which case a new BDFL-Delegate will be appointed in thesame manner as for a new PEP (including deferral of the PEP if no suitablereplacement can be found). In the event that a BDFL-Delegate is asked to stepdown, this will overrule any prior acceptance or rejection of the PEP, and itwill revert to Draft status.

With the approval of the Steering Council, PEP review and resolution may alsooccur on a list other than python-dev (for example, distutils-sig for packagingrelated PEPs that don't immediately affect the standard library). In thesecases, the "Discussions-To" heading in the PEP will identify the appropriatealternative list where discussion, review and pronouncement on the PEP willoccur.

When such standing delegations are put in place, the Steering Council willmaintain sufficient public records to allow subsequent Councils, the coredevelopers, and the wider Python community to understand the delegations thatcurrently exist, why they were put in place, and the circumstances under whichthey may no longer be needed.

For a PEP to be accepted it must meet certain minimum criteria. Itmust be a clear and complete description of the proposed enhancement.The enhancement must represent a net improvement. The proposedimplementation, if applicable, must be solid and must not complicatethe 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 tothe Steering Council. This logic is intentionally circular.) SeePEP 2[2]for standard library module acceptance criteria.

Once a PEP has been accepted, the reference implementation must becompleted. When the reference implementation is complete and incorporatedinto the main source code repository, the status will be changed to "Final".

To allow gathering of additional design and interface feedback before committingto long term stability for a language feature or standard library API, a PEPmay also be marked as "Provisional". This is short for "Provisionally Accepted",and indicates that the proposal has been accepted for inclusion in the referenceimplementation, but additional user feedback is needed before the full designcan be considered "Final". Unlike regular accepted PEPs, provisionally acceptedPEPs may still be Rejected or Withdrawneven after the related changes havebeen included in a Python release.

Wherever possible, it is considered preferable to reduce the scope of a proposalto avoid the need to rely on the "Provisional" status (e.g. by deferring somefeatures to later PEPs), as this status can lead to version compatibilitychallenges in the wider Python ecosystem.PEP 411 provides additional detailson potential use cases for the Provisional status.

A PEP can also be assigned the status "Deferred". The PEP author or aneditor can assign the PEP this status when no progress is being madeon the PEP. Once a PEP is deferred, a PEP editor can re-assign itto draft status.

A PEP can also be "Rejected". Perhaps after all is said and done itwas not a good idea. It is still important to have a record of thisfact. The "Withdrawn" status is similar - it means that the PEP authorthemselves has decided that the PEP is actually a bad idea, or hasaccepted that a competing proposal is a better alternative.

When a PEP is Accepted, Rejected or Withdrawn, the PEP should be updatedaccordingly. In addition to updating the status field, at the very leastthe Resolution header should be added with a link to the relevant postin the python-dev mailing list archives.

PEPs can also be superseded by a different PEP, rendering the originalobsolete. This is intended for Informational PEPs, where version 2 ofan API can replace version 1.

The possible paths of the status of PEPs are as follows:

While not shown in the diagram, "Accepted" PEPs may technically move to"Rejected" or "Withdrawn" even after acceptance. This will only occur ifthe implementation process reveals fundamental flaws in the design that werenot noticed prior to acceptance of the PEP. Unlike Provisional PEPs, thesetransitions are only permitted if the accepted proposal hasnot been includedin a Python release - released changes must instead go through the regulardeprecation process (which may require a new PEP providing the rationale forthe deprecation).

Some Informational and Process PEPs may also have a status of "Active"if they are never meant to be completed. E.g.PEP 1 (this PEP).

What belongs in a successful PEP?

Each PEP should have the following parts/sections:

1. Preamble --RFC 822 style headers containing meta-data about thePEP, including the PEP number, a short descriptive title (limitedto a maximum of 44 characters), the names, and optionally thecontact info for each author, etc.

2. Abstract -- a short (~200 word) description of the technical issuebeing addressed.

3. Motivation -- The motivation is critical for PEPs that want tochange the Python language, library, or ecosystem. It shouldclearly explain why the existing language specification isinadequate to address the problem that the PEP solves. PEPsubmissions without sufficient motivation may be rejected outright.

4. Rationale -- The rationale fleshes out the specification bydescribing why particular design decisions were made. It shoulddescribe alternate designs that were considered and related work,e.g. how the feature is supported in other languages.

   The rationale should provide evidence of consensus within thecommunity and discuss important objections or concerns raisedduring discussion.

5. Specification -- The technical specification should describe thesyntax and semantics of any new language feature. Thespecification should be detailed enough to allow competing,interoperable implementations for at least the current major Pythonplatforms (CPython, Jython, IronPython, PyPy).

6. Backwards Compatibility -- All PEPs that introduce backwardsincompatibilities must include a section describing theseincompatibilities and their severity. The PEP must explain how theauthor proposes to deal with these incompatibilities. PEPsubmissions without a sufficient backwards compatibility treatisemay be rejected outright.

7. Security Implications -- If there are security concerns in relationto the PEP, those concerns should be explicitly written out to makesure reviewers of the PEP are aware of them.

8. How to Teach This -- For a PEP that adds new functionality or changeslanguage behavior, it is helpful to include a section on how toteach users, new and experienced, how to apply the PEP to theirwork.

   This section may include key points and recommended documentationchanges that would help users adopt a new feature or migrate theircode to use a language change.

9. Reference Implementation -- The reference implementation must becompleted before any PEP is given status "Final", but it need notbe completed before the PEP is accepted. While there is meritto the approach of reaching consensus on the specification andrationale before writing code, the principle of "rough consensusand running code" is still useful when it comes to resolving manydiscussions of API details.

   The final implementation must include test code and documentationappropriate for either the Python language reference or thestandard library reference.

10. Rejected Ideas -- Throughout the discussion of a PEP, various ideaswill be proposed which are not accepted. Those rejected ideas shouldbe recorded along with the reasoning as to why they were rejected.This both helps record the thought process behind the final versionof the PEP as well as preventing people from bringing up the samerejected idea again in subsequent discussions.

    In a way this section can be thought of as a breakout section of theRationale section that is focused specifically on why certain ideaswere not ultimately pursued.

11. Open Issues -- While a PEP is in draft, ideas can come up whichwarrant further discussion. Those ideas should be recorded so peopleknow that they are being thought about but do not have a concreteresolution. This helps make sure all issues required for the PEP to beready for consideration are complete complete and reduces peopleduplicating prior discussion.

12. References -- A collection of URLs used as references through the PEP.

13. Copyright/license -- Each new PEP must be placed under a dual license ofpublic domain andCC0-1.0-Universal[8] (see this PEP for an example).

PEP Formats and Templates

PEPs are UTF-8 encoded text files using thereStructuredText[9] format.ReStructuredText[9] allows for rich markup that is still quite easy toread, but also results in good-looking and functional HTML.PEP 12contains instructions and a template[4] for reStructuredText PEPs.

The PEP text files are automatically converted to HTML[6] for easieronline reading.

PEP Header Preamble

Each PEP must begin with anRFC 822 style header preamble. The headersmust appear in the following order. Headers marked with "*" areoptional and are described below. All other headers are required.

  PEP: <pep number>  Title: <pep title>  Author: <list of authors' real names and optionally, email addrs>* Sponsor: <real name of sponsor>* BDFL-Delegate: <PEP czar's real name>* Discussions-To: <email address>  Status: <Draft | Active | Accepted | Provisional | Deferred | Rejected |           Withdrawn | Final | Superseded>  Type: <Standards Track | Informational | Process>* Content-Type: <text/x-rst | text/plain>* Requires: <pep numbers>  Created: <date created on, in dd-mmm-yyyy format>* Python-Version: <version number>  Post-History: <dates of postings to python-ideas and/or python-dev>* Replaces: <pep number>* Superseded-By: <pep number>* Resolution: <url>

The Author header lists the names, and optionally the email addressesof all the authors/owners of the PEP. The format of the Author headervalue must be

Random J. User <address@dom.ain>

if the email address is included, and just

Random J. User

if the address is not given. For historical reasons the format"address@dom.ain (Random J. User)" may appear in a PEP, however newPEPs must use the mandated format above, and it is acceptable tochange to this format when PEPs are updated.

If there are multiple authors, each should be on a separate linefollowingRFC 2822 continuation line conventions. Note that personalemail addresses in PEPs will be obscured as a defense against spamharvesters.

The Sponsor field records which developer (core, or otherwise approved by theSteering Council) is sponsoring the PEP. If one of the authors of the PEP is acore developer then no sponsor is necessary and thus this field should be leftout.

The BDFL-Delegate field is used to record the individual appointed by theSteering Council to make the final decision on whether or not to approve orreject a PEP. (The delegate's email address is currently omitted due to alimitation in the email address masking for reStructuredText PEPs)

Note: The Resolution header is required for Standards Track PEPsonly. It contains a URL that should point to an email message orother web resource where the pronouncement about the PEP is made.

For a PEP where final pronouncement will be made on a list other thanpython-dev, a Discussions-To header will indicate the mailing listor URL where the pronouncement will occur. A temporary Discussions-To headermay also be used when a draft PEP is being discussed prior to submission forpronouncement. No Discussions-To header is necessary if the PEP is beingdiscussed privately with the author, or on the python-list, python-ideasor python-dev mailing lists. Note that email addresses in theDiscussions-To header will not be obscured.

The Type header specifies the type of PEP: Standards Track,Informational, or Process.

The format of a PEP is specified with a Content-Type header. Theacceptable values are "text/plain" for plaintext PEPs (seePEP 9[3])and "text/x-rst" for reStructuredText PEPs (seePEP 12[4]).reStructuredText is strongly preferred, but for backwardscompatibility plain text is currently still the default if noContent-Type header is present.

The Created header records the date that the PEP was assigned anumber, while Post-History is used to record the dates of when newversions of the PEP are posted to python-ideas and/or python-dev. Bothheaders should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.

Standards Track PEPs will typically have a Python-Version header whichindicates the version of Python that the feature will be released with.Standards Track PEPs without a Python-Version header indicateinteroperability standards that will initially be supported throughexternal libraries and tools, and then potentially supplemented by a later PEPto add support to the standard library. Informational and Process PEPs donot need a Python-Version header.

PEPs may have a Requires header, indicating the PEP numbers that thisPEP depends on.

PEPs may also have a Superseded-By header indicating that a PEP hasbeen rendered obsolete by a later document; the value is the number ofthe PEP that replaces the current document. The newer PEP must have aReplaces header containing the number of the PEP that it renderedobsolete.

Auxiliary Files

PEPs may include auxiliary files such as diagrams. Such files should benamedpep-XXXX-Y.ext, where "XXXX" is the PEP number, "Y" is aserial number (starting at 1), and "ext" is replaced by the actualfile extension (e.g. "png").

Alternatively, all support files may be placed in a subdirectory calledpep-XXXX, where "XXXX" is the PEP number. When using a subdirectory, thereare no constraints on the names used in files.

Reporting PEP Bugs, or Submitting PEP Updates

How you report a bug, or submit a PEP update depends on severalfactors, such as the maturity of the PEP, the preferences of the PEPauthor, and the nature of your comments. For the early draft stagesof the PEP, it's probably best to send your comments and changesdirectly to the PEP author. For more mature, or finished PEPs you maywant to submit corrections as aGitHub issue[12] orGitHub pull request[11] so thatyour changes don't get lost.

When in doubt about where to send your changes, please check firstwith the PEP author and/or a PEP editor.

PEP authors with git push privileges for the PEP repository can update thePEPs themselves by using "git push" or the GitHub PR interface to submit theirchanges.

Transferring PEP Ownership

It occasionally becomes necessary to transfer ownership of PEPs to anew champion. In general, it is preferable to retain the original author asa co-author of the transferred PEP, but that's really up to theoriginal author. A good reason to transfer ownership is because theoriginal author no longer has the time or interest in updating it orfollowing through with the PEP process, or has fallen off the face ofthe 'net (i.e. is unreachable or not responding to email). A badreason to transfer ownership is because the author doesn't agree with thedirection of the PEP. One aim of the PEP process is to try to buildconsensus around a PEP, but if that's not possible, an author can alwayssubmit a competing PEP.

If you are interested in assuming ownership of a PEP, you can also do this viapull request. Fork thePEP repository[10], make your ownership modification,and submit a pull request. You should also send a message asking to takeover, addressed to both the original author and the PEP editors<peps@python.org>. If the original author doesn't respond to email in atimely manner, the PEP editors will make a unilateral decision (it's not likesuch decisions can't be reversed :).

PEP Editor Responsibilities & Workflow

A PEP editor must subscribe to the <peps@python.org> list and must watch thePEP repository[10]. Most correspondence regarding PEP administration can behandled through GitHub issues and pull requests, but you may also use<peps@python.org> for semi-private discussions. Please do not cross-post!

For each new PEP that comes in an editor does the following:

• Make sure that the PEP is either co-authored by a core developer, has a coredeveloper as a sponsor, or has a sponsor specifically approved for this PEPby the Steering Council.
• Read the PEP to check if it is ready: sound and complete. The ideasmust make technical sense, even if they don't seem likely to beaccepted.
• The title should accurately describe the content.
• The file name extension is correct (i.e..rst).
• Skim the PEP for obvious defects in language (spelling, grammar,sentence structure, etc.), and code style (examples should conform toPEP 8 &PEP 7). Editors may correct problems themselves, but arenot required to do so. (Text format is checked by Travis CI.)

If the PEP isn't ready, an editor will send it back to the author forrevision, with specific instructions. If reST formatting is aproblem, ask the author(s) to usePEP 12 as a template and resubmit.

Once the PEP is ready for the repository, a PEP editor will:

• Assign a PEP number (almost always just the next available number,but sometimes it's a special/joke number, like 666 or 3141).(Clarification: For Python 3, numbers in the 3000s were used forPy3k-specific proposals. But now that all new features go intoPython 3 only, the process is back to using numbers in the 100s again.Remember that numbers below 100 are meta-PEPs.)

• Check that the author has correctly labeled the PEP's type("Standards Track", "Informational", or "Process"), and marked itsstatus as "Draft".

• Add the PEP to a local fork of the PEP repository. For workflowinstructions, followThe Python Developers Guide

  The git repo for the peps is:

  https://github.com/python/peps

• Run./genpepindex.py and./pep2html.py <PEP Number> to ensure theyare generated without errors. If either triggers errors, then the web sitewill not be updated to reflect the PEP changes.

• Commit and push the new (or updated) PEP

• Monitor python.org to make sure the PEP gets added to the siteproperly. If it fails to appear, runningmake will build all of thecurrent PEPs. If any of these are triggering errors, they must becorrected before any PEP will update on the site.

• Send email back to the PEP author with next steps (post topython-list & -dev).

Updates to existing PEPs should be submitted as aGitHub pull request[11].Questions may of course still be sent to <peps@python.org>.

Many PEPs are written and maintained by developers with write accessto the Python codebase. The PEP editors monitor the python-checkinslist for PEP changes, and correct any structure, grammar, spelling, ormarkup mistakes they see.

PEP editors don't pass judgment on PEPs. They merely do theadministrative & editorial part (which is generally a low volume task).

Resources:

• Index of Python Enhancement Proposals
• Following Python's Development
• Python Developer's Guide
• Frequently Asked Questions for Developers

References and Footnotes

Copyright

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