PEP 12 – 示例 reStructuredText PEP 模板

抽象

此 PEP 提供了一个样板或示例模板，用于创建您的 拥有 reStructuredText PEP。结合内容指南 在 PEP 1 中，这应该使您能够轻松符合自己的要求 PEP 转换为下面概述的格式。

注意：如果您通过网络阅读此 PEP，您应该首先获取 此 PEP 的文本 （reStructuredText） 源，以便完成 步骤如下。不要将 HTML 文件用作模板！

此（或任何）PEP 的源代码可以在 PEP 存储库中找到， 以及通过每个 PEP 底部的链接。

理由

如果您打算提交 PEP，则必须在 结合以下格式指南，以确保您的 PEP 提交不会因为表单而被自动拒绝。

ReStructuredText 为 PEP 作者提供了有用的功能和 表现力，同时保持源文本的易读性。 经过处理的 HTML 表单使读者可以访问该功能： 实时超链接、样式文本、表格、图像和自动表格 内容，以及其他优势。

如何使用此模板

要使用此模板，您必须首先确定您的 PEP 是否要进行 成为信息或标准跟踪 PEP。大多数 PEP 是 标准跟踪，因为他们为 Python 提出了一个新功能 语言或标准库。如有疑问，请阅读 PEP 1 了解详情， 或在 PEP 存储库上打开跟踪器问题以寻求帮助。

一旦您决定了您将要成为哪种类型的 PEP，请遵循 说明如下。

复制此文件（文件，而不是 HTML！），然后 执行以下编辑。将新文件命名为 ，使用 下一个可用号码（未被已发布或 PR 中的 PEP 使用）。.rstpep-NNNN.rst

将“PEP：12”标头替换为“PEP：NNNN”， 匹配文件名。请注意，文件名应填充为 零（例如），但标头不应 （）。pep-0012.rstPEP: 12

将 Title 标头更改为 PEP 的标题。

更改“作者”标题以包含您的姓名，并（可选）更改您的姓名 电子邮件地址。请务必仔细遵循格式：您的姓名 必须首先出现，并且不得包含在括号中。 您的电子邮件地址可能会排在第二位（也可以省略），如果 它出现，它必须出现在尖括号中。没关系 混淆您的电子邮件地址。

如果作者都不是 Python 核心开发人员，请包括发起人 标头替换为赞助 PEP 的核心开发人员的名称。

添加 PEP 规范讨论线程的直接 URL （例如 Python-Dev、Discourse 等）在 Discussions-To 标题下。 如果在 PEP 作为官方提交后将创建线程 草稿，最初只列出场地名称是可以的，但请记住 成功合并 PEP 后，立即使用 URL 更新 PEP 添加到 PEP 存储库，然后创建相应的讨论线程。 有关更多详细信息，请参阅 PEP 1。

将“状态”标题更改为“草稿”。

对于标准跟踪 PEP，将“类型”标头更改为“标准” 跟踪”。

对于信息性 PEP，将 Type 标头更改为“Informational”。

对于标准跟踪 PEP，如果您的功能取决于验收 对于其他一些当前正在开发的 PEP，添加一个 Requires 标头 紧跟在 Type 标头之后。该值应为 PEP 数 你所依赖的 PEP。如果您的依赖项，请不要添加此标头 功能在最终 PEP 中描述。

将“已创建”标头更改为今天的日期。请务必遵循 格式必须小心：必须采用格式，其中 是 3 个英文字母月份的缩写，即 Jan， 2月、3月、4月、5月、6月、7月、8月、9月、10月、11月、12月dd-mmm-yyyymmm

对于标准跟踪 PEP，在 Created 标头之后，添加一个 Python-Version 标头，并将值设置为下一个计划的版本 的 Python，即您的新功能有望使其 首次登场。请勿使用 alpha 或 beta 版本 此处指定。因此，如果 Python 的最后一个版本是 2.2 alpha 1 并且您希望将新功能引入 Python 2.2，请将 标头设置为：

Python-Version: 2.2

如果 PEP 属于主题索引中显示的 PEP ，则添加 Topic 标头。 大多数 PEP 没有。

