Contents

• 什么是 PEP？
• PEP 受众
• PEP 类型
• PEP 工作流程
  • Python 的指导理事会
  • Python 的核心开发者
  • Python 的 BDFL
  • PEP 编辑者
  • 从 Python 的创意开始
  • 提交 PEP
  • PEP 审查与解决
  • PEP 的维护
• 哪些是属于成功的 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

什么是 PEP？

PEP 是 Python Enhancement Proposal 的缩写。PEP 是一个向 Python 社区提供信息的设计文件，或者描述 Python （或其进程或环境）新特性。PEP 应该提供该特性的简明技术规范和该特性的提出理由。

我们打算让 PEP 成为提出主要新特性、收集社区对某一议题的意见、以及记录 Python 设计决策的主要机制。PEP 的作者负责在社区内建立共识，并记录不同的意见。

因为 PEP 是以文本文件的形式保存在一个版本库中，它们的修订历史是特性建议的历史记录 1。

PEP 受众

PEP 典型的主要受众是 CPython 参考解释器的核心开发者和他们选出的指导委员会，以及 Python 语言规范的其他实现的开发者。

然而，Python 社区的其他部分也可能选择使用这个过程（尤其是信息性 PEP）来记录预期的 API 约定，并管理需要在多个项目间协作的复杂设计协调问题。

PEP 类型

有三种 PEP：

1. 标准追踪 的 PEP 描述了 Python 的新特性或实现。它也可以描述一个互操作性标准，在后续的 PEP 在未来的版本中增加标准库支持之前，它将在标准库之外支持当前的 Python 版本。
2. 信息性的 PEP 描述了 Python 设计问题，或者为 Python 社区提供了一般的指南或信息，但并没有提出一个新的特性。信息性 PEP 不一定代表 Python 社区的共识或建议，所以用户和实现者可以自由地忽略信息性 PEP 或遵循其建议。
3. 过程 的 PEP 描述了围绕 Python 的一个过程，或者提出了对一个过程的改变（或一个事件）。过程 PEP 与标准跟踪 PEP 类似，但适用于 Pytho n语言本身以外的领域。 它们可以提出一个实现，但不是针对 Python 代码库；它们通常需要社区达成共识；与信息性 PEP 不同，它们不仅仅是建议，而且用户通常不能随意忽略它们。例子包括程序、指南、对决策过程的改变，以及对 Python 开发中使用的工具或环境的改变。任何 PEP 元信息 也被认为是过程 PEP”

PEP 工作流程

PEP 审查与解决

一旦作者完成了 PEP，他们可以要求 PEP 的编辑对风格和一致性进行审查。

然而，PEP 的内容审查和最终接受必须向核心开发者提出请求，通常是通过向 python-dev 邮件列表发送电子邮件。

为了在选定的情况下加快进程（例如，当一个变化明显有益并准备被接受，但 PEP 还没有正式提交审查），指导委员会也可以启动 PEP 审查，首先通知 PEP 作者，给他们一个机会进行修改。

批准 PEP 的最终权力是指导委员会。然而，每当一个新的 PEP 被提出时，任何核心开发者如果认为他们有适当的经验来对该 PEP 做出最终决定，可以提出作为该 PEP 的授权人，然后他们将有权力批准（或拒绝）该 PEP。承担这一责任的个人可以在任何时候寻求指导委员会的额外指导，而且还应该考虑到其他核心开发者的建议和观点。

每个 PEP 的指定决策者被记录在 PEP 中的 “PEP-Delegate” 头部下。

这种自荐是默认接受的，但指导委员会可以明确地拒绝。指导委员会拒绝自我提名为 PEP-Delegate 的可能原因包括，但不限于，认为有潜在的利益冲突（例如，与 PEP 提交者在同一个组织工作），或者只是认为另一个潜在的 PEP-Delegate 更合适。如果核心开发者（或其他社区成员）对任何特定的 PEP-Delegate 的合适性有顾虑，他们可以要求指导委员会审查该委托。

如果没有志愿者站出来，那么指导委员会将与具有相关专业知识的核心开发者（以及可能的其他 Python 社区成员）接触，试图确定一个愿意担任该 PEP-Delegate 的候选人。如果找不到合适的人选，那么该 PEP 将被标记为 “Deferred”，直到有合适的人选。

以前任命的 PEP-Delegates 可以选择卸任，或被理事会要求卸任，在这种情况下，将按照任命新的 PEP-Delegates 的方式任命新的 PEP-Delegate（包括如果找不到合适的替代者，则推迟 PEP 的任命）。如果 PEP-Delegate 被要求卸任，这将推翻之前对 PEP 的任何接受或拒绝，并且它将恢复到草案状态。

