235 lines
9.2 KiB
Plaintext
235 lines
9.2 KiB
Plaintext
PEP: 1
|
||
Title: PEP Purpose and Guidelines
|
||
Version: $Revision$
|
||
Author: bwarsaw@beopen.com (Barry A. Warsaw),
|
||
jeremy@beopen.com (Jeremy Hylton)
|
||
Status: Draft
|
||
Type: Informational
|
||
Created: 13-Jun-2000
|
||
Post-History:
|
||
|
||
|
||
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 three kinds of PEPs. A standards track PEP describes a
|
||
new feature 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. A technical
|
||
PEP describes a new implementation or other internal modification
|
||
that doesn't directly expose new features to the Python
|
||
programmer.
|
||
|
||
|
||
PEP Workflow
|
||
|
||
The PEP editor, Barry Warsaw <bwarsaw@beopen.com>, assigns numbers
|
||
for each PEP and changes its status.
|
||
|
||
When a new feature is introduced on python-dev, a brief high-level
|
||
discussion should be conducted, not on the merits of the proposal,
|
||
but on whether the idea is significant enough to warrant a PEP.
|
||
Should consensus on PEP-ability be reached, a champion must be
|
||
identified. The champion offers to take the discussion off-line
|
||
and specifies a location (e.g. egroups, python.org, Roundup).
|
||
|
||
The champion then emails the PEP editor with a proposed title and
|
||
an abstract of about a paragraph in length.
|
||
|
||
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 an initial template for 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@beopen.com>) is the
|
||
final arbitrator of the latter.
|
||
|
||
Discussion concerning a PEP should initially be kept out of the
|
||
python-dev and python-list mailing lists. Instead, comments
|
||
should be sent to, and collected by, the PEP owner, who has the
|
||
responsibility to incorporate these comments into the document.
|
||
|
||
The authors of the PEP are then responsible for writing the PEP
|
||
and marshaling community support for it. The structure of a PEP
|
||
is described in detail below. The PEP 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. A Standards Track PEP 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 and python-dev will not be accepted for
|
||
review. 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.
|
||
|
||
PEP work flow is as follows:
|
||
|
||
Draft -> Accepted -> Final
|
||
^
|
||
+----> 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. Title -- a short, descriptive title
|
||
|
||
2. Author(s) -- names and contact info for each author
|
||
|
||
3. Abstract -- a short (~200 word) description of the technical issue
|
||
being addressed
|
||
|
||
4. Copyright/public domain -- Each PEP must either be explicitly
|
||
labelled in the public domain or the Open Publication
|
||
License[2].
|
||
|
||
5. 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).
|
||
|
||
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. 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[3].
|
||
|
||
Each PEP begins with an RFC822 style header section. Required
|
||
headers are as follows, and must appear in this order:
|
||
|
||
PEP: <pep number>
|
||
Title: <pep title>
|
||
Version: <cvs version string>
|
||
Author: <list of authors' email and real name>
|
||
Status: <Draft | Active | Accepted | Deferred | Final>
|
||
Type: <Informational | Standards Track>
|
||
Created: <date created on, in dd-mmm-yyyy format>
|
||
Post-History: <dates of postings to python-list and python-dev>
|
||
|
||
Standards track PEPs should additionally have a Python-Version:
|
||
header which indicates the version of Python that the feature will
|
||
be released with.
|
||
|
||
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.
|
||
|
||
PEP headings should begin in column zero and should be
|
||
capitalized. The body of each section should 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 should use two blank lines between
|
||
the last line of a section's body and the next section heading.
|
||
|
||
No tabs should appear in the document at all. A PEP should
|
||
include the Emacs stanza included by example in this PEP to aid
|
||
Emacs editors.
|
||
|
||
A PEP must contain a Copyright heading, and it is strongly
|
||
recommended to put the PEP in the public domain.
|
||
|
||
You should footnote any URLs in the body of the PEP, and a PEP
|
||
should include a References section with those URLs expanded.
|
||
|
||
|
||
Copyright
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
|
||
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://www.opencontent.org/openpub/
|
||
|
||
[3] 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/
|
||
|
||
|
||
|
||
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
End:
|