暂时不要管后历史;您将添加日期和相应的链接 每次将 PEP 发布到指定的论坛时，都到此标题 （并使用上述链接更新 Discussions-To 标题，如上所述）。 对于每个线程，使用日期（格式）作为 链接文本，并将 URL 内联插入为匿名 reST 超链接， 每次发布之间都有逗号。dd-mmm-yyy

如果您在 2001 年 8 月 14 日和 2001 年 9 月 3 日发布了 PEP 的帖子， Post-History 标题如下所示，例如：

Post-History: `14-Aug-2001 <https://www.example.com/thread_1>`__,              `03-Sept-2001 <https://www.example.com/thread_2>`__

您应该在发布 新的讨论线程。

如果 PEP 过时了早期的 PEP，请添加 Rereplace 标头。这 此标头的值是新 PEP 的 PEP 编号 取代。仅当较旧的 PEP 处于“最终”状态时才添加此标头 形式，即“已接受”、“最终”或“拒绝”。你不是 如果您要提交竞争性想法，请替换旧的开放式 PEP。

现在为您的 PEP 写下您的摘要、基本原理和其他内容， 用你自己的文本替换所有这些 gobbledygook。一定要 遵守以下格式指南，特别是 禁止制表符和缩进要求。 请参阅下面的“建议部分”，了解要包含的部分的模板。

更新您的脚注部分，列出所有脚注和 文本引用的非内联链接目标。

运行以确保 PEP 呈现时没有错误， 并检查输出是否符合您的预期。./build.pybuild/pep-NNNN.html

针对 PEP 存储库创建拉取请求。

作为参考，以下是所有可能的标题字段（所有内容 如果出现以下情况，则应替换括号中的字段或删除该字段 它有一个前导标记，将其标记为可选，不适用于 您的 PEP）：*

PEP: [NNN]Title: [...]Author: [Full Name <emAIl at example.com>]Sponsor: *[Full Name <email at example.com>]PEP-Delegate:Discussions-To: [URL]Status: DraftType: [Standards Track | Informational | Process]Topic: *[Governance | Packaging | Release | Typing]Requires: *[NNN]Created: [DD-MMM-YYYY]Python-Version: *[M.N]Post-History: [`DD-MMM-YYYY <URL>`__]Replaces: *[NNN]Superseded-By: *[NNN]Resolution:

ReStructuredText PEP 格式要求

以下是特定于 PEP 的 reStructuredText 语法摘要。 为了简单明了起见，省略了很多细节。为 更多详细信息，请参阅下面的参考资料。文字块（其中没有 标记处理完成）用于整个示例，以 说明纯文本标记。

常规

线条通常不应超过第 79 列， URL 和类似情况除外。 制表符绝不能出现在文档中。

章节标题

PEP 标题必须以第 0 列开头，并且每个标题的首字母 单词必须像书名一样大写。首字母缩略词应全部 资本。章节标题必须用下划线装饰，一个 重复标点符号，从第 0 列开始，必须 至少延伸到标题文本的右边缘 （4 最小字符数）。一级章节标题带有下划线 “=”（等号），带“-”（连字符）的二级章节标题， 和带有“'”的三级章节标题（单引号或 撇号）。例如：

如果您的 PEP 中有超过三个级别的部分，您可以 为第一个和第二个插入上划线/下划线修饰的标题 级别如下：

您的 PEP 中不应有超过五个级别的部分。如果 你这样做了，你应该考虑重写它。

必须在节正文的最后一行之间使用两个空行 和下一节标题。如果小节标题立即 在章节标题之后，中间的单个空行是 足够。

每个部分的正文通常不会缩进，尽管有些 构造确实使用缩进，如下所述。空行是 用于分隔构造。

段落

段落是左对齐的文本块，由空行分隔。 段落不会缩进，除非它们是缩进的一部分 构造（例如块引号或列表项）。

内联标记

段落和其他文本块中的文本部分可能是 风格。例如：

Text may be marked as *emphasized* (single asterisk markup,
typically shown in italics) or **strongly emphasized** (double
asterisks, typically boldface).  ``Inline literals`` (using double
backquotes) are typically rendered in a monospaced typeface.  No
further markup recognition is done within the double backquotes,
so they're safe for any kind of code snippets.