在指导委员会的批准下，PEP 的审查和解决也可能发生在 python-dev 之外的列表中（例如，distutils-sig 用于与打包相关的、不会立即影响标准库的 PEP）。在这种情况下，PEP 中的 “Discussions-To” 头信息将确定适当的替代列表，在那里对 PEP 进行讨论、审查和宣布

当这种常设授权到位时，指导委员会将保持足够的公共记录，以使后来的理事会、核心开发商和更广泛的 Python 社区了解目前存在的授权，为什么会有这些授权，以及在什么情况下可能不再需要这些授权。

要接受 PEP，它必须满足某些最低标准。它必须是对拟议改进的清晰和完整的描述。该改进必须代表净改进。建议的实现，如果适用的话，必须是可靠的，并且不能使解释器过度复杂化。最后，提议的改进必须是 “pythonic”，以便被指导委员会接受。（然而，“pythonic” 是一个不精确的术语；它可以被定义为指导委员会可以接受的任何东西。这个逻辑是故意循环的）。参见 PEP 2 2 关于标准库模块的接受标准。

一旦一个 PEP 被接受，必须完成参考实现。当参考实现完成并被纳入主源代码库时，状态将被改变为 “Final”。

为了在对语言功能或标准库 API 的长期稳定性做出承诺之前收集额外的设计和接口反馈，PEP 也可以被标记为 “Provisional”。这是 “Provisionally Accepted” 的简称，表示该提案已被接受纳入参考实现，但在完整的设计被认为是 “Final” 之前还需要更多的用户反馈。与常规接受的 PEP 不同，临时接受的 PEP 仍然可能被拒绝或撤回，即使相关的修改已经包含在 Python 版本中。

只要有可能，我们认为最好是缩小提案的范围，以避免依赖 “Provisional” 状态（例如将一些特性推迟到以后的 PEP），因为这种状态可能会导致更广泛的 Python 生态系统中的版本兼容性问题。PEP 411 提供了关于临时状态的潜在用例的更多细节。

一个 PEP 也可以被赋予状态：”Deferred”。当 PEP 没有进展时，PEP 的作者或编辑可以给该 PEP 分配这种状态。一旦 PEP 被推迟，PEP 编辑可以将其重新分配为草案状态。

PEP也可以是 “Rejected” 的。也许说来说去，这并不是一个好主意。对这一事实进行记录仍然是很重要的。”Withdrawn” 状态是类似的–它意味着 PEP 作者自己已经决定该 PEP 实际上是一个坏主意，或者已经接受了一个竞争提案是更好的选择。

当一个 PEP 被接受、拒绝或撤回时，PEP 应该被相应地更新。除了更新状态字段之外，至少应该在决议头部中添加一个指向 python-dev 邮件列表档案中相关帖子的链接。

PEP 也可以被一个不同的 PEP所取代，使原来的 PEP 过时。这是为信息性 PEP 准备的，即一个 API 的第二版可以取代第一版。

PEP 的状态的可能路径如下：

虽然在图中没有显示，但从技术上讲，”Accepted” 的 PEP 可能会转到 “Rejected” 或 “Withdrawn”，甚至在接受之后。只有在实施过程中发现了设计中的基本缺陷，而在接受 PEP 之前没有注意到时，才会发生这种情况。与临时 PEP 不同的是，只有在被接受的建议没有被包含在 Python 版本中的情况下才允许这些转换–被发布的修改必须通过常规的废弃过程（这可能需要一个新的 PEP 来提供废弃的理由）。

一些信息性和过程性的 PEPs 如果从未打算完成，也可能有一个状态为 “Active”。例如，PEP 1（本 PEP）。

哪些是属于成功的 PEP？

每个 PEP 应该有以下部分/节：

1. Preamble – RFC 822 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.
2. Abstract – a short (~200 word) description of the technical issue being addressed.
3. 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.
4. 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.

   The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.

5. 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).
6. 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.
7. 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.
8. 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.

   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.

9. 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.

   The final implementation must include test code and documentation appropriate for either the Python language reference or the standard library reference.

10. 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.

    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.

11. 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.
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 of public domain and CC0-1.0-Universal 9 (see this PEP for an example).

PEP Formats and Templates

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

The PEP text files are automatically converted to HTML 6 for easier online reading.

PEP Header Preamble

Each PEP must begin with an RFC 822 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.

  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: <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 addresses of all the authors/owners of the PEP. The format of the Author header value 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 new PEPs must use the mandated format above, and it is acceptable to change to this format when PEPs are updated.

If there are multiple authors, each should be on a separate line following RFC 2822 continuation line conventions. Note that personal email addresses in PEPs will be obscured as a defense against spam harvesters.

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.

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. (The delegate’s email address is currently omitted due to a limitation in the email address masking for reStructuredText PEPs)

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 the PEP is made.

