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

Several PEPs: Use explicit `:pep:` and `:rfc:` roles (#2209)

This commit is contained in:
Adam Turner 2022-01-21 11:03:51 +00:00 committed by GitHub
parent cf5b6b1649
commit 113e490701
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
394 changed files with 2661 additions and 3596 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
pep-0001.txt
View File

@ -80,7 +80,7 @@ Python's Steering Council
There are several references in this PEP to the "Steering Council" or "Council".
This refers to the current members of the elected Steering Council described
in PEP 13 [5]_, in their role as the final authorities on whether or not PEPs
in :pep:`13`, in their role as the final authorities on whether or not PEPs
will be accepted or rejected.
@ -88,7 +88,7 @@ Python's Core Developers
------------------------
There are several references in this PEP to "core developers". This refers to
the currently active Python core team members described in PEP 13 [5]_.
the currently active Python core team members described in :pep:`13`.
Python's BDFL
@ -188,7 +188,7 @@ The standard PEP workflow is:
"Informational", or "Process" as appropriate, and for the "Status:"
field enter "Draft". For full details, see `PEP Header Preamble`_.
* Update `.github/CODEOWNERS` [7]_ such that any co-author(s) or sponsors
* Update `.github/CODEOWNERS` [3]_ such that any co-author(s) or sponsors
with write access to the `PEP repository`_ are listed for your new file.
This ensures any future pull requests changing the file will be assigned
to them.
@ -196,7 +196,7 @@ The standard PEP workflow is:
* Push this to your GitHub fork and submit a pull request.
* The PEP editors review your PR for structure, formatting, and other
errors. For a reST-formatted PEP, PEP 12 is provided as a template.
errors. For a reST-formatted PEP, :pep:`12` is provided as a template.
It also provides a complete introduction to reST markup that is used
in PEPs. Approval criteria are:
@ -204,7 +204,7 @@ The standard PEP workflow is:
editors do not consider whether they seem likely to be accepted.
* The title accurately describes the content.
* The PEP's language (spelling, grammar, sentence structure, etc.)
and code style (examples should match PEP 8 & PEP 7) should be
and code style (examples should match :pep:`8` & :pep:`7`) should be
correct and conformant. The PEP will be checked for formatting
(plain text or reStructuredText) by Travis CI, and will not be
approved until this passes.
@ -343,7 +343,7 @@ 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 Steering Council. (However,
"pythonic" is an imprecise term; it may be defined as whatever is acceptable to
the Steering Council. This logic is intentionally circular.) See PEP 2 [2]_
the Steering Council. This logic is intentionally circular.) See :pep:`2`
for standard library module acceptance criteria.
Once a PEP has been accepted, the reference implementation must be
@ -362,7 +362,7 @@ been included in a Python release*.
Wherever possible, it is considered preferable to reduce the scope of a proposal
to avoid the need to rely on the "Provisional" status (e.g. by deferring some
features to later PEPs), as this status can lead to version compatibility
challenges in the wider Python ecosystem. PEP 411 provides additional details
challenges in the wider Python ecosystem. :pep:`411` provides additional details
on potential use cases for the Provisional status.
A PEP can also be assigned the status "Deferred". The PEP author or an
@ -400,7 +400,7 @@ deprecation process (which may require a new PEP providing the rationale for
the deprecation).
Some Informational and Process PEPs may also have a status of "Active"
if they are never meant to be completed. E.g. PEP 1 (this PEP).
if they are never meant to be completed. E.g. :pep:`1` (this PEP).
PEP Maintenance
@ -427,7 +427,7 @@ What belongs in a successful PEP?
Each PEP should have the following parts/sections:
1. Preamble -- RFC 822 style headers containing meta-data about the
1. Preamble -- :rfc:`2822` 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.
@ -519,17 +519,18 @@ PEP Formats and Templates
PEPs are UTF-8 encoded text files using the reStructuredText_ format.
ReStructuredText_ allows for rich markup that is still quite easy to
read, but also results in good-looking and functional HTML. PEP 12
contains instructions and a template [4]_ for reStructuredText PEPs.
read, but also results in good-looking and functional HTML. :pep:`12`
contains instructions and a :pep:`template <12#suggested-sections>`
for reStructuredText PEPs.
The PEP text files are automatically converted to HTML [6]_ for easier
The PEP text files are automatically converted to HTML [2]_ for easier
`online reading <https://www.python.org/dev/peps/>`__.
PEP Header Preamble
===================
Each PEP must begin with an RFC 822 style header preamble. The headers
Each PEP must begin with an :rfc:`2822` 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. ::
@ -567,7 +568,7 @@ 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
following :rfc:`2822` continuation line conventions. Note that personal
email addresses in PEPs will be obscured as a defense against spam
harvesters.
@ -598,8 +599,8 @@ The Type header specifies the type of PEP: Standards Track,
Informational, or Process.
The format of a PEP is specified with a Content-Type header. The
acceptable values are "text/plain" for plaintext PEPs (see PEP 9 [3]_)
and "text/x-rst" for reStructuredText PEPs (see PEP 12 [4]_).
acceptable values are "text/plain" for plaintext PEPs (see :pep:`9`)
and "text/x-rst" for reStructuredText PEPs (see :pep:`12`).
reStructuredText is strongly preferred, but for backwards
compatibility plain text is currently still the default if no
Content-Type header is present.
@ -709,11 +710,11 @@ For each new PEP that comes in an editor does the following:
* The file name extension is correct (i.e. ``.rst``).
* Ensure that everyone listed as a sponsor or co-author of the PEP who has write
access to the `PEP repository`_ is added to `.github/CODEOWNERS` [7]_.
access to the `PEP repository`_ is added to `.github/CODEOWNERS` [3]_.
* Skim the PEP for obvious defects in language (spelling, grammar,
sentence structure, etc.), and code style (examples should conform to
PEP 8 & PEP 7). Editors may correct problems themselves, but are
:pep:`8` & :pep:`7`). Editors may correct problems themselves, but are
not required to do so. (Text format is checked by Travis CI.)
* If a project is portrayed as benefiting from or supporting the PEP, make sure
@ -723,7 +724,7 @@ For each new PEP that comes in an editor does the following:
If the PEP isn't ready, an editor will send it back to the author for
revision, with specific instructions. If reST formatting is a
problem, ask the author(s) to use PEP 12 as a template and resubmit.
problem, ask the author(s) to use :pep:`12` as a template and resubmit.
Once the PEP is ready for the repository, a PEP editor will:
@ -789,23 +790,11 @@ References and Footnotes
for retrieving older revisions, and can also be browsed via HTTP here:
https://github.com/python/peps
.. [2] PEP 2, Procedure for Adding New Modules
(http://www.python.org/dev/peps/pep-0002)
.. [3] PEP 9, Sample Plaintext PEP Template
(http://www.python.org/dev/peps/pep-0009)
.. [4] PEP 12, Sample reStructuredText PEP Template
(http://www.python.org/dev/peps/pep-0012)
.. [5] PEP 13, Python Language Governance
(http://www.python.org/dev/peps/pep-0013)
.. [6] More details on the PEP rendering and publication process can be found
.. [2] More details on the PEP rendering and publication process can be found
in the PEPs repo README at
https://github.com/python/peps/blob/main/README.rst
.. [7] `CODEOWNERS` documentation
.. [3] `CODEOWNERS` documentation
(https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners)
.. _issue tracker:

10
pep-0002.txt
View File

@ -35,10 +35,10 @@ the library; things that are missing but should be added.
New functionality is commonly added to the library in the form of new
modules. This PEP will describe the procedure for the *addition* of
new modules. PEP 4 deals with procedures for deprecation of modules;
new modules. :pep:`4` deals with procedures for deprecation of modules;
the *removal* of old and unused modules from the standard library.
Finally there is also the issue of *changing* existing modules to make
the picture of library evolution complete. PEP 3 and PEP 5 give some
the picture of library evolution complete. :pep:`3` and :pep:`5` give some
guidelines on this. The continued maintenance of existing modules is
an integral part of the decision on whether to add a new module to the
standard library. Therefore, this PEP also introduces concepts
@ -101,7 +101,7 @@ One or more maintainers shall step forward as PEP champion (the people
listed in the Author field are the champions). The PEP champion(s)
shall be the initial head maintainer(s).
As described in PEP 1, a standards track PEP should consist of a
As described in :pep:`1`, a standards track PEP should consist of a
design document and a reference implementation. The library PEP
differs from a normal standard track PEP in that the reference
implementation should in this case always already have been written
@ -126,7 +126,7 @@ This different requirement exists for the following reasons:
Once the library PEP has been submitted for review, the integrators
will then evaluate it. The PEP will follow the normal PEP work flow
as described in PEP 1. If the PEP is accepted, they will work through
as described in :pep:`1`. If the PEP is accepted, they will work through
the head maintainers to make the contribution ready for integration.
@ -155,7 +155,7 @@ In the case where no head maintainer can be found (possibly because
there are no maintainers left), the integrators will issue a call to
the community at large asking for new maintainers to step forward. If
no one does, the integrators can decide to declare the contribution
deprecated as described in PEP 4.
deprecated as described in :pep:`4`.
Open issues

4
pep-0003.txt
View File

@ -35,8 +35,8 @@ Original Guidelines
out, say, what all the open Tkinter bugs are.
2. If it's a minor feature request that you don't plan to address
right away, add it to PEP 42 or ask the owner to add it for you.
If you add the bug to PEP 42, mark the bug as "feature request",
right away, add it to :pep:`42` or ask the owner to add it for you.
If you add the bug to :pep:`42`, mark the bug as "feature request",
"later", and "closed"; and add a comment to the bug saying that
this is the case (mentioning the PEP explicitly).

4
pep-0004.txt
View File

@ -56,7 +56,7 @@ For modules existing in both Python 2.7 and Python 3.5
In order to facilitate writing code that works in both Python 2 & 3
simultaneously, any module that exists in both Python 3.5 and
Python 2.7 will not be removed from the standard library until
Python 2.7 is no longer supported as specified by PEP 373. Exempted
Python 2.7 is no longer supported as specified by :pep:`373`. Exempted
from this rule is any module in the idlelib package as well as any
exceptions granted by the Python development team.
@ -293,7 +293,7 @@ Deprecated modules
Deprecation of modules removed in Python 3.0
============================================
PEP 3108 lists all modules that have been removed from Python 3.0.
:pep:`3108` lists all modules that have been removed from Python 3.0.
They all are documented as deprecated in Python 2.6, and raise a
DeprecationWarning if the -3 flag is activated.

11
pep-0006.txt
View File

@ -143,7 +143,7 @@ the maintenance branch, or else mark the patch in the commit message.
In addition, anyone from the Python community is free to suggest
patches for inclusion. Patches may be submitted specifically for
bugfix releases; they should follow the guidelines in PEP 3 [2]_. In
bugfix releases; they should follow the guidelines in :pep:`3`. In
general, though, it's probably better that a bug in a specific release
also be fixed on the HEAD as well as the branch.
@ -194,7 +194,7 @@ sticking with a strict bug fix policy.
Following feedback from the BDFL and others, the draft PEP was written
containing an expanded bugfix release cycle that permitted any
previous major release to obtain patches and also relaxed the strict
bug fix requirement (mainly due to the example of PEP 235 [3]_, which
bug fix requirement (mainly due to the example of :pep:`235`, which
could be argued as either a bug fix or a feature).
Discussion then mostly moved to python-dev, where BDFL finally issued
@ -213,13 +213,6 @@ References
.. [1] http://www.tcl.tk/cgi-bin/tct/tip/28.html
.. [2] PEP 3, Guidelines for Handling Bug Reports, Hylton
(http://www.python.org/dev/peps/pep-0003/)
.. [3] PEP 235, Import on Case-Insensitive Platforms, Peters
(http://www.python.org/dev/peps/pep-0235/)
Copyright
=========

9
pep-0007.txt
View File

@ -15,7 +15,7 @@ Introduction
This document gives coding conventions for the C code comprising the C
implementation of Python. Please see the companion informational PEP
describing style guidelines for Python code [1]_.
describing :pep:`style guidelines for Python code <8>`.
Note, rules are there to be broken. Two good reasons to break a
particular rule:
@ -217,13 +217,6 @@ Documentation Strings
not all do; the MSVC compiler is known to complain about this.
References
==========
.. [1] PEP 8, "Style Guide for Python Code", van Rossum, Warsaw
(http://www.python.org/dev/peps/pep-0008)
Copyright
=========

44
pep-0008.txt
View File

@ -17,10 +17,10 @@ Introduction
This document gives coding conventions for the Python code comprising
the standard library in the main Python distribution. Please see the
companion informational PEP describing style guidelines for the C code
in the C implementation of Python [1]_.
companion informational PEP describing :pep:`style guidelines for the C code
in the C implementation of Python <7>`.
This document and PEP 257 (Docstring Conventions) were adapted from
This document and :pep:`257` (Docstring Conventions) were adapted from
Guido's original Python Style Guide essay, with some additions from
Barry's style guide [2]_.
@ -38,7 +38,7 @@ A Foolish Consistency is the Hobgoblin of Little Minds
One of Guido's key insights is that code is read much more often than
it is written. The guidelines provided here are intended to improve
the readability of code and make it consistent across the wide
spectrum of Python code. As PEP 20 says, "Readability counts".
spectrum of Python code. As :pep:`20` says, "Readability counts".
A style guide is about consistency. Consistency with this style guide
is important. Consistency within a project is more important.
@ -431,7 +431,7 @@ characters, however, use the other one to avoid backslashes in the
string. It improves readability.
For triple-quoted strings, always use double quote characters to be
consistent with the docstring convention in PEP 257.
consistent with the docstring convention in :pep:`257`.
Whitespace in Expressions and Statements
@ -748,14 +748,14 @@ Documentation Strings
---------------------
Conventions for writing good documentation strings
(a.k.a. "docstrings") are immortalized in PEP 257.
(a.k.a. "docstrings") are immortalized in :pep:`257`.
- Write docstrings for all public modules, functions, classes, and
methods. Docstrings are not necessary for non-public methods, but
you should have a comment that describes what the method does. This
comment should appear after the ``def`` line.
- PEP 257 describes good docstring conventions. Note that most
- :pep:`257` describes good docstring conventions. Note that most
importantly, the ``"""`` that ends a multiline docstring should be
on a line by itself::
@ -865,8 +865,8 @@ ASCII Compatibility
Identifiers used in the standard library must be ASCII compatible
as described in the
`policy section <https://www.python.org/dev/peps/pep-3131/#policy-specification>`_
of PEP 3131.
:pep:`policy section <3131#policy-specification>`
of :pep:`3131`.
Package and Module Names
~~~~~~~~~~~~~~~~~~~~~~~~
@ -896,7 +896,7 @@ convention used only for exception names and builtin constants.
Type Variable Names
~~~~~~~~~~~~~~~~~~~
Names of type variables introduced in PEP 484 should normally use CapWords
Names of type variables introduced in :pep:`484` should normally use CapWords
preferring short names: ``T``, ``AnyStr``, ``Num``. It is recommended to add
suffixes ``_co`` or ``_contra`` to the variables used to declare covariant
or contravariant behavior correspondingly::
@ -1125,7 +1125,7 @@ Programming Recommendations
To minimize the effort involved, the ``functools.total_ordering()``
decorator provides a tool to generate missing comparison methods.
PEP 207 indicates that reflexivity rules *are* assumed by Python.
:pep:`207` indicates that reflexivity rules *are* assumed by Python.
Thus, the interpreter may swap ``y > x`` with ``x < y``, ``y >= x``
with ``x <= y``, and may swap the arguments of ``x == y`` and ``x !=
y``. The ``sort()`` and ``min()`` operations are guaranteed to use
@ -1159,7 +1159,7 @@ Programming Recommendations
*catching* the exceptions is likely to need, rather than the locations
where the exceptions are raised. Aim to answer the question
"What went wrong?" programmatically, rather than only stating that
"A problem occurred" (see PEP 3151 for an example of this lesson being
"A problem occurred" (see :pep:`3151` for an example of this lesson being
learned for the builtin exception hierarchy)
Class naming conventions apply here, although you should add the
@ -1356,18 +1356,18 @@ Programming Recommendations
Function Annotations
--------------------
With the acceptance of PEP 484, the style rules for function
With the acceptance of :pep:`484`, the style rules for function
annotations have changed.
- Function annotations should use PEP 484 syntax (There are some
- Function annotations should use :pep:`484` syntax (There are some
formatting recommendations for annotations in the previous section).
- The experimentation with annotation styles that was recommended
previously in this PEP is no longer encouraged.
- However, outside the stdlib, experiments within the rules of PEP 484
- However, outside the stdlib, experiments within the rules of :pep:`484`
are now encouraged. For example, marking up a large third party
library or application with PEP 484 style type annotations,
library or application with :pep:`484` style type annotations,
reviewing how easy it was to add those annotations, and observing
whether their presence increases code understandability.
@ -1382,7 +1382,7 @@ annotations have changed.
near the top of the file; this tells type checkers to ignore all
annotations. (More fine-grained ways of disabling complaints from
type checkers can be found in PEP 484.)
type checkers can be found in :pep:`484`.)
- Like linters, type checkers are optional, separate tools. Python
interpreters by default should not issue any messages due to type
@ -1391,7 +1391,7 @@ annotations have changed.
- Users who don't want to use type checkers are free to ignore them.
However, it is expected that users of third party library packages
may want to run type checkers over those packages. For this purpose
PEP 484 recommends the use of stub files: .pyi files that are read
:pep:`484` recommends the use of stub files: .pyi files that are read
by the type checker in preference of the corresponding .py files.
Stub files can be distributed with a library, or separately (with
the library author's permission) through the typeshed repo [5]_.
@ -1400,7 +1400,7 @@ annotations have changed.
Variable Annotations
--------------------
PEP 526 introduced variable annotations. The style recommendations for them are
:pep:`526` introduced variable annotations. The style recommendations for them are
similar to those on function annotations described above:
- Annotations for module level variables, class and instance variables,
@ -1429,9 +1429,9 @@ similar to those on function annotations described above:
class Test:
result: int=0 # No spaces around equality sign
- Although the PEP 526 is accepted for Python 3.6, the variable annotation
- Although the :pep:`526` is accepted for Python 3.6, the variable annotation
syntax is the preferred syntax for stub files on all versions of Python
(see PEP 484 for details).
(see :pep:`484` for details).
.. rubric:: Footnotes
@ -1446,8 +1446,6 @@ similar to those on function annotations described above:
References
==========
.. [1] PEP 7, Style Guide for C Code, van Rossum
.. [2] Barry's GNU Mailman style guide
http://barry.warsaw.us/software/STYLEGUIDE.txt

13
pep-0012.rst
View File

@ -19,7 +19,7 @@ Abstract
This PEP provides a boilerplate or sample template for creating your
own reStructuredText PEPs. In conjunction with the content guidelines
in PEP 1 [1]_, this should make it easy for you to conform your own
in :pep:`1`, this should make it easy for you to conform your own
PEPs to the format outlined below.
Note: if you are reading this PEP via the web, you should first grab
@ -50,7 +50,7 @@ How to Use This Template
To use this template you must first decide whether your PEP is going
to be an Informational or Standards Track PEP. Most PEPs are
Standards Track because they propose a new feature for the Python
language or standard library. When in doubt, read PEP 1 for details,
language or standard library. When in doubt, read :pep:`1` for details,
or open a tracker issue on the PEPs repo to ask for assistance.
Once you've decided which type of PEP yours is going to be, follow the
@ -611,7 +611,7 @@ Suggested Sections
==================
Various sections are found to be common across PEPs and are outlined in
PEP 1 [1]_. Those sections are provided here for convenience.
:pep:`1`. Those sections are provided here for convenience.
.. _template:
@ -651,13 +651,6 @@ list`_. The `Docutils project web site`_ has more information.
http://docutils.sf.net/docs/user/mailing-lists.html#docutils-users
References
==========
.. [1] PEP 1, PEP Purpose and Guidelines, Warsaw, Hylton
(http://www.python.org/dev/peps/pep-0001)
Copyright
=========

20
pep-0013.rst
View File

@ -27,7 +27,7 @@ The current steering council consists of:
* Thomas Wouters
* Pablo Galindo Salgado
Per the results of the vote tracked in PEP 8102.
Per the results of the vote tracked in :pep:`8102`.
The core team consists of those listed in the private
https://github.com/python/voters/ repository which is publicly
@ -314,14 +314,14 @@ when he `stepped down
After discussion, a number of proposals were put forward for a new
governance model, and the core devs voted to choose between them. The
overall process is described in PEP 8000 and PEP 8001, a review of
other projects was performed in PEP 8002, and the proposals themselves
overall process is described in :pep:`8000` and :pep:`8001`, a review of
other projects was performed in :pep:`8002`, and the proposals themselves
were written up as the 801x series of PEPs. Eventually the proposal in
PEP 8016 was `selected
:pep:`8016` was `selected
<https://discuss.python.org/t/python-governance-vote-december-2018-results/546>`__
as the new governance model, and was used to create the initial
version of this PEP. The 8000-series PEPs are preserved for historical
reference (and in particular, PEP 8016 contains additional rationale
reference (and in particular, :pep:`8016` contains additional rationale
and links to contemporary discussions), but this PEP is now the
official reference, and will evolve following the rules described
herein.
@ -330,10 +330,10 @@ herein.
History of council elections
----------------------------
* January 2019: PEP 8100
* December 2019: PEP 8101
* December 2020: PEP 8102
* December 2021: PEP 8103
* January 2019: :pep:`8100`
* December 2019: :pep:`8101`
* December 2020: :pep:`8102`
* December 2021: :pep:`8104`
History of amendments
@ -346,7 +346,7 @@ History of amendments
Acknowledgements
================
This PEP began as PEP 8016, which was written by Nathaniel J. Smith
This PEP began as :pep:`8016`, which was written by Nathaniel J. Smith
and Donald Stufft, based on a Django governance document written by
Aymeric Augustin, and incorporated feedback and assistance from
numerous others.

4
pep-0042.txt
View File

@ -25,7 +25,7 @@ This PEP contains a list of feature requests that may be considered
for future versions of Python. Large feature requests should not be
included here, but should be described in separate PEPs; however a
large feature request that doesn't have its own PEP can be listed here
until its own PEP is created. See PEP 0 for details.
until its own PEP is created. See :pep:`0` for details.
This PEP was created to allow us to close bug reports that are really
feature requests. Marked as Open, they distract from the list of real
@ -150,7 +150,7 @@ Standard Library
https://bugs.python.org/issue210849
* urlparse should be updated to comply with RFC 2396, which defines
* urlparse should be updated to comply with :rfc:`2396`, which defines
optional parameters for each segment of the path.
https://bugs.python.org/issue210834

6
pep-0100.txt
View File

@ -1083,11 +1083,9 @@ References
* UCS-2: http://www.uazone.org/multiling/unicode/ucs2.html
* UTF-7: Defined in RFC2152, e.g.
http://www.uazone.org/multiling/ml-docs/rfc2152.txt
* UTF-7: Defined in :rfc:`2152`
* UTF-8: Defined in RFC2279, e.g.
https://tools.ietf.org/html/rfc2279
* UTF-8: Defined in :rfc:`2279`
* UTF-16: http://www.uazone.org/multiling/unicode/wg2n1035.html

12
pep-0102.txt
View File

@ -8,7 +8,7 @@ Author: anthony@interlink.com.au (Anthony Baxter),
Status: Superseded
Type: Informational
Content-Type: text/x-rst
Created: 22-Aug-2001 (edited down on 9-Jan-2002 to become PEP 102)
Created: 22-Aug-2001 (edited down on 9-Jan-2002 to become :pep:`102`)
Post-History:
Superseded-By: 101
@ -17,10 +17,10 @@ Replacement Note
================
Although the size of the to-do list in this PEP is much less scary
than that in PEP 101, it turns out not to be enough justification
than that in :pep:`101`, it turns out not to be enough justification
for the duplication of information, and with it, the danger of one
of the copies to become out of date. Therefore, this PEP is not
maintained anymore, and micro releases are fully covered by PEP 101.
maintained anymore, and micro releases are fully covered by :pep:`101`.
Abstract
@ -33,8 +33,8 @@ Guido himself. But several recent releases have been performed by
other folks, so this PEP attempts to collect, in one place, all
the steps needed to make a Python bugfix release.
The major Python release process is covered in PEP 101 - this PEP
is just PEP 101, trimmed down to only include the bits that are
The major Python release process is covered in :pep:`101` - this PEP
is just :pep:`101`, trimmed down to only include the bits that are
relevant for micro releases, a.k.a. patch, or bug fix releases.
It is organized as a recipe and you can actually print this out and
@ -160,7 +160,7 @@ from the release21-maint branch.
11. Once the release process has started, the documentation needs to
be built and posted on python.org according to the instructions
in PEP 101.
in :pep:`101`.
Note that Fred is responsible both for merging doc changes from
the trunk to the branch AND for merging any branch changes from

2
pep-0103.txt
View File

@ -137,7 +137,7 @@ you have done something like that::
$ git branch v1 origin/v1
The first command clones remote repository into local directory
`python``, creates a new local branch master, sets
``python``, creates a new local branch master, sets
remotes/origin/master as its upstream remote-tracking branch and
checks it out into the working directory.

6
pep-0200.txt
View File

@ -298,7 +298,7 @@ Open items -- completed/fixed
Accepted and completed
======================
* Change meaning of \x escapes - PEP 223 - Fredrik Lundh
* Change meaning of \x escapes - :pep:`223` - Fredrik Lundh
* Add \U1234678 escapes in u"" strings - Fredrik Lundh
@ -330,8 +330,8 @@ Accepted and completed
doing. It also makes the xrange objects obvious when working in the
interactive interpreter.
* Extended print statement - Barry Warsaw PEP 214
http://www.python.org/dev/peps/pep-0214/ SF Patch #100970
* Extended print statement - Barry Warsaw :pep:`214`
SF Patch #100970
http://sourceforge.net/patch/?func=detailpatch&patch_id=100970&group_id=5470
* interface to poll system call - Andrew Kuchling SF Patch 100852

2
pep-0201.txt
View File

@ -95,7 +95,7 @@ Neither of these forms would work, since they both already mean
something in Python and changing the meanings would break existing
code. All other suggestions for new syntax suffered the same problem,
or were in conflict with other another proposed feature called 'list
comprehensions' (see PEP 202).
comprehensions' (see :pep:`202`).
The Proposed Solution
=====================

7
pep-0203.txt
View File

@ -171,8 +171,8 @@ To work around this problem, the packages currently have to use methods or
functions to modify an object in-place, which is definitely less readable than
an augmented assignment expression. Augmented assignment won't solve all the
problems for these packages, since some operations cannot be expressed in the
limited set of binary operators to start with, but it is a start. A
different PEP [3]_ is looking at adding new operators.
limited set of binary operators to start with, but it is a start. :pep:`211`
is looking at adding new operators.
New methods
@ -324,9 +324,6 @@ References
.. [2] http://sourceforge.net/patch?func=detailpatch&patch_id=100699&group_id=5470
.. [3] PEP 211, Adding A New Outer Product Operator, Wilson
http://www.python.org/dev/peps/pep-0211/
..
Local Variables:

6
pep-0204.txt
View File

@ -230,7 +230,7 @@ Open issues
[5, 6, 1, 2, 3, 4, 5, 7, 9]
- How should range literals interact with another proposed new
feature, "list comprehensions" [2]_? Specifically, should it be
feature, :pep:`"list comprehensions" <202>`? Specifically, should it be
possible to create lists in list comprehensions? E.g.::
>>> [x:y for x in (1, 2) y in (3, 4)]
@ -241,7 +241,7 @@ Open issues
Or a list of lists, like so::
[[1, 2], [1, 2, 3], [2]_, [2, 3]]
[[1, 2], [1, 2, 3], [2], [2, 3]]
However, as the syntax and semantics of list comprehensions are
still subject of hot debate, these issues are probably best
@ -297,8 +297,6 @@ References
==========
.. [1] http://sourceforge.net/patch/?func=detailpatch&patch_id=100902&group_id=5470
.. [2] PEP 202, List Comprehensions
..

2
pep-0208.txt
View File

@ -185,7 +185,7 @@ stating the result. Currently, this result integer may only be -1, 0, 1.
If the slot cannot handle the type combination, it may return a
reference to ``Py_NotImplemented``. [XXX Note that this slot is still
in flux since it should take into account rich comparisons
(i.e. PEP 207).]
(i.e. :pep:`207`).]
Numeric comparisons are handled by a new numeric protocol API::

14
pep-0209.txt
View File

@ -80,7 +80,7 @@ Some planned features are:
Instead of using Python's global coercion model which creates
temporary arrays, Numeric 2, like Numeric 1, will implement a
local coercion model as described in PEP 208 which defers the
local coercion model as described in :pep:`208` which defers the
responsibility of coercion to the operator. By using internal
buffers, a coercion operation can be done for each array
(including output arrays), if necessary, at the time of the
@ -167,7 +167,7 @@ Some planned features are:
4. Rich comparisons
The implementation of PEP 207: Rich Comparisons in Python 2.1
The implementation of :pep:`207`: Rich Comparisons in Python 2.1
provides additional flexibility when manipulating arrays. We
intend to implement this feature in Numeric 2.
@ -684,19 +684,19 @@ This document is placed in the public domain.
Related PEPs
============
* PEP 207: Rich Comparisons
* :pep:`207`: Rich Comparisons
by Guido van Rossum and David Ascher
* PEP 208: Reworking the Coercion Model
* :pep:`208`: Reworking the Coercion Model
by Neil Schemenauer and Marc-Andre' Lemburg
* PEP 211: Adding New Linear Algebra Operators to Python
* :pep:`211`: Adding New Linear Algebra Operators to Python
by Greg Wilson
* PEP 225: Elementwise/Objectwise Operators
* :pep:`225`: Elementwise/Objectwise Operators
by Huaiyu Zhu
* PEP 228: Reworking Python's Numeric Model
* :pep:`228`: Reworking Python's Numeric Model
by Moshe Zadka

34
pep-0211.txt
View File

@ -9,7 +9,7 @@ Content-Type: text/x-rst
Created: 15-Jul-2000
Python-Version: 2.1
Post-History:
Resolution: https://www.python.org/dev/peps/pep-0465/#rejected-alternatives-to-adding-a-new-operator
Resolution: :pep:`PEP 465 -- Rejected alternatives to adding a new operator <465#rejected-alternatives-to-adding-a-new-operator>`
Introduction
@ -31,7 +31,7 @@ will be equivalent to::
Classes will be able to overload this operator using the special
methods ``__across__``, ``__racross__``, and ``__iacross__``. In
particular, the new Numeric module (PEP 209) will overload this
particular, the new Numeric module (:pep:`209`) will overload this
operator for multi-dimensional arrays to implement matrix
multiplication.
@ -49,12 +49,12 @@ elements of its matrix arguments. The other implements the
"mathematical" definition of that operation, e.g. performs
row-column matrix multiplication.
Zhu and Lielens have proposed doubling up Python's operators in
this way [1]_. Their proposal would create six new binary infix
Zhu and Lielens have :pep:`proposed <225>` doubling up Python's operators in
this way. Their proposal would create six new binary infix
operators, and six new in-place operators.
The original version of this proposal was much more conservative.
The author consulted the developers of GNU Octave [2]_, an open
The author consulted the developers of GNU Octave [1]_, an open
source clone of MATLAB. Its developers agreed that providing an
infix operator for matrix multiplication was important: numerical
programmers really do care whether they have to write ``mmul(A,B)``
@ -62,7 +62,7 @@ instead of ``A op B``.
On the other hand, when asked how important it was to have infix
operators for matrix solution and other operations, Prof. James
Rawlings replied [3]_:
Rawlings replied [2]_:
I DON'T think it's a must have, and I do a lot of matrix
inversion. I cannot remember if its ``A\b`` or ``b\A`` so I always
@ -77,9 +77,9 @@ Iterators
=========
The planned addition of iterators to Python 2.2 opens up a broader
scope for this proposal. As part of the discussion of PEP 201,
Lockstep Iteration [4]_, the author of this proposal conducted an
informal usability experiment [5]_. The results showed that users
scope for this proposal. As part of the discussion of :pep:`201`,
Lockstep Iteration, the author of this proposal conducted an
informal usability experiment [3]_. The results showed that users
are psychologically receptive to "cross-product" loop syntax. For
example, most users expected::
@ -163,10 +163,10 @@ Alternatives
expression of a very common idiom (nested loops).
3. Introduce prefixed forms of all existing operators, such as
``~*`` and ``~+``, as proposed in PEP 225 [1]_.
``~*`` and ``~+``, as proposed in :pep:`225`.
Our objections to this are that there isn't enough demand to
justify the additional complexity (see Rawlings' comments [3]_),
justify the additional complexity (see Rawlings' comments [2]_),
and that the proposed syntax fails the "low toner" readability
test.
@ -182,17 +182,11 @@ discussions of what numerical programmers really care about.
References
==========
.. [1] PEP 225, Elementwise/Objectwise Operators, Zhu, Lielens
http://www.python.org/dev/peps/pep-0225/
.. [1] http://bevo.che.wisc.edu/octave/
.. [2] http://bevo.che.wisc.edu/octave/
.. [2] http://www.egroups.com/message/python-numeric/4
.. [3] http://www.egroups.com/message/python-numeric/4
.. [4] PEP 201, Lockstep Iteration, Warsaw
http://www.python.org/dev/peps/pep-0201/
.. [5] https://mail.python.org/pipermail/python-dev/2000-July/006427.html
.. [3] https://mail.python.org/pipermail/python-dev/2000-July/006427.html

7
pep-0212.txt
View File

@ -14,7 +14,7 @@ Post-History:
Rejection Notice
================
This PEP has been rejected. ``enumerate()``, introduced in PEP 279 [6]_,
This PEP has been rejected. ``enumerate()``, introduced in :pep:`279`,
covers the use-case proposed in this PEP, and the PEP author has been
unreachable.
@ -175,7 +175,7 @@ References
.. [1] http://docs.python.org/reference/compound_stmts.html#for
.. [2] Lockstep Iteration, PEP 201
.. [2] Lockstep Iteration, :pep:`201`
.. [3] http://sourceforge.net/patch/download.php?id=101138
@ -183,9 +183,6 @@ References
.. [5] http://sourceforge.net/patch/download.php?id=101178
.. [6] PEP 279, The enumerate() built-in function, Hettinger
https://www.python.org/dev/peps/pep-0279/
..
Local Variables:

2
pep-0213.txt
View File

@ -229,7 +229,7 @@ Caveats
Note
====
The descriptor mechanism described in PEP 252 is powerful enough
The descriptor mechanism described in :pep:`252` is powerful enough
to support this more directly. A 'getset' constructor may be
added to the language making this possible::

6
pep-0218.txt
View File

@ -140,10 +140,10 @@ dictionaries less instantly recognizable.
It was also contemplated that the braced notation would support set
comprehensions; however, Python 2.4 provided generator expressions
which fully met that need and did so it a more general way.
(See PEP 289 for details on generator expressions).
(See :pep:`289` for details on generator expressions).
So, Guido ruled that there would not be a set syntax; however, the
issue could be revisited for Python 3000 (see PEP 3000).
issue could be revisited for Python 3000 (see :pep:`3000`).
History
@ -195,7 +195,7 @@ reliable lookup. While it would be easy to require set elements
to be immutable, this would preclude sets of sets (which are
widely used in graph algorithms and other applications).
Earlier drafts of PEP 218 had only a single set type, but the
Earlier drafts of :pep:`218` had only a single set type, but the
``sets.py`` implementation in Python 2.3 has two, Set and
ImmutableSet. For Python 2.4, the new built-in types were named
``set`` and ``frozenset`` which are slightly less cumbersome.

4
pep-0219.txt
View File

@ -16,7 +16,7 @@ Introduction
This PEP discusses changes required to core Python in order to
efficiently support generators, microthreads and coroutines. It is
related to PEP 220, which describes how Python should be extended
related to :pep:`220`, which describes how Python should be extended
to support these facilities. The focus of this PEP is strictly on
the changes required to allow these extensions to work.
@ -59,7 +59,7 @@ way for making Python able to realistically manage thousands of
separate "threads" of activity (vs. today's limit of perhaps dozens
of separate threads of activity).
Another justification for this PEP (explored in PEP 220) is that
Another justification for this PEP (explored in :pep:`220`) is that
coroutines and generators often allow a more direct expression of
an algorithm than is possible in today's Python.

6
pep-0225.txt
View File

@ -10,7 +10,7 @@ Content-Type: text/x-rst
Created: 19-Sep-2000
Python-Version: 2.1
Post-History:
Resolution: https://www.python.org/dev/peps/pep-0465/#rejected-alternatives-to-adding-a-new-operator
Resolution: :pep:`PEP 465 -- Rejected alternatives to adding a new operator <465#rejected-alternatives-to-adding-a-new-operator>`
Introduction
@ -751,13 +751,13 @@ These are earlier drafts of this PEP:
http://www.python.org/pipermail/python-list/2000-August/112529.html
http://www.python.org/pipermail/python-dev/2000-August/014906.html
There is an alternative PEP (officially, PEP 211) by Greg Wilson, titled
There is an alternative PEP (officially, :pep:`211`) by Greg Wilson, titled
"Adding New Linear Algebra Operators to Python".
Its first (and current) version is at:
http://www.python.org/pipermail/python-dev/2000-August/014876.html
http://www.python.org/dev/peps/pep-0211/
:pep:`211`
Additional References

2
pep-0226.txt
View File

@ -53,7 +53,7 @@ The guidelines and schedule will be revised based on discussion in
the python-dev@python.org mailing list.
The PEP system was instituted late in the Python 2.0 development
cycle and many changes did not follow the process described in PEP 1.
cycle and many changes did not follow the process described in :pep:`1`.
The development process for 2.1, however, will follow the PEP
process as documented.

2
pep-0227.txt
View File

@ -37,7 +37,7 @@ This proposal changes the rules for resolving free variables in
Python functions. The new name resolution semantics will take
effect with Python 2.2. These semantics will also be available in
Python 2.1 by adding "from __future__ import nested_scopes" to the
top of a module. (See PEP 236.)
top of a module. (See :pep:`236`.)
The Python 2.0 definition specifies exactly three namespaces to
check for each name -- the local namespace, the global namespace,

2
pep-0228.txt
View File

@ -13,7 +13,7 @@ Post-History:
Withdrawal
==========
This PEP has been withdrawn in favor of PEP 3141.
This PEP has been withdrawn in favor of :pep:`3141`.
Abstract

8
pep-0231.txt
View File

@ -120,9 +120,9 @@ is used.
Related Work
============
PEP 213 [9]_ describes a different approach to hooking into
attribute access and modification. The semantics proposed in PEP
213 can be implemented using the ``__findattr__()`` hook described
:pep:`213` describes a different approach to hooking into
attribute access and modification. The semantics proposed in :pep:`213`
can be implemented using the ``__findattr__()`` hook described
here, with one caveat. The current reference implementation of
``__findattr__()`` does not support hooking on attribute deletion.
This could be added if it's found desirable. See example below.
@ -614,8 +614,6 @@ References
.. [6] http://www.python.org/doc/essays/metaclasses/
.. [7] http://www.foretec.com/python/workshops/1998-11/dd-ascher-sum.html
.. [8] http://docs.python.org/howto/regex.html
.. [9] PEP 213, Attribute Access Handlers, Prescod
http://www.python.org/dev/peps/pep-0213/
Rejection

35
pep-0236.txt
View File

@ -20,17 +20,17 @@ semantics of core language constructs, or changes their accidental
capriciously, and is always done with the aim of improving the language over
the long term, over the short term it's contentious and disrupting.
PEP 5, Guidelines for Language Evolution [1]_ suggests ways to ease the pain,
:pep:`5`, Guidelines for Language Evolution suggests ways to ease the pain,
and this PEP introduces some machinery in support of that.
PEP 227, Statically Nested Scopes [2]_ is the first application, and will be
:pep:`227`, Statically Nested Scopes is the first application, and will be
used as an example here.
Intent
======
[Note: This is policy, and so should eventually move into PEP 5 [1]_]
[Note: This is policy, and so should eventually move into :pep:`5`]
When an incompatible change to core language syntax or semantics is being
made:
@ -41,9 +41,9 @@ made:
2. A future release R is identified in which the new syntax or semantics will
be enforced.
3. The mechanisms described in PEP 3, Warning Framework [3]_ are used to
3. The mechanisms described in :pep:`230`, Warning Framework are used to
generate warnings, whenever possible, about constructs or operations whose
meaning may [4]_ change in release R.
meaning may [1]_ change in release R.
4. The new future_statement (see below) can be explicitly included in a module
M to request that the code in module M use the new syntax or semantics in
@ -106,7 +106,7 @@ cannot be pushed off until runtime.
For any given release, the compiler knows which feature names have been
defined, and raises a compile-time error if a future_statement contains a
feature not known to it [5]_.
feature not known to it [2]_.
The direct runtime semantics are the same as for any ``import`` statement:
there is a standard module ``__future__.py``, described later, and it will be
@ -140,7 +140,7 @@ Under 2.0, it prints::
x is 42
Nested scopes [2]_ are being introduced in 2.1. But under 2.1, it still
Nested scopes (:pep:`227`) are being introduced in 2.1. But under 2.1, it still
prints::
x is 42
@ -241,7 +241,7 @@ This isn't always desired, though. For example, ``doctest.testmod(M)``
compiles examples taken from strings in M, and those examples should use M's
choices, not necessarily the doctest module's choices. In the 2.1 release,
this isn't possible, and no scheme has yet been suggested for working around
this. NOTE: PEP 264 later addressed this in a flexible way, by adding
this. NOTE: :pep:`264` later addressed this in a flexible way, by adding
optional arguments to ``compile()``.
In any case, a future_statement appearing "near the top" (see Syntax above) of
@ -279,10 +279,10 @@ However, the machinery used internally by native interactive shells has not
been exposed, and there isn't a clear way for tools building their own
interactive shells to achieve the desired behavior.
NOTE: PEP 264 later addressed this, by adding intelligence to the standard
NOTE: :pep:`264` later addressed this, by adding intelligence to the standard
``codeop.py``. Simulated shells that don't use the standard library shell
helpers can get a similar effect by exploiting the new optional arguments to
``compile()`` added by PEP 264.
``compile()`` added by :pep:`264`.
Questions and Answers
@ -297,7 +297,7 @@ PEP if you want to pursue it.
What about incompatibilities due to changes in the Python virtual machine?
--------------------------------------------------------------------------
Outside the scope of this PEP, although PEP 5 [1]_ suggests a grace period
Outside the scope of this PEP, although :pep:`5` suggests a grace period
there too, and the future_statement may also have a role to play there.
What about incompatibilities due to changes in Python's C API?
@ -350,19 +350,10 @@ This document has been placed in the public domain.
References and Footnotes
========================
.. [1] PEP 5, Guidelines for Language Evolution, Prescod
http://www.python.org/dev/peps/pep-0005/
.. [2] PEP 227, Statically Nested Scopes, Hylton
http://www.python.org/dev/peps/pep-0227/
.. [3] PEP 230, Warning Framework, Van Rossum
http://www.python.org/dev/peps/pep-0230/
.. [4] Note that this is *may* and not *will*: better safe than sorry. Of course
.. [1] Note that this is *may* and not *will*: better safe than sorry. Of course
spurious warnings won't be generated when avoidable with reasonable cost.
.. [5] This ensures that a future_statement run under a release prior to the
.. [2] This ensures that a future_statement run under a release prior to the
first one in which a given feature is known (but >= 2.1) will raise a
compile-time error rather than silently do a wrong thing. If transported
to a release prior to 2.1, a runtime error will be raised because of the

40
pep-0238.txt
View File

@ -96,7 +96,7 @@ of code to be fixed, but the amount of code that might be affected by the bug
in the future is unbounded.
Another reason for this change is the desire to ultimately unify Python's
numeric model. This is the subject of PEP 228 [0]_ (which is currently
numeric model. This is the subject of :pep:`228` (which is currently
incomplete). A unified numeric model removes most of the user's need to be
aware of different numerical types. This is good for beginners, but also
takes away concerns about different numeric behavior for advanced programmers.
@ -156,7 +156,7 @@ discussed on c.l.py that isn't mentioned here, please mail the second author.
- Let ``/`` keep its classic semantics; introduce ``//`` for true division.
This still leaves a broken operator in the language, and invites to use the
broken behavior. It also shuts off the road to a unified numeric model a la
PEP 228 [0]_.
:pep:`228`.
- Let int division return a special "portmanteau" type that behaves as an
integer in integer context, but like a float in a float context. The
@ -316,7 +316,7 @@ language). Algorithms that consciously use longs should consider using
``//``, as true division of longs retains no more than 53 bits of precision
(on most platforms).
If and when a rational type is added to Python (see PEP 239 [2]_), true
If and when a rational type is added to Python (see :pep:`239`), true
division for ints and longs should probably return a rational. This avoids
the problem with true division of ints and longs losing information. But
until then, for consistency, float is the only choice for true division.
@ -333,7 +333,7 @@ Python 3.0 comes along, where they are always translated to true division).
The future division statement has no effect on the recognition or translation
of ``//`` and ``//=``.
See PEP 236 [4]_ for the general rules for future statements.
See :pep:`236` for the general rules for future statements.
(It has been proposed to use a longer phrase, like *true_division* or
*modern_division*. These don't seem to add much information.)
@ -416,7 +416,7 @@ Why isn't true division called float division?
----------------------------------------------
Because I want to keep the door open to *possibly* introducing rationals
and making 1/2 return a rational rather than a float. See PEP 239 [2]_.
and making 1/2 return a rational rather than a float. See :pep:`239`.
Why is there a need for ``__truediv__`` and ``__itruediv__``?
-------------------------------------------------------------
@ -427,7 +427,7 @@ Why is there a need for ``__truediv__`` and ``__itruediv__``?
How do I write code that works under the classic rules as well as under the new rules without using ``//`` or a future division statement?
------------------------------------------------------------------------------------------------------------------------------------------
Use ``x*1.0/y`` for true division, ``divmod(x, y)`` [0]_ for int
Use ``x*1.0/y`` for true division, ``divmod(x, y)`` (:pep:`228`) for int
division. Especially the latter is best hidden inside a function. You
may also write ``float(x)/y`` for true division if you are sure that you
don't expect complex numbers. If you know your integers are never
@ -442,13 +442,13 @@ How do I write code that works under the classic rules as well as under the new
How do I specify the division semantics for ``input()``, ``compile()``, ``execfile()``, ``eval()`` and ``exec``?
----------------------------------------------------------------------------------------------------------------
They inherit the choice from the invoking module. PEP 236 [4]_ now lists
this as a resolved problem, referring to PEP 264 [5]_.
They inherit the choice from the invoking module. :pep:`236` now lists
this as a resolved problem, referring to :pep:`264`.
What about code compiled by the codeop module?
----------------------------------------------
This is dealt with properly; see PEP 264 [5]_.
This is dealt with properly; see :pep:`264`.
Will there be conversion tools or aids?
---------------------------------------
@ -476,28 +476,6 @@ Essentially everything mentioned here is implemented in CVS and will be
released with Python 2.2a3; most of it was already released with Python 2.2a2.
References
==========
.. [0] PEP 228, Reworking Python's Numeric Model
http://www.python.org/dev/peps/pep-0228/
.. [1] PEP 237, Unifying Long Integers and Integers, Zadka,
http://www.python.org/dev/peps/pep-0237/
.. [2] PEP 239, Adding a Rational Type to Python, Zadka,
http://www.python.org/dev/peps/pep-0239/
.. [3] PEP 240, Adding a Rational Literal to Python, Zadka,
http://www.python.org/dev/peps/pep-0240/
.. [4] PEP 236, Back to the __future__, Peters,
http://www.python.org/dev/peps/pep-0236/
.. [5] PEP 264, Future statements in simulated shells
http://www.python.org/dev/peps/pep-0236/
Copyright
=========

13
pep-0239.txt
View File

@ -18,19 +18,19 @@ Python has no numeric type with the semantics of an unboundedly
precise rational number. This proposal explains the semantics of
such a type, and suggests builtin functions and literals to
support such a type. This PEP suggests no literals for rational
numbers; that is left for another PEP [1]_.
numbers; that is left for :pep:`another PEP <240>`.
BDFL Pronouncement
==================
This PEP is rejected. The needs outlined in the rationale section
have been addressed to some extent by the acceptance of PEP 327
have been addressed to some extent by the acceptance of :pep:`327`
for decimal arithmetic. Guido also noted, "Rational arithmetic
was the default 'exact' arithmetic in ABC and it did not work out as
expected". See the python-dev discussion on 17 June 2005 [2]_.
expected". See the python-dev discussion on 17 June 2005 [1]_.
*Postscript:* With the acceptance of PEP 3141, "A Type Hierarchy
*Postscript:* With the acceptance of :pep:`3141`, "A Type Hierarchy
for Numbers", a 'Rational' numeric abstract base class was added
with a concrete implementation in the 'fractions' module.
@ -127,10 +127,7 @@ Open Issues
References
==========
.. [1] PEP 240, Adding a Rational Literal to Python, Zadka,
http://www.python.org/dev/peps/pep-0240/
.. [2] Raymond Hettinger, Propose rejection of PEPs 239 and 240 -- a builtin
.. [1] Raymond Hettinger, Propose rejection of PEPs 239 and 240 -- a builtin
rational type and rational literals
https://mail.python.org/pipermail/python-dev/2005-June/054281.html

10
pep-0240.txt
View File

@ -14,7 +14,7 @@ Post-History: 16-Mar-2001
Abstract
========
A different PEP [1]_ suggests adding a builtin rational type to
A :pep:`different PEP <239>` suggests adding a builtin rational type to
Python. This PEP suggests changing the ddd.ddd float literal to a
rational in Python, and modifying non-integer division to return
it.
@ -24,10 +24,10 @@ BDFL Pronouncement
==================
This PEP is rejected. The needs outlined in the rationale section
have been addressed to some extent by the acceptance of PEP 327
have been addressed to some extent by the acceptance of :pep:`327`
for decimal arithmetic. Guido also noted, "Rational arithmetic
was the default 'exact' arithmetic in ABC and it did not work out as
expected". See the python-dev discussion on 17 June 2005 [2]_.
expected". See the python-dev discussion on 17 June 2005 [1]_.
Rationale
@ -88,9 +88,7 @@ point, which gives us a new loss of precision.
References
==========
.. [1] PEP 239, Adding a Rational Type to Python, Zadka,
http://www.python.org/dev/peps/pep-0239/
.. [2] Raymond Hettinger, Propose rejection of PEPs 239 and 240 -- a builtin
.. [1] Raymond Hettinger, Propose rejection of PEPs 239 and 240 -- a builtin
rational type and rational literals
https://mail.python.org/pipermail/python-dev/2005-June/054281.html

4
pep-0241.txt
View File

@ -33,7 +33,7 @@ command will, if it detects an existing PKG-INFO file, terminate
with an appropriate error message. This should prevent confusion
caused by the PKG-INFO and setup.py files being out of sync.
The PKG-INFO file format is a single set of RFC-822 headers
The PKG-INFO file format is a single set of :rfc:`822` headers
parseable by the rfc822.py module. The field names listed in the
following section are used as the header names. There's no
extension mechanism in this simple format; the Catalog and Distutils
@ -165,7 +165,7 @@ Author-email
------------
A string containing the author's e-mail address. It can contain
a name and e-mail address in the legal forms for a RFC-822
a name and e-mail address in the legal forms for a :rfc:`822`
'From:' header. It's not optional because cataloging systems
can use the e-mail portion of this field as a unique key
representing the author. A catalog might provide authors the

23
pep-0243.txt
View File

@ -34,11 +34,11 @@ Upload Process
==============
The upload will include the Distutils ``PKG-INFO`` meta-data
information (as specified in PEP 241 [1]_), the actual software
information (as specified in :pep:`241`), the actual software
distribution, and other optional information. This information
will be uploaded as a multi-part form encoded the same as a
regular HTML file upload request. This form is posted using
``ENCTYPE="multipart/form-data"`` encoding [2]_.
``ENCTYPE="multipart/form-data"`` encoding (:rfc:`1867`).
The upload will be made to the host "www.python.org" on port
80/tcp (``POST http://www.python.org:80/pypi``). The form
@ -53,7 +53,7 @@ will consist of the following fields:
ord(byte))``).
- ``pkginfo`` (optional) -- The file containing the distribution
meta-data (as specified in PEP 241 [1]_). Note that if this is
meta-data (as specified in :pep:`241`). Note that if this is
not included, the distribution file is expected to be in ``.tar``
format (gzipped and bzipped compressed are allowed) or ``.zip``
format, with a ``PKG-INFO`` file in the top-level directory it
@ -70,7 +70,7 @@ will consist of the following fields:
``<os_name>-<os_version>-<platform architecture>-<python
version>``.
- ``signature`` (optional) -- A OpenPGP-compatible signature [3]_ of
- ``signature`` (optional) -- A :rfc:`OpenPGP-compatible <2440>` signature of
the uploaded distribution as signed by the author. This may
be used by the cataloging system to automate acceptance of
uploads.
@ -161,25 +161,12 @@ Status
I currently have a proof-of-concept client and server implemented.
I plan to have the Distutils patches ready for the 2.1 release.
Combined with Andrew's PEP 241 [1]_ for specifying distribution
Combined with Andrew's :pep:`241` for specifying distribution
meta-data, I hope to have a platform which will allow us to gather
real-world data for finalizing the catalog system for the 2.2
release.
References
==========
.. [1] Metadata for Python Software Package, Kuchling,
http://www.python.org/dev/peps/pep-0241/
.. [2] RFC 1867, Form-based File Upload in HTML
http://www.faqs.org/rfcs/rfc1867.html
.. [3] RFC 2440, OpenPGP Message Format
http://www.faqs.org/rfcs/rfc2440.html
Copyright
=========

27
pep-0244.txt
View File

@ -21,11 +21,11 @@ this is never done capriciously, and is always done with the aim
of improving the language over the long term, over the short term
it's contentious and disrupting.
PEP 1, Guidelines for Language Evolution [1]_ suggests ways to ease
:pep:`5`, Guidelines for Language Evolution suggests ways to ease
the pain, and this PEP introduces some machinery in support of
that.
PEP 2, Statically Nested Scopes [2]_ is the first application, and
:pep:`227`, Statically Nested Scopes is the first application, and
will be used as an example here.
When a new, potentially incompatible language feature is added,
@ -40,7 +40,7 @@ kinds of "settable" language features:
- those that are designed to eventually become the only option, at
which time specifying use of them is not necessary anymore. The
features for which the syntax of the "Back to the ``__future__``"
PEP 236, Back to the ``__future__`` [3]_ was proposed fall into this
:pep:`236`, Back to the ``__future__`` was proposed fall into this
category. This PEP supports declaring such features, and
supports phasing out the "old" meaning of constructs whose
semantics has changed under the new feature. However, it
@ -75,7 +75,7 @@ placed on the directive (e.g. placement of the directive in the
module may be restricted to the top of the module).
In the directive_statement, ``directive`` is a new
keyword. According to [1]_, this keyword is initially considered as
keyword. According to :pep:`5`, this keyword is initially considered as
a keyword only when used in a directive statement, see "Backwards
Compatibility" below.
@ -94,7 +94,7 @@ Specific Directives: transitional
=================================
If a syntactical or semantical change is added to Python which is
incompatible, [1]_ mandates a transitional evolution of the
incompatible, :pep:`5` mandates a transitional evolution of the
language, where the new feature is initially available alongside
with the old one. Such a transition is possible by means of the
transitional directive.
@ -117,7 +117,7 @@ Backwards Compatibility
Introducing ``directive`` as a new keyword might cause
incompatibilities with existing code. Following the guideline in
[1]_, in the initial implementation of this specification,
:pep:`5`, in the initial implementation of this specification,
directive is a new keyword only if it was used in a valid
directive_statement (i.e. if it appeared as the first non-string
token in a module).
@ -147,7 +147,7 @@ allow source code encodings, no specific directive is proposed.
**Q:** Then why was this PEP written at all?
**A:** It acts as a counter-proposal to [3]_, which proposes to
**A:** It acts as a counter-proposal to :pep:`236`, which proposes to
overload the import statement with a new meaning. This PEP
allows to solve the problem in a more general way.
@ -158,19 +158,6 @@ mixing apples and oranges?
"transitional" directive has been defined.
References and Footnotes
========================
.. [1] PEP 5, Guidelines for Language Evolution, Prescod
http://www.python.org/dev/peps/pep-0005/
.. [2] PEP 227, Statically Nested Scopes, Hylton
http://www.python.org/dev/peps/pep-0227/
.. [3] PEP 236, Back to the ``__future__``, Peters
http://www.python.org/dev/peps/pep-0236/
Copyright
=========

30
pep-0245.txt
View File

@ -17,7 +17,7 @@ Rejection Notice
I'm rejecting this PEP. It's been five years now. While at some
point I expect that Python will have interfaces, it would be naive
to expect it to resemble the syntax in this PEP. Also, PEP 246 is
to expect it to resemble the syntax in this PEP. Also, :pep:`246` is
being rejected in favor of something completely different; interfaces
won't play a role in adaptation or whatever will replace it. GvR.
@ -48,10 +48,10 @@ standard software. Zope's Interface package is used as the
reference implementation for this PEP.
The syntax proposed by this PEP relies on syntax enhancements
describe in PEP 232 [3]_ and describes an underlying framework
which PEP 233 [4]_ could be based upon. There is some work being
describe in :pep:`232` and describes an underlying framework
which :pep:`233` could be based upon. There is some work being
done with regard to interface objects and Proxy objects, so for
those optional parts of this PEP you may want to see [5]_.
those optional parts of this PEP you may want to see [3]_.
The Problem
@ -328,7 +328,7 @@ Formal Interface Syntax
=======================
Python syntax is defined in a modified BNF grammar notation
described in the Python Reference Manual [8]_. This section
described in the Python Reference Manual [4]_. This section
describes the proposed interface syntax using this grammar::
interfacedef: "interface" interfacename [extends] ":" suite
@ -437,8 +437,8 @@ defining ``interface`` as a new keyword will introduce. This
extension to Python's syntax does not change any existing syntax
in any backward incompatible way.
The new ``from __future__`` Python syntax [6]_, and the new warning
framework [7]_ is ideal for resolving this backward
The new ``from __future__`` Python syntax (:pep:`236`), and the new warning
framework (:pep:`236`) is ideal for resolving this backward
incompatibility. To use interface syntax now, a developer could
use the statement::
@ -496,21 +496,9 @@ References
.. [2] http://www.zope.org
.. [3] PEP 232, Function Attributes, Warsaw
http://www.python.org/dev/peps/pep-0232/
.. [3] http://www.lemburg.com/files/python/mxProxy.html
.. [4] PEP 233, Python Online Help, Prescod
http://www.python.org/dev/peps/pep-0233/
.. [5] http://www.lemburg.com/files/python/mxProxy.html
.. [6] PEP 236, Back to the __future__, Peters
http://www.python.org/dev/peps/pep-0236/
.. [7] PEP 230, Warning Framework, van Rossum
http://www.python.org/dev/peps/pep-0236/
.. [8] Python Reference Manual
.. [4] Python Reference Manual
http://docs.python.org/reference/

5
pep-0246.txt
View File

@ -61,7 +61,7 @@ intended to leave this proposal compatible with both existing
categories of protocols, such as the existing system of type and
classes, as well as the many concepts for "interfaces" as such
which have been proposed or implemented for Python, such as the
one in PEP 245 [1]_, the one in Zope3 [2]_, or the ones discussed in
one in :pep:`245`, the one in Zope3 [2]_, or the ones discussed in
the BDFL's Artima blog in late 2004 and early 2005 [3]_. However,
some reflections on these subjects, intended to be suggestive and
not normative, are also included.
@ -737,9 +737,6 @@ adaptation of interfaces and protocols in Python.
References and Footnotes
========================
.. [1] PEP 245, Python Interface Syntax, Pelletier
http://www.python.org/dev/peps/pep-0245/
.. [2] http://www.zope.org/Wikis/Interfaces/FrontPage
.. [3] http://www.artima.com/weblogs/index.jsp?blogger=guido

15
pep-0251.txt
View File

@ -54,7 +54,7 @@ every alpha, beta or other release, we forked off a branch which
became the release. Changes to the branch are limited to the
release manager and his designated 'bots. This experiment was
deemed a success and should be observed for future releases. See
PEP 101 for the actual release mechanics [1]_.
:pep:`101` for the actual release mechanics.
New features for Python 2.2
@ -65,19 +65,16 @@ more detailed account, see Misc/NEWS [2]_ in the Python
distribution, or Andrew Kuchling's "What's New in Python 2.2"
document [3]_.
- iterators (PEP 234)
- generators (PEP 255)
- unifying long ints and plain ints (PEP 237)
- division (PEP 238)
- unification of types and classes (PEP 252, PEP 253)
- iterators (:pep:`234`)
- generators (:pep:`255`)
- unifying long ints and plain ints (:pep:`237`)
- division (:pep:`238`)
- unification of types and classes (:pep:`252`, :pep:`253`)
References
==========
.. [1] PEP 101, Doing Python Releases 101
http://www.python.org/dev/peps/pep-0101/
.. [2] Misc/NEWS file from CVS
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/python/dist/src/Misc/NEWS?rev=1.337.2.4&content-type=text/vnd.viewcvs-markup

12
pep-0252.txt
View File

@ -84,7 +84,7 @@ are:
(The last two rules together are often summarized as the
left-to-right, depth-first rule for attribute search. This is the
classic Python attribute lookup rule. Note that PEP 253 will
classic Python attribute lookup rule. Note that :pep:`253` will
propose to change the attribute lookup order, and if accepted,
this PEP will follow suit.)
@ -257,7 +257,7 @@ specific attribute of a given object.
orders. In particular, classic classes use the old
left-to-right depth-first rule, while new-style classes use a
more advanced rule (see the section on method resolution order
in PEP 253).
in :pep:`253`).
When a dynamic attribute (one defined in a regular object's
``__dict__``) has the same name as a static attribute (one defined
@ -466,7 +466,7 @@ explicit first argument. (If you don't understand this, don't
worry, you're not alone.) Note that calling ``cls.foo(y)`` would be a
mistake -- it would cause infinite recursion. Also note that you
can't specify an explicit 'cls' argument to a class method. If
you want this (e.g. the ``__new__`` method in PEP 253 requires this),
you want this (e.g. the ``__new__`` method in :pep:`253` requires this),
use a static method with a class as its explicit first argument
instead.
@ -530,7 +530,7 @@ this situation substantially.
field tells what kind of descriptor it is (method, member, or
getset).
- As explained in PEP 252, descriptors have a ``get()`` method that
- As explained in :pep:`252`, descriptors have a ``get()`` method that
takes an object argument and returns that object's attribute;
descriptors for writable attributes also have a ``set()`` method
that takes an object and a value and set that object's
@ -683,7 +683,7 @@ You can invoke any method from this list directly::
This is just like it is for user-defined classes.
Notice a familiar yet surprising name in the list: ``__init__``. This
is the domain of PEP 253.
is the domain of :pep:`253`.
Backwards compatibility
@ -711,7 +711,7 @@ add the arguments "-r descr-branch" to the cvs checkout command.
here, see the file Lib/test/test_descr.py.
Note: the code in this branch goes way beyond this PEP; it is also
the experimentation area for PEP 253 (Subtyping Built-in Types).
the experimentation area for :pep:`253` (Subtyping Built-in Types).
References

14
pep-0253.txt
View File

@ -67,10 +67,10 @@ This PEP will introduce the following features:
specifying the specific names of the instance variables
supported
This PEP builds on PEP 252, which adds standard introspection to
This PEP builds on :pep:`252`, which adds standard introspection to
types; for example, when a particular type object initializes the
``tp_hash`` slot, that type object has a ``__hash__`` method when
introspected. PEP 252 also adds a dictionary to type objects
introspected. :pep:`252` also adds a dictionary to type objects
which contains all methods. At the Python level, this dictionary
is read-only for built-in types; at the C level, it is accessible
directly (but it should not be modified except as part of
@ -86,9 +86,9 @@ checking of this flag bit. This should be fixed before the final
release.)
In current Python, a distinction is made between types and
classes. This PEP together with PEP 254 will remove that
classes. This PEP together with :pep:`254` will remove that
distinction. However, for backwards compatibility the distinction
will probably remain for years to come, and without PEP 254, the
will probably remain for years to come, and without :pep:`254`, the
distinction is still large: types ultimately have a built-in type
as a base class, while classes ultimately derive from a
user-defined class. Therefore, in the rest of this PEP, I will
@ -550,7 +550,7 @@ Assume B is a type object. Since type objects are objects, and
every object has a type, B has a type. Since B is itself a type,
we also call its type its metatype. B's metatype is accessible
via ``type(B)`` or ``B.__class__`` (the latter notation is new for types;
it is introduced in PEP 252). Let's say this metatype is M (for
it is introduced in :pep:`252`). Let's say this metatype is M (for
Metatype). The class statement will create a new type, C. Since
C will be a type object just like B, we view the creation of C as
an instantiation of the metatype, M. The information that needs
@ -902,7 +902,7 @@ Additional topics to be discussed in this PEP:
- cooperative methods and ``super()``
- mapping between type object slots (tp_foo) and special methods
(``__foo__``) (actually, this may belong in PEP 252)
(``__foo__``) (actually, this may belong in :pep:`252`)
- built-in names for built-in types (object, int, str, list etc.)
@ -942,7 +942,7 @@ open issues
Implementation
==============
A prototype implementation of this PEP (and for PEP 252) is
A prototype implementation of this PEP (and for :pep:`252`) is
available from CVS, and in the series of Python 2.2 alpha and beta
releases. For some examples of the features described here, see
the file Lib/test/test_descr.py and the extension module

42
pep-0255.txt
View File

@ -51,7 +51,8 @@ only want to see whether something specific appears early in the program (e.g.,
a future statement, or, as is done in IDLE, just the first indented statement),
and then parsing the whole program first is a severe waste of time.
Another alternative would be to make tokenize an iterator [1], delivering the
Another alternative would be to make tokenize an :pep:`iterator <234>`,
delivering the
next token whenever its ``.next()`` method is invoked. This is pleasant for the
caller in the same way a large list of results would be, but without the memory
and "what if I want to get out early?" drawbacks. However, this shifts the
@ -69,7 +70,7 @@ provides a usable synchronized-communication class for doing that in a general
way. This doesn't work on platforms without threads, though, and is very slow
on platforms that do (compared to what is achievable without threads).
A final option is to use the Stackless [2] [3] variant implementation of Python
A final option is to use the Stackless [1]_ (:pep:`219`) variant implementation of Python
instead, which supports lightweight coroutines. This has much the same
programmatic benefits as the thread option, but is much more efficient.
However, Stackless is a controversial rethinking of the Python core, and it may
@ -80,8 +81,8 @@ current CPython implementation, and is believed to be relatively
straightforward for other Python implementations.
That exhausts the current alternatives. Some other high-level languages
provide pleasant solutions, notably iterators in Sather [4], which were
inspired by iterators in CLU; and generators in Icon [5], a novel language
provide pleasant solutions, notably iterators in Sather [2]_, which were
inspired by iterators in CLU; and generators in Icon [3]_, a novel language
where every expression *is a generator*. There are differences among these,
but the basic idea is the same: provide a kind of function that can return an
intermediate result ("the next value") to its caller, but maintaining the
@ -111,7 +112,7 @@ The same kind of approach applies to many producer/consumer functions. For
example, ``tokenize.py`` could yield the next token instead of invoking a
callback function with it as argument, and tokenize clients could iterate over
the tokens in a natural way: a Python generator is a kind of Python
iterator [1]_, but of an especially powerful kind.
:pep:`iterator <234>`, but of an especially powerful kind.
Specification: Yield
@ -121,13 +122,13 @@ A new statement is introduced::
yield_stmt: "yield" expression_list
``yield`` is a new keyword, so a ``future`` statement [8]_ is needed to phase
``yield`` is a new keyword, so a ``future`` statement (:pep:`236`) is needed to phase
this in: in the initial release, a module desiring to use generators must
include the line::
from __future__ import generators
near the top (see PEP 236 [8]_) for details). Modules using the identifier
near the top (see :pep:`236`) for details). Modules using the identifier
``yield`` without a ``future`` statement will trigger warnings. In the
following release, ``yield`` will be a language keyword and the ``future``
statement will no longer be needed.
@ -140,7 +141,7 @@ function is an ordinary function object in all respects, but has the new
When a generator function is called, the actual arguments are bound to
function-local formal argument names in the usual way, but no code in the body
of the function is executed. Instead a generator-iterator object is returned;
this conforms to the iterator protocol [6]_, so in particular can be used in
this conforms to the :pep:`iterator protocol <234>`, so in particular can be used in
for-loops in a natural way. Note that when the intent is clear from context,
the unqualified name "generator" may be used to refer either to a
generator-function or a generator-iterator.
@ -474,37 +475,26 @@ Reference Implementation
========================
The current implementation, in a preliminary state (no docs, but well tested
and solid), is part of Python's CVS development tree [9]_. Using this requires
and solid), is part of Python's CVS development tree [5]_. Using this requires
that you build Python from source.
This was derived from an earlier patch by Neil Schemenauer [7]_.
This was derived from an earlier patch by Neil Schemenauer [4]_.
Footnotes and References
========================
.. [1] PEP 234, Iterators, Yee, Van Rossum
http://www.python.org/dev/peps/pep-0234/
.. [1] http://www.stackless.com/
.. [2] http://www.stackless.com/
.. [3] PEP 219, Stackless Python, McMillan
http://www.python.org/dev/peps/pep-0219/
.. [4] "Iteration Abstraction in Sather"
.. [2] "Iteration Abstraction in Sather"
Murer, Omohundro, Stoutamire and Szyperski
http://www.icsi.berkeley.edu/~sather/Publications/toplas.html
.. [5] http://www.cs.arizona.edu/icon/
.. [3] http://www.cs.arizona.edu/icon/
.. [6] The concept of iterators is described in PEP 234. See [1] above.
.. [4] http://python.ca/nas/python/generator.diff
.. [7] http://python.ca/nas/python/generator.diff
.. [8] PEP 236, Back to the __future__, Peters
http://www.python.org/dev/peps/pep-0236/
.. [9] To experiment with this implementation, check out Python from CVS
.. [5] To experiment with this implementation, check out Python from CVS
according to the instructions at http://sf.net/cvs/?group_id=5470
Note that the std test ``Lib/test/test_generators.py`` contains many
examples, including all those in this PEP.

29
pep-0256.txt
View File

@ -48,27 +48,27 @@ have broken up the issues in order to deal with each of them in
isolation, or as close as possible. The individual aspects and
associated PEPs are as follows:
* Docstring syntax. PEP 287, "reStructuredText Docstring Format"
[#PEP-287]_, proposes a syntax for Python docstrings, PEPs, and
* Docstring syntax. :pep:`287`, "reStructuredText Docstring Format",
proposes a syntax for Python docstrings, PEPs, and
other uses.
* Docstring semantics consist of at least two aspects:
- Conventions: the high-level structure of docstrings. Dealt with
in PEP 257, "Docstring Conventions" [#PEP-257]_.
in :pep:`257`, "Docstring Conventions".
- Methodology: rules for the informational content of docstrings.
Not addressed.
* Processing mechanisms. This PEP (PEP 256) outlines the high-level
* Processing mechanisms. This PEP (:pep:`256`) outlines the high-level
issues and specification of an abstract docstring processing system
(DPS). PEP 258, "Docutils Design Specification" [#PEP-258]_, is an
(DPS). :pep:`258`, "Docutils Design Specification", is an
overview of the design and implementation of one DPS under
development.
* Output styles: developers want the documentation generated from
their source code to look good, and there are many different ideas
about what that means. PEP 258 touches on "Stylist Transforms".
about what that means. :pep:`258` touches on "Stylist Transforms".
This aspect of docstring processing has yet to be fully explored.
By separating out the issues, we can form consensus more easily
@ -149,7 +149,7 @@ deficiencies, including:
There are security issues involved with importing untrusted code.
Also, information from the source is lost when importing, such as
comments, "additional docstrings" (string literals in non-docstring
contexts; see PEP 258 [#PEP-258]_), and the order of definitions.
contexts; see :pep:`258`), and the order of definitions.
The functionality proposed in this PEP could be added to or used by
PyDoc when serving HTML pages. The proposed docstring processing
@ -177,7 +177,7 @@ The docstring processing system framework is broken up as follows:
- First line is a one-line synopsis.
PEP 257 [#PEP-257]_ documents some of these issues.
:pep:`257` documents some of these issues.
2. Docstring processing system design specification. Documents
issues such as:
@ -206,11 +206,11 @@ The docstring processing system framework is broken up as follows:
files, or objects in memory).
These issues are applicable to any docstring processing system
implementation. PEP 258 [#PEP-258]_ documents these issues.
implementation. :pep:`258` documents these issues.
3. Docstring processing system implementation.
4. Input markup specifications: docstring syntax. PEP 287 [#PEP-287]_
4. Input markup specifications: docstring syntax. :pep:`287`
proposes a standard syntax.
5. Input parser implementations.
@ -241,15 +241,6 @@ http://docutils.sourceforge.net/.
References and Footnotes
========================
.. [#PEP-287] PEP 287, reStructuredText Docstring Format, Goodger
(http://www.python.org/dev/peps/pep-0287/)
.. [#PEP-257] PEP 257, Docstring Conventions, Goodger, Van Rossum
(http://www.python.org/dev/peps/pep-0257/)
.. [#PEP-258] PEP 258, Docutils Design Specification, Goodger
(http://www.python.org/dev/peps/pep-0258/)
.. _Literate Programming: http://www.literateprogramming.com/
.. _POD: http://www.perldoc.com/perl5.6/pod/perlpod.html

17
pep-0257.txt
View File

@ -36,7 +36,7 @@ conventions, not laws or syntax.
If you violate these conventions, the worst you'll get is some dirty
looks. But some software (such as the Docutils_ docstring processing
system [1]_ [2]_) will be aware of the conventions, so following them
system :pep:`256`, :pep:`258`) will be aware of the conventions, so following them
will get you the best results.
@ -69,7 +69,7 @@ extracted by software tools:
2. String literals occurring immediately after another docstring are
called "additional docstrings".
Please see PEP 258, "Docutils Design Specification" [2]_, for a
Please see :pep:`258`, "Docutils Design Specification", for a
detailed description of attribute and additional docstrings.
For consistency, always use ``"""triple double quotes"""`` around
@ -276,17 +276,8 @@ Once trimmed, these docstrings are equivalent::
References and Footnotes
========================
.. [1] PEP 256, Docstring Processing System Framework, Goodger
(http://www.python.org/dev/peps/pep-0256/)
.. [2] PEP 258, Docutils Design Specification, Goodger
(http://www.python.org/dev/peps/pep-0258/)
.. _Docutils: http://docutils.sourceforge.net/
.. _Python Style Guide:
http://www.python.org/dev/peps/pep-0008/
.. _Doc-SIG: http://www.python.org/sigs/doc-sig/
@ -299,8 +290,8 @@ This document has been placed in the public domain.
Acknowledgements
================
The "Specification" text comes mostly verbatim from the `Python Style
Guide`_ essay by Guido van Rossum.
The "Specification" text comes mostly verbatim from :pep:`8`
by Guido van Rossum.
This document borrows ideas from the archives of the Python Doc-SIG_.
Thanks to all members past and present.

29
pep-0258.txt
View File

@ -27,8 +27,8 @@ standard library.
This PEP documents design issues and implementation details for
Docutils, a Python Docstring Processing System (DPS). The rationale
and high-level concepts of a DPS are documented in PEP 256, "Docstring
Processing System Framework" [#PEP-256]_. Also see PEP 256 for a
and high-level concepts of a DPS are documented in :pep:`256`, "Docstring
Processing System Framework". Also see :pep:`256` for a
"Road Map to the Docstring PEPs".
Docutils is being designed modularly so that any of its components can
@ -142,11 +142,11 @@ Examples:
* Python Source: See `Python Source Reader`_ below. This Reader is
currently in development in the Docutils sandbox.
* Email: RFC-822 headers, quoted excerpts, signatures, MIME parts.
* Email: :rfc:`822` headers, quoted excerpts, signatures, MIME parts.
* PEP: RFC-822 headers, "PEP xxxx" and "RFC xxxx" conversion to URIs.
* PEP: :rfc:`822` headers, "PEP xxxx" and "RFC xxxx" conversion to URIs.
The "PEP Reader" has been implemented in module
``docutils.readers.pep``; see PEP 287 and PEP 12.
``docutils.readers.pep``; see :pep:`287` and :pep:`12`.
* Wiki: Global reference lookups of "wiki links" incorporated into
transforms. (CamelCase only or unrestricted?) Lazy
@ -711,7 +711,7 @@ slight performance hit.
Attribute Docstrings
''''''''''''''''''''
(This is a simplified version of PEP 224 [#PEP-224]_.)
(This is a simplified version of :pep:`224`.)
A string literal immediately following an assignment statement is
interpreted by the docstring extraction machinery as the docstring of
@ -787,7 +787,7 @@ Examples::
Additional Docstrings
'''''''''''''''''''''
(This idea was adapted from PEP 216 [#PEP-216]_.)
(This idea was adapted from :pep:`216`.)
Many programmers would like to make extensive use of docstrings for
API documentation. However, docstrings do take up space in the
@ -865,10 +865,10 @@ established.
The ``__docformat__`` string may contain an optional second field,
separated from the format name (first field) by a single space: a
case-insensitive language identifier as defined in RFC 1766. A
case-insensitive language identifier as defined in :rfc:`1766`. A
typical language identifier consists of a 2-letter language code from
`ISO 639`_ (3-letter codes used only if no 2-letter code exists; RFC
1766 is currently being revised to allow 3-letter codes). If no
`ISO 639`_ (3-letter codes used only if no 2-letter code exists;
:rfc:`1766` is currently being revised to allow 3-letter codes). If no
language identifier is specified, the default is "en" for English.
The language identifier is passed to the parser and can be used for
language-dependent markup features.
@ -950,15 +950,6 @@ stylist code will lower the barrier considerably.
References and Footnotes
==========================
.. [#PEP-256] PEP 256, Docstring Processing System Framework, Goodger
(http://www.python.org/dev/peps/pep-0256/)
.. [#PEP-224] PEP 224, Attribute Docstrings, Lemburg
(http://www.python.org/dev/peps/pep-0224/)
.. [#PEP-216] PEP 216, Docstring Format, Zadka
(http://www.python.org/dev/peps/pep-0216/)
.. _docutils.dtd:
http://docutils.sourceforge.net/docs/ref/docutils.dtd

2
pep-0261.txt
View File

@ -201,7 +201,7 @@ There is a new configure option:
===================== ============================================
--enable-unicode=ucs2 configures a narrow ``Py_UNICODE``, and uses
wchar_t if it fits
--enable-unicode=ucs4 configures a wide `Py_UNICODE``, and uses
--enable-unicode=ucs4 configures a wide ``Py_UNICODE``, and uses
wchar_t if it fits
--enable-unicode same as "=ucs2"
--disable-unicode entirely remove the Unicode functionality.

4
pep-0262.txt
View File

@ -88,8 +88,8 @@ Each section of the file is used for a different purpose.
PKG-INFO section
----------------
An initial set of RFC-822 headers containing the distribution
information for a file, as described in PEP 241, "Metadata for
An initial set of :rfc:`822` headers containing the distribution
information for a file, as described in :pep:`241`, "Metadata for
Python Software Packages".
FILES section

4
pep-0264.txt
View File

@ -15,13 +15,13 @@ Post-History: 30-Jul-2001
Abstract
========
As noted in PEP 236, there is no clear way for "simulated
As noted in :pep:`236`, there is no clear way for "simulated
interactive shells" to simulate the behaviour of ``__future__``
statements in "real" interactive shells, i.e. have ``__future__``
statements' effects last the life of the shell.
The PEP also takes the opportunity to clean up the other
unresolved issue mentioned in PEP 236, the inability to stop
unresolved issue mentioned in :pep:`236`, the inability to stop
``compile()`` inheriting the effect of future statements affecting the
code calling ``compile()``.

4
pep-0267.txt
View File

@ -15,7 +15,7 @@ Deferral
========
While this PEP is a nice idea, no-one has yet emerged to do the work of
hashing out the differences between this PEP, PEP 266 and PEP 280.
hashing out the differences between this PEP, :pep:`266` and :pep:`280`.
Hence, it is being deferred.
@ -258,7 +258,7 @@ implementation could provide warnings.
Related PEPs
============
PEP 266, Optimizing Global Variable/Attribute Access, proposes a
:pep:`266`, Optimizing Global Variable/Attribute Access, proposes a
different mechanism for optimizing access to global variables as
well as attributes of objects. The mechanism uses two new opcodes
``TRACK_OBJECT`` and ``UNTRACK_OBJECT`` to create a slot in the local

10
pep-0268.txt
View File

@ -30,8 +30,8 @@ Rationale
=========
Python has been quite popular as a result of its "batteries included"
positioning. One of the most heavily used protocols, HTTP (see RFC
2616), has been included with Python for years (``httplib``). However,
positioning. One of the most heavily used protocols, HTTP (see
:rfc:`2616`), has been included with Python for years (``httplib``). However,
this support has not kept up with the full needs and requirements of
many HTTP-based applications and systems. In addition, new protocols
based on HTTP, such as WebDAV and XML-RPC, are becoming useful and are
@ -79,7 +79,7 @@ The mixin will delegate the authentication process to one or more
"authenticator" objects, allowing multiple connections to share
authenticators. The use of a separate object allows for a long term
connection to an authentication system (e.g. LDAP). An authenticator
for the Basic and Digest mechanisms (see RFC 2617) will be
for the Basic and Digest mechanisms (see :rfc:`2617`) will be
provided. User-supplied authenticator subclasses can be registered and
used by the connections.
@ -118,7 +118,7 @@ cached (into the Credentials object; see below), the caller can simply
regenerate the request. The mixin will attach the appropriate
credentials.
A "protection space" (see RFC 2617, section 1.2) is defined as a tuple
A "protection space" (see :rfc:`2617`, section 1.2) is defined as a tuple
of the host, port, and authentication realm. When a request is
initially sent to an HTTP server, we do not know the authentication
realm (the realm is only returned when authentication fails). However,
@ -180,7 +180,7 @@ classes (the mixin may possibly work with the HTTP and HTTPS
compatibility classes, but that is not a requirement).
The mixin provides methods to perform the various HTTP methods defined
by HTTP in RFC 2616, and by WebDAV in RFC 2518.
by HTTP in :rfc:`2616`, and by WebDAV in :rfc:`2518`.
A custom response object is used to decode ``207 (Multi-Status)``
responses. The response object will use the standard library's xml

3
pep-0269.txt
View File

@ -198,8 +198,7 @@ References
.. [3] Hylton, Jeremy.
http://docs.python.org/library/compiler.html
.. [4] Pelletier, Michel. "Python Interface Syntax", PEP-245.
http://www.python.org/dev/peps/pep-0245/
.. [4] Pelletier, Michel. "Python Interface Syntax", :pep:`245`
.. [5] The Python Types-SIG
http://www.python.org/sigs/types-sig/

2
pep-0270.txt
View File

@ -25,7 +25,7 @@ This PEP is withdrawn by the author. He writes:
a matter of choosing a different data structure: a set instead
of a list.
As described in PEP 218, sets are being added to the standard
As described in :pep:`218`, sets are being added to the standard
library for Python 2.3.

5
pep-0272.txt
View File

@ -47,7 +47,7 @@ SP 800-38A [1]_. Descriptions of the first three feedback modes can
also be found in Bruce Schneier's book *Applied Cryptography* [2]_.
(The numeric value 4 is reserved for MODE_PGP, a variant of CFB
described in RFC 2440: "OpenPGP Message Format" [3]_. This mode
described in :rfc:`2440`: "OpenPGP Message Format". This mode
isn't considered important enough to make it worth requiring it
for all block encryption ciphers, though supporting it is a nice
extra feature.)
@ -209,9 +209,6 @@ References
.. [2] Applied Cryptography
.. [3] RFC2440: "OpenPGP Message Format" (http://rfc2440.x42.com,
http://www.faqs.org/rfcs/rfc2440.html)
Changes
=======

6
pep-0273.txt
View File

@ -26,7 +26,7 @@ Note
Zip imports were added to Python 2.3, but the final implementation
uses an approach different from the one described in this PEP.
The 2.3 implementation is SourceForge patch #652586 [1]_, which adds
new import hooks described in PEP 302.
new import hooks described in :pep:`302`.
The rest of this PEP is therefore only of historical interest.
@ -210,8 +210,8 @@ A newer version (updated for recent CVS by Paul Moore) is 645650.
Superseded by patch 652586 and current CVS. [3]_
A competing implementation by Just van Rossum is 652586, which is
the basis for the final implementation of PEP 302. PEP 273 has
been implemented using PEP 302's import hooks. [1]_
the basis for the final implementation of :pep:`302`. :pep:`273` has
been implemented using :pep:`302`'s import hooks. [1]_
References

2
pep-0274.txt
View File

@ -14,7 +14,7 @@ Post-History: 29-Oct-2001
Abstract
========
PEP 202 introduces a syntactical extension to Python called the
:pep:`202` introduces a syntactical extension to Python called the
"list comprehension". This PEP proposes a similar syntactical
extension called the "dictionary comprehension" or "dict
comprehension" for short. You can use dict comprehensions in ways

4
pep-0275.txt
View File

@ -13,7 +13,7 @@ Post-History:
Rejection Notice
================
A similar PEP for Python 3000, PEP 3103 [2]_, was already rejected,
A similar PEP for Python 3000, :pep:`3103`, was already rejected,
so this proposal has no chance of being accepted either.
Abstract
@ -353,8 +353,6 @@ References
.. [1] https://sourceforge.net/tracker/index.php?func=detail&aid=481118&group_id=5470&atid=305470
.. [2] http://www.python.org/dev/peps/pep-3103
Copyright
=========

29
pep-0276.txt
View File

@ -14,7 +14,7 @@ Post-History:
Abstract
========
Python 2.1 added new functionality to support iterators [1]_.
Python 2.1 added new functionality to support iterators (:pep:`234`).
Iterators have proven to be useful and convenient in many coding
situations. It is noted that the implementation of Python's
for-loop control structure uses the iterator protocol as of
@ -152,7 +152,7 @@ idiom is:
And from time to time proposals are put forth for ways in which
Python could provide a better mechanism for this idiom. Recent
examples include PEP 204, "Range Literals", and PEP 212, "Loop
examples include :pep:`204`, "Range Literals", and :pep:`212`, "Loop
Counter Iteration".
Most often, such proposal include changes to Python's syntax and
@ -263,13 +263,13 @@ Tim Peters has pointed out two such examples:
Issues
======
Extensive discussions concerning PEP 276 on the Python interest
Extensive discussions concerning :pep:`276` on the Python interest
mailing list suggests a range of opinions: some in favor, some
neutral, some against. Those in favor tend to agree with the
claims above of the usefulness, convenience, ease of learning,
and simplicity of a simple iterator for integers.
Issues with PEP 276 include:
Issues with :pep:`276` include:
- Using range/xrange is fine as is.
@ -325,7 +325,7 @@ Issues with PEP 276 include:
noted above is an a case in point.
Response: From the author's perspective the examples of the
above that were identified in the PEP 276 discussions did
above that were identified in the :pep:`276` discussions did
not appear to be ones that would be accidentally misused
in ways that would lead to subtle and hard-to-detect errors.
@ -376,7 +376,7 @@ Issues with PEP 276 include:
- Why not propose even bigger changes?
The majority of disagreement with PEP 276 came from those who
The majority of disagreement with :pep:`276` came from those who
favor much larger changes to Python to address the more general
problem of specifying a sequence of integers where such
a specification is general enough to handle the starting value,
@ -403,10 +403,10 @@ These include:
It should be noted that there was much debate but not an
overwhelming consensus for any of these larger-scale suggestions.
Clearly, PEP 276 does not propose such a large-scale change
Clearly, :pep:`276` does not propose such a large-scale change
and instead focuses on a specific problem area. Towards the
end of the discussion period, several posters expressed favor
for the narrow focus and simplicity of PEP 276 vis-a-vis the more
for the narrow focus and simplicity of :pep:`276` vis-a-vis the more
ambitious suggestions that were advanced. There did appear to be
consensus for the need for a PEP for any such larger-scale,
alternative suggestion. In light of this recognition, details of
@ -422,19 +422,6 @@ int with an ``__iter__`` method (written in Python) as a means to test
out the ideas in this proposal, however.
References
==========
.. [1] PEP 234, Iterators
http://www.python.org/dev/peps/pep-0234/
.. [2] PEP 204, Range Literals
http://www.python.org/dev/peps/pep-0204/
.. [3] PEP 212, Loop Counter Iteration
http://www.python.org/dev/peps/pep-0212/
Copyright
=========

23
pep-0279.txt
View File

@ -24,17 +24,17 @@ Rationale
=========
Python 2.2 introduced the concept of an iterable interface as
proposed in PEP 234 [3]_. The ``iter()`` factory function was provided
proposed in :pep:`234`. The ``iter()`` factory function was provided
as common calling convention and deep changes were made to use
iterators as a unifying theme throughout Python. The unification
came in the form of establishing a common iterable interface for
mappings, sequences, and file objects.
Generators, as proposed in PEP 255 [1]_, were introduced as a means
Generators, as proposed in :pep:`255`, were introduced as a means
for making it easier to create iterators, especially ones with
complex internal execution or variable states. The availability
of generators makes it possible to improve on the loop counter
ideas in PEP 212 [2]_. Those ideas provided a clean syntax for
ideas in :pep:`212`. Those ideas provided a clean syntax for
iteration with indices and values, but did not apply to all
iterable objects. Also, that approach did not have the memory
friendly benefit provided by generators which do not evaluate the
@ -73,13 +73,13 @@ Specification for a new built-in
yield (i, it.next())
i += 1
Note A: PEP 212 Loop Counter Iteration [2]_ discussed several
Note A: :pep:`212` Loop Counter Iteration discussed several
proposals for achieving indexing. Some of the proposals only work
for lists unlike the above function which works for any generator,
xrange, sequence, or iterable object. Also, those proposals were
presented and evaluated in the world prior to Python 2.2 which did
not include generators. As a result, the non-generator version in
PEP 212 had the disadvantage of consuming memory with a giant list
:pep:`212` had the disadvantage of consuming memory with a giant list
of tuples. The generator version presented here is fast and
light, works with all iterables, and allows users to abandon the
sequence in mid-stream with no loss of computation effort.
@ -197,19 +197,6 @@ Author response:
the ``itertools`` module.
References
==========
.. [1] PEP 255 Simple Generators
http://www.python.org/dev/peps/pep-0255/
.. [2] PEP 212 Loop Counter Iteration
http://www.python.org/dev/peps/pep-0212/
.. [3] PEP 234 Iterators
http://www.python.org/dev/peps/pep-0234/
Copyright
=========

6
pep-0280.txt
View File

@ -15,7 +15,7 @@ Deferral
========
While this PEP is a nice idea, no-one has yet emerged to do the work of
hashing out the differences between this PEP, PEP 266 and PEP 267.
hashing out the differences between this PEP, :pep:`266` and :pep:`267`.
Hence, it is being deferred.
@ -23,8 +23,8 @@ Abstract
========
This PEP describes yet another approach to optimizing access to
module globals, providing an alternative to PEP 266 (Optimizing
Global Variable/Attribute Access by Skip Montanaro) and PEP 267
module globals, providing an alternative to :pep:`266` (Optimizing
Global Variable/Attribute Access by Skip Montanaro) and :pep:`267`
(Optimized Access to Module Namespaces by Jeremy Hylton).
The expectation is that eventually one approach will be picked and

17
pep-0281.txt
View File

@ -16,16 +16,16 @@ Abstract
This PEP describes yet another way of exposing the loop counter in
for-loops. It basically proposes that the functionality of the
function ``indices()`` from PEP 212 [1]_ be included in the existing
function ``indices()`` from :pep:`212` be included in the existing
functions ``range()`` and ``xrange()``.
Pronouncement
=============
In commenting on PEP 279's ``enumerate()`` function, this PEP's author
offered, "I'm quite happy to have it make PEP 281 obsolete."
Subsequently, PEP 279 was accepted into Python 2.3.
In commenting on :pep:`279`'s ``enumerate()`` function, this PEP's author
offered, "I'm quite happy to have it make :pep:`281` obsolete."
Subsequently, :pep:`279` was accepted into Python 2.3.
On 17 June 2005, the BDFL concurred with it being obsolete and
hereby rejected the PEP. For the record, he found some of the
@ -116,7 +116,7 @@ Example::
print num # The line itself is not accessible
A more controversial alternative (to deal with this) would be to
let ``range()`` behave like the function ``irange()`` of PEP 212 when
let ``range()`` behave like the function ``irange()`` of :pep:`212` when
supplied with a sequence.
Example::
@ -136,13 +136,6 @@ the case of lazy iteration with ``xrange``). The author does not
believe that this is a significant problem.
References and Footnotes
========================
.. [1] PEP 212, Loop Counter Iteration
http://www.python.org/dev/peps/pep-0212/
Copyright
=========

38
pep-0283.txt
View File

@ -50,13 +50,13 @@ for more, and of course ``Misc/NEWS`` for the full list.
- Tk 8.4 update.
- The ``bool`` type and its constants, ``True`` and ``False`` (PEP 285).
- The ``bool`` type and its constants, ``True`` and ``False`` (:pep:`285`).
- ``PyMalloc`` was greatly enhanced and is enabled by default.
- Universal newline support (PEP 278).
- Universal newline support (:pep:`278`).
- PEP 263 Defining Python Source Code Encodings, Lemburg
- :pep:`263` Defining Python Source Code Encodings, Lemburg
Implemented (at least phase 1, which is all that's planned for
2.3).
@ -70,7 +70,7 @@ for more, and of course ``Misc/NEWS`` for the full list.
- Timeout sockets. https://bugs.python.org/issue555085
- Stage B0 of the ``int``/``long`` integration (PEP 237). This means
- Stage B0 of the ``int``/``long`` integration (:pep:`237`). This means
issuing a ``FutureWarning`` about situations where ``hex`` or ``oct``
conversions or left shifts returns a different value for an ``int``
than for a ``long`` with the same value. The semantics do *not*
@ -96,7 +96,7 @@ for more, and of course ``Misc/NEWS`` for the full list.
- Warn for assignment to ``None`` (in various forms).
- PEP 218 Adding a Built-In Set Object Type, Wilson
- :pep:`218` Adding a Built-In Set Object Type, Wilson
Alex Martelli contributed a new version of Greg Wilson's
prototype, and I've reworked that quite a bit. It's in the
@ -104,12 +104,12 @@ for more, and of course ``Misc/NEWS`` for the full list.
may still change until the first beta release. (There are no
plans to make this a built-in type, for now.)
- PEP 293 Codec error handling callbacks, Dörwald
- :pep:`293` Codec error handling callbacks, Dörwald
Fully implemented. Error handling in ``unicode.encode`` or
``str.decode`` can now be customized.
- PEP 282 A Logging System, Mick
- :pep:`282` A Logging System, Mick
Vinay Sajip's implementation has been packagized and imported.
(Documentation and unit tests still pending.)
@ -130,23 +130,23 @@ for more, and of course ``Misc/NEWS`` for the full list.
prototype was coded in ``nondist/sandbox/datetime/``. Tim Peters
has finished the C implementation and checked it in.
- PEP 273 Import Modules from Zip Archives, Ahlstrom
- :pep:`273` Import Modules from Zip Archives, Ahlstrom
Implemented as a part of the PEP 302 implementation work.
Implemented as a part of the :pep:`302` implementation work.
- PEP 302 New Import Hooks, JvR
- :pep:`302` New Import Hooks, JvR
Implemented (though the 2.3a1 release contained some bugs that
have been fixed post-release).
- A new pickling protocol. See PEP 307.
- A new pickling protocol. See :pep:`307`.
- PEP 305 (CSV File API, by Skip Montanaro et al.) is in; this is
- :pep:`305` (CSV File API, by Skip Montanaro et al.) is in; this is
the csv module.
- Raymond Hettinger's ``itertools`` module is in.
- PEP 311 (Simplified GIL Acquisition for Extensions, by Mark
- :pep:`311` (Simplified GIL Acquisition for Extensions, by Mark
Hammond) has been included in beta 1.
- Two new ``PyArg_Parse*()`` format codes, 'k' returns an unsigned C
@ -236,7 +236,7 @@ Features that did not make it into Python 2.3
I believe this is dead now.
- PEP 304 (Controlling Generation of Bytecode Files by Montanaro)
- :pep:`304` (Controlling Generation of Bytecode Files by Montanaro)
seems to have lost steam.
- For a class defined inside another class, the ``__name__`` should be
@ -272,7 +272,7 @@ Features that did not make it into Python 2.3
It seems that this is never going to be resolved.
- PEP 269 Pgen Module for Python, Riehl
- :pep:`269` Pgen Module for Python, Riehl
(Some necessary changes are in; the ``pgen`` module itself needs to
mature more.)
@ -283,11 +283,11 @@ Features that did not make it into Python 2.3
to champion it. (Some changes to distutils to support this are
in, at least.)
- PEP 266 Optimizing Global Variable/Attribute Access, Montanaro
- :pep:`266` Optimizing Global Variable/Attribute Access, Montanaro
PEP 267 Optimized Access to Module Namespaces, Hylton
:pep:`267` Optimized Access to Module Namespaces, Hylton
PEP 280 Optimizing access to globals, van Rossum
:pep:`280` Optimizing access to globals, van Rossum
These are basically three friendly competing proposals. Jeremy
has made a little progress with a new compiler, but it's going
@ -305,7 +305,7 @@ Features that did not make it into Python 2.3
Not much enthusiasm I believe.
- PEP 286 Enhanced Argument Tuples, von Loewis
- :pep:`286` Enhanced Argument Tuples, von Loewis
I haven't had the time to review this thoroughly. It seems a
deep optimization hack (also makes better correctness guarantees

32
pep-0284.txt
View File

@ -35,7 +35,7 @@ Pronouncement
This PEP is rejected. There were a number of fixable issues with
the proposal (see the fixups listed in Raymond Hettinger's
python-dev post on 18 June 2005 [5]_). However, even with the fixups the
python-dev post on 18 June 2005 [1]_). However, even with the fixups the
proposal did not garner support. Specifically, Guido did not buy
the premise that the ``range()`` format needed fixing, "The whole point
(15 years ago) of ``range()`` was to *avoid* needing syntax to specify a
@ -59,21 +59,21 @@ code that uses ``range()`` or ``xrange()``.
The perceived lack of a natural, intuitive integer iteration
syntax has led to heated debate on python-list, and spawned at
least four PEPs before this one. PEP 204 [1]_ (rejected) proposed
least four PEPs before this one. :pep:`204` (rejected) proposed
to re-use Python's slice syntax for integer ranges, leading to a
terser syntax but not solving the readability problem of
multi-argument ``range()``. PEP 212 [2]_ (deferred) proposed several
multi-argument ``range()``. :pep:`212` (deferred) proposed several
syntaxes for directly converting a list to a sequence of integer
indices, in place of the current idiom ::
range(len(list))
for such conversion, and PEP 281 [3]_ proposes to simplify the same
for such conversion, and :pep:`281` proposes to simplify the same
idiom by allowing it to be written as ::
range(list).
PEP 276 [4]_ proposes to allow automatic conversion of integers to
:pep:`276` proposes to allow automatic conversion of integers to
iterators, simplifying the most common half-open case but not
addressing the complexities of other types of interval.
Additional alternatives have been discussed on python-list.
@ -213,13 +213,13 @@ proposals on the Python list.
this loss is outweighed by the increase in readability from a
natural integer iteration syntax.
- To some extent, this PEP addresses the same issues as PEP 276
[4]_. We feel that the two PEPs are not in conflict since PEP
276 is primarily concerned with half-open ranges starting in 0
- To some extent, this PEP addresses the same issues as :pep:`276`.
We feel that the two PEPs are not in conflict since :pep:`276`
is primarily concerned with half-open ranges starting in 0
(the easy case of ``range()``) while this PEP is primarily concerned
with simplifying all other cases. However, if this PEP is
approved, its new simpler syntax for integer loops could to some
extent reduce the motivation for PEP 276.
extent reduce the motivation for :pep:`276`.
- It is not clear whether it makes sense to allow floating point
bounds for an integer loop: if a float represents an inexact
@ -256,19 +256,7 @@ into a loop over the items in a special iterator object.
References
==========
.. [1] PEP 204, Range Literals
http://www.python.org/dev/peps/pep-0204/
.. [2] PEP 212, Loop Counter Iteration
http://www.python.org/dev/peps/pep-0212/
.. [3] PEP 281, Loop Counter Iteration with range and xrange
http://www.python.org/dev/peps/pep-0281/
.. [4] PEP 276, Simple Iterator for ints
http://www.python.org/dev/peps/pep-0276/
.. [5] Raymond Hettinger, Propose updating PEP 284 -- Integer for-loops
.. [1] Raymond Hettinger, Propose updating PEP 284 -- Integer for-loops
https://mail.python.org/pipermail/python-dev/2005-June/054316.html

2
pep-0286.txt
View File

@ -28,7 +28,7 @@ PEP and collecting and incorporating feedback, and with sufficient
available time to do so effectively.
The resolution of this PEP may also be affected by the resolution of
PEP 426, which proposes the use of a preprocessing step to generate
:pep:`426`, which proposes the use of a preprocessing step to generate
some aspects of C API interface code.

32
pep-0287.txt
View File

@ -25,7 +25,7 @@ what-you-see-is-what-you-get plaintext markup syntax.
Only the low-level syntax of docstrings is addressed here. This PEP
is not concerned with docstring semantics or processing at all (see
PEP 256 for a "Road Map to the Docstring PEPs"). Nor is it an attempt
:pep:`256` for a "Road Map to the Docstring PEPs"). Nor is it an attempt
to deprecate pure plaintext docstrings, which are always going to be
legitimate. The reStructuredText markup is an alternative for those
who want more expressive docstrings.
@ -152,7 +152,7 @@ b) Replace the PEP section structure constructs with the
Strategy (b) is recommended, and its implementation is complete.
Support for RFC 2822 headers has been added to the reStructuredText
Support for :rfc:`2822` headers has been added to the reStructuredText
parser for PEPs (unambiguous given a specific context: the first
contiguous block of the document). It may be desired to concretely
specify what over/underline styles are allowed for PEP section
@ -406,7 +406,7 @@ Docstring-Significant Features
such as identifying parameters, exceptions raised, etc.; such usage
is beyond the scope of this PEP.
A modified RFC 2822 syntax is used, with a colon *before* as well as
A modified :rfc:`2822` syntax is used, with a colon *before* as well as
*after* the field name. Field bodies are more versatile as well;
they may contain multiple field bodies (even nested field lists).
For example::
@ -418,7 +418,7 @@ Docstring-Significant Features
- Myself
- I
Standard RFC 2822 header syntax cannot be used for this construct
Standard :rfc:`2822` header syntax cannot be used for this construct
because it is ambiguous. A word followed by a colon at the
beginning of a line is common in written text.
@ -624,8 +624,8 @@ Questions & Answers
The PEP markup proposal may be removed if it is deemed that there
is no need for PEP markup, or it could be made into a separate PEP.
If accepted, PEP 1, PEP Purpose and Guidelines [#PEP-1]_, and PEP
9, Sample PEP Template [#PEP-9]_ will be updated.
If accepted, :pep:`1`, PEP Purpose and Guidelines, and :pep:`9`,
Sample PEP Template will be updated.
It seems natural to adopt a single consistent markup standard for
all uses of structured plaintext in Python, and to propose it all
@ -670,8 +670,8 @@ Questions & Answers
input and check the output for correctness.
In a strict sense, the reStructuredText parser is very unforgiving
(as it should be; "In the face of ambiguity, refuse the temptation
to guess" [#Zen]_ applies to parsing markup as well as computer
(as it should be; :pep:`"In the face of ambiguity, refuse the temptation
to guess" <20>` applies to parsing markup as well as computer
languages). Here's design goal 3 from `An Introduction to
reStructuredText`_:
@ -727,20 +727,6 @@ Questions & Answers
References & Footnotes
======================
.. [#PEP-1] PEP 1, PEP Guidelines, Warsaw, Hylton
(http://www.python.org/dev/peps/pep-0001/)
.. [#PEP-9] PEP 9, Sample PEP Template, Warsaw
(http://www.python.org/dev/peps/pep-0009/)
.. [#Zen] From `The Zen of Python (by Tim Peters)`__ (or just
"``import this``" in Python)
__ http://www.python.org/doc/Humor.html#zen
.. [#PEP-216] PEP 216, Docstring Format, Zadka
(http://www.python.org/dev/peps/pep-0216/)
.. _reStructuredText markup: http://docutils.sourceforge.net/rst.html
.. _Doc-SIG: http://www.python.org/sigs/doc-sig/
@ -799,7 +785,7 @@ This document has been placed in the public domain.
Acknowledgements
================
Some text is borrowed from PEP 216, Docstring Format [#PEP-216]_, by
Some text is borrowed from :pep:`216`, Docstring Format, by
Moshe Zadka.
Special thanks to all members past & present of the Python Doc-SIG_.

10
pep-0288.txt
View File

@ -22,7 +22,7 @@ Status
======
This PEP is withdrawn. The exception raising mechanism was extended
and subsumed into PEP 343. The attribute passing capability
and subsumed into :pep:`343`. The attribute passing capability
never built a following, did not have a clear implementation,
and did not have a clean way for the running generator to access
its own namespace.
@ -119,7 +119,7 @@ code cannot be excepted to or through.
Generator exception passing also helps address an intrinsic
limitation on generators, the prohibition against their using
try/finally to trigger clean-up code [2]_.
try/finally to trigger clean-up code (:pep:`255`).
Note A: The name of the throw method was selected for several
reasons. Raise is a keyword and so cannot be used as a method
@ -149,12 +149,6 @@ References
http://gnosis.cx/publish/programming/charming_python_b5.txt
http://gnosis.cx/publish/programming/charming_python_b7.txt
.. [2] PEP 255 Simple Generators
http://www.python.org/dev/peps/pep-0255/
.. [3] Proof-of-concept recipe
http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/164044
Copyright

29
pep-0289.txt
View File

@ -15,8 +15,8 @@ Abstract
========
This PEP introduces generator expressions as a high performance,
memory efficient generalization of list comprehensions [1]_ and
generators [2]_.
memory efficient generalization of list comprehensions :pep:`202` and
generators :pep:`255`.
Rationale
@ -214,7 +214,7 @@ for-expression should be evaluated immediately and that the remaining
expressions be evaluated when the generator is executed.
Asked to summarize the reasoning for binding the first expression,
Guido offered [5]_::
Guido offered [1]_::
Consider sum(x for x in foo()). Now suppose there's a bug in foo()
that raises an exception, and a bug in sum() that raises an
@ -243,7 +243,7 @@ issues were hard to understand and that users should be strongly
encouraged to use generator expressions inside functions that consume
their arguments immediately. For more complex applications, full
generator definitions are always superior in terms of being obvious
about scope, lifetime, and binding [6]_.
about scope, lifetime, and binding [2]_.
Reduction Functions
@ -275,35 +275,22 @@ Acknowledgements
* Armin Rigo, Tim Peters, Guido van Rossum, Samuele Pedroni,
Hye-Shik Chang and Raymond Hettinger teased out the issues surrounding
early versus late binding [5]_.
early versus late binding [1]_.
* Jiwon Seo single-handedly implemented various versions of the proposal
including the final version loaded into CVS. Along the way, there
were periodic code reviews by Hye-Shik Chang and Raymond Hettinger.
Guido van Rossum made the key design decisions after comments from
Armin Rigo and newsgroup discussions. Raymond Hettinger provided
the test suite, documentation, tutorial, and examples [6]_.
the test suite, documentation, tutorial, and examples [2]_.
References
==========
.. [1] PEP 202 List Comprehensions
http://www.python.org/dev/peps/pep-0202/
.. [2] PEP 255 Simple Generators
http://www.python.org/dev/peps/pep-0255/
.. [3] Peter Norvig's Accumulation Display Proposal
http://www.norvig.com/pyacc.html
.. [4] Jeff Epler had worked up a patch demonstrating
the previously proposed bracket and yield syntax
https://bugs.python.org/issue795947
.. [5] Discussion over the relative merits of early versus late binding
.. [1] Discussion over the relative merits of early versus late binding
https://mail.python.org/pipermail/python-dev/2004-April/044555.html
.. [6] Patch discussion and alternative patches on Source Forge
.. [2] Patch discussion and alternative patches on Source Forge
https://bugs.python.org/issue872326

15
pep-0290.txt
View File

@ -29,8 +29,8 @@ This repository of procedures serves as a catalog or checklist of
known migration issues and procedures for addressing those issues.
Migration issues can arise for several reasons. Some obsolete
features are slowly deprecated according to the guidelines in PEP 4
[1]_. Also, some code relies on undocumented behaviors which are
features are slowly deprecated according to the guidelines in :pep:`4`.
Also, some code relies on undocumented behaviors which are
subject to change between versions. Some code may rely on behavior
which was subsequently shown to be a bug and that behavior changes
when the bug is fixed.
@ -426,7 +426,7 @@ Pattern::
NewError = 'NewError' --> class NewError(Exception): pass
Locating: Use PyChecker_.
Locating: Use `PyChecker <http://pychecker.sourceforge.net/>`__.
All Python Versions
@ -448,15 +448,6 @@ Pattern::
Locating: ``grep '== None'`` or ``grep '!= None'``
References
==========
.. [1] PEP 4, Deprecation of Standard Modules, von Loewis
(http://www.python.org/dev/peps/pep-0004/)
.. _PyChecker: http://pychecker.sourceforge.net/
Copyright
=========

16
pep-0292.txt
View File

@ -23,8 +23,8 @@ respects:
(i.e. ``%``-substitution) is complicated and error prone. This PEP
is simpler at the cost of some expressiveness.
2. PEP 215 proposed an alternative string interpolation feature,
introducing a new ``$`` string prefix. PEP 292 is simpler than
2. :pep:`215` proposed an alternative string interpolation feature,
introducing a new ``$`` string prefix. :pep:`292` is simpler than
this because it involves no syntax changes and has much simpler
rules for what substitutions can occur in the string.
@ -128,16 +128,16 @@ easier to teach, learn, and remember.
Comparison to PEP 215
=====================
PEP 215 describes an alternate proposal for string interpolation.
:pep:`215` describes an alternate proposal for string interpolation.
Unlike that PEP, this one does not propose any new syntax for
Python. All the proposed new features are embodied in a new
library module. PEP 215 proposes a new string prefix
library module. :pep:`215` proposes a new string prefix
representation such as ``$""`` which signal to Python that a new type
of string is present. ``$``-strings would have to interact with the
existing r-prefixes and u-prefixes, essentially doubling the
number of string prefix combinations.
PEP 215 also allows for arbitrary Python expressions inside the
:pep:`215` also allows for arbitrary Python expressions inside the
``$``-strings, so that you could do things like::
import sys
@ -147,15 +147,15 @@ which would return::
sys = <module 'sys' (built-in)>, sys = <module 'sys' (built-in)>
It's generally accepted that the rules in PEP 215 are safe in the
sense that they introduce no new security issues (see PEP 215,
It's generally accepted that the rules in :pep:`215` are safe in the
sense that they introduce no new security issues (see :pep:`215`,
"Security Issues" for details). However, the rules are still
quite complex, and make it more difficult to see the substitution
placeholder in the original ``$``-string.
The interesting thing is that the ``Template`` class defined in this
PEP is designed for inheritance and, with a little extra work,
it's possible to support PEP 215's functionality using existing
it's possible to support :pep:`215`'s functionality using existing
Python syntax.
For example, one could define subclasses of ``Template`` and dict that

2
pep-0294.txt
View File

@ -27,7 +27,7 @@ The long capitalized names currently in the types module will be
deprecated.
With this change the types module can serve as a replacement for the
new module. The new module shall be deprecated and listed in PEP 4.
new module. The new module shall be deprecated and listed in :pep:`4`.
Pronouncement

2
pep-0296.txt
View File

@ -14,7 +14,7 @@ Post-History:
Notice
=======
This PEP is withdrawn by the author (in favor of PEP 358).
This PEP is withdrawn by the author (in favor of :pep:`358`).
Abstract

5
pep-0298.txt
View File

@ -193,7 +193,7 @@ Guido recommends
For strings that might be impractical because the string
object would have to grow 4 bytes to hold the counter; but the
new bytes object (PEP 296) could easily implement the counter,
new bytes object (:pep:`296`) could easily implement the counter,
and the array object too -- that way there will be plenty of
opportunity to test proper use of the protocol.
@ -224,9 +224,6 @@ References
.. [1] The buffer interface
https://mail.python.org/pipermail/python-dev/2000-October/009974.html
.. [2] The Buffer Problem
http://www.python.org/dev/peps/pep-0296/
Copyright
=========

24
pep-0301.txt
View File

@ -20,9 +20,9 @@ tools for submitting package information to the index and extensions
to the package metadata to include Trove [2]_ information.
This PEP does not address issues of package dependency. It also does
not address storage and download of packages as described in PEP 243
[6]_. Nor is it proposing a local database of packages as described
in PEP 262 [7]_.
not address storage and download of packages as described in :pep:`243`.
Nor is it proposing a local database of packages as described
in :pep:`262`.
Existing package repositories such as the Vaults of Parnassus [3]_,
CPAN [4]_ and PAUSE [5]_ will be investigated as prior art in this
@ -52,15 +52,15 @@ The interface for submitting information to the catalog should be as
simple as possible - hopefully just a one-line command for most users.
Issues of package dependency are not addressed due to the complexity
of such a system. PEP 262 proposes such a system, but as of this
of such a system. :pep:`262` proposes such a system, but as of this
writing the PEP is still unfinished.
Issues of package dissemination (storage on a central server) are
not addressed because they require assumptions about availability of
storage and bandwidth that I am not in a position to make. PEP 243,
storage and bandwidth that I am not in a position to make. :pep:`243`,
which is still being developed, is tackling these issues and many
more. This proposal is considered compatible with, and adjunct to
the proposal in PEP 243.
the proposal in :pep:`243`.
Specification
@ -333,7 +333,7 @@ Rejected Proposals
==================
Originally, the index server was to return custom headers (inspired by
PEP 243):
:pep:`243`):
**X-Pypi-Status**
Either "success" or "fail".
@ -342,7 +342,7 @@ PEP 243):
A description of the reason for failure, or additional information
in the case of a success.
However, it has been pointed out [8]_ that this is a bad scheme to
However, it has been pointed out [6]_ that this is a bad scheme to
use.
@ -364,13 +364,7 @@ References
.. [5] PAUSE
(http://pause.cpan.org/)
.. [6] PEP 243, Module Repository Upload Mechanism
(http://www.python.org/dev/peps/pep-0243/)
.. [7] PEP 262, A Database of Installed Python Packages
(http://www.python.org/dev/peps/pep-0262/)
.. [8] [PEP243] upload status is bogus
.. [6] [PEP243] upload status is bogus
(https://mail.python.org/pipermail/distutils-sig/2001-March/002262.html)

19
pep-0302.txt
View File

@ -72,13 +72,13 @@ are stored in a non-standard way. Examples include modules that are bundled
together in an archive; byte code that is not stored in a ``pyc`` formatted
file; modules that are loaded from a database over a network.
The work on this PEP was partly triggered by the implementation of PEP 273,
The work on this PEP was partly triggered by the implementation of :pep:`273`,
which adds imports from Zip archives as a built-in feature to Python. While
the PEP itself was widely accepted as a must-have feature, the implementation
left a few things to desire. For one thing it went through great lengths to
integrate itself with ``import.c``, adding lots of code that was either
specific for Zip file imports or *not* specific to Zip imports, yet was not
generally useful (or even desirable) either. Yet the PEP 273 implementation
generally useful (or even desirable) either. Yet the :pep:`273` implementation
can hardly be blamed for this: it is simply extremely hard to do, given the
current state of ``import.c``.
@ -265,7 +265,7 @@ The ``load_module()`` method has a few responsibilities that it must fulfill
importer-specific extras, for example getting data associated with an
importer.
* The ``__package__`` attribute [8]_ must be set.
* The ``__package__`` attribute must be set (:pep:`366`).
If the module is a Python module (as opposed to a built-in module or a
dynamically loaded extension), it should execute the module's code in the
@ -398,7 +398,8 @@ the module as a string (using newline characters for line endings) or ``None``
if the source is not available (yet it should still raise ``ImportError`` if
the module can't be found by the importer at all).
To support execution of modules as scripts [6]_, the above three methods for
To support execution of modules as scripts (:pep:`338`),
the above three methods for
finding the code associated with a module must be implemented. In addition to
those methods, the following method may be provided in order to allow the
``runpy`` module to correctly set the ``__file__`` attribute::
@ -519,11 +520,11 @@ user-defined hooks either before or after it.
Implementation
==============
The PEP 302 implementation has been integrated with Python as of 2.3a1. An
The :pep:`302` implementation has been integrated with Python as of 2.3a1. An
earlier version is available as patch #652586 [9]_, but more interestingly,
the issue contains a fairly detailed history of the development and design.
PEP 273 has been implemented using PEP 302's import hooks.
:pep:`273` has been implemented using :pep:`302`'s import hooks.
References and Footnotes
@ -546,15 +547,9 @@ References and Footnotes
from the actual parent module or be supplied by ``imp.find_module()`` or
the proposed ``imp.get_loader()`` function.
.. [6] PEP 338: Executing modules as scripts
http://www.python.org/dev/peps/pep-0338/
.. [7] Quixote, a framework for developing Web applications
http://www.mems-exchange.org/software/quixote/
.. [8] PEP 366: Main module explicit relative imports
http://www.python.org/dev/peps/pep-0366/
.. [9] New import hooks + Import from Zip files
http://bugs.python.org/issue652586

11
pep-0304.txt
View File

@ -20,7 +20,7 @@ by other changes in the intervening years:
- the introduction of isolated mode to handle potential security concerns
- the switch to ``importlib``, a fully import-hook based import system implementation
- PEP 3147's change in the bytecode cache layout to use ``__pycache__``
- :pep:`3147`'s change in the bytecode cache layout to use ``__pycache__``
subdirectories, including the ``source_to_cache(path)`` and
``cache_to_source(path)`` APIs that allow the interpreter to automatically
handle the redirection to a separate cache directory
@ -239,11 +239,11 @@ Issues
- The interaction of this PEP with import hooks has not been
considered yet. In fact, the best way to implement this idea might
be as an import hook. See PEP 302. [5]_
be as an import hook. See :pep:`302`.
- In the current (pre-PEP 304) environment, it is safe to delete a
- In the current (pre-:pep:`304`) environment, it is safe to delete a
source file after the corresponding bytecode file has been created,
since they reside in the same directory. With PEP 304 as currently
since they reside in the same directory. With :pep:`304` as currently
defined, this is not the case. A bytecode file in the augmented
directory is only considered when the source file is present and it
thus never considered when looking for module files ending in
@ -344,9 +344,6 @@ References
.. [4] python-dev thread, Parallel pyc construction, Dubois
(https://mail.python.org/pipermail/python-dev/2003-January/032060.html)
.. [5] PEP 302, New Import Hooks, van Rossum and Moore
(http://www.python.org/dev/peps/pep-0302)
.. [6] patch 677103, PYTHONBYTECODEBASE patch (PEP 304), Montanaro
(https://bugs.python.org/issue677103)

4
pep-0310.txt
View File

@ -30,7 +30,7 @@ This PEP proposes a piece of syntax (a 'with' block) and a
Pronouncement
=============
This PEP is rejected in favor of PEP 343.
This PEP is rejected in favor of :pep:`343`.
Rationale
@ -191,7 +191,7 @@ in deep and subtle ways and as such belong to a different PEP.
Any Smalltalk/Ruby anonymous block style extension obviously
subsumes this one.
PEP 319 is in the same area, but did not win support when aired on
:pep:`319` is in the same area, but did not win support when aired on
python-dev.

20
pep-0313.txt
View File

@ -87,11 +87,11 @@ The new built-in function "roman" will aide the translation from
integers to Roman numeral literals. It will accept a single
object as an argument, and return a string containing the literal
of the same value. If the argument is not an integer or a
rational (see PEP 239 [1]_) it will passed through the existing
rational (see :pep:`239`) it will passed through the existing
built-in "int" to obtain the value. This may cause a loss of
information if the object was a float. If the object is a
rational, then the result will be formatted as a rational literal
(see PEP 240 [2]_) with the integers in the string being Roman
(see :pep:`240`) with the integers in the string being Roman
numeral literals.
@ -104,31 +104,17 @@ characters M, D, C, L, X, V and I will be affected by the new
literals. These programs will now have syntax errors when those
variables are assigned, and either syntax errors or subtle bugs
when those variables are referenced in expressions. Since such
variable names violate PEP 8 [3]_, the code is already broken, it
variable names violate :pep:`8`, the code is already broken, it
just wasn't generating exceptions. This proposal corrects that
oversight in the language.
References
==========
.. [1] PEP 239, Adding a Rational Type to Python
http://www.python.org/dev/peps/pep-0239/
.. [2] PEP 240, Adding a Rational Literal to Python
http://www.python.org/dev/peps/pep-0240/
.. [3] PEP 8, Style Guide for Python Code
http://www.python.org/dev/peps/pep-0008/
Copyright
=========
This document has been placed in the public domain.
..
Local Variables:
mode: indented-text

13
pep-0314.txt
View File

@ -20,7 +20,7 @@ packages. It includes specifics of the field names, and their
semantics and usage.
This document specifies version 1.1 of the metadata format.
Version 1.0 is specified in PEP 241.
Version 1.0 is specified in :pep:`241`.
Including Metadata in Packages
@ -37,7 +37,7 @@ command will, if it detects an existing PKG-INFO file, terminate
with an appropriate error message. This should prevent confusion
caused by the PKG-INFO and setup.py files being out of sync.
The PKG-INFO file format is a single set of RFC-822 headers
The PKG-INFO file format is a single set of :rfc:`822` headers
parseable by the rfc822.py module. The field names listed in the
following section are used as the header names.
@ -181,7 +181,7 @@ Author-email
------------
A string containing the author's e-mail address. It can contain
a name and e-mail address in the legal forms for a RFC-822
a name and e-mail address in the legal forms for a :rfc:`822`
'From:' header. It's not optional because cataloging systems
can use the e-mail portion of this field as a unique key
representing the author. A catalog might provide authors the
@ -212,7 +212,7 @@ Classifier (multiple use)
-------------------------
Each entry is a string giving a single classification value
for the package. Classifiers are described in PEP 301 [2]_.
for the package. Classifiers are described in :pep:`301`.
Examples::
@ -297,7 +297,7 @@ Summary of Differences From PEP 241
* Metadata-Version is now 1.1.
* Added the Classifiers field from PEP 301.
* Added the Classifiers field from :pep:`301`.
* The License and Platform files should now only be used if the
platform or license can't be handled by an appropriate Classifier
@ -324,9 +324,6 @@ References
.. [1] reStructuredText
http://docutils.sourceforge.net/
.. [2] PEP 301
http://www.python.org/dev/peps/pep-0301/
Copyright
=========

15
pep-0317.txt
View File

@ -43,7 +43,7 @@ proposed implementation schedule, Python 2.4 will introduce warnings
about uses of ``raise`` which will eventually become incorrect, and
Python 3.0 will eliminate them entirely. (It is assumed that this
transition period -- 2.4 to 3.0 -- will be at least one year long, to
comply with the guidelines of PEP 5 [2]_.)
comply with the guidelines of :pep:`5`.)
Motivation
@ -184,7 +184,7 @@ Migration Plan
Future Statement
''''''''''''''''
Under the future statement [4]_ ::
Under the :pep:`236` future statement::
from __future__ import raise_with_two_args
@ -200,7 +200,7 @@ simple exception raising does not require it.
Warnings
''''''''
Three new warnings [5]_, all of category ``DeprecationWarning``, are
Three new :pep:`warnings <230>`, all of category ``DeprecationWarning``, are
to be issued to point out uses of ``raise`` which will become
incorrect under the proposed changes.
@ -433,18 +433,9 @@ References
.. [1] "Standard Exception Classes in Python 1.5", Guido van Rossum.
http://www.python.org/doc/essays/stdexceptions.html
.. [2] "Guidelines for Language Evolution", Paul Prescod.
http://www.python.org/dev/peps/pep-0005/
.. [3] "Python Language Reference", Guido van Rossum.
http://docs.python.org/reference/simple_stmts.html#raise
.. [4] PEP 236 "Back to the __future__", Tim Peters.
http://www.python.org/dev/peps/pep-0236/
.. [5] PEP 230 "Warning Framework", Guido van Rossum.
http://www.python.org/dev/peps/pep-0230/
.. [6] Guido van Rossum, 11 June 2003 post to ``python-dev``.
https://mail.python.org/pipermail/python-dev/2003-June/036176.html

13
pep-0318.txt
View File

@ -72,7 +72,7 @@ using metaclasses is sufficiently obscure that there is some attraction
to having an easier way to make simple modifications to classes. For
Python 2.4, only function/method decorators are being added.
PEP 3129 [#PEP-3129] proposes to add class decorators as of Python 2.6.
:pep:`3129` proposes to add class decorators as of Python 2.6.
Why Is This So Hard?
@ -110,7 +110,7 @@ seem to be most divisive.
* Syntax discussions in general appear to cause more contention than
almost anything else. Readers are pointed to the ternary operator
discussions that were associated with PEP 308 for another example of
discussions that were associated with :pep:`308` for another example of
this.
@ -836,7 +836,7 @@ syntactic support.
.. _strong arguments:
https://mail.python.org/pipermail/python-dev/2004-March/thread.html
PEP 3129 [#PEP-3129] proposes to add class decorators as of Python 2.6.
:pep:`3129` proposes to add class decorators as of Python 2.6.
2. The choice of the ``@`` character will be re-examined before
Python 2.4b1.
@ -844,13 +844,6 @@ syntactic support.
In the end, the ``@`` character was kept.
References
==========
.. [#PEP-3129] PEP 3129, "Class Decorators", Winter
http://www.python.org/dev/peps/pep-3129
Copyright
=========

18
pep-0319.txt
View File

@ -20,7 +20,7 @@ and 'asynchronize'.
Pronouncement
=============
This PEP is rejected in favor of PEP 343.
This PEP is rejected in favor of :pep:`343`.
The 'synchronize' Keyword
The concept of code synchronization in Python is too low-level.
@ -375,7 +375,8 @@ Backward Compatibility
======================
Backward compatibility is solved with the new ``from __future__``
Python syntax [2]_, and the new warning framework [3]_ to evolve the
Python syntax (:pep:`236`), and the new warning framework (:pep:`230`)
to evolve the
Python language into phasing out any conflicting names that use
the new keywords 'synchronize' and 'asynchronize'. To use the
syntax now, a developer could use the statement::
@ -393,7 +394,7 @@ an exception.
PEP 310 Reliable Acquisition/Release Pairs
==========================================
PEP 310 [4]_ proposes the 'with' keyword that can serve the same
:pep:`310` proposes the 'with' keyword that can serve the same
function as 'synchronize' (but no facility for 'asynchronize').
The pattern::
@ -407,7 +408,7 @@ is equivalent to the proposed::
synchronize the_lock:
change_shared_data()
PEP 310 must synchronize on an existing lock, while this PEP
:pep:`310` must synchronize on an existing lock, while this PEP
proposes that unqualified 'synchronize' statements synchronize on
a global, internal, transparent lock in addition to qualified
'synchronize' statements. The 'with' statement also requires lock
@ -489,15 +490,6 @@ References
.. [1] The Python Language Reference
http://docs.python.org/reference/
.. [2] PEP 236, Back to the __future__, Peters
http://www.python.org/dev/peps/pep-0236/
.. [3] PEP 230, Warning Framework, van Rossum
http://www.python.org/dev/peps/pep-0230/
.. [4] PEP 310, Reliable Acquisition/Release Pairs, Hudson, Moore
http://www.python.org/dev/peps/pep-0310/
Copyright
=========

32
pep-0320.txt
View File

@ -53,19 +53,19 @@ Release Schedule
Completed features for 2.4
==========================
- PEP 218 Builtin Set Objects.
- :pep:`218` Builtin Set Objects.
- PEP 289 Generator expressions.
- :pep:`289` Generator expressions.
- PEP 292 Simpler String Substitutions to be implemented as a module.
- :pep:`292` Simpler String Substitutions to be implemented as a module.
- PEP 318: Function/method decorator syntax, using @syntax
- :pep:`318`: Function/method decorator syntax, using @syntax
- PEP 322 Reverse Iteration.
- :pep:`322` Reverse Iteration.
- PEP 327: A Decimal package for fixed precision arithmetic.
- :pep:`327`: A Decimal package for fixed precision arithmetic.
- PEP 328: Multi-line Imports
- :pep:`328`: Multi-line Imports
- Encapsulate the decorate-sort-undecorate pattern in a keyword for
``list.sort()``.
@ -85,10 +85,10 @@ Completed features for 2.4
Deferred until 2.5
==================
- Deprecate and/or remove the modules listed in PEP 4 (``posixfile``,
- Deprecate and/or remove the modules listed in :pep:`4` (``posixfile``,
``gopherlib``, ``pre``, ``others``)
- Remove support for platforms as described in PEP 11.
- Remove support for platforms as described in :pep:`11`.
- Finish implementing the Distutils ``bdist_dpkg`` command. (AMK)
@ -161,7 +161,7 @@ Carryover features from Python 2.3
widgets in Tk 8.4? Note that we've got better Tix support
already (though not on Windows yet).
- PEP 304 (Controlling Generation of Bytecode Files by Montanaro)
- :pep:`304` (Controlling Generation of Bytecode Files by Montanaro)
seems to have lost steam.
- For a class defined inside another class, the ``__name__`` should be
@ -182,22 +182,22 @@ Carryover features from Python 2.3
covered yet (e.g. ``string.whitespace`` and ``types.TracebackType``).
It seems we can't get consensus on this.
- PEP 262 Database of Installed Python Packages (Kuchling)
- :pep:`262` Database of Installed Python Packages (Kuchling)
This turns out to be useful for Jack Jansen's Python installer,
so the database is worth implementing. Code will go in
sandbox/pep262.
- PEP 269 Pgen Module for Python (Riehl)
- :pep:`269` Pgen Module for Python (Riehl)
(Some necessary changes are in; the ``pgen`` module itself needs to
mature more.)
- PEP 266 Optimizing Global Variable/Attribute Access (Montanaro)
- :pep:`266` Optimizing Global Variable/Attribute Access (Montanaro)
PEP 267 Optimized Access to Module Namespaces (Hylton)
:pep:`267` Optimized Access to Module Namespaces (Hylton)
PEP 280 Optimizing access to globals (van Rossum)
:pep:`280` Optimizing access to globals (van Rossum)
These are basically three friendly competing proposals. Jeremy
has made a little progress with a new compiler, but it's going
@ -208,7 +208,7 @@ Carryover features from Python 2.3
- Lazily tracking tuples? [6]_ [7]_
Not much enthusiasm I believe.
- PEP 286 Enhanced Argument Tuples (von Loewis)
- :pep:`286` Enhanced Argument Tuples (von Loewis)
I haven't had the time to review this thoroughly. It seems a
deep optimization hack (also makes better correctness guarantees

6
pep-0321.txt
View File

@ -35,7 +35,7 @@ Input Formats
Useful formats to support include:
* `ISO8601`_
* ARPA/`RFC2822`_
* ARPA/:rfc:`2822`
* `ctime`_
* Formats commonly written by humans such as the American
"MM/DD/YYYY", the European "YYYY/MM/DD", and variants such as
@ -92,7 +92,7 @@ Output Formats
Not all input formats need to be supported as output formats, because it's
pretty trivial to get the ``strftime()`` argument right for simple things
such as YYYY/MM/DD. Only complicated formats need to be supported; RFC2822
such as YYYY/MM/DD. Only complicated formats need to be supported; :rfc:`2822`
is currently the only one I can think of.
Options:
@ -117,8 +117,6 @@ http://simon.incutio.com/archive/2003/10/07/dateInPython)
References
==========
.. _RFC2822: http://rfc2822.x42.com
.. _ISO8601: http://www.cl.cam.ac.uk/~mgk25/iso-time.html
.. _ParseDate.pm: http://search.cpan.org/author/MUIR/Time-modules-2003.0211/lib/Time/ParseDate.pm

4
pep-0323.txt
View File

@ -252,7 +252,7 @@ iterkeys, itervalues, and iteritems of built-in type dict.
Iterators produced by generator functions will not be copyable.
However, iterators produced by the new "generator expressions" of
Python 2.4 (PEP 289 [3]_) should be copyable if their underlying
Python 2.4 (:pep:`289`) should be copyable if their underlying
``iterator[s]`` are; the strict limitations on what is possible in a
generator expression, compared to the much vaster generality of a
generator, should make that feasible. Similarly, the iterators
@ -481,8 +481,6 @@ References
.. [2] Online documentation for the copy module of the standard library:
http://docs.python.org/library/copy.html
.. [3] PEP 289, Generator Expressions, Hettinger
http://www.python.org/dev/peps/pep-0289/
Copyright
=========

22
pep-0325.txt
View File

@ -31,7 +31,7 @@ generators.
Pronouncement
=============
Rejected in favor of PEP 342 which includes substantially all of
Rejected in favor of :pep:`342` which includes substantially all of
the requested behavior in a more refined form.
@ -128,7 +128,7 @@ with such semantics that the example could be rewritten as::
finally:
all.close() # close on generator
Currently PEP 255 [1]_ disallows yield inside a try clause of a
Currently :pep:`255` disallows yield inside a try clause of a
try-finally statement, because the execution of the finally clause
cannot be guaranteed as required by try-finally semantics.
@ -264,24 +264,14 @@ clauses has been proposed more than once. Alone it cannot
guarantee that timely release of resources acquired by a generator
can be enforced.
PEP 288 [2]_ proposes a more general solution, allowing custom
:pep:`288` proposes a more general solution, allowing custom
exception passing to generators. The proposal in this PEP
addresses more directly the problem of resource release. Were PEP
288 implemented, Exceptions Semantics for close could be layered
on top of it, on the other hand PEP 288 should make a separate
addresses more directly the problem of resource release. Were
:pep:`288` implemented, Exceptions Semantics for close could be layered
on top of it, on the other hand :pep:`288` should make a separate
case for the more general functionality.
References
==========
.. [1] PEP 255 Simple Generators
http://www.python.org/dev/peps/pep-0255/
.. [2] PEP 288 Generators Attributes and Exceptions
http://www.python.org/dev/peps/pep-0288/
Copyright
=========

4
pep-0326.txt
View File

@ -16,7 +16,7 @@ Results
=======
This PEP has been rejected by the BDFL [12]_. As per the
pseudo-sunset clause [13]_, PEP 326 is being updated one last time
pseudo-sunset clause [13]_, :pep:`326` is being updated one last time
with the latest suggestions, code modifications, etc., and includes a
link to a module [14]_ that implements the behavior described in the
PEP. Users who desire the behavior listed in this PEP are encouraged
@ -508,7 +508,7 @@ Changes
- Added some `References`_.
- BDFL rejects [12]_ PEP 326
- BDFL rejects [12]_ :pep:`326`
Copyright

2
pep-0327.txt
View File

@ -137,7 +137,7 @@ Quoting Alex Martelli:
truly major use case in the real world.
Anyway, if you're interested in this data type, you maybe will want to
take a look at PEP 239: Adding a Rational Type to Python.
take a look at :pep:`239`: Adding a Rational Type to Python.
So, what do we have?

5
pep-0329.txt
View File

@ -124,7 +124,7 @@ Questions and Answers
values that never change?
No, this has long been known. Skip Montanaro provides an eloquent
explanation in [1]_.
explanation in :pep:`266`.
7. What if I want to replace the builtins module and supply my own
implementations?
@ -255,9 +255,6 @@ The final code should add a flag to make it easy to disable binding.
References
==========
.. [1] Optimizing Global Variable/Attribute Access
http://www.python.org/dev/peps/pep-0266/
.. [2] ASPN Recipe for a non-private implementation
http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/277940

3
pep-0331.txt
View File

@ -172,9 +172,6 @@ Löwis on 2004-06-08, as stated in the bug report.
References
==========
.. [1] PEP 1, PEP Purpose and Guidelines, Warsaw, Hylton
http://www.python.org/dev/peps/pep-0001/
.. [2] Python locale documentation for embedding,
http://docs.python.org/library/locale.html

48
pep-0333.txt
View File

@ -17,7 +17,7 @@ Preface
Note: For an updated version of this spec that supports Python 3.x and
includes community errata, addenda, and clarifications, please
see PEP 3333 instead.
see :pep:`3333` instead.
Abstract
@ -477,7 +477,7 @@ If the iterable returned by the application has a ``close()`` method,
the server or gateway **must** call that method upon completion of the
current request, whether the request was completed normally, or
terminated early due to an error (this is to support resource release
by the application). This protocol is intended to complement PEP 325's
by the application). This protocol is intended to complement :pep:`325`'s
generator support, and other common iterables with ``close()`` methods.
(Note: the application **must** invoke the ``start_response()``
@ -492,7 +492,7 @@ attributes of the iterable returned by the application, unless it is an
instance of a type specific to that server or gateway, such as a "file
wrapper" returned by ``wsgi.file_wrapper`` (see `Optional
Platform-Specific File Handling`_). In the general case, only
attributes specified here, or accessed via e.g. the PEP 234 iteration
attributes specified here, or accessed via e.g. the :pep:`234` iteration
APIs are acceptable.
@ -560,7 +560,7 @@ unless their value would be an empty string, in which case they
A server or gateway **should** attempt to provide as many other CGI
variables as are applicable. In addition, if SSL is in use, the server
or gateway **should** also provide as many of the Apache SSL environment
variables [5]_ as are applicable, such as ``HTTPS=on`` and
variables [3]_ as are applicable, such as ``HTTPS=on`` and
``SSL_PROTOCOL``. Note, however, that an application that uses any CGI
variables other than the ones listed above are necessarily non-portable
to web servers that do not support the relevant extensions. (For
@ -713,7 +713,7 @@ The ``status`` argument is an HTTP "status" string like ``"200 OK"``
or ``"404 Not Found"``. That is, it is a string consisting of a
Status-Code and a Reason-Phrase, in that order and separated by a
single space, with no surrounding whitespace or other characters.
(See RFC 2616, Section 6.1.1 for more information.) The string
(See :rfc:`2616`, Section 6.1.1 for more information.) The string
**must not** contain control characters, and must not be terminated
with a carriage return, linefeed, or combination thereof.
@ -721,7 +721,7 @@ The ``response_headers`` argument is a list of ``(header_name,
header_value)`` tuples. It must be a Python list; i.e.
``type(response_headers) is ListType``, and the server **may** change
its contents in any way it desires. Each ``header_name`` must be a
valid HTTP header field-name (as defined by RFC 2616, Section 4.2),
valid HTTP header field-name (as defined by :rfc:`2616`, Section 4.2),
without a trailing colon or other punctuation.
Each ``header_value`` **must not** include *any* control characters,
@ -832,12 +832,13 @@ whose ``len()`` is 1, then the server can automatically determine
``Content-Length`` by taking the length of the first string yielded
by the iterable.
And, if the server and client both support HTTP/1.1 "chunked
encoding" [3]_, then the server **may** use chunked encoding to send
And, if the server and client both support HTTP/1.1
:rfc:`"chunked encoding"<2616#section-3.6.1>`,
then the server **may** use chunked encoding to send
a chunk for each ``write()`` call or string yielded by the iterable,
thus generating a ``Content-Length`` header for each chunk. This
allows the server to keep the client connection alive, if it wishes
to do so. Note that the server **must** comply fully with RFC 2616
to do so. Note that the server **must** comply fully with :rfc:`2616`
when doing this, or else fall back to one of the other strategies for
dealing with the absence of ``Content-Length``.
@ -984,8 +985,8 @@ strings, not Unicode objects. The result of using a Unicode object
where a string object is required, is undefined.
Note also that strings passed to ``start_response()`` as a status or
as response headers **must** follow RFC 2616 with respect to encoding.
That is, they must either be ISO-8859-1 characters, or use RFC 2047
as response headers **must** follow :rfc:`2616` with respect to encoding.
That is, they must either be ISO-8859-1 characters, or use :rfc:`2047`
MIME encoding.
On Python platforms where the ``str`` or ``StringType`` type is in
@ -1086,8 +1087,8 @@ may be done in any of several ways:
Note that these behavior restrictions do not apply for HTTP 1.0
requests, or for requests that are not directed to an application
object. For more information on HTTP 1.1 Expect/Continue, see RFC
2616, sections 8.2.3 and 10.1.1.
object. For more information on HTTP 1.1 Expect/Continue, see
:rfc:`2616`, sections 8.2.3 and 10.1.1.
Other HTTP Features
@ -1100,13 +1101,14 @@ response. It is always possible for the application developer to add
middleware components to supply additional features, so server/gateway
developers should be conservative in their implementation. In a sense,
a server should consider itself to be like an HTTP "gateway server",
with the application being an HTTP "origin server". (See RFC 2616,
with the application being an HTTP "origin server". (See :rfc:`2616`,
section 1.3, for the definition of these terms.)
However, because WSGI servers and applications do not communicate via
HTTP, what RFC 2616 calls "hop-by-hop" headers do not apply to WSGI
HTTP, what :rfc:`2616` calls "hop-by-hop" headers do not apply to WSGI
internal communications. WSGI applications **must not** generate any
"hop-by-hop" headers [4]_, attempt to use HTTP features that would
:rfc:`"hop-by-hop" headers <2616#section-13.5.1>`,
attempt to use HTTP features that would
require them to generate such headers, or rely on the content of
any incoming "hop-by-hop" headers in the ``environ`` dictionary.
WSGI servers **must** handle any supported inbound "hop-by-hop" headers
@ -1302,7 +1304,7 @@ simply restrict themselves to using only a standard "for" loop to
iterate over any iterable returned by an application. This is the
only way to ensure source-level compatibility with both the pre-2.2
iterator protocol (discussed further below) and "today's" iterator
protocol (see PEP 234).
protocol (see :pep:`234`).
(Note that this technique necessarily applies only to servers,
gateways, or middleware that are written in Python. Discussion of
@ -1479,7 +1481,7 @@ Questions and Answers
iterable is garbage collected. The ``close()`` idiom allows an
application to release critical resources at the end of a request,
and it's forward-compatible with the support for try/finally in
generators that's proposed by PEP 325.
generators that's proposed by :pep:`325`.
4. Why is this interface so low-level? I want feature X! (e.g.
cookies, sessions, persistence, ...)
@ -1636,15 +1638,9 @@ References
(http://www.python.org/cgi-bin/moinmoin/WebProgramming)
.. [2] The Common Gateway Interface Specification, v 1.1, 3rd Draft
(http://ken.coar.org/cgi/draft-coar-cgi-v11-03.txt)
(https://datatracker.ietf.org/doc/html/draft-coar-cgi-v11-03)
.. [3] "Chunked Transfer Coding" -- HTTP/1.1, section 3.6.1
(http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6.1)
.. [4] "End-to-end and Hop-by-hop Headers" -- HTTP/1.1, Section 13.5.1
(http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.5.1)
.. [5] mod_ssl Reference, "Environment Variables"
.. [3] mod_ssl Reference, "Environment Variables"
(http://www.modssl.org/docs/2.8/ssl_reference.html#ToC25)

10
pep-0334.txt
View File

@ -25,7 +25,7 @@ help the application developer grapple with this state management
difficulty.
This PEP proposes a limited approach to coroutines based on an
extension to the iterator protocol [5]_. Currently, an iterator may
extension to the :pep:`iterator protocol <234>`. Currently, an iterator may
raise a StopIteration exception to indicate that it is done producing
values. This proposal adds another exception to this protocol,
SuspendIteration, which indicates that the given iterator may have
@ -62,7 +62,7 @@ portable across runtimes.
There are four places where this new exception impacts:
* The simple generator [8]_ mechanism could be extended to safely
* The :pep:`255` simple generator mechanism could be extended to safely
'catch' this SuspendIteration exception, stuff away its current
state, and pass the exception on to the caller.
@ -381,18 +381,12 @@ References
.. [4] Coroutines
(http://c2.com/cgi/wiki?CallWithCurrentContinuation)
.. [5] PEP 234, Iterators
(http://www.python.org/dev/peps/pep-0234/)
.. [6] Stackless Python
(http://stackless.com)
.. [7] Parrot /w coroutines
(http://www.sidhe.org/~dan/blog/archives/000178.html)
.. [8] PEP 255, Simple Generators
(http://www.python.org/dev/peps/pep-0255/)
.. [9] itertools - Functions creating iterators
(http://docs.python.org/library/itertools.html)

5
pep-0337.txt
View File

@ -14,7 +14,7 @@ Post-History: 10-Nov-2004
Abstract
========
This PEP defines a standard for using the logging system (PEP 282 [1]_) in the
This PEP defines a standard for using the logging system (:pep:`282`) in the
standard library.
Implementing this PEP will simplify development of daemon
@ -186,9 +186,6 @@ name "dummy.junk".
References
==========
.. [1] PEP 282, A Logging System, Vinay Sajip, Trent Mick
http://www.python.org/dev/peps/pep-0282/
.. [2] https://mail.python.org/pipermail/python-dev/2004-October/049282.html

28
pep-0338.txt
View File

@ -19,7 +19,7 @@ script, either with the ``-m`` command line switch, or by invoking
it via ``runpy.run_module(modulename)``.
The ``-m`` switch implemented in Python 2.4 is quite limited. This
PEP proposes making use of the PEP 302 [4]_ import hooks to allow any
PEP proposes making use of the :pep:`302` import hooks to allow any
module which provides access to its code object to be executed.
Rationale
@ -68,7 +68,7 @@ mechanisms (such as ``zipimport``).
Prior discussions suggest it should be noted that this PEP is **not**
about changing the idiom for making Python modules also useful as
scripts (see PEP 299 [1]_). That issue is considered orthogonal to the
scripts (see :pep:`299`). That issue is considered orthogonal to the
specific feature addressed by this PEP.
Current Behaviour
@ -98,7 +98,7 @@ Proposed Semantics
==================
The semantics proposed are fairly simple: if ``-m`` is used to execute
a module the PEP 302 import mechanisms are used to locate the module and
a module the :pep:`302` import mechanisms are used to locate the module and
retrieve its compiled code, before executing the module in accordance
with the semantics for a top-level module. The interpreter does this by
invoking a new standard library function ``runpy.run_module``.
@ -109,7 +109,7 @@ variable during initialisation. In addition, paths may be affected by
``*.pth`` files, and some packages will install custom loaders on
``sys.metapath``. Accordingly, the only way for Python to reliably
locate the module is by importing the containing package and
using the PEP 302 import hooks to gain access to the Python code.
using the :pep:`302` import hooks to gain access to the Python code.
Note that the process of locating the module to be executed may require
importing the containing package. The effects of such a package import
@ -140,7 +140,7 @@ The delegation has the form::
Execute the code of the specified module and return the resulting
module globals dictionary. The module's code is first located using
the standard import mechanism (refer to PEP 302 for details) and
the standard import mechanism (refer to :pep:`302` for details) and
then executed in a fresh module namespace.
The optional dictionary argument ``init_globals`` may be used to
@ -156,7 +156,7 @@ The delegation has the form::
``__name__`` is set to ``run_name`` if this optional argument is
supplied, and the original ``mod_name`` argument otherwise.
``__loader__`` is set to the PEP 302 module loader used to retrieve
``__loader__`` is set to the :pep:`302` module loader used to retrieve
the code for the module (This loader may be a wrapper around the
standard import mechanism).
@ -184,7 +184,7 @@ Import Statements and the Main Module
=====================================
The release of 2.5b1 showed a surprising (although obvious in
retrospect) interaction between this PEP and PEP 328 - explicit
retrospect) interaction between this PEP and :pep:`328` - explicit
relative imports don't work from a main module. This is due to
the fact that relative imports rely on ``__name__`` to determine
the current module's position in the package hierarchy. In a main
@ -229,7 +229,7 @@ Here's an example file layout::
So long as the current directory is ``devel``, or ``devel`` is already
on ``sys.path`` and the test modules use absolute imports (such as
``import pkg moduleA`` to retrieve the module under test, PEP 338
``import pkg moduleA`` to retrieve the module under test, :pep:`338`
allows the tests to be run as::
python -m pkg.test.test_A
@ -276,7 +276,7 @@ Python script with this behaviour can be found in the discussion of
the ``execmodule`` cookbook recipe [3]_.
The ``execmodule`` cookbook recipe itself was the proposed mechanism in
an earlier version of this PEP (before the PEP's author read PEP 302).
an earlier version of this PEP (before the PEP's author read :pep:`302`).
Both approaches were rejected as they do not meet the main goal of the
``-m`` switch -- to allow the full Python namespace to be used to
@ -305,19 +305,13 @@ actual search for the module, and releases it before execution, even if
References
==========
.. [1] Special __main__() function in modules
(http://www.python.org/dev/peps/pep-0299/)
.. [2] PEP 338 implementation (runpy module and ``-m`` update)
.. [2] :pep:`338` implementation (runpy module and ``-m`` update)
(https://bugs.python.org/issue1429601)
.. [3] execmodule Python Cookbook Recipe
(http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/307772)
.. [4] New import hooks
(http://www.python.org/dev/peps/pep-0302/)
.. [5] PEP 338 documentation (for runpy module)
.. [5] :pep:`338` documentation (for runpy module)
(https://bugs.python.org/issue1429605)
Copyright

2
pep-0339.txt
View File

@ -83,7 +83,7 @@ To tie all of this example, consider the rule for 'while'::
The node representing this will have ``TYPE(node) == while_stmt`` and
the number of children can be 4 or 7 depending on if there is an 'else'
statement. To access what should be the first ':' and require it be an
actual ':' token, `(REQ(CHILD(node, 2), COLON)``.
actual ':' token, ``(REQ(CHILD(node, 2), COLON)``.
Abstract Syntax Trees (AST)

18
pep-0340.txt
View File

@ -17,9 +17,9 @@ used for resource management purposes. The new statement type
is provisionally called the block-statement because the keyword
to be used has not yet been chosen.
This PEP competes with several other PEPs: PEP 288 (Generators
Attributes and Exceptions; only the second part), PEP 310
(Reliable Acquisition/Release Pairs), and PEP 325
This PEP competes with several other PEPs: :pep:`288` (Generators
Attributes and Exceptions; only the second part), :pep:`310`
(Reliable Acquisition/Release Pairs), and :pep:`325`
(Resource-Release Support for Generators).
I should clarify that using a generator to "drive" a block
@ -30,14 +30,14 @@ turned into a template). But the key idea is using a generator to
drive a block statement; the rest is elaboration, so I'd like to
keep these two parts together.
(PEP 342, Enhanced Iterators, was originally a part of this PEP;
(:pep:`342`, Enhanced Iterators, was originally a part of this PEP;
but the two proposals are really independent and with Steven
Bethard's help I have moved it to a separate PEP.)
Rejection Notice
================
I am rejecting this PEP in favor of PEP 343. See the motivational
I am rejecting this PEP in favor of :pep:`343`. See the motivational
section in that PEP for the reasoning behind this rejection. GvR.
Motivation and Summary
@ -62,7 +62,7 @@ controlled code more than once (or not at all), catch exceptions,
or receive data from the body of the block statement.
A convenient way to write block iterators is to write a generator
(PEP 255). A generator looks a lot like a Python function, but
(:pep:`255`). A generator looks a lot like a Python function, but
instead of returning a value immediately, generators pause their
execution at "yield" statements. When a generator is used as a
block iterator, the yield statement tells the Python interpreter
@ -115,7 +115,7 @@ assigned are still evaluated!).
The choice of the 'block' keyword is contentious; many
alternatives have been proposed, including not to use a keyword at
all (which I actually like). PEP 310 uses 'with' for similar
all (which I actually like). :pep:`310` uses 'with' for similar
semantics, but I would like to reserve that for a with-statement
similar to the one found in Pascal and VB. (Though I just found
that the C# designers don't like 'with' [2]_, and I have to agree
@ -380,7 +380,7 @@ there a use for that capability here?"
I believe there are definitely uses for this; several people have
already shown how to do asynchronous light-weight threads using
generators (e.g. David Mertz quoted in PEP 288, and Fredrik
generators (e.g. David Mertz quoted in :pep:`288`, and Fredrik
Lundh [3]_).
And finally, Greg says: "a thunk implementation has the potential
@ -398,7 +398,7 @@ that defeats the purpose of using thunks in the first place.)
Examples
========
(Several of these examples contain "yield None". If PEP 342 is
(Several of these examples contain "yield None". If :pep:`342` is
accepted, these can be changed to just "yield" of course.)
1. A template for ensuring that a lock, acquired at the start of a

20
pep-0342.txt
View File

@ -19,13 +19,13 @@ make them usable as simple coroutines. It is basically a combination of ideas
from these two PEPs, which may be considered redundant if this PEP is
accepted:
- PEP 288, Generators Attributes and Exceptions. The current PEP covers its
- :pep:`288`, Generators Attributes and Exceptions. The current PEP covers its
second half, generator exceptions (in fact the ``throw()`` method name was
taken from PEP 288). PEP 342 replaces generator attributes, however, with a
concept from an earlier revision of PEP 288, the *yield expression*.
taken from :pep:`288`). :pep:`342` replaces generator attributes, however, with a
concept from an earlier revision of :pep:`288`, the *yield expression*.
- PEP 325, Resource-Release Support for Generators. PEP 342 ties up a few
loose ends in the PEP 325 spec, to make it suitable for actual
- :pep:`325`, Resource-Release Support for Generators. :pep:`342` ties up a few
loose ends in the :pep:`325` spec, to make it suitable for actual
implementation.
@ -314,7 +314,7 @@ the generator should be released whenever its execution is terminated due to
an error or normal exit. This will ensure that generators that cannot be
resumed do not remain part of an uncollectable reference cycle. This allows
other code to potentially use ``close()`` in a ``try/finally`` or ``with``
block (per PEP 343) to ensure that a given generator is properly finalized.
block (per :pep:`343`) to ensure that a given generator is properly finalized.
Optional Extensions
@ -324,7 +324,7 @@ The Extended ``continue`` Statement
-----------------------------------
An earlier draft of this PEP proposed a new ``continue EXPR`` syntax for use
in for-loops (carried over from PEP 340), that would pass the value of
in for-loops (carried over from :pep:`340`), that would pass the value of
*EXPR* into the iterator being looped over. This feature has been withdrawn
for the time being, because the scope of this PEP has been narrowed to focus
only on passing values into generator-iterators, and not other kinds of
@ -344,7 +344,7 @@ reflects this preferred resolution.
I originally chose ``TypeError`` because it represents gross misbehavior of
the generator function, which should be fixed by changing the code. But the
``with_template`` decorator class in PEP 343 uses ``RuntimeError`` for
``with_template`` decorator class in :pep:`343` uses ``RuntimeError`` for
similar offenses. Arguably they should all use the same exception. I'd
rather not introduce a new exception class just for this purpose, since it's
not an exception that I want people to catch: I want it to turn into a
@ -579,11 +579,11 @@ This patch was committed to CVS 01-02 August 2005.
Acknowledgements
================
Raymond Hettinger (PEP 288) and Samuele Pedroni (PEP 325) first formally
Raymond Hettinger (:pep:`288`) and Samuele Pedroni (:pep:`325`) first formally
proposed the ideas of communicating values or exceptions into generators, and
the ability to *close* generators. Timothy Delaney suggested the title of this
PEP, and Steven Bethard helped edit a previous version. See also the
Acknowledgements section of PEP 340.
Acknowledgements section of :pep:`340`.
References

48
pep-0343.txt
View File

@ -40,8 +40,8 @@ originally in the future are now in the past :)
Introduction
============
After a lot of discussion about PEP 340 and alternatives, I
decided to withdraw PEP 340 and proposed a slight variant on PEP
After a lot of discussion about :pep:`340` and alternatives, I
decided to withdraw :pep:`340` and proposed a slight variant on PEP
310. After more discussion, I have added back a mechanism for
raising an exception in a suspended generator using a ``throw()``
method, and a ``close()`` method which throws a new GeneratorExit
@ -52,10 +52,10 @@ exception; these additions were first proposed on python-dev in
After acceptance of this PEP, the following PEPs were rejected due
to overlap:
- PEP 310, Reliable Acquisition/Release Pairs. This is the
- :pep:`310`, Reliable Acquisition/Release Pairs. This is the
original with-statement proposal.
- PEP 319, Python Synchronize/Asynchronize Block. Its use cases
- :pep:`319`, Python Synchronize/Asynchronize Block. Its use cases
can be covered by the current PEP by providing suitable
with-statement controllers: for 'synchronize' we can use the
"locking" template from example 1; for 'asynchronize' we can use
@ -64,7 +64,7 @@ to overlap:
important; in fact it may be better to always be explicit about
the mutex being used.
PEP 340 and PEP 346 also overlapped with this PEP, but were
:pep:`340` and :pep:`346` also overlapped with this PEP, but were
voluntarily withdrawn when this PEP was submitted.
Some discussion of earlier incarnations of this PEP took place on
@ -73,7 +73,7 @@ the Python Wiki [3]_.
Motivation and Summary
======================
PEP 340, Anonymous Block Statements, combined many powerful ideas:
:pep:`340`, Anonymous Block Statements, combined many powerful ideas:
using generators as block templates, adding exception handling and
finalization to generators, and more. Besides praise it received
a lot of opposition from people who didn't like the fact that it
@ -86,16 +86,16 @@ But the final blow came when I read Raymond Chen's rant about
flow-control macros [1]_. Raymond argues convincingly that hiding
flow control in macros makes your code inscrutable, and I find
that his argument applies to Python as well as to C. I realized
that PEP 340 templates can hide all sorts of control flow; for
that :pep:`340` templates can hide all sorts of control flow; for
example, its example 4 (``auto_retry()``) catches exceptions and
repeats the block up to three times.
However, the with-statement of PEP 310 does **not** hide control
However, the with-statement of :pep:`310` does **not** hide control
flow, in my view: while a finally-suite temporarily suspends the
control flow, in the end, the control flow resumes as if the
finally-suite wasn't there at all.
Remember, PEP 310 proposes roughly this syntax (the "VAR =" part is
Remember, :pep:`310` proposes roughly this syntax (the "VAR =" part is
optional)::
with VAR = EXPR:
@ -129,13 +129,13 @@ other exceptions; the nature of exceptions is that they can happen
write bug-free code, a KeyboardInterrupt exception can still cause
it to exit between any two virtual machine opcodes.)
This argument almost led me to endorse PEP 310, but I had one idea
left from the PEP 340 euphoria that I wasn't ready to drop: using
This argument almost led me to endorse :pep:`310`, but I had one idea
left from the :pep:`340` euphoria that I wasn't ready to drop: using
generators as "templates" for abstractions like acquiring and
releasing a lock or opening and closing a file is a powerful idea,
as can be seen by looking at the examples in that PEP.
Inspired by a counter-proposal to PEP 340 by Phillip Eby I tried
Inspired by a counter-proposal to :pep:`340` by Phillip Eby I tried
to create a decorator that would turn a suitable generator into an
object with the necessary ``__enter__()`` and ``__exit__()`` methods.
Here I ran into a snag: while it wasn't too hard for the locking
@ -155,7 +155,7 @@ and used it like this::
with f = opening(filename):
...read data from f...
The problem is that in PEP 310, the result of calling ``EXPR`` is
The problem is that in :pep:`310`, the result of calling ``EXPR`` is
assigned directly to ``VAR``, and then ``VAR``'s ``__exit__()`` method is
called upon exit from ``BLOCK1``. But here, ``VAR`` clearly needs to
receive the opened file, and that would mean that ``__exit__()`` would
@ -172,13 +172,13 @@ returns; the wrapper instance's ``__exit__()`` method calls ``next()``
again but expects it to raise StopIteration. (Details below in
the section Optional Generator Decorator.)
So now the final hurdle was that the PEP 310 syntax::
So now the final hurdle was that the :pep:`310` syntax::
with VAR = EXPR:
BLOCK1
would be deceptive, since ``VAR`` does **not** receive the value of
``EXPR``. Borrowing from PEP 340, it was an easy step to::
``EXPR``. Borrowing from :pep:`340`, it was an easy step to::
with EXPR as VAR:
BLOCK1
@ -217,7 +217,7 @@ not make the same guarantee. This applies to Jython, IronPython,
and probably to Python running on Parrot.
(The details of the changes made to generators can now be found in
PEP 342 rather than in the current PEP)
:pep:`342` rather than in the current PEP)
Use Cases
=========
@ -306,7 +306,7 @@ as if the body of the generator were expanded in-line at the place
of the with-statement.
The motivation for passing the exception details to ``__exit__()``, as
opposed to the argument-less ``__exit__()`` from PEP 310, was given by
opposed to the argument-less ``__exit__()`` from :pep:`310`, was given by
the ``transactional()`` use case, example 3 below. The template in
that example must commit or roll back the transaction depending on
whether an exception occurred or not. Rather than just having a
@ -361,7 +361,7 @@ and 'as' are always keywords.
Generator Decorator
===================
With PEP 342 accepted, it is possible to write a decorator
With :pep:`342` accepted, it is possible to write a decorator
that makes it possible to use a generator that yields exactly once
to control a with-statement. Here's a sketch of such a decorator::
@ -536,7 +536,7 @@ of any major objections on python-dev).
1. What exception should ``GeneratorContextManager`` raise when the
underlying generator-iterator misbehaves? The following quote is
the reason behind Guido's choice of ``RuntimeError`` for both this
and for the generator ``close()`` method in PEP 342 (from [8]_):
and for the generator ``close()`` method in :pep:`342` (from [8]_):
"I'd rather not introduce a new exception class just for this
purpose, since it's not an exception that I want people to catch:
@ -577,7 +577,7 @@ The ongoing problems [10]_ [13]_ with explaining what it was and why
it was and how it was meant to work eventually lead to Guido
killing the concept outright [15]_ (and there was much rejoicing!).
The notion of using the PEP 342 generator API directly to define
The notion of using the :pep:`342` generator API directly to define
the with statement was also briefly entertained [6]_, but quickly
dismissed as making it too difficult to write non-generator
based context managers.
@ -586,7 +586,7 @@ based context managers.
Examples
========
The generator based examples rely on PEP 342. Also, some of the
The generator based examples rely on :pep:`342`. Also, some of the
examples are unnecessary in practice, as the appropriate objects,
such as ``threading.RLock``, are able to be used directly in with
statements.
@ -820,7 +820,7 @@ refers to an action which is to be done in the ``__exit__`` method.
(Python 2.5's contextlib module contains a version
of this context manager)
11. PEP 319 gives a use case for also having a ``released()``
11. :pep:`319` gives a use case for also having a ``released()``
context to temporarily release a previously acquired lock;
this can be written very similarly to the locked context
manager above by swapping the ``acquire()`` and ``release()`` calls::
@ -906,8 +906,8 @@ Acknowledgements
================
Many people contributed to the ideas and concepts in this PEP,
including all those mentioned in the acknowledgements for PEP 340
and PEP 346.
including all those mentioned in the acknowledgements for :pep:`340`
and :pep:`346`.
Additional thanks goes to (in no meaningful order): Paul Moore,
Phillip J. Eby, Greg Ewing, Jason Orendorff, Michael Hudson,

6
pep-0344.txt
View File

@ -14,7 +14,7 @@ Post-History:
Numbering Note
==============
This PEP has been renumbered to PEP 3134. The text below is the last version
This PEP has been renumbered to :pep:`3134`. The text below is the last version
submitted under the old number.
@ -70,7 +70,7 @@ original exception.
Greg Ewing [4]_ and Guido van Rossum [5]_, and probably others, have
previously mentioned adding a traceback attribute to ``Exception`` instances.
This is noted in PEP 3000.
This is noted in :pep:`3000`.
This PEP was motivated by yet another recent Python-Dev reposting of the same
ideas [6]_ [7]_.
@ -463,7 +463,7 @@ Possible Future Compatible Changes
These changes are consistent with the appearance of exceptions as a single
object rather than a triple at the interpreter level.
- If PEP 340 or PEP 343 is accepted, replace the three (``type``, ``value``,
- If :pep:`340` or :pep:`343` is accepted, replace the three (``type``, ``value``,
``traceback``) arguments to ``__exit__`` with a single exception argument.
- Deprecate ``sys.exc_type``, ``sys.exc_value``, ``sys.exc_traceback``, and

33
pep-0345.txt
View File

@ -20,8 +20,8 @@ It includes specifics of the field names, and their semantics and
usage.
This document specifies version 1.2 of the metadata format.
Version 1.0 is specified in PEP 241.
Version 1.1 is specified in PEP 314.
Version 1.0 is specified in :pep:`241`.
Version 1.1 is specified in :pep:`314`.
Version 1.2 of the metadata format adds a number of optional fields
designed to make third-party packaging of Python Software easier.
@ -68,7 +68,7 @@ Version
:::::::
A string containing the distribution's version number. This
field must be in the format specified in PEP 440.
field must be in the format specified in :pep:`440`.
Example::
@ -127,10 +127,10 @@ field as-is. This means that authors should be conservative in
the markup they use.
To support empty lines and lines with indentation with respect to
the RFC 822 format, any CRLF character has to be suffixed by 7 spaces
the :rfc:`822` format, any CRLF character has to be suffixed by 7 spaces
followed by a pipe ("|") char. As a result, the Description field is
encoded into a folded field that can be interpreted by RFC822
parser [2]_.
encoded into a folded field that can be interpreted by :rfc:`822#section-3.1.1`
parser.
Example::
@ -145,7 +145,7 @@ Example::
This encoding implies that any occurrences of a CRLF followed by 7 spaces
and a pipe char have to be replaced by a single CRLF when the field is unfolded
using a RFC822 reader.
using a :rfc:`822` reader.
Keywords (optional)
@ -193,7 +193,7 @@ Author-email (optional)
:::::::::::::::::::::::
A string containing the author's e-mail address. It can contain
a name and e-mail address in the legal forms for a RFC-822
a name and e-mail address in the legal forms for a :rfc:`822`
``From:`` header.
Example::
@ -221,7 +221,7 @@ Maintainer-email (optional)
:::::::::::::::::::::::::::
A string containing the maintainer's e-mail address. It can contain
a name and e-mail address in the legal forms for a RFC-822
a name and e-mail address in the legal forms for a :rfc:`822`
``From:`` header.
Note that this field is intended for use when a project is being
@ -255,7 +255,7 @@ Classifier (multiple use)
:::::::::::::::::::::::::
Each entry is a string giving a single classification value
for the distribution. Classifiers are described in PEP 301 [3]_.
for the distribution. Classifiers are described in :pep:`301`.
Examples::
@ -371,7 +371,7 @@ parentheses.
Because they refer to non-Python software releases, version numbers
for this field are **not** required to conform to the format
specified in PEP 440: they should correspond to the
specified in :pep:`440`: they should correspond to the
version scheme used by the external dependency.
Notice that there's is no particular rule on the strings to be used.
@ -411,7 +411,7 @@ Any number of conditional operators can be specified, e.g.
the string ">1.0, !=1.3.4, <2.0" is a legal version declaration.
The comma (",") is equivalent to the **and** operator.
Each version number must be in the format specified in PEP 440.
Each version number must be in the format specified in :pep:`440`.
When a version is provided, it always includes all versions that
starts with the same value. For example, the "2.5" version of Python
@ -536,19 +536,14 @@ References
==========
This document specifies version 1.2 of the metadata format.
Version 1.0 is specified in PEP 241.
Version 1.1 is specified in PEP 314.
Version 1.0 is specified in :pep:`241`.
Version 1.1 is specified in :pep:`314`.
.. [1] reStructuredText markup:
http://docutils.sourceforge.net/
.. _`Python Package Index`: http://pypi.python.org/pypi/
.. [2] RFC 822 Long Header Fields:
http://www.freesoft.org/CIE/RFC/822/7.htm
.. [3] PEP 301, Package Index and Metadata for Distutils:
http://www.python.org/dev/peps/pep-0301/
Copyright
=========

98
pep-0346.txt
View File

@ -14,10 +14,10 @@ Post-History:
Abstract
========
This PEP is a combination of PEP 310's "Reliable Acquisition/Release
Pairs" with the "Anonymous Block Statements" of Guido's PEP 340. This
PEP aims to take the good parts of PEP 340, blend them with parts of
PEP 310 and rearrange the lot into an elegant whole. It borrows from
This PEP is a combination of :pep:`310`'s "Reliable Acquisition/Release
Pairs" with the "Anonymous Block Statements" of Guido's :pep:`340`. This
PEP aims to take the good parts of :pep:`340`, blend them with parts of
:pep:`310` and rearrange the lot into an elegant whole. It borrows from
various other PEPs in order to paint a complete picture, and is
intended to stand on its own.
@ -25,24 +25,24 @@ intended to stand on its own.
Author's Note
=============
During the discussion of PEP 340, I maintained drafts of this PEP as
During the discussion of :pep:`340`, I maintained drafts of this PEP as
PEP 3XX on my own website (since I didn't have CVS access to update a
submitted PEP fast enough to track the activity on python-dev).
Since the first draft of this PEP, Guido wrote PEP 343 as a simplified
version of PEP 340. PEP 343 (at the time of writing) uses the exact
Since the first draft of this PEP, Guido wrote :pep:`343` as a simplified
version of :pep:`340`. :pep:`343` (at the time of writing) uses the exact
same semantics for the new statements as this PEP, but uses a slightly
different mechanism to allow generators to be used to write statement
templates. However, Guido has indicated that he intends to accept a
new PEP being written by Raymond Hettinger that will integrate PEP 288
and PEP 325, and will permit a generator decorator like the one
new PEP being written by Raymond Hettinger that will integrate :pep:`288`
and :pep:`325`, and will permit a generator decorator like the one
described in this PEP to be used to write statement templates for PEP
343. The other difference was the choice of keyword ('with' versus
'do') and Guido has stated he will organise a vote on that in the
context of PEP 343.
context of :pep:`343`.
Accordingly, the version of this PEP submitted for archiving on
python.org is to be WITHDRAWN immediately after submission. PEP 343
python.org is to be WITHDRAWN immediately after submission. :pep:`343`
and the combined generator enhancement PEP will cover the important
ideas.
@ -58,51 +58,51 @@ a 'user defined statement', and the associated class definitions are
called 'statement templates'.
The above is the main point of the PEP. However, if that was all it
said, then PEP 310 would be sufficient and this PEP would be
said, then :pep:`310` would be sufficient and this PEP would be
essentially redundant. Instead, this PEP recommends additional
enhancements that make it natural to write these statement templates
using appropriately decorated generators. A side effect of those
enhancements is that it becomes important to appropriately deal
with the management of resources inside generators.
This is quite similar to PEP 343, but the exceptions that occur are
This is quite similar to :pep:`343`, but the exceptions that occur are
re-raised inside the generators frame, and the issue of generator
finalisation needs to be addressed as a result. The template
generator decorator suggested by this PEP also creates reusable
templates, rather than the single use templates of PEP 340.
templates, rather than the single use templates of :pep:`340`.
In comparison to PEP 340, this PEP eliminates the ability to suppress
In comparison to :pep:`340`, this PEP eliminates the ability to suppress
exceptions, and makes the user defined statement a non-looping
construct. The other main difference is the use of a decorator to
turn generators into statement templates, and the incorporation of
ideas for addressing iterator finalisation.
If all that seems like an ambitious operation. . . well, Guido was the
one to set the bar that high when he wrote PEP 340 :)
one to set the bar that high when he wrote :pep:`340` :)
Relationship with other PEPs
============================
This PEP competes directly with PEP 310 [1]_, PEP 340 [2]_ and PEP 343
[3]_, as those PEPs all describe alternative mechanisms for handling
This PEP competes directly with :pep:`310`, :pep:`340` and :pep:`343`,
as those PEPs all describe alternative mechanisms for handling
deterministic resource management.
It does not compete with PEP 342 [4]_ which splits off PEP 340's
It does not compete with :pep:`342` which splits off :pep:`340`'s
enhancements related to passing data into iterators. The associated
changes to the ``for`` loop semantics would be combined with the
iterator finalisation changes suggested in this PEP. User defined
statements would not be affected.
Neither does this PEP compete with the generator enhancements
described in PEP 288 [5]_. While this PEP proposes the ability to
described in :pep:`288`. While this PEP proposes the ability to
inject exceptions into generator frames, it is an internal
implementation detail, and does not require making that ability
publicly available to Python code. PEP 288 is, in part, about
publicly available to Python code. :pep:`288` is, in part, about
making that implementation detail easily accessible.
This PEP would, however, make the generator resource release support
described in PEP 325 [6]_ redundant - iterators which require
described in :pep:`325` redundant - iterators which require
finalisation should provide an appropriate implementation of the
statement template protocol.
@ -110,7 +110,7 @@ statement template protocol.
User defined statements
=======================
To steal the motivating example from PEP 310, correct handling of a
To steal the motivating example from :pep:`310`, correct handling of a
synchronisation lock currently looks like this::
the_lock.acquire()
@ -119,7 +119,7 @@ synchronisation lock currently looks like this::
finally:
the_lock.release()
Like PEP 310, this PEP proposes that such code be able to be written
Like :pep:`310`, this PEP proposes that such code be able to be written
as::
with the_lock:
@ -372,16 +372,16 @@ Accordingly, if this PEP is accepted, ``yield``, like ``return``, will
supply a default value of ``None`` (i.e. ``yield`` and ``yield None``
will become equivalent statements).
This same change is being suggested in PEP 342. Obviously, it would
This same change is being suggested in :pep:`342`. Obviously, it would
only need to be implemented once if both PEPs were accepted :)
Template generator decorator: ``statement_template``
----------------------------------------------------
As with PEP 343, a new decorator is suggested that wraps a generator
As with :pep:`343`, a new decorator is suggested that wraps a generator
in an object with the appropriate statement template semantics.
Unlike PEP 343, the templates suggested here are reusable, as the
Unlike :pep:`343`, the templates suggested here are reusable, as the
generator is instantiated anew in each call to ``__enter__()``.
Additionally, any exceptions that occur in ``BLOCK1`` are re-raised in
the generator's internal frame::
@ -756,7 +756,7 @@ Examples
with tag('a', href="http://www.python.org"):
print "Not a dead parrot!"
12. From PEP 343, another useful example would be an operation that
12. From :pep:`343`, another useful example would be an operation that
blocks signals. The use could be like this::
from signal import blocked_signals
@ -801,7 +801,7 @@ Rejected Options
Having the basic construct be a looping construct
-------------------------------------------------
The major issue with this idea, as illustrated by PEP 340's
The major issue with this idea, as illustrated by :pep:`340`'s
``block`` statements, is that it causes problems with factoring
``try`` statements that are inside loops, and contain ``break`` and
``continue`` statements (as these statements would then apply to the
@ -823,7 +823,7 @@ construct. With the current PEP, there is no such problem - ``for``
loops continue to be used for iteration, and the new ``do`` statements
are used to factor out exception handling.
Another issue, specifically with PEP 340's anonymous block statements,
Another issue, specifically with :pep:`340`'s anonymous block statements,
is that they make it quite difficult to write statement templates
directly (i.e. not using a generator). This problem is addressed by
the current proposal, as can be seen by the relative simplicity of the
@ -837,7 +837,7 @@ Allowing statement templates to suppress exceptions
Earlier versions of this PEP gave statement templates the ability to
suppress exceptions. The BDFL expressed concern over the associated
complexity, and I agreed after reading an article by Raymond Chen
about the evils of hiding flow control inside macros in C code [7]_.
about the evils of hiding flow control inside macros in C code [1]_.
Removing the suppression ability eliminated a whole lot of complexity
from both the explanation and implementation of user defined
@ -880,7 +880,7 @@ Differentiating between non-exceptional exits
Earlier versions of this PEP allowed statement templates to
distinguish between exiting the block normally, and exiting via a
``return``, ``break`` or ``continue`` statement. The BDFL flirted
with a similar idea in PEP 343 and its associated discussion. This
with a similar idea in :pep:`343` and its associated discussion. This
added significant complexity to the description of the semantics, and
it required each and every statement template to decide whether or not
those statements should be treated like exceptions, or like a normal
@ -899,7 +899,7 @@ template is concerned.
Not injecting raised exceptions into generators
-----------------------------------------------
PEP 343 suggests simply invoking next() unconditionally on generators
:pep:`343` suggests simply invoking next() unconditionally on generators
used to define statement templates. This means the template
generators end up looking rather unintuitive, and the retention of the
ban against yielding inside ``try``/``finally`` means that Python's
@ -937,17 +937,17 @@ generator objects to be used to implement generator finalisation.
Using ``do`` as the keyword
---------------------------
``do`` was an alternative keyword proposed during the PEP 340
``do`` was an alternative keyword proposed during the :pep:`340`
discussion. It reads well with appropriately named functions, but it
reads poorly when used with methods, or with objects that provide
native statement template support.
When ``do`` was first suggested, the BDFL had rejected PEP 310's
When ``do`` was first suggested, the BDFL had rejected :pep:`310`'s
``with`` keyword, based on a desire to use it for a Pascal/Delphi
style ``with`` statement. Since then, the BDFL has retracted this
objection, as he no longer intends to provide such a statement. This
change of heart was apparently based on the C# developers reasons for
not providing the feature [8]_.
not providing the feature [2]_.
Not having a keyword
@ -1251,9 +1251,9 @@ addition to the iterator protocol backwards compatible.
Acknowledgements
================
The acknowledgements section for PEP 340 applies, since this text grew
The acknowledgements section for :pep:`340` applies, since this text grew
out of the discussion of that PEP, but additional thanks go to Michael
Hudson, Paul Moore and Guido van Rossum for writing PEP 310 and PEP
Hudson, Paul Moore and Guido van Rossum for writing :pep:`310` and PEP
340 in the first place, and to (in no meaningful order) Fredrik Lundh,
Phillip J. Eby, Steven Bethard, Josiah Carlson, Greg Ewing, Tim
Delaney and Arnold deVos for prompting particular ideas that made
@ -1263,28 +1263,10 @@ their way into this text.
References
==========
.. [1] Reliable Acquisition/Release Pairs
(http://www.python.org/dev/peps/pep-0310/)
.. [2] Anonymous block statements
(http://www.python.org/dev/peps/pep-0340/)
.. [3] Anonymous blocks, redux
(http://www.python.org/dev/peps/pep-0343/)
.. [4] Enhanced Iterators
(http://www.python.org/dev/peps/pep-0342/)
.. [5] Generator Attributes and Exceptions
(http://www.python.org/dev/peps/pep-0288/)
.. [6] Resource-Release Support for Generators
(http://www.python.org/dev/peps/pep-0325/)
.. [7] A rant against flow control macros
.. [1] A rant against flow control macros
(http://blogs.msdn.com/oldnewthing/archive/2005/01/06/347666.aspx)
.. [8] Why doesn't C# have a 'with' statement?
.. [2] Why doesn't C# have a 'with' statement?
(http://msdn.microsoft.com/vcsharp/programming/language/ask/withstatement/)

22
pep-0348.txt
View File

@ -55,7 +55,7 @@ simplify catching them in ``except`` clauses. To allow people to
be able to rely on this hierarchy, a common superclass that all
raise objects must inherit from is being proposed. It also allows
guarantees about the interface to raised objects to be made (see
PEP 344 [#PEP344]_). A discussion about all of this has occurred
:pep:`344`). A discussion about all of this has occurred
before on python-dev [#Summary2004-08-01]_.
As bare ``except`` clauses stand now, they catch *all* exceptions.
@ -118,7 +118,7 @@ New Hierarchy
+-- BaseException (new; broader inheritance for subclasses)
+-- Exception
+-- GeneratorExit (defined in PEP 342 [#PEP342]_)
+-- GeneratorExit (defined in :pep:`342`)
+-- StandardError
+-- ArithmeticError
+-- DivideByZeroError
@ -221,7 +221,7 @@ Required Superclass for ``raise``
By requiring all objects passed to a ``raise`` statement to inherit
from a specific superclass, all exceptions are guaranteed to have
certain attributes. If PEP 344 [#PEP344]_ is accepted, the attributes
certain attributes. If :pep:`344` is accepted, the attributes
outlined there will be guaranteed to be on all exceptions raised.
This should help facilitate debugging by making the querying of
information from exceptions much easier.
@ -256,7 +256,7 @@ semantics are what most people want for bare ``except`` clauses.
The complete removal of bare ``except`` clauses has been argued for.
The case has been made that they violate both Only One Way To Do It
(OOWTDI) and Explicit Is Better Than Implicit (EIBTI) as listed in the
Zen of Python [#zen]_. But Practicality Beats Purity (PBP), also in
:pep:`Zen of Python <20>`. But Practicality Beats Purity (PBP), also in
the Zen of Python, trumps both of these in this case. The BDFL has
stated that bare ``except`` clauses will work this way
[#python-dev8]_.
@ -294,7 +294,7 @@ reflect several programming guidelines:
the inheritance from RuntimeError
The documentation for the 'exceptions' module [#exceptions-stdlib]_,
tutorial [#tutorial]_, and PEP 290 [#PEP290]_ will all require
tutorial [#tutorial]_, and :pep:`290` will all require
updating.
@ -446,15 +446,6 @@ discussion.
References
==========
.. [#PEP342] PEP 342 (Coroutines via Enhanced Generators)
http://www.python.org/dev/peps/pep-0342/
.. [#PEP344] PEP 344 (Exception Chaining and Embedded Tracebacks)
http://www.python.org/dev/peps/pep-0344/
.. [#PEP290] PEP 290 (Code Migration and Modernization)
http://www.python.org/dev/peps/pep-0290/
.. [#Summary2004-08-01] python-dev Summary (An exception is an
exception, unless it doesn't inherit from Exception)
http://www.python.org/dev/summary/2004-08-01_2004-08-15.html#an-exception-is-an-exception-unless-it-doesn-t-inherit-from-exception
@ -504,9 +495,6 @@ References
.. [#python-dev8] python-dev email (PEP 348 (exception reorg) revised again)
https://mail.python.org/pipermail/python-dev/2005-August/055423.html
.. [#zen] PEP 20 (The Zen of Python)
http://www.python.org/dev/peps/pep-0020/
.. [#tutorial] Python Tutorial
http://docs.python.org/tutorial/

Some files were not shown because too many files have changed in this diff Show More