306 lines
12 KiB
Plaintext
306 lines
12 KiB
Plaintext
PEP: 1
|
||
Title: PEP Purpose and Guidelines
|
||
Version: $Revision$
|
||
Author: barry@digicool.com (Barry A. Warsaw),
|
||
jeremy@zope.com (Jeremy Hylton)
|
||
Status: Active
|
||
Type: Informational
|
||
Created: 13-Jun-2000
|
||
Post-History: 21-Mar-2001
|
||
|
||
|
||
What is a PEP?
|
||
|
||
PEP stands for Python Enhancement Proposal. A PEP is a design
|
||
document providing information to the Python community, or
|
||
describing a new feature for Python. The PEP should provide a
|
||
concise technical specification of the feature and a rationale for
|
||
the feature.
|
||
|
||
We intend PEPs to be the primary mechanisms for proposing new
|
||
features, for collecting community input on an issue, and for
|
||
documenting the design decisions that have gone into Python. The
|
||
PEP author is responsible for building consensus within the
|
||
community and documenting dissenting opinions.
|
||
|
||
Because the PEPs are maintained as plain text files under CVS
|
||
control, their revision history is the historical record of the
|
||
feature proposal[1].
|
||
|
||
|
||
Kinds of PEPs
|
||
|
||
There are two kinds of PEPs. A standards track PEP describes a
|
||
new feature or implementation for Python. An informational PEP
|
||
describes a Python design issue, or provides general guidelines or
|
||
information to the Python community, but does not propose a new
|
||
feature.
|
||
|
||
|
||
PEP Work Flow
|
||
|
||
The PEP editor, Barry Warsaw <barry@digicool.com>, assigns numbers
|
||
for each PEP and changes its status.
|
||
|
||
The PEP process begins with a new idea for Python. Each PEP must
|
||
have a champion -- someone who writes the PEP using the style and
|
||
format described below, shepherds the discussions in the
|
||
appropriate forums, and attempts to build community consensus
|
||
around the idea. The PEP champion (a.k.a. Author) should first
|
||
attempt to ascertain whether the idea is PEP-able. Small
|
||
enhancements or patches often don't need a PEP and can be injected
|
||
into the Python development work flow with a patch submission to
|
||
the SourceForge patch manager[2] or feature request tracker[3].
|
||
|
||
The PEP champion then emails the PEP editor with a proposed title
|
||
and a rough, but fleshed out, draft of the PEP. This draft must
|
||
be written in PEP style as described below.
|
||
|
||
If the PEP editor approves, he will assign the PEP a number, label
|
||
it as standards track or informational, give it status 'draft',
|
||
and create and check-in the initial draft of the PEP. The PEP
|
||
editor will not unreasonably deny a PEP. Reasons for denying PEP
|
||
status include duplication of effort, being technically unsound,
|
||
or not in keeping with the Python philosophy. The BDFL
|
||
(Benevolent Dictator for Life, Guido van Rossum
|
||
<guido@python.org>) can be consulted during the approval phase,
|
||
and is the final arbitrator of the draft's PEP-ability.
|
||
|
||
The author of the PEP is then responsible for posting the PEP to
|
||
the community forums, and marshaling community support for it. As
|
||
updates are necessary, the PEP author can check in new versions if
|
||
they have CVS commit permissions, or can email new PEP versions to
|
||
the PEP editor for committing.
|
||
|
||
Standards track PEPs consists of two parts, a design document and
|
||
a reference implementation. The PEP should be reviewed and
|
||
accepted before a reference implementation is begun, unless a
|
||
reference implementation will aid people in studying the PEP.
|
||
Standards Track PEPs must include an implementation - in the form
|
||
of code, patch, or URL to same - before it can be considered
|
||
Final.
|
||
|
||
PEP authors are responsible for collecting community feedback on a
|
||
PEP before submitting it for review. A PEP that has not been
|
||
discussed on python-list@python.org and/or python-dev@python.org
|
||
will not be accepted. However, wherever possible, long open-ended
|
||
discussions on public mailing lists should be avoided. A better
|
||
strategy is to encourage public feedback directly to the PEP
|
||
author, who collects and integrates the comments back into the
|
||
PEP.
|
||
|
||
Once the authors have completed a PEP, they must inform the PEP
|
||
editor that it is ready for review. PEPs are reviewed by the BDFL
|
||
and his chosen consultants, who may accept or reject a PEP or send
|
||
it back to the author(s) for revision.
|
||
|
||
Once a PEP has been accepted, the reference implementation must be
|
||
completed. When the reference implementation is complete and
|
||
accepted by the BDFL, the status will be changed to `Final.'
|
||
|
||
A PEP can also be assigned status `Deferred.' The PEP author or
|
||
editor can assign the PEP this status when no progress is being
|
||
made on the PEP. Once a PEP is deferred, the PEP editor can
|
||
re-assign it to draft status.
|
||
|
||
A PEP can also be `Rejected'. Perhaps after all is said and done
|
||
it was not a good idea. It is still important to have a record of
|
||
this fact.
|
||
|
||
PEPs can also be replaced by a different PEP, rendering the
|
||
original obsolete. This is intended for Informational PEPs, where
|
||
version 2 of an API can replace version 1.
|
||
|
||
PEP work flow is as follows:
|
||
|
||
Draft -> Accepted -> Final -> Replaced
|
||
^
|
||
+----> Rejected
|
||
v
|
||
Deferred
|
||
|
||
Some informational PEPs may also have a status of `Active' if they
|
||
are never meant to be completed. E.g. PEP 1.
|
||
|
||
|
||
What belongs in a successful PEP?
|
||
|
||
Each PEP should have the following parts:
|
||
|
||
1. Preamble -- RFC822 style headers containing meta-data about the
|
||
PEP, including the PEP number, a short descriptive title
|
||
(limited to a maximum of 38 characters), the names contact info
|
||
for each author, etc.
|
||
|
||
2. Abstract -- a short (~200 word) description of the technical
|
||
issue being addressed.
|
||
|
||
3. Copyright/public domain -- Each PEP must either be explicitly
|
||
labelled in the public domain or the Open Publication
|
||
License[4].
|
||
|
||
4. 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 any of the current Python
|
||
platforms (CPython, JPython, Python .NET).
|
||
|
||
5. Rationale -- The rationale fleshes out the specification by
|
||
describing what motivated the design and 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.
|
||
|
||
6. 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. It is better
|
||
to finish the specification and rationale first and reach
|
||
consensus on it before writing code.
|
||
|
||
The final implementation must include test code and
|
||
documentation appropriate for either the Python language
|
||
reference or the standard library reference.
|
||
|
||
|
||
PEP Style
|
||
|
||
PEPs are written in plain ASCII text, and should adhere to a
|
||
rigid style. There is a Python script that parses this style and
|
||
converts the plain text PEP to HTML for viewing on the web[5].
|
||
|
||
Each PEP must begin with an RFC822 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>
|
||
Version: <cvs version string>
|
||
* Last-Modified: <cvs date string>
|
||
Author: <list of authors' email and real name>
|
||
* Discussions-To: <email address>
|
||
Status: <Draft | Active | Accepted | Deferred | Final | Replaced>
|
||
Type: <Informational | Standards Track>
|
||
* Requires: <pep numbers>
|
||
Created: <date created on, in dd-mmm-yyyy format>
|
||
* Python-Version: <version number>
|
||
Post-History: <dates of postings to python-list and python-dev>
|
||
* Replaces: <pep number>
|
||
* Replaced-By: <pep number>
|
||
|
||
Standards track PEPs must have a Python-Version: header which
|
||
indicates the version of Python that the feature will be released
|
||
with. Informational PEPs do not need a Python-Version: header.
|
||
|
||
While a PEP is in private discussions (usually during the initial
|
||
Draft phase), a Discussions-To: header will indicate the mailing
|
||
list or URL where the PEP is being discussed. No Discussions-To:
|
||
header is necessary if the PEP is being discussed privately with
|
||
the author, or on the python-list or python-dev email mailing
|
||
lists.
|
||
|
||
PEPs may have a Requires: header, indicating the PEP numbers that
|
||
this PEP depends on.
|
||
|
||
PEPs may also have a Replaced-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.
|
||
|
||
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. The body of each section must be indented 4
|
||
spaces. Code samples inside body sections should be indented a
|
||
further 4 spaces, and other indentation can be used as required to
|
||
make the text readable. You must use two blank lines between the
|
||
last line of a section's body and the next section heading.
|
||
|
||
Tab characters must never appear in the document at all. A PEP
|
||
should include the Emacs stanza included by example in this PEP.
|
||
|
||
A PEP must contain a Copyright section, and it is strongly
|
||
recommended to put the PEP in the public domain.
|
||
|
||
When referencing an external web page in the body of a PEP, you
|
||
should include the title of the page in the text, with a
|
||
footnote reference to the URL. Do not include the URL in the body
|
||
text of the PEP. E.g.
|
||
|
||
Refer to the Python Language web site [1] for more details.
|
||
...
|
||
[1] http://www.python.org
|
||
|
||
When referring to another PEP, include the PEP number in the body
|
||
text, such as "PEP 1". The title may optionally appear. Add a
|
||
footnote reference that includes the PEP's title and author. It
|
||
may optionally include the explicit URL on a separate line, but
|
||
only in the References section. Note that the pep2html.py script
|
||
will calculate URLs automatically, e.g.:
|
||
|
||
...
|
||
Refer to PEP 1 [7] for more information about PEP style
|
||
...
|
||
|
||
References
|
||
|
||
[7] PEP 1, PEP Purpose and Guidelines, Warsaw, Hylton
|
||
http://www.python.org/peps/pep-0001.html
|
||
|
||
If you decide to provide an explicit URL for a PEP, please use
|
||
this as the URL template:
|
||
|
||
http://www.python.org/peps/pep-xxxx.html
|
||
|
||
PEP numbers in URLs must be padded with zeros from the left, so as
|
||
to be exactly 4 characters wide, however PEP numbers in text are
|
||
never padded.
|
||
|
||
|
||
Reporting PEP Bugs, or Submitting PEP Updates
|
||
|
||
Please use the SourceForge bug manager[6] if you want to report
|
||
problems with PEPs, or better yet, the SourceForge patch
|
||
manager[2] for submitting patches to PEPs.
|
||
|
||
|
||
References and Footnotes
|
||
|
||
[1] This historical record is available by the normal CVS commands
|
||
for retrieving older revisions. For those without direct access
|
||
to the CVS tree, you can browse the current and past PEP revisions
|
||
via the SourceForge web site at
|
||
|
||
http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/python/nondist/peps/?cvsroot=python
|
||
|
||
[2] http://sourceforge.net/tracker/?group_id=5470&atid=305470
|
||
|
||
[3] http://sourceforge.net/tracker/?atid=355470&group_id=5470&func=browse
|
||
|
||
[4] http://www.opencontent.org/openpub/
|
||
|
||
[5] The script referred to here is pep2html.py, which lives in
|
||
the same directory in the CVS tree as the PEPs themselves. Try
|
||
"pep2html.py --help" for details.
|
||
|
||
The URL for viewing PEPs on the web is
|
||
http://python.sourceforge.net/peps/
|
||
|
||
[6] http://sourceforge.net/tracker/?group_id=5470&atid=305470
|
||
|
||
|
||
Copyright
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
|
||
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
End:
|