区块报价

块引号由缩进的正文元素组成。例如：

This is a paragraph.

    This is a block quote.

    A block quote may contain many paragraphs.

块引号用于引用其他来源的扩展段落。 块引号可以嵌套在其他正文元素中。使用 4 个空格 每个缩进级别。

文字块

文本块用于代码示例和其他预格式化文本。 要指示文本块，请在缩进的文本块前面加上 “”（两个冒号），或使用指令。 将文本块缩进 4 个空格;文字块一直持续到最后 的缩进。例如：::.. code-block::

This is a typical paragraph.  A literal block follows.::    for a in [5, 4, 3, 2, 1]:  # this is program code, shown as-is        print(a)    print("it's...")

“”也在任何段落的末尾被识别;如果不是立即 在空格之前，一个冒号将在最终输出中保持可见：::

This is an example::

    Literal block

默认情况下，文本块将作为 Python 代码进行语法突出显示。 对于包含其他语言/格式的代码或数据的特定块， 使用指令，替换“短名称” 的相应 Pygments 词法分析器（或禁用突出显示）。例如：.. code-block:: languagetextlanguage

.. code-block:: rst

    An example of the ``rst`` lexer (i.e. *reStructuredText*).

对于主要包含特定语言的文字块的 PEP， 在 PEP 正文的顶部（标题下方和摘要上方）使用带有适当内容的指令。 然后，所有文字块都将被视为该语言， 除非在特定 .例如：.. highlight:: languagelanguage.. code-block

.. highlight:: cAbstract========Here's some C code::

    printf("Hello, World!\n");

列表

项目符号列表项以“-”、“*”或“+”之一开头（连字符、 星号或加号），后跟空格和列表项 身体。列表项正文必须左对齐并相对于 子弹;紧跟在项目符号后面的文本确定 凹痕。例如：

This paragraph is followed by a list.* This is the first bullet list item.  The blank line above the
  first list item is required; blank lines between list items
  (such as below this paragraph) are optional.* This is the first paragraph in the second item in the list.

  This is the second paragraph in the second item in the list.
  The blank line above this paragraph is required.  The left edge
  of this paragraph lines up with the paragraph above, both
  indented relative to the bullet.  - This is a sublist.  The bullet lines up with the left edge of
    the text blocks above.  A sublist is a new list so requires a
    blank line above and below.* This is the third item of the main list.

This paragraph is not part of the list.

枚举（编号）列表项类似，但使用枚举器 而不是子弹。枚举器是数字 （1， 2， 3， ...）， 字母 （A， B， C， ...;大写或小写）或罗马数字（i， ii， iii， 四。。。;大写或小写），格式为句点后缀 （“1.”、“2.”）、括号（“（1）”、“（2）”）或右括号 后缀 （“1）”， “2）”）。例如：

1. As with bullet list items, the left edge of paragraphs must
   align.2. Each list item may contain multiple paragraphs, sublists, etc.

   This is the second paragraph of the second list item.

   a) Enumerated lists may be nested.
   b) Blank lines may be omitted between list items.

定义列表是这样写的：

what
    Definition lists associate a term with a definition.

how
    The term is a one-line phrase, and the definition is one
    or more paragraphs or body elements, indented relative to
    the term.

表

简单的表格既简单又紧凑：

表中必须至少有两列（以区分 章节标题）。列跨度使用连字符的下划线 （“Inputs” 跨越前两列）：

第一列单元格中的文本将开始新行。第一个中没有文本 column 表示延续线;其余细胞可能 由多行组成。例如：

超链接

在 PEP 正文中引用外部网页时，您应该 在正文中包括页面标题或适当的描述，并 内联超链接或带有 URL 的单独显式目标。 不要在 PEP 的正文中包含裸 URL，并使用 HTTPS 链接（任何可用）。

超链接引用使用反引号和尾部下划线来标记 向上参考文本;如果引用文本 是一个词。例如，要引用名为 的超链接目标，可以编写：Python website

In this paragraph, we refer to the `Python website`_.

如果您打算只引用一次链接，并且想要以内联方式定义它 对于文本，将链接插入文本后面的尖括号 （） 中 您想要链接，但在结束反引号之前，在 文本和开始的反引号。您还应该在 结束反引号而不是单个反引号，这使它成为匿名的 引用以避免与其他目标名称冲突。例如：<>

