398 lines
16 KiB
Plaintext
398 lines
16 KiB
Plaintext
PEP: 1
|
||
Title: PEP Purpose and Guidelines
|
||
Version: $Revision$
|
||
Last-Modified: $Date$
|
||
Author: Barry A. Warsaw, 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. Informational PEPs do not necessarily represent a Python
|
||
community consensus or recommendation, so users and implementors
|
||
are free to ignore informational PEPs or follow their advice.
|
||
|
||
|
||
PEP Work Flow
|
||
|
||
The PEP editor, Barry Warsaw <peps@python.org>, assigns numbers
|
||
for each PEP and changes its status.
|
||
|
||
The PEP process begins with a new idea for Python. It is highly
|
||
recommended that a single PEP contain a single key proposal or new
|
||
idea. The more focussed the PEP, the more successfully it tends
|
||
to be. The PEP editor reserves the right to reject PEP proposals
|
||
if they appear too unfocussed or too broad. If in doubt, split
|
||
your PEP into several well-focussed ones.
|
||
|
||
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 <peps@python.org> 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) 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. Strategies
|
||
to keep the discussions efficient include, setting up a separate
|
||
SIG mailing list for the topic, having the PEP author accept
|
||
private comments in the early design phases, etc. PEP authors
|
||
should use their discretion here.
|
||
|
||
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 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. Copyright/public domain -- Each PEP must either be explicitly
|
||
labelled as placed in the public domain (see this PEP as an
|
||
example) or licensed under 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 Template
|
||
|
||
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].
|
||
PEP 9 contains a boilerplate[7] template you can use to get
|
||
started writing your PEP.
|
||
|
||
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' real names and optionally, email addrs>
|
||
* 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>
|
||
|
||
The Author: header lists the names and optionally, the email
|
||
addresses of all the authors/owners of the PEP. The format of the
|
||
author entry should be
|
||
|
||
address@dom.ain (Random J. User)
|
||
|
||
if the email address is included, and just
|
||
|
||
Random J. User
|
||
|
||
if the address is not given. If there are multiple authors, each
|
||
should be on a separate line following RFC 822 continuation line
|
||
conventions. Note that personal email addresses in PEPs will be
|
||
obscured as a defense against spam harvesters.
|
||
|
||
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. Note that email addresses in the Discussions-To: header
|
||
will not be obscured.
|
||
|
||
Created: 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-list and/or python-dev.
|
||
Both headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.
|
||
|
||
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 Formatting Requirements
|
||
|
||
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.
|
||
|
||
You must adhere to the Emacs convention of adding two spaces at
|
||
the end of every sentence. You should fill your paragraphs to
|
||
column 70, but under no circumstances should your lines extend
|
||
past column 79. If your code samples spill over column 79, you
|
||
should rewrite them.
|
||
|
||
Tab characters must never appear in the document at all. A PEP
|
||
should include the standard Emacs stanza included by example at
|
||
the bottom of 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
|
||
|
||
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 to the SourceForge bug
|
||
manager[6] or better yet, the SourceForge patch manager[2] so that
|
||
your changes don't get lost. If the PEP author is a SF developer,
|
||
assign the bug/patch to him, otherwise assign it to the PEP
|
||
editor.
|
||
|
||
When in doubt about where to send your changes, please check first
|
||
with the PEP author and/or PEP editor.
|
||
|
||
PEP authors who are also SF committers, can update the PEPs
|
||
themselves by using "cvs commit" to commit their changes.
|
||
Remember to also push the formatted PEP text out to the web by
|
||
doing the following:
|
||
|
||
% python pep2html.py -i NUM
|
||
|
||
where NUM is the number of the PEP you want to push out. See
|
||
|
||
% python pep2html.py --help
|
||
|
||
for details.
|
||
|
||
|
||
Transferring PEP Ownership
|
||
|
||
It occasionally becomes necessary to transfer ownership of PEPs to
|
||
a new champion. In general, we'd like 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 you don't agree with the direction of the PEP. We try to
|
||
build consensus around a PEP, but if that's not possible, you can
|
||
always submit a competing PEP.
|
||
|
||
If you are interested assuming ownership of a PEP, send a message
|
||
asking to take over, addressed to both the original author and the
|
||
PEP editor <peps@python.org>. If the original author doesn't
|
||
respond to email in a timely manner, the PEP editor will make a
|
||
unilateral decision (it's not like such decisions can be
|
||
reversed. :).
|
||
|
||
|
||
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://www.python.org/peps/
|
||
|
||
[6] http://sourceforge.net/tracker/?group_id=5470&atid=305470
|
||
|
||
[7] PEP 9, Sample PEP Template
|
||
http://www.python.org/peps/pep-0009.html
|
||
|
||
|
||
Copyright
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
|
||
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 70
|
||
End:
|