For a PEP where final pronouncement will be made on a list other than python-dev, a Discussions-To header will indicate the mailing list or URL where the pronouncement will occur. A temporary Discussions-To header may also be used when a draft PEP is being discussed prior to submission for pronouncement. No Discussions-To header is necessary if the PEP is being discussed privately with the author, or on the python-list, python-ideas or python-dev mailing lists. Note that email addresses in the Discussions-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. The acceptable values are “text/plain” for plaintext PEPs (see PEP 9 3) and “text/x-rst” for reStructuredText PEPs (see PEP 12 4). reStructuredText is strongly preferred, but for backwards compatibility plain text is currently still the default if no Content-Type header is present.

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

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.

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

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.

Auxiliary Files

PEPs may include auxiliary files such as diagrams. Such files should be named pep-XXXX-Y.ext, 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”).

Alternatively, all support files may be placed in a subdirectory called pep-XXXX, where “XXXX” is the PEP number. When using a subdirectory, there are 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 several factors, such as the maturity of the PEP, the preferences of the PEP author, and the nature of your comments. For the early draft stages of the PEP, it’s probably best to send your comments and changes directly to the PEP author. For more mature, or finished PEPs you may want to submit corrections as a GitHub issue 13 or GitHub pull request 12 so that your changes don’t get lost.

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

PEP authors with git push privileges for the PEP repository can update the PEPs themselves by using “git push” or the GitHub PR interface to submit their changes.

Transferring PEP Ownership

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.

If you are interested in assuming ownership of a PEP, you can also do this via pull request. Fork the PEP repository 11, make your ownership modification, and submit a pull request. You should mention both the original author and @python/pep-editors 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 :).

PEP Editor Responsibilities & Workflow

A PEP editor must be added to the @python/pep-editors group on GitHub and must watch the PEP repository 11.

Note that developers with git push privileges for the PEP repository 11 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 @python/pep-editors on GitHub.

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 core developer as a sponsor, or has a sponsor specifically approved for this PEP by the Steering Council.
• 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.
• The title should accurately describe the content.
• The file name extension is correct (i.e. .rst).
• Make sure the appropriate core developer(s) is added to .github/CODEOWNERS 7.
• Skim the PEP for obvious defects in language (spelling, grammar, sentence structure, etc.), and code style (examples should conform to PEP 8 & PEP 7). Editors may correct problems themselves, but are not required to do so. (Text format is checked by Travis CI.)
• 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.

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 PEP 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 for Py3k-specific proposals. But now that all new features go into Python 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 its status as “Draft”.
• 将 PEP 添加到 PEP 仓库的本地分叉中。关于工作流程的说明，请遵循 Python 开发者指南

  The git repo for the peps is:

  https://github.com/python/peps
  

• Run ./genpepindex.py and ./pep2html.py <PEP Number> to ensure they are generated without errors. If either triggers errors, then the web site will 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 site properly. If it fails to appear, running make will build all of the current PEPs. If any of these are triggering errors, they must be corrected before any PEP will update on the site.
• Send email back to the PEP author with next steps (post to python-list & -dev).

Updates to existing PEPs should be submitted as a GitHub pull request 12.

许多 PEP 是由具有 Python 代码库写入权限的开发者编写和维护的。PEP 编辑人员监视 PEP 仓库的变化，并纠正他们看到的任何结构、语法、拼写或标记错误。

PEP editors don’t pass judgment on PEPs. They merely do the administrative & 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

1

This historical record is available by the normal git commands for retrieving older revisions, and can also be browsed via HTTP here: https://github.com/python/peps

2

PEP 2, Procedure for Adding New Modules (http://www.python.org/dev/peps/pep-0002)

3

PEP 9, Sample Plaintext PEP Template (http://www.python.org/dev/peps/pep-0009)

4 (1, 2)

PEP 12, Sample reStructuredText PEP Template (http://www.python.org/dev/peps/pep-0012)

5 (1, 2)

PEP 13, Python Language Governance (http://www.python.org/dev/peps/pep-0013)

6

More details on the PEP rendering and publication process can be found in the PEPs repo README at https://github.com/python/peps/blob/master/README.rst

7 (1, 2)

CODEOWNERS documentation (https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners)

8

http://bugs.python.org/

9

https://choosealicense.com/licenses/cc0-1.0/

10 (1, 2)

http://docutils.sourceforge.net/rst.html

11 (1, 2, 3, 4, 5, 6)

https://github.com/python/peps

12 (1, 2, 3)

https://github.com/python/peps/pulls

13

https://github.com/python/peps/issues

Copyright

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