mirror of https://github.com/python/peps
927 lines
55 KiB
HTML
927 lines
55 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 12 – Sample reStructuredText PEP Template | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0012/">
|
||
<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 12 – Sample reStructuredText PEP Template | peps.python.org'>
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0012/">
|
||
<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 12</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 12 – Sample reStructuredText PEP Template</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">David Goodger <goodger at python.org>,
|
||
Barry Warsaw <barry at python.org>,
|
||
Brett Cannon <brett at python.org></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">05-Aug-2002</dd>
|
||
<dt class="field-odd">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="https://mail.python.org/archives/list/python-dev@python.org/thread/KX3AS7QAY26QH3WIUAEOCCNXQ4V2TGGV/" title="Python-Dev thread">30-Aug-2002</a></dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<section id="contents">
|
||
<details><summary>Table of Contents</summary><ul class="simple">
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#how-to-use-this-template">How to Use This Template</a></li>
|
||
<li><a class="reference internal" href="#restructuredtext-pep-formatting-requirements">ReStructuredText PEP Formatting Requirements</a><ul>
|
||
<li><a class="reference internal" href="#general">General</a></li>
|
||
<li><a class="reference internal" href="#section-headings">Section Headings</a></li>
|
||
<li><a class="reference internal" href="#paragraphs">Paragraphs</a></li>
|
||
<li><a class="reference internal" href="#inline-markup">Inline Markup</a></li>
|
||
<li><a class="reference internal" href="#block-quotes">Block Quotes</a></li>
|
||
<li><a class="reference internal" href="#literal-blocks">Literal Blocks</a></li>
|
||
<li><a class="reference internal" href="#lists">Lists</a></li>
|
||
<li><a class="reference internal" href="#tables">Tables</a></li>
|
||
<li><a class="reference internal" href="#hyperlinks">Hyperlinks</a></li>
|
||
<li><a class="reference internal" href="#internal-and-pep-rfc-links">Internal and PEP/RFC Links</a></li>
|
||
<li><a class="reference internal" href="#footnotes">Footnotes</a></li>
|
||
<li><a class="reference internal" href="#images">Images</a></li>
|
||
<li><a class="reference internal" href="#comments">Comments</a></li>
|
||
<li><a class="reference internal" href="#escaping-mechanism">Escaping Mechanism</a></li>
|
||
<li><a class="reference internal" href="#canonical-documentation-and-intersphinx">Canonical Documentation and Intersphinx</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#habits-to-avoid">Habits to Avoid</a></li>
|
||
<li><a class="reference internal" href="#suggested-sections">Suggested Sections</a></li>
|
||
<li><a class="reference internal" href="#resources">Resources</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>For those who have written a PEP before, there is a <a class="reference internal" href="#template">template</a>
|
||
(which is included as a file in the <a class="reference external" href="https://github.com/python/peps/">PEPs repository</a>).</p>
|
||
</div>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>This PEP provides a boilerplate or sample template for creating your
|
||
own reStructuredText PEPs. In conjunction with the content guidelines
|
||
in <a class="pep reference internal" href="../pep-0001/" title="PEP 1 – PEP Purpose and Guidelines">PEP 1</a>, this should make it easy for you to conform your own
|
||
PEPs to the format outlined below.</p>
|
||
<p>Note: if you are reading this PEP via the web, you should first grab
|
||
the text (reStructuredText) source of this PEP in order to complete
|
||
the steps below. <strong>DO NOT USE THE HTML FILE AS YOUR TEMPLATE!</strong></p>
|
||
<p>The source for this (or any) PEP can be found in the
|
||
<a class="reference external" href="https://github.com/python/peps/">PEPs repository</a>,
|
||
as well as via a link at the bottom of each PEP.</p>
|
||
</section>
|
||
<section id="rationale">
|
||
<h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2>
|
||
<p>If you intend to submit a PEP, you MUST use this template, in
|
||
conjunction with the format guidelines below, to ensure that your PEP
|
||
submission won’t get automatically rejected because of form.</p>
|
||
<p>ReStructuredText provides PEP authors with useful functionality and
|
||
expressivity, while maintaining easy readability in the source text.
|
||
The processed HTML form makes the functionality accessible to readers:
|
||
live hyperlinks, styled text, tables, images, and automatic tables of
|
||
contents, among other advantages.</p>
|
||
</section>
|
||
<section id="how-to-use-this-template">
|
||
<h2><a class="toc-backref" href="#how-to-use-this-template" role="doc-backlink">How to Use This Template</a></h2>
|
||
<p>To use this template you must first decide whether your PEP is going
|
||
to be an Informational or Standards Track PEP. Most PEPs are
|
||
Standards Track because they propose a new feature for the Python
|
||
language or standard library. When in doubt, read <a class="pep reference internal" href="../pep-0001/" title="PEP 1 – PEP Purpose and Guidelines">PEP 1</a> for details,
|
||
or open a tracker issue on the PEPs repo to ask for assistance.</p>
|
||
<p>Once you’ve decided which type of PEP yours is going to be, follow the
|
||
directions below.</p>
|
||
<ul>
|
||
<li>Make a copy of this file (the <code class="docutils literal notranslate"><span class="pre">.rst</span></code> file, <strong>not</strong> the HTML!) and
|
||
perform the following edits. Name the new file <code class="file docutils literal notranslate"><span class="pre">pep-</span><em><span class="pre">NNNN</span></em><span class="pre">.rst</span></code>, using
|
||
the next available number (not used by a published or in-PR PEP).</li>
|
||
<li>Replace the “PEP: 12” header with “PEP: NNNN”,
|
||
matching the file name. Note that the file name should be padded with
|
||
zeros (eg <code class="docutils literal notranslate"><span class="pre">pep-0012.rst</span></code>), but the header should not (<code class="docutils literal notranslate"><span class="pre">PEP:</span> <span class="pre">12</span></code>).</li>
|
||
<li>Change the Title header to the title of your PEP.</li>
|
||
<li>Change the Author header to include your name, and optionally your
|
||
email address. Be sure to follow the format carefully: your name
|
||
must appear first, and it must not be contained in parentheses.
|
||
Your email address may appear second (or it can be omitted) and if
|
||
it appears, it must appear in angle brackets. It is okay to
|
||
obfuscate your email address.</li>
|
||
<li>If none of the authors are Python core developers, include a Sponsor
|
||
header with the name of the core developer sponsoring your PEP.</li>
|
||
<li>Add the direct URL of the PEP’s canonical discussion thread
|
||
(on e.g. Python-Dev, Discourse, etc) under the Discussions-To header.
|
||
If the thread will be created after the PEP is submitted as an official
|
||
draft, it is okay to just list the venue name initially, but remember to
|
||
update the PEP with the URL as soon as the PEP is successfully merged
|
||
to the PEPs repository and you create the corresponding discussion thread.
|
||
See <a class="pep reference internal" href="../pep-0001/#discussing-a-pep" title="PEP 1 – PEP Purpose and Guidelines § Discussing a PEP">PEP 1</a> for more details.</li>
|
||
<li>Change the Status header to “Draft”.</li>
|
||
<li>For Standards Track PEPs, change the Type header to “Standards
|
||
Track”.</li>
|
||
<li>For Informational PEPs, change the Type header to “Informational”.</li>
|
||
<li>For Standards Track PEPs, if your feature depends on the acceptance
|
||
of some other currently in-development PEP, add a Requires header
|
||
right after the Type header. The value should be the PEP number of
|
||
the PEP yours depends on. Don’t add this header if your dependent
|
||
feature is described in a Final PEP.</li>
|
||
<li>Change the Created header to today’s date. Be sure to follow the
|
||
format carefully: it must be in <code class="docutils literal notranslate"><span class="pre">dd-mmm-yyyy</span></code> format, where the
|
||
<code class="docutils literal notranslate"><span class="pre">mmm</span></code> is the 3 English letter month abbreviation, i.e. one of Jan,
|
||
Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.</li>
|
||
<li>For Standards Track PEPs, after the Created header, add a
|
||
Python-Version header and set the value to the next planned version
|
||
of Python, i.e. the one your new feature will hopefully make its
|
||
first appearance in. Do not use an alpha or beta release
|
||
designation here. Thus, if the last version of Python was 2.2 alpha
|
||
1 and you’re hoping to get your new feature into Python 2.2, set the
|
||
header to:<div class="highlight-email notranslate"><div class="highlight"><pre><span></span><span class="nt">Python-Version:</span><span class="w"> </span>2.2
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Add a Topic header if the PEP belongs under one shown at the <a class="reference internal" href="../topic/#topic-index"><span class="std std-ref">Topic Index</span></a>.
|
||
Most PEPs don’t.</li>
|
||
<li>Leave Post-History alone for now; you’ll add dates and corresponding links
|
||
to this header each time you post your PEP to the designated discussion forum
|
||
(and update the Discussions-To header with said link, as above).
|
||
For each thread, use the date (in the <code class="docutils literal notranslate"><span class="pre">dd-mmm-yyy</span></code> format) as the
|
||
linked text, and insert the URLs inline as anonymous reST <a class="reference internal" href="#hyperlinks">hyperlinks</a>,
|
||
with commas in between each posting.<p>If you posted threads for your PEP on August 14, 2001 and September 3, 2001,
|
||
the Post-History header would look like, e.g.:</p>
|
||
<div class="highlight-email notranslate"><div class="highlight"><pre><span></span><span class="nt">Post-History:</span><span class="w"> </span>`14-Aug-2001<span class="w"> </span><https://<span class="nf">www.example.com</span>/thread_1>`__,
|
||
<span class="w"> </span>`03-Sept-2001<span class="w"> </span><https://<span class="nf">www.example.com</span>/thread_2>`__
|
||
</pre></div>
|
||
</div>
|
||
<p>You should add the new dates/links here as soon as you post a
|
||
new discussion thread.</p>
|
||
</li>
|
||
<li>Add a Replaces header if your PEP obsoletes an earlier PEP. The
|
||
value of this header is the number of the PEP that your new PEP is
|
||
replacing. Only add this header if the older PEP is in “final”
|
||
form, i.e. is either Accepted, Final, or Rejected. You aren’t
|
||
replacing an older open PEP if you’re submitting a competing idea.</li>
|
||
<li>Now write your Abstract, Rationale, and other content for your PEP,
|
||
replacing all this gobbledygook with your own text. Be sure to
|
||
adhere to the format guidelines below, specifically on the
|
||
prohibition of tab characters and the indentation requirements.
|
||
See “Suggested Sections” below for a template of sections to include.</li>
|
||
<li>Update your Footnotes section, listing any footnotes and
|
||
non-inline link targets referenced by the text.</li>
|
||
<li>Run <code class="docutils literal notranslate"><span class="pre">./build.py</span></code> to ensure the PEP is rendered without errors,
|
||
and check that the output in <code class="file docutils literal notranslate"><span class="pre">build/pep-</span><em><span class="pre">NNNN</span></em><span class="pre">.html</span></code> looks as you intend.</li>
|
||
<li>Create a pull request against the <a class="reference external" href="https://github.com/python/peps/">PEPs repository</a>.</li>
|
||
</ul>
|
||
<p>For reference, here are all of the possible header fields (everything
|
||
in brackets should either be replaced or have the field removed if
|
||
it has a leading <code class="docutils literal notranslate"><span class="pre">*</span></code> marking it as optional and it does not apply to
|
||
your PEP):</p>
|
||
<div class="highlight-email notranslate"><div class="highlight"><pre><span></span><span class="nt">PEP:</span><span class="w"> </span>[NNN]
|
||
<span class="nt">Title:</span><span class="w"> </span>[...]
|
||
<span class="nt">Author:</span><span class="w"> </span>[Full<span class="w"> </span>Name<span class="w"> </span><email<span class="w"> </span>at<span class="w"> </span><span class="nf">example.com</span>>]
|
||
<span class="nt">Sponsor:</span><span class="w"> </span>*[Full<span class="w"> </span>Name<span class="w"> </span><email<span class="w"> </span>at<span class="w"> </span><span class="nf">example.com</span>>]
|
||
<span class="nt">PEP-Delegate:</span>
|
||
<span class="nt">Discussions-To:</span><span class="w"> </span>[URL]
|
||
<span class="nt">Status:</span><span class="w"> </span>Draft
|
||
<span class="nt">Type:</span><span class="w"> </span>[Standards<span class="w"> </span>Track<span class="w"> </span>|<span class="w"> </span>Informational<span class="w"> </span>|<span class="w"> </span>Process]
|
||
<span class="nt">Topic:</span><span class="w"> </span>*[Governance<span class="w"> </span>|<span class="w"> </span>Packaging<span class="w"> </span>|<span class="w"> </span>Release<span class="w"> </span>|<span class="w"> </span>Typing]
|
||
<span class="nt">Requires:</span><span class="w"> </span>*[NNN]
|
||
<span class="nt">Created:</span><span class="w"> </span>[DD-MMM-YYYY]
|
||
<span class="nt">Python-Version:</span><span class="w"> </span>*[M.N]
|
||
<span class="nt">Post-History:</span><span class="w"> </span>[`DD-MMM-YYYY<span class="w"> </span><URL>`__]
|
||
<span class="nt">Replaces:</span><span class="w"> </span>*[NNN]
|
||
<span class="nt">Superseded-By:</span><span class="w"> </span>*[NNN]
|
||
<span class="nt">Resolution:</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="restructuredtext-pep-formatting-requirements">
|
||
<h2><a class="toc-backref" href="#restructuredtext-pep-formatting-requirements" role="doc-backlink">ReStructuredText PEP Formatting Requirements</a></h2>
|
||
<p>The following is a PEP-specific summary of reStructuredText syntax.
|
||
For the sake of simplicity and brevity, much detail is omitted. For
|
||
more detail, see <a class="reference internal" href="#resources">Resources</a> below. <a class="reference internal" href="#literal-blocks">Literal blocks</a> (in which no
|
||
markup processing is done) are used for examples throughout, to
|
||
illustrate the plaintext markup.</p>
|
||
<section id="general">
|
||
<h3><a class="toc-backref" href="#general" role="doc-backlink">General</a></h3>
|
||
<p>Lines should usually not extend past column 79,
|
||
excepting URLs and similar circumstances.
|
||
Tab characters must never appear in the document at all.</p>
|
||
</section>
|
||
<section id="section-headings">
|
||
<h3><a class="toc-backref" href="#section-headings" role="doc-backlink">Section Headings</a></h3>
|
||
<p>PEP headings must begin in column zero and the initial letter of each
|
||
word must be capitalized as in book titles. Acronyms should be in all
|
||
capitals. Section titles must be adorned with an underline, a single
|
||
repeated punctuation character, which begins in column zero and must
|
||
extend at least as far as the right edge of the title text (4
|
||
characters minimum). First-level section titles are underlined with
|
||
“=” (equals signs), second-level section titles with “-” (hyphens),
|
||
and third-level section titles with “’” (single quotes or
|
||
apostrophes). For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">First-Level Title</span>
|
||
<span class="gh">=================</span>
|
||
|
||
<span class="gh">Second-Level Title</span>
|
||
<span class="gh">------------------</span>
|
||
|
||
<span class="gh">Third-Level Title</span>
|
||
<span class="gh">'''''''''''''''''</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If there are more than three levels of sections in your PEP, you may
|
||
insert overline/underline-adorned titles for the first and second
|
||
levels as follows:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">============================</span>
|
||
<span class="gh">First-Level Title (optional)</span>
|
||
<span class="gh">============================</span>
|
||
|
||
<span class="gh">-----------------------------</span>
|
||
<span class="gh">Second-Level Title (optional)</span>
|
||
<span class="gh">-----------------------------</span>
|
||
|
||
<span class="gh">Third-Level Title</span>
|
||
<span class="gh">=================</span>
|
||
|
||
<span class="gh">Fourth-Level Title</span>
|
||
<span class="gh">------------------</span>
|
||
|
||
<span class="gh">Fifth-Level Title</span>
|
||
<span class="gh">'''''''''''''''''</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>You shouldn’t have more than five levels of sections in your PEP. If
|
||
you do, you should consider rewriting it.</p>
|
||
<p>You must use two blank lines between the last line of a section’s body
|
||
and the next section heading. If a subsection heading immediately
|
||
follows a section heading, a single blank line in-between is
|
||
sufficient.</p>
|
||
<p>The body of each section is not normally indented, although some
|
||
constructs do use indentation, as described below. Blank lines are
|
||
used to separate constructs.</p>
|
||
</section>
|
||
<section id="paragraphs">
|
||
<h3><a class="toc-backref" href="#paragraphs" role="doc-backlink">Paragraphs</a></h3>
|
||
<p>Paragraphs are left-aligned text blocks separated by blank lines.
|
||
Paragraphs are not indented unless they are part of an indented
|
||
construct (such as a block quote or a list item).</p>
|
||
</section>
|
||
<section id="inline-markup">
|
||
<h3><a class="toc-backref" href="#inline-markup" role="doc-backlink">Inline Markup</a></h3>
|
||
<p>Portions of text within paragraphs and other text blocks may be
|
||
styled. For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Text may be marked as <span class="ge">*emphasized*</span> (single asterisk markup,
|
||
typically shown in italics) or <span class="gs">**strongly emphasized**</span> (double
|
||
asterisks, typically boldface). <span class="s">``Inline literals``</span> (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.
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="block-quotes">
|
||
<h3><a class="toc-backref" href="#block-quotes" role="doc-backlink">Block Quotes</a></h3>
|
||
<p>Block quotes consist of indented body elements. For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>This is a paragraph.
|
||
|
||
This is a block quote.
|
||
|
||
A block quote may contain many paragraphs.
|
||
</pre></div>
|
||
</div>
|
||
<p>Block quotes are used to quote extended passages from other sources.
|
||
Block quotes may be nested inside other body elements. Use 4 spaces
|
||
per indent level.</p>
|
||
</section>
|
||
<section id="literal-blocks">
|
||
<h3><a class="toc-backref" href="#literal-blocks" role="doc-backlink">Literal Blocks</a></h3>
|
||
<p>Literal blocks are used for code samples and other preformatted text.
|
||
To indicate a literal block, preface the indented text block with
|
||
“<code class="docutils literal notranslate"><span class="pre">::</span></code>” (two colons), or use the <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block::</span></code> directive.
|
||
Indent the text block by 4 spaces; the literal block continues until the end
|
||
of the indentation. For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>This is a typical paragraph. A literal block follows.
|
||
|
||
<span class="se">::</span>
|
||
|
||
<span class="s"> for a in [5, 4, 3, 2, 1]: # this is program code, shown as-is</span>
|
||
<span class="s"> print(a)</span>
|
||
<span class="s"> print("it's...")</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>“<code class="docutils literal notranslate"><span class="pre">::</span></code>” is also recognized at the end of any paragraph; if not immediately
|
||
preceded by whitespace, one colon will remain visible in the final output:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>This is an example::
|
||
|
||
Literal block
|
||
</pre></div>
|
||
</div>
|
||
<p>By default, literal blocks will be syntax-highlighted as Python code.
|
||
For specific blocks that contain code or data in other languages/formats,
|
||
use the <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block::</span> <span class="pre">language</span></code> directive, substituting the “short name”
|
||
of the appropriate <a class="reference external" href="https://pygments.org/docs/lexers/">Pygments lexer</a>
|
||
(or <code class="docutils literal notranslate"><span class="pre">text</span></code> to disable highlighting) for <code class="docutils literal notranslate"><span class="pre">language</span></code>. For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> rst
|
||
|
||
An example of the <span class="s">``rst``</span> lexer (i.e. <span class="ge">*reStructuredText*</span>).
|
||
</pre></div>
|
||
</div>
|
||
<p>For PEPs that predominantly contain literal blocks of a specific language,
|
||
use the <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">highlight::</span> <span class="pre">language</span></code> directive with the appropriate <code class="docutils literal notranslate"><span class="pre">language</span></code>
|
||
at the top of the PEP body (below the headers and above the Abstract).
|
||
All literal blocks will then be treated as that language,
|
||
unless specified otherwise in the specific <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block</span></code>. For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">highlight</span><span class="p">::</span> c
|
||
|
||
<span class="gh">Abstract</span>
|
||
<span class="gh">========</span>
|
||
|
||
Here's some C code::
|
||
|
||
printf("Hello, World!\n");
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="lists">
|
||
<h3><a class="toc-backref" href="#lists" role="doc-backlink">Lists</a></h3>
|
||
<p>Bullet list items begin with one of “-”, “*”, or “+” (hyphen,
|
||
asterisk, or plus sign), followed by whitespace and the list item
|
||
body. List item bodies must be left-aligned and indented relative to
|
||
the bullet; the text immediately after the bullet determines the
|
||
indentation. For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>This paragraph is followed by a list.
|
||
|
||
<span class="m">*</span> 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.
|
||
|
||
<span class="m">*</span> 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.
|
||
|
||
<span class="m">-</span> 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.
|
||
|
||
<span class="m">*</span> This is the third item of the main list.
|
||
|
||
This paragraph is not part of the list.
|
||
</pre></div>
|
||
</div>
|
||
<p>Enumerated (numbered) list items are similar, but use an enumerator
|
||
instead of a bullet. Enumerators are numbers (1, 2, 3, …), letters
|
||
(A, B, C, …; uppercase or lowercase), or Roman numerals (i, ii, iii,
|
||
iv, …; uppercase or lowercase), formatted with a period suffix
|
||
(“1.”, “2.”), parentheses (“(1)”, “(2)”), or a right-parenthesis
|
||
suffix (“1)”, “2)”). For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="m">1.</span> As with bullet list items, the left edge of paragraphs must
|
||
align.
|
||
|
||
<span class="m">2.</span> 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.
|
||
</pre></div>
|
||
</div>
|
||
<p>Definition lists are written like this:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>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.
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="tables">
|
||
<h3><a class="toc-backref" href="#tables" role="doc-backlink">Tables</a></h3>
|
||
<p>Simple tables are easy and compact:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>===== ===== =======
|
||
A B A and B
|
||
===== ===== =======
|
||
False False False
|
||
True False False
|
||
False True False
|
||
True True True
|
||
===== ===== =======
|
||
</pre></div>
|
||
</div>
|
||
<p>There must be at least two columns in a table (to differentiate from
|
||
section titles). Column spans use underlines of hyphens (“Inputs”
|
||
spans the first two columns):</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>===== ===== ======
|
||
Inputs Output
|
||
------------ ------
|
||
A B A or B
|
||
===== ===== ======
|
||
False False False
|
||
True False True
|
||
False True True
|
||
True True True
|
||
===== ===== ======
|
||
</pre></div>
|
||
</div>
|
||
<p>Text in a first-column cell starts a new row. No text in the first
|
||
column indicates a continuation line; the rest of the cells may
|
||
consist of multiple lines. For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>===== =========================
|
||
col 1 col 2
|
||
===== =========================
|
||
1 Second column of row 1.
|
||
2 Second column of row 2.
|
||
Second line of paragraph.
|
||
3 - Second column of row 3.
|
||
|
||
<span class="m">-</span> Second item in bullet
|
||
list (row 3, column 2).
|
||
===== =========================
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="hyperlinks">
|
||
<h3><a class="toc-backref" href="#hyperlinks" role="doc-backlink">Hyperlinks</a></h3>
|
||
<p>When referencing an external web page in the body of a PEP, you should
|
||
include the title of the page or a suitable description in the text, with
|
||
either an inline hyperlink or a separate explicit target with the URL.
|
||
Do not include bare URLs in the body text of the PEP, and use HTTPS
|
||
links wherever available.</p>
|
||
<p>Hyperlink references use backquotes and a trailing underscore to mark
|
||
up the reference text; backquotes are optional if the reference text
|
||
is a single word. For example, to reference a hyperlink target named
|
||
<code class="docutils literal notranslate"><span class="pre">Python</span> <span class="pre">website</span></code>, you would write:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>In this paragraph, we refer to the <span class="s">`Python website`_</span>.
|
||
</pre></div>
|
||
</div>
|
||
<p>If you intend to only reference a link once, and want to define it inline
|
||
with the text, insert the link into angle brackets (<code class="docutils literal notranslate"><span class="pre"><></span></code>) after the text
|
||
you want to link, but before the closing backtick, with a space between the
|
||
text and the opening backtick. You should also use a double-underscore after
|
||
the closing backtick instead of a single one, which makes it an anonymous
|
||
reference to avoid conflicting with other target names. For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Visit the <span class="s">`website </span><span class="si"><https://www.python.org/></span><span class="s">`__</span> for more.
|
||
</pre></div>
|
||
</div>
|
||
<p>If you want to use one link multiple places with different linked text,
|
||
or want to ensure you don’t have to update your link target names when
|
||
changing the linked text, include the target name within angle brackets
|
||
following the text to link, <em>with an underscore after the target name
|
||
but before the closing angle bracket</em> (or the link <strong>will not work</strong>).
|
||
For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>For further examples, see the <span class="s">`documentation </span><span class="si"><pydocs_></span><span class="s">`_</span>.
|
||
</pre></div>
|
||
</div>
|
||
<p>An explicit target provides the URL. Put targets in the Footnotes section
|
||
at the end of the PEP, or immediately after the paragraph with the reference.
|
||
Hyperlink targets begin with two periods and a space (the “explicit
|
||
markup start”), followed by a leading underscore, the reference text,
|
||
a colon, and the URL.</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_Python web site:</span> https://www.python.org/
|
||
<span class="p">..</span> <span class="nt">_pydocs:</span> https://docs.python.org/
|
||
</pre></div>
|
||
</div>
|
||
<p>The reference text and the target text must match (although the match
|
||
is case-insensitive and ignores differences in whitespace). Note that
|
||
the underscore trails the reference text but precedes the target text.
|
||
If you think of the underscore as a right-pointing arrow, it points
|
||
<em>away</em> from the reference and <em>toward</em> the target.</p>
|
||
</section>
|
||
<section id="internal-and-pep-rfc-links">
|
||
<h3><a class="toc-backref" href="#internal-and-pep-rfc-links" role="doc-backlink">Internal and PEP/RFC Links</a></h3>
|
||
<p>The same mechanism as hyperlinks can be used for internal references.
|
||
Every unique section title implicitly defines an internal hyperlink target.
|
||
We can make a link to the Abstract section like this:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Here is a hyperlink reference to the <span class="s">`Abstract`_</span> section. The
|
||
backquotes are optional since the reference text is a single word;
|
||
we can also just write: Abstract_.
|
||
</pre></div>
|
||
</div>
|
||
<p>To refer to PEPs or RFCs, always use the <code class="docutils literal notranslate"><span class="pre">:pep:</span></code> and <code class="docutils literal notranslate"><span class="pre">:rfc:</span></code> roles,
|
||
never hardcoded URLs.
|
||
For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>See <span class="na">:pep:</span><span class="nv">`1`</span> for more information on how to write a PEP,
|
||
and <span class="na">:pep:</span><span class="nv">`the Hyperlink section of PEP 12 <12#hyperlinks>`</span> for how to link.
|
||
</pre></div>
|
||
</div>
|
||
<p>This renders as:</p>
|
||
<blockquote>
|
||
<div>See <a class="pep reference internal" href="../pep-0001/" title="PEP 1 – PEP Purpose and Guidelines">PEP 1</a> for more information on how to write a PEP,
|
||
and <a class="pep reference internal" href="../pep-0012/#hyperlinks" title="PEP 12 – Sample reStructuredText PEP Template § Hyperlinks">the Hyperlink section of PEP 12</a> for how to link.</div></blockquote>
|
||
<p>PEP numbers in the text are never padded, and there is a space (not a dash)
|
||
between “PEP” or “RFC” and the number; the above roles will take care of
|
||
that for you.</p>
|
||
</section>
|
||
<section id="footnotes">
|
||
<h3><a class="toc-backref" href="#footnotes" role="doc-backlink">Footnotes</a></h3>
|
||
<p>Footnote references consist of a left square bracket, a label, a
|
||
right square bracket, and a trailing underscore.
|
||
Instead of a number, use a label of the
|
||
form “#word”, where “word” is a mnemonic consisting of alphanumerics
|
||
plus internal hyphens, underscores, and periods (no whitespace or
|
||
other characters are allowed).
|
||
For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Refer to The TeXbook <span class="s">[#TeXbook]_</span> for more information.
|
||
</pre></div>
|
||
</div>
|
||
<p>which renders as</p>
|
||
<blockquote>
|
||
<div>Refer to The TeXbook <a class="footnote-reference brackets" href="#texbook" id="id1">[1]</a> for more information.</div></blockquote>
|
||
<p>Whitespace must precede the footnote reference. Leave a space between
|
||
the footnote reference and the preceding word.</p>
|
||
<p>Use footnotes for additional notes, explanations and caveats, as well as
|
||
for references to books and other sources not readily available online.
|
||
Native reST hyperlink targets or inline hyperlinks in the text should be
|
||
used in preference to footnotes for including URLs to online resources.</p>
|
||
<p>Footnotes begin with “.. “ (the explicit
|
||
markup start), followed by the footnote marker (no underscores),
|
||
followed by the footnote body. For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">[#TeXbook]</span> Donald Knuth's <span class="ge">*The TeXbook*</span>, pages 195 and 196.
|
||
</pre></div>
|
||
</div>
|
||
<p>which renders as</p>
|
||
<blockquote>
|
||
<div><aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="texbook" role="doc-footnote">
|
||
<dt class="label" id="texbook">[<a href="#id1">1</a>]</dt>
|
||
<dd>Donald Knuth’s <em>The TeXbook</em>, pages 195 and 196.</aside>
|
||
</aside>
|
||
</div></blockquote>
|
||
<p>Footnotes and footnote references will be numbered automatically, and
|
||
the numbers will always match.</p>
|
||
</section>
|
||
<section id="images">
|
||
<h3><a class="toc-backref" href="#images" role="doc-backlink">Images</a></h3>
|
||
<p>If your PEP contains a diagram or other graphic, you may include it in the
|
||
processed output using the <code class="docutils literal notranslate"><span class="pre">image</span></code> directive:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">image</span><span class="p">::</span> diagram.png
|
||
</pre></div>
|
||
</div>
|
||
<p>Any browser-friendly graphics format is possible; PNG should be
|
||
preferred for graphics, JPEG for photos and GIF for animations.
|
||
Currently, SVG must be avoided due to compatibility issues with the
|
||
PEP build system.</p>
|
||
<p>For accessibility and readers of the source text, you should include
|
||
a description of the image and any key information contained within
|
||
using the <code class="docutils literal notranslate"><span class="pre">:alt:</span></code> option to the <code class="docutils literal notranslate"><span class="pre">image</span></code> directive:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">image</span><span class="p">::</span> dataflow.png
|
||
<span class="nc">:alt:</span> Data flows from the input module, through the "black box"
|
||
module, and finally into (and through) the output module.
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="comments">
|
||
<h3><a class="toc-backref" href="#comments" role="doc-backlink">Comments</a></h3>
|
||
<p>A comment is an indented block of arbitrary text immediately
|
||
following an explicit markup start: two periods and whitespace. Leave
|
||
the “..” on a line by itself to ensure that the comment is not
|
||
misinterpreted as another explicit markup construct. Comments are not
|
||
visible in the processed document. For example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="cp">..</span>
|
||
<span class="cp"> This section should be updated in the final PEP.</span>
|
||
<span class="cp"> Ensure the date is accurate.</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="escaping-mechanism">
|
||
<h3><a class="toc-backref" href="#escaping-mechanism" role="doc-backlink">Escaping Mechanism</a></h3>
|
||
<p>reStructuredText uses backslashes (”<code class="docutils literal notranslate"><span class="pre">\</span></code>”) to override the special
|
||
meaning given to markup characters and get the literal characters
|
||
themselves. To get a literal backslash, use an escaped backslash
|
||
(”<code class="docutils literal notranslate"><span class="pre">\\</span></code>”). There are two contexts in which backslashes have no
|
||
special meaning: <a class="reference internal" href="#literal-blocks">literal blocks</a> and inline literals (see <a class="reference internal" href="#inline-markup">Inline
|
||
Markup</a> above). In these contexts, no markup recognition is done,
|
||
and a single backslash represents a literal backslash, without having
|
||
to double up.</p>
|
||
<p>If you find that you need to use a backslash in your text, consider
|
||
using inline literals or a literal block instead.</p>
|
||
</section>
|
||
<section id="canonical-documentation-and-intersphinx">
|
||
<h3><a class="toc-backref" href="#canonical-documentation-and-intersphinx" role="doc-backlink">Canonical Documentation and Intersphinx</a></h3>
|
||
<p>As <a class="pep reference internal" href="../pep-0001/#pep-maintenance" title="PEP 1 – PEP Purpose and Guidelines § PEP Maintenance">PEP 1 describes</a>,
|
||
PEPs are considered historical documents once marked Final,
|
||
and their canonical documentation/specification should be moved elsewhere.
|
||
To indicate this, use the <code class="docutils literal notranslate"><span class="pre">canonical-doc</span></code> directive
|
||
or an appropriate subclass:</p>
|
||
<ul class="simple">
|
||
<li><code class="docutils literal notranslate"><span class="pre">canonical-pypa-spec</span></code> for packaging standards</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">canonical-typing-spec</span></code> for typing standards</li>
|
||
</ul>
|
||
<p>Furthermore, you can use
|
||
<a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html">Intersphinx references</a>
|
||
to other Sphinx sites,
|
||
currently the <a class="reference external" href="https://docs.python.org/">Python documentation</a>
|
||
and <a class="reference external" href="https://packaging.python.org/">packaging.python.org</a>,
|
||
to easily cross-reference pages, sections and Python/C objects.
|
||
This works with both the “canonical” directives and anywhere in your PEP.</p>
|
||
<p>Add the directive between the headers and the first section of the PEP
|
||
(typically the Abstract)
|
||
and pass as an argument an Intersphinx reference of the canonical doc/spec
|
||
(or if the target is not on a Sphinx site, a <a class="reference internal" href="#hyperlinks">reST hyperlink</a>).</p>
|
||
<p>For example,
|
||
to create a banner pointing to the <a class="reference external" href="https://docs.python.org/3/library/sqlite3.html#module-sqlite3" title="(in Python v3.12)"><code class="docutils literal notranslate"><span class="pre">sqlite3</span></code></a> docs,
|
||
you would write the following:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">canonical-doc</span><span class="p">::</span> <span class="na">:mod:</span><span class="nv">`python:sqlite3`</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>which would generate the banner:</p>
|
||
<blockquote>
|
||
<div><div class="pep-banner canonical-doc sticky-banner admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>This PEP is a historical document. The up-to-date, canonical documentation can now be found at <a class="reference external" href="https://docs.python.org/3/library/sqlite3.html#module-sqlite3" title="(in Python v3.12)"><code class="docutils literal notranslate"><span class="pre">sqlite3</span></code></a>.</p>
|
||
<p class="close-button">×</p>
|
||
<p>See <a class="pep reference internal" href="../pep-0001/" title="PEP 1 – PEP Purpose and Guidelines">PEP 1</a> for how to propose changes.</p>
|
||
</div>
|
||
</div></blockquote>
|
||
<p>Or for a PyPA spec,
|
||
such as the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata" title="(in Python Packaging User Guide)"><span>Core metadata specifications</span></a>,
|
||
you would use:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">canonical-pypa-spec</span><span class="p">::</span> <span class="na">:ref:</span><span class="nv">`packaging:core-metadata`</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>which renders as:</p>
|
||
<blockquote>
|
||
<div><div class="pep-banner canonical-pypa-spec sticky-banner admonition attention">
|
||
<p class="admonition-title">Attention</p>
|
||
<p>This PEP is a historical document. The up-to-date, canonical spec, <a class="reference external" href="https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata" title="(in Python Packaging User Guide)"><span>Core metadata specifications</span></a>, is maintained on the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/">PyPA specs page</a>.</p>
|
||
<p class="close-button">×</p>
|
||
<p>See the <a class="reference external" href="https://www.pypa.io/en/latest/specifications/#handling-fixes-and-other-minor-updates">PyPA specification update process</a> for how to propose changes.</p>
|
||
</div>
|
||
</div></blockquote>
|
||
<p>The argument accepts arbitrary reST,
|
||
so you can include multiple linked docs/specs and name them whatever you like,
|
||
and you can also include directive content that will be inserted into the text.
|
||
The following advanced example:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">canonical-doc</span><span class="p">::</span> the <span class="na">:ref:</span><span class="nv">`python:sqlite3-connection-objects`</span> and <span class="na">:exc:</span><span class="nv">`python:~sqlite3.DataError`</span> docs
|
||
|
||
Also, see the <span class="na">:ref:</span><span class="nv">`Data Persistence docs <persistence>`</span> for other examples.
|
||
</pre></div>
|
||
</div>
|
||
<p>would render as:</p>
|
||
<blockquote>
|
||
<div><div class="pep-banner canonical-doc sticky-banner admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>This PEP is a historical document. The up-to-date, canonical documentation can now be found at the <a class="reference external" href="https://docs.python.org/3/library/sqlite3.html#sqlite3-connection-objects" title="(in Python v3.12)"><span>Connection objects</span></a> and <a class="reference external" href="https://docs.python.org/3/library/sqlite3.html#sqlite3.DataError" title="(in Python v3.12)"><code class="docutils literal notranslate"><span class="pre">sqlite3.DataError</span></code></a> docs.</p>
|
||
<p class="close-button">×</p>
|
||
<p>Also, see the <a class="reference external" href="https://docs.python.org/3/library/persistence.html#persistence" title="(in Python v3.12)"><span class="xref std std-ref">Data Persistence docs</span></a> for other examples.</p>
|
||
<p>See <a class="pep reference internal" href="../pep-0001/" title="PEP 1 – PEP Purpose and Guidelines">PEP 1</a> for how to propose changes.</p>
|
||
</div>
|
||
</div></blockquote>
|
||
</section>
|
||
</section>
|
||
<section id="habits-to-avoid">
|
||
<h2><a class="toc-backref" href="#habits-to-avoid" role="doc-backlink">Habits to Avoid</a></h2>
|
||
<p>Many programmers who are familiar with TeX often write quotation marks
|
||
like this:</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>`single-quoted' or ``double-quoted''
|
||
</pre></div>
|
||
</div>
|
||
<p>Backquotes are significant in reStructuredText, so this practice
|
||
should be avoided. For ordinary text, use ordinary ‘single-quotes’ or
|
||
“double-quotes”. For inline literal text (see <a class="reference internal" href="#inline-markup">Inline Markup</a>
|
||
above), use double-backquotes:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="s">``literal text: in here, anything goes!``</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="suggested-sections">
|
||
<h2><a class="toc-backref" href="#suggested-sections" role="doc-backlink">Suggested Sections</a></h2>
|
||
<p>Various sections are found to be common across PEPs and are outlined in
|
||
<a class="pep reference internal" href="../pep-0001/" title="PEP 1 – PEP Purpose and Guidelines">PEP 1</a>. Those sections are provided here for convenience.</p>
|
||
<div class="code rst highlight-rst notranslate" id="template"><div class="highlight"><pre><span></span>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>
|
||
|
||
|
||
<span class="gh">Abstract</span>
|
||
<span class="gh">========</span>
|
||
|
||
[A short (~200 word) description of the technical issue being addressed.]
|
||
|
||
|
||
<span class="gh">Motivation</span>
|
||
<span class="gh">==========</span>
|
||
|
||
[Clearly explain why the existing language specification is inadequate to address the problem that the PEP solves.]
|
||
|
||
|
||
<span class="gh">Rationale</span>
|
||
<span class="gh">=========</span>
|
||
|
||
[Describe why particular design decisions were made.]
|
||
|
||
|
||
<span class="gh">Specification</span>
|
||
<span class="gh">=============</span>
|
||
|
||
[Describe the syntax and semantics of any new language feature.]
|
||
|
||
|
||
<span class="gh">Backwards Compatibility</span>
|
||
<span class="gh">=======================</span>
|
||
|
||
[Describe potential impact and severity on pre-existing code.]
|
||
|
||
|
||
<span class="gh">Security Implications</span>
|
||
<span class="gh">=====================</span>
|
||
|
||
[How could a malicious user take advantage of this new feature?]
|
||
|
||
|
||
<span class="gh">How to Teach This</span>
|
||
<span class="gh">=================</span>
|
||
|
||
[How to teach users, new and experienced, how to apply the PEP to their work.]
|
||
|
||
|
||
<span class="gh">Reference Implementation</span>
|
||
<span class="gh">========================</span>
|
||
|
||
[Link to any existing implementation and details about its state, e.g. proof-of-concept.]
|
||
|
||
|
||
<span class="gh">Rejected Ideas</span>
|
||
<span class="gh">==============</span>
|
||
|
||
[Why certain ideas that were brought while discussing this PEP were not ultimately pursued.]
|
||
|
||
|
||
<span class="gh">Open Issues</span>
|
||
<span class="gh">===========</span>
|
||
|
||
[Any points that are still being decided/discussed.]
|
||
|
||
|
||
<span class="gh">Footnotes</span>
|
||
<span class="gh">=========</span>
|
||
|
||
[A collection of footnotes cited in the PEP, and a place to list non-inline hyperlink targets.]
|
||
|
||
|
||
<span class="gh">Copyright</span>
|
||
<span class="gh">=========</span>
|
||
|
||
This document is placed in the public domain or under the
|
||
CC0-1.0-Universal license, whichever is more permissive.
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="resources">
|
||
<h2><a class="toc-backref" href="#resources" role="doc-backlink">Resources</a></h2>
|
||
<p>Many other constructs and variations are possible,
|
||
both those supported by basic <a class="reference external" href="https://docutils.sourceforge.io/">Docutils</a>
|
||
and the extensions added by <a class="reference external" href="https://www.sphinx-doc.org/">Sphinx</a>.</p>
|
||
<p>A number of resources are available to learn more about them:</p>
|
||
<ul class="simple">
|
||
<li><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html">Sphinx ReStructuredText Primer</a>,
|
||
a gentle but fairly detailed introduction.</li>
|
||
<li><a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html">reStructuredText Markup Specification</a>,
|
||
the authoritative, comprehensive documentation of the basic reST syntax,
|
||
directives, roles and more.</li>
|
||
<li><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html">Sphinx Roles</a>
|
||
and <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html">Sphinx Directives</a>,
|
||
the extended constructs added by the Sphinx documentation system used to
|
||
render the PEPs to HTML.</li>
|
||
</ul>
|
||
<p>If you have questions or require assistance with writing a PEP that the above
|
||
resources don’t address, ping <code class="docutils literal notranslate"><span class="pre">@python/pep-editors</span></code> on GitHub, open an
|
||
<a class="reference external" href="https://github.com/python/peps/issues">issue on the PEPs repository</a>
|
||
or reach out to a PEP editor directly.</p>
|
||
</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-0012.rst">https://github.com/python/peps/blob/main/peps/pep-0012.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0012.rst">2024-01-12 07:20:09 GMT</a></p>
|
||
|
||
</article>
|
||
<nav id="pep-sidebar">
|
||
<h2>Contents</h2>
|
||
<ul>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#how-to-use-this-template">How to Use This Template</a></li>
|
||
<li><a class="reference internal" href="#restructuredtext-pep-formatting-requirements">ReStructuredText PEP Formatting Requirements</a><ul>
|
||
<li><a class="reference internal" href="#general">General</a></li>
|
||
<li><a class="reference internal" href="#section-headings">Section Headings</a></li>
|
||
<li><a class="reference internal" href="#paragraphs">Paragraphs</a></li>
|
||
<li><a class="reference internal" href="#inline-markup">Inline Markup</a></li>
|
||
<li><a class="reference internal" href="#block-quotes">Block Quotes</a></li>
|
||
<li><a class="reference internal" href="#literal-blocks">Literal Blocks</a></li>
|
||
<li><a class="reference internal" href="#lists">Lists</a></li>
|
||
<li><a class="reference internal" href="#tables">Tables</a></li>
|
||
<li><a class="reference internal" href="#hyperlinks">Hyperlinks</a></li>
|
||
<li><a class="reference internal" href="#internal-and-pep-rfc-links">Internal and PEP/RFC Links</a></li>
|
||
<li><a class="reference internal" href="#footnotes">Footnotes</a></li>
|
||
<li><a class="reference internal" href="#images">Images</a></li>
|
||
<li><a class="reference internal" href="#comments">Comments</a></li>
|
||
<li><a class="reference internal" href="#escaping-mechanism">Escaping Mechanism</a></li>
|
||
<li><a class="reference internal" href="#canonical-documentation-and-intersphinx">Canonical Documentation and Intersphinx</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#habits-to-avoid">Habits to Avoid</a></li>
|
||
<li><a class="reference internal" href="#suggested-sections">Suggested Sections</a></li>
|
||
<li><a class="reference internal" href="#resources">Resources</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-0012.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> |