Visit the `website <https://www.python.org/>`__ for more.

如果您想在多个地方使用一个链接，其中包含不同的链接文本， 或者希望确保在以下情况下不必更新链接目标名称 更改链接文本，将目标名称包含在尖括号内 在要链接的文本之后，在目标名称后加下划线 但在右尖括号之前（否则链接将不起作用）。 例如：

For further examples, see the `documentation <pydocs_>`_.

显式目标提供 URL。将目标放在“脚注”部分 在 PEP 的末尾，或紧接在带有参考文献的段落之后。 超链接目标以两个句点和一个空格（“显式 markup start“），后跟前导下划线，即参考文本， 冒号和 URL。

.. _Python web site: https://www.python.org/.. _pydocs: https://docs.python.org/

参考文本和目标文本必须匹配（尽管匹配 不区分大小写，并忽略空格中的差异）。请注意， 下划线位于参考文本之后，但位于目标文本之前。 如果将下划线视为向右箭头，则它指向远离参考并指向目标。

内部和 PEP/RFC 链接

与超链接相同的机制可用于内部引用。 每个唯一的节标题都隐式定义了一个内部超链接目标。 我们可以像这样链接到摘要部分：

Here is a hyperlink reference to the `Abstract`_ section.  The
backquotes are optional since the reference text is a single word;
we can also just write: Abstract_.

要引用 PEP 或 RFC，请始终使用 和 角色， 从不硬编码 URL。 例如：:pep::rfc:

See :pep:`1` for more information on how to write a PEP,
and :pep:`the Hyperlink section of PEP 12 <12#hyperlinks>` for how to link.

这将呈现为：

有关如何编写 PEP 的更多信息，请参见 PEP 1， 以及 PEP 12 的 Hyperlink 部分，了解如何链接。

文本中的 PEP 数字从不填充，并且有一个空格（不是破折号） 在“PEP”或“RFC”与数字之间;上述角色将负责 给你的。

脚注

脚注引用由左方括号、标签、 右方括号和尾部下划线。 不要使用数字，而是使用 形式“#word”，其中“单词”是由字母数字组成的助记符 加上内部连字符、下划线和句点（没有空格或 允许使用其他字符）。 例如：

