iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Some updates based on feedback from PEP authors. Also, this applies 

SF patch #410223 by Andrew Kuchling, describing the new Replaces: and
Replaced-by: headers.
This commit is contained in:
Barry Warsaw 2001-03-21 17:05:27 +00:00
parent c3157b3336
commit 7ce8ba5d99
1 changed files with 92 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
pep-0001.txt
View File

@ -6,7 +6,7 @@ Author: barry@digicool.com (Barry A. Warsaw),
Status: Draft Status: Draft
Type: Informational Type: Informational
Created: 13-Jun-2000 Created: 13-Jun-2000
Post-History: Post-History: 21-Mar-2001
What is a PEP? What is a PEP?
@ -37,52 +37,57 @@ Kinds of PEPs
feature. feature.
PEP Workflow PEP Work Flow
The PEP editor, Barry Warsaw <barry@digicool.com>, assigns numbers The PEP editor, Barry Warsaw <barry@digicool.com>, assigns numbers
for each PEP and changes its status. for each PEP and changes its status.
When a new feature is introduced on python-dev, a brief high-level The PEP process begins with a new idea for Python. Each PEP must
discussion should be conducted, not on the merits of the proposal, have a champion -- someone who writes the PEP using the style and
but on whether the idea is significant enough to warrant a PEP. format described below, shepherds the discussions in the
Should consensus on PEP-ability be reached, a champion must be appropriate forums, and attempts to build community consensus
identified. The champion offers to take the discussion off-line around the idea. The PEP champion (a.k.a. Author) should first
and specifies a location (e.g. egroups, python.org, Roundup). 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 champion then emails the PEP editor with a proposed title and The PEP champion then emails the PEP editor with a proposed title
a rough, but fleshed out, draft of the PEP. 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 If the PEP editor approves, he will assign the PEP a number, label
it as standards track or informational, give it status 'draft', it as standards track or informational, give it status 'draft',
and create and check-in the initial draft of the PEP. The PEP and create and check-in the initial draft of the PEP. The PEP
editor will not unreasonably deny a PEP. Reasons for denying PEP editor will not unreasonably deny a PEP. Reasons for denying PEP
status include duplication of effort, being technically unsound, status include duplication of effort, being technically unsound,
or not in keeping with the Python philosophy; the BDFL (Benevolent or not in keeping with the Python philosophy. The BDFL
Dictator for Life, Guido van Rossum <guido@python.org>) is the (Benevolent Dictator for Life, Guido van Rossum
final arbitrator of the latter. <guido@python.org>) can be consulted during the approval phase,
and is the final arbitrator of the draft's PEP-ability.
In general, an initial draft of the PEP should be prepared before The author of the PEP is then responsible for posting the PEP to
discussion occurs on the python-dev and pyton-list mailing lists. the community forums, and marshaling community support for it. As
The author should incorporate comments and feedback into this updates are necessary, the PEP author can check in new versions if
initial draft when possible. they have CVS commit permissions, or can email new PEP versions to
the PEP editor for committing.
The authors of the PEP are then responsible for writing the PEP Standards track PEPs consists of two parts, a design document and
and marshaling community support for it. The structure of a PEP a reference implementation. The PEP should be reviewed and
is described in detail below. The PEP consists of two parts, a accepted before a reference implementation is begun, unless a
design document and a reference implementation. The PEP should be reference implementation will aid people in studying the PEP.
reviewed and accepted before a reference implementation is begun, Standards Track PEPs must include an implementation - in the form
unless a reference implementation will aid people in studying the of code, patch, or URL to same - before it can be considered
PEP. A Standards Track PEP must include an implementation - in Final.
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 authors are responsible for collecting community feedback on a
PEP before submitting it for review. A PEP that has not been PEP before submitting it for review. A PEP that has not been
discussed on python-list and python-dev will not be accepted for discussed on python-list@python.org and/or python-dev@python.org
review. However, wherever possible, long open-ended discussions will not be accepted. However, wherever possible, long open-ended
on public mailing lists should be avoided. A better strategy is discussions on public mailing lists should be avoided. A better
to encourage public feedback directly to the PEP author, who strategy is to encourage public feedback directly to the PEP
collects and integrates the comments back into 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 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 editor that it is ready for review. PEPs are reviewed by the BDFL
@ -102,9 +107,13 @@ PEP Workflow
it was not a good idea. It is still important to have a record of it was not a good idea. It is still important to have a record of
this fact. 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: PEP work flow is as follows:
Draft -> Accepted -> Final Draft -> Accepted -> Final -> Replaced
^ ^
+----> Rejected +----> Rejected
v v
@ -118,24 +127,24 @@ What belongs in a successful PEP?
Each PEP should have the following parts: Each PEP should have the following parts:
1. Title -- a short, descriptive title 1. Preamble -- RFC822 style headers containing meta-data about the
PEP, including the PEP number, a short descriptive title, the
names contact info for each author, etc.
2. Author(s) -- names and contact info for each author 2. Abstract -- a short (~200 word) description of the technical
issue being addressed.
3. Abstract -- a short (~200 word) description of the technical issue 3. Copyright/public domain -- Each PEP must either be explicitly
being addressed
4. Copyright/public domain -- Each PEP must either be explicitly
labelled in the public domain or the Open Publication labelled in the public domain or the Open Publication
License[2]. License[4].
5. Specification -- The technical specification should describe 4. Specification -- The technical specification should describe
the syntax and semantics of any new language feature. The the syntax and semantics of any new language feature. The
specification should be detailed enough to allow competing, specification should be detailed enough to allow competing,
interoperable implementations for any of the current Python interoperable implementations for any of the current Python
platforms (CPython, JPython, Python .NET). platforms (CPython, JPython, Python .NET).
6. Rationale -- The rationale fleshes out the specification by 5. Rationale -- The rationale fleshes out the specification by
describing what motivated the design and why particular design describing what motivated the design and why particular design
decisions were made. It should describe alternate designs that decisions were made. It should describe alternate designs that
were considered and related work, e.g. how the feature is were considered and related work, e.g. how the feature is
@ -145,8 +154,8 @@ What belongs in a successful PEP?
community and discuss important objections or concerns raised community and discuss important objections or concerns raised
during discussion. during discussion.
7. Reference Implementation -- The reference implementation must 6. Reference Implementation -- The reference implementation must
be completed before any PEP is given status 'final,' but it be completed before any PEP is given status 'Final,' but it
need not be completed before the PEP is accepted. It is better need not be completed before the PEP is accepted. It is better
to finish the specification and rationale first and reach to finish the specification and rationale first and reach
consensus on it before writing code. consensus on it before writing code.
@ -160,51 +169,61 @@ PEP Style
PEPs are written in plain ASCII text, and should adhere to a PEPs are written in plain ASCII text, and should adhere to a
rigid style. There is a Python script that parses this style and 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]. converts the plain text PEP to HTML for viewing on the web[5].
Each PEP begins with an RFC822 style header section. Required Each PEP must begin with an RFC822 style header preamble. The
headers are as follows, and must appear in this order: headers must appear in the following order. Headers marked with
`*' are optional and are described below. All other headers are
required.
PEP: <pep number> PEP: <pep number>
Title: <pep title> Title: <pep title>
Version: <cvs version string> Version: <cvs version string>
Author: <list of authors' email and real name> Author: <list of authors' email and real name>
* Discussions-To: <email address>
Status: <Draft | Active | Accepted | Deferred | Final> Status: <Draft | Active | Accepted | Deferred | Final>
Type: <Informational | Standards Track> Type: <Informational | Standards Track>
Created: <date created on, in dd-mmm-yyyy format> Created: <date created on, in dd-mmm-yyyy format>
* Python-Version: <version number>
Post-History: <dates of postings to python-list and python-dev> Post-History: <dates of postings to python-list and python-dev>
* Replaces: <pep number>
* Replaced-By: <pep number>
Standards track PEPs should additionally have a Python-Version: Standards track PEPs must have a Python-Version: header which
header which indicates the version of Python that the feature will indicates the version of Python that the feature will be released
be released with. with. Informational PEPs do not need a Python-Version: header.
While a PEP is in private discussions (usually during the initial While a PEP is in private discussions (usually during the initial
Draft phase), a Discussions-To: header will indicate the mailing Draft phase), a Discussions-To: header will indicate the mailing
list or URL where the PEP is being discussed. 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.
PEP headings should begin in column zero and should be PEPs may also have a Replaced-By: header indicating that a PEP has
capitalized. The body of each section should be indented 4 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 spaces. Code samples inside body sections should be indented a
further 4 spaces, and other indentation can be used as required to further 4 spaces, and other indentation can be used as required to
make the text readable. You should use two blank lines between make the text readable. You must use two blank lines between the
the last line of a section's body and the next section heading. last line of a section's body and the next section heading.
No tabs should appear in the document at all. A PEP should Tab characters must never appear in the document at all. A PEP
include the Emacs stanza included by example in this PEP to aid should include the Emacs stanza included by example in this PEP.
Emacs editors.
A PEP must contain a Copyright heading, and it is strongly A PEP must contain a Copyright section, and it is strongly
recommended to put the PEP in the public domain. recommended to put the PEP in the public domain.
You should footnote any URLs in the body of the PEP, and a PEP You should footnote any URLs in the body of the PEP, and a PEP
should include a References section with those URLs expanded. should include a References section with those URLs expanded.
Copyright
This document has been placed in the public domain.
References and Footnotes References and Footnotes
[1] This historical record is available by the normal CVS commands [1] This historical record is available by the normal CVS commands
@ -214,9 +233,13 @@ References and Footnotes
http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/python/nondist/peps/?cvsroot=python http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/python/nondist/peps/?cvsroot=python
[2] http://www.opencontent.org/openpub/ [2] http://sourceforge.net/tracker/?group_id=5470&atid=305470
[3] The script referred to here is pep2html.py, which lives in [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 the same directory in the CVS tree as the PEPs themselves. Try
"pep2html.py --help" for details. "pep2html.py --help" for details.
@ -224,6 +247,10 @@ References and Footnotes
http://python.sourceforge.net/peps/ http://python.sourceforge.net/peps/
Copyright
This document has been placed in the public domain.
Local Variables: Local Variables: