417 lines
18 KiB
Plaintext
417 lines
18 KiB
Plaintext
PEP: 1
|
||
Title: PEP Purpose and Guidelines
|
||
Version: $Revision$
|
||
Last-Modified: $Date$
|
||
Author: Barry A. Warsaw, Jeremy Hylton, David Goodger
|
||
Status: Active
|
||
Type: Informational
|
||
Content-Type: text/plain
|
||
Created: 13-Jun-2000
|
||
Post-History: 21-Mar-2001, 29-Jul-2002
|
||
|
||
|
||
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 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 editors assign PEP numbers and change their status. The
|
||
current PEP editors are David Goodger and Barry Warsaw. Please
|
||
send all PEP-related email to <peps@python.org>.
|
||
|
||
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,
|
||
not providing proper motivation or addressing backwards
|
||
compatibility, 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.
|
||
|
||
If a pre-PEP is rejected, the author may elect to take the pre-PEP
|
||
to the comp.lang.python newsgroup (a.k.a. python-list@python.org
|
||
mailing list) to help flesh it out, gain feedback and consensus
|
||
from the community at large, and improve the PEP for
|
||
re-submission.
|
||
|
||
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. For a PEP that is
|
||
pre-determined to be acceptable (e.g., it is an obvious win as-is
|
||
and/or its implementation has already been checked in) the BDFL
|
||
may also initiate a PEP review, first notifying the PEP author(s)
|
||
and giving them a chance to make revisions.
|
||
|
||
For a PEP to be accepted it must meet certain minimum criteria.
|
||
It must be a clear and complete description of the proposed
|
||
enhancement. The enhancement must represent a net improvement.
|
||
The proposed implementation, if applicable, must be solid and must
|
||
not complicate the interpreter unduly. Finally, a proposed
|
||
enhancement must be "pythonic" in order to be accepted by the
|
||
BDFL. (However, "pythonic" is an imprecise term; it may be
|
||
defined as whatever is acceptable to the BDFL. This logic is
|
||
intentionally circular.) See PEP 2 [10] for standard library
|
||
module acceptance criteria.
|
||
|
||
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. Motivation -- The motivation is critical for PEPs that want to
|
||
change the Python language. It should clearly explain why the
|
||
existing language specification is inadequate to address the
|
||
problem that the PEP solves. PEP submissions without
|
||
sufficient motivation may be rejected outright.
|
||
|
||
6. 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.
|
||
|
||
7. Backwards Compatibility -- All PEPs that introduce backwards
|
||
incompatibilities must include a section describing these
|
||
incompatibilities and their severity. The PEP must explain how
|
||
the author proposes to deal with these incompatibilities. PEP
|
||
submissions without a sufficient backwards compatibility
|
||
treatise may be rejected outright.
|
||
|
||
8. 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 Formats and Templates
|
||
|
||
There are two PEP formats available to authors: plaintext and
|
||
reStructuredText.
|
||
|
||
Plaintext PEPs are written in plain ASCII text, contain minimal
|
||
structural markup, and should adhere to a rigid style. PEP 9
|
||
contains a boilerplate template[7] you can use to get started
|
||
writing your plaintext PEP.
|
||
|
||
ReStructuredText PEPs allow for rich markup that is still quite
|
||
easy to read, but results in much better-looking and more
|
||
functional HTML. PEP 12 contains a boilerplate template[8] for
|
||
use with reStructuredText PEPs.
|
||
|
||
There is a Python script that converts both styles of PEPs to HTML
|
||
for viewing on the web[5]. Parsing and conversion of plaintext
|
||
PEPs is self-contained within the script. reStructuredText PEPs
|
||
are parsed and converted by Docutils[9] code called from the
|
||
script.
|
||
|
||
|
||
PEP Header Preamble
|
||
|
||
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 | Rejected |
|
||
Final | Replaced>
|
||
Type: <Informational | Standards Track>
|
||
* Content-Type: <text/plain | text/x-rst>
|
||
* 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 header value must be
|
||
|
||
Random J. User <address@dom.ain>
|
||
|
||
if the email address is included, and just
|
||
|
||
Random J. User
|
||
|
||
if the address is not given. For historical reasons the format
|
||
"address@dom.ain (Random J. User)" may appear in a PEP, however
|
||
new PEPs must use the mandated format above, and it is acceptable
|
||
to change to this format when PEPs are updated.
|
||
|
||
If there are multiple authors, each should be on a separate line
|
||
following RFC 2822 continuation line conventions. Note that
|
||
personal email addresses in PEPs will be obscured as a defense
|
||
against spam harvesters.
|
||
|
||
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.
|
||
|
||
The Type header specifies the type of PEP: Informational or
|
||
Standards Track.
|
||
|
||
The format of a PEP is specified with a Content-Type header. The
|
||
acceptable values are "text/plain" for plaintext PEPs (see PEP 9
|
||
[7]) and "text/x-rst" for reStructuredText PEPs (see PEP 12 [8]).
|
||
Plaintext ("text/plain") is the default if no Content-Type header
|
||
is present.
|
||
|
||
The Created header records the date that the PEP was assigned a
|
||
number, while Post-History is used to record the dates of when new
|
||
versions of the PEP are posted to python-list and/or python-dev.
|
||
Both headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
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 in 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't 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 Plaintext PEP Template, Warsaw
|
||
http://www.python.org/peps/pep-0009.html
|
||
|
||
[8] PEP 12, Sample reStructuredText PEP Template, Goodger, Warsaw
|
||
http://www.python.org/peps/pep-0012.html
|
||
|
||
[9] http://docutils.sourceforge.net/
|
||
|
||
[10] PEP 2, Procedure for Adding New Modules, Faassen
|
||
http://www.python.org/peps/pep-0002.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:
|