Refer to The TeXbook [#TeXbook]_ for more information.

脚注引用之前必须有空格。在 脚注引用和前面的单词。

使用脚注获取其他注释、解释和注意事项，以及 用于参考在线不易获得的书籍和其他资源。 文本中的本机 reST 超链接目标或内联超链接应为 优先于脚注，用于包含联机资源的 URL。

脚注以“..”开头（显式 markup start），后跟脚注标记（无下划线）， 后跟脚注正文。例如：

.. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.

脚注和脚注引用将自动编号，并且 数字将始终匹配。

图像

如果您的 PEP 包含图表或其他图形，您可以将其包含在 使用指令处理输出：image

.. image:: diagram.png

任何浏览器友好的图形格式都是可能的;PNG 应该是 首选图形，JPEG 用于照片，GIF 用于动画。 目前，由于与 PEP 构建系统。

对于源文本的可访问性和读者，您应该包括 图像的描述以及其中包含的任何关键信息 使用指令的选项：:alt:image

.. image:: dataflow.png   :alt: Data flows from the input module, through the "black box"
         module, and finally into (and through) the output module.

评论

注释是立即缩进的任意文本块 在显式标记开始之后：两个句点和空格。离开 “..”本身，以确保注释不是 被误解为另一个显式标记构造。评论不是 在已处理的文档中可见。例如：

..   This section should be updated in the final PEP.   Ensure the date is accurate.

逃逸机制

reStructuredText 使用反斜杠 （“”） 来覆盖特殊 赋予标记字符的含义并获取文本字符 他们自己。若要获取文字反斜杠，请使用转义的反斜杠 ("").在两种上下文中，反斜杠没有 特殊含义：文字块和内联文字（参见内联 上面的标记）。在这些上下文中，不进行标记识别， 单个反斜杠表示字面上的反斜杠，而没有 加倍。\\\

如果您发现需要在文本中使用反斜杠，请考虑 请改用内联文本或文本块。

规范文档和 Intersphinx

正如 PEP 1 所描述的， PEP 一旦标记为最终文件，就被视为历史文件， 他们的规范文档/规范应该移到其他地方。 若要指示这一点，请使用指令 或适当的子类：canonical-doc

canonical-pypa-spec用于包装标准

canonical-typing-spec用于打字标准

此外，您可以使用Intersphinx对其他Sphinx站点的引用， 目前 Python 文档和 packaging.python.org， 轻松交叉引用页面、部分和 Python/C 对象。 这既适用于“规范”指令，也适用于 PEP 中的任何位置。

在标头和 PEP 的第一部分之间添加指令 （通常为摘要） 并传递规范 doc/spec 的 Intersphinx 引用作为参数 （或者，如果目标不在 Sphinx 站点上，则为 reST 超链接）。

例如 要创建指向文档的横幅， 你可以写以下内容：

.. canonical-doc:: :mod:`python:sqlite3`

这将生成横幅：

重要

这个 PEP 是一份历史文件。现在可以在以下位置找到最新的规范文档。

×

请参阅 PEP 1 了解如何提出更改。

或者对于 PyPA 规范， 例如核心元数据规范， 您将使用：

.. canonical-pypa-spec:: :ref:`packaging:core-metadata`

其呈现为：

该参数接受任意 reST， 因此，您可以包含多个链接的文档/规范，并随心所欲地命名它们， 您还可以包含将插入到文本中的指令内容。 以下高级示例：

.. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:~sqlite3.DataError` docs

    Also, see the :ref:`Data Persistence docs <persistence>` for other examples.

将呈现为：

重要

这个 PEP 是一份历史文件。现在可以在 Connection 对象和文档中找到最新的规范文档。

×

此外，有关其他示例，请参阅数据持久性文档。

请参阅 PEP 1 了解如何提出更改。

要避免的习惯

很多熟悉TeX的程序员经常会写引号 喜欢这个：

`single-quoted' or ``double-quoted''

反引号在 reStructuredText 中很重要，因此这种做法 应避免。对于普通文本，请使用普通的“单引号”或 “双引号”。对于内联文本（请参阅上面的内联标记），请使用双反引号：

``literal text: in here, anything goes!``

建议的章节

发现各个部分在 PEP 中很常见，并在 PEP 1 中进行了概述。为方便起见，此处提供了这些部分。

PEP: <REQUIRED: pep number>
Title: <REQUIRED: pep title>
Author: <REQUIRED: list of authors' real names and optionally, email addrs>
Sponsor: <real name of sponsor>
PEP-Delegate: <PEP delegate's real name>
Discussions-To: <REQUIRED: URL of current canonical discussion thread>
Status: <REQUIRED: Draft | Active | Accepted | Provisional | Deferred | Rejected | Withdrawn | Final | Superseded>
Type: <REQUIRED: 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: <REQUIRED: dates, in dd-mmm-yyyy format, and corresponding links to PEP discussion threads>
Replaces: <pep number>
Superseded-By: <pep number>
Resolution: <url>Abstract========[A short (~200 word) description of the technical issue being addressed.]Motivation==========[Clearly explain why the existing language specification is inadequate to address the problem that the PEP solves.]Rationale=========[Describe why particular design decisions were made.]Specification=============[Describe the syntax and semantics of any new language feature.]Backwards Compatibility=======================[Describe potential impact and severity on pre-existing code.]Security Implications=====================[How could a malicious user take advantage of this new feature?]How to Teach This=================[How to teach users, new and experienced, how to apply the PEP to their work.]Reference Implementation========================[Link to any existing implementation and details about its state, e.g. proof-of-concept.]Rejected Ideas==============[Why certain ideas that were brought while discussing this PEP were not ultimately pursued.]Open Issues===========[Any points that are still being decided/discussed.]Footnotes=========[A collection of footnotes cited in the PEP, and a place to list non-inline hyperlink targets.]Copyright=========This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.

版权

本文档被置于公共领域或位于 CC0-1.0-通用许可证，以更宽松的许可证为准。

The End