diff --git a/pep-0001.txt b/pep-0001.txt index 657da71a4f1..b75f0a350cf 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -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. @@ -283,7 +283,7 @@ The final authority for PEP approval is the Steering Council. However, whenever a new PEP is put forward, any core developer that believes they are suitably experienced to make the final decision on that PEP may offer to serve as the PEP-Delegate for that PEP, and they will then have the -authority to approve (or reject) that PEP. +authority to approve (or reject) that PEP. The term "PEP-Delegate" is used under the Steering Council governance model. The PEP's designated decision maker, @@ -291,8 +291,8 @@ the "PEP-Delegate" with the Steering Council's support, is recorded in the "PEP-Delegate" field in the PEP's header. For PEPs written prior to the Steering Council's governance model, the field name "BDFL-Delegate" will still be kept. -The terms PEP-Delegate and BDFL-Delegate may be used interchangeably in -discussion. PEP-Delegate is the preferred term under the Steering Council +The terms PEP-Delegate and BDFL-Delegate may be used interchangeably in +discussion. PEP-Delegate is the preferred term under the Steering Council governance model. Individuals offering to serve as PEP-Delegate should notify the Steering @@ -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 `__. 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: diff --git a/pep-0002.txt b/pep-0002.txt index b4793217988..73928ad1cd2 100644 --- a/pep-0002.txt +++ b/pep-0002.txt @@ -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 diff --git a/pep-0003.txt b/pep-0003.txt index 2d0e9118e00..92e9c049b71 100644 --- a/pep-0003.txt +++ b/pep-0003.txt @@ -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). diff --git a/pep-0004.txt b/pep-0004.txt index 353f4563c48..d0b63625094 100644 --- a/pep-0004.txt +++ b/pep-0004.txt @@ -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. diff --git a/pep-0006.txt b/pep-0006.txt index 93cb72d8498..8a67e530fcc 100644 --- a/pep-0006.txt +++ b/pep-0006.txt @@ -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 ========= diff --git a/pep-0007.txt b/pep-0007.txt index c3ec7f37bf9..33766f5deb6 100644 --- a/pep-0007.txt +++ b/pep-0007.txt @@ -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 ========= diff --git a/pep-0008.txt b/pep-0008.txt index 3939cba1572..a3ea5b220c5 100644 --- a/pep-0008.txt +++ b/pep-0008.txt @@ -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 `_ -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 diff --git a/pep-0012.rst b/pep-0012.rst index f2fb41dbcdc..0ec4c1863f5 100644 --- a/pep-0012.rst +++ b/pep-0012.rst @@ -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 ========= diff --git a/pep-0013.rst b/pep-0013.rst index 03a0308549a..9c8442ea579 100644 --- a/pep-0013.rst +++ b/pep-0013.rst @@ -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 `__ 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. diff --git a/pep-0042.txt b/pep-0042.txt index 08ba663f95e..eeed0c96c3a 100644 --- a/pep-0042.txt +++ b/pep-0042.txt @@ -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 diff --git a/pep-0100.txt b/pep-0100.txt index f93b78292de..8684524993d 100644 --- a/pep-0100.txt +++ b/pep-0100.txt @@ -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 diff --git a/pep-0101.txt b/pep-0101.txt index 7b8528e1073..3b6a18ac570 100644 --- a/pep-0101.txt +++ b/pep-0101.txt @@ -548,52 +548,52 @@ the main repo. following feature release. When finished, the ``main`` branch will now build Python ``X.Y+1``. - - First, set main up to be the next release, i.e.X.Y+1.a0:: + - First, set main up to be the next release, i.e.X.Y+1.a0:: - $ git checkout main - $ .../release-tools/release.py --bump 3.9.0a0 + $ git checkout main + $ .../release-tools/release.py --bump 3.9.0a0 - - Edit all version references in README.rst + - Edit all version references in README.rst - - Move any historical "what's new" entries from ``Misc/NEWS`` to - ``Misc/HISTORY``. + - Move any historical "what's new" entries from ``Misc/NEWS`` to + ``Misc/HISTORY``. - - Edit ``Doc/tutorial/interpreter.rst`` (2 references to '[Pp]ython3x', - one to 'Python 3.x', also make the date in the banner consistent). + - Edit ``Doc/tutorial/interpreter.rst`` (2 references to '[Pp]ython3x', + one to 'Python 3.x', also make the date in the banner consistent). - - Edit ``Doc/tutorial/stdlib.rst`` and ``Doc/tutorial/stdlib2.rst``, which - have each one reference to '[Pp]ython3x'. + - Edit ``Doc/tutorial/stdlib.rst`` and ``Doc/tutorial/stdlib2.rst``, which + have each one reference to '[Pp]ython3x'. - - Add a new ``whatsnew/3.x.rst`` file (with the comment near the top - and the toplevel sections copied from the previous file) and - add it to the toctree in ``whatsnew/index.rst``. But beware that - the initial ``whatsnew/3.x.rst`` checkin from previous releases - may be incorrect due to the initial midstream change to ``blurb`` - that propagates from release to release! Help break the cycle: if - necessary make the following change:: + - Add a new ``whatsnew/3.x.rst`` file (with the comment near the top + and the toplevel sections copied from the previous file) and + add it to the toctree in ``whatsnew/index.rst``. But beware that + the initial ``whatsnew/3.x.rst`` checkin from previous releases + may be incorrect due to the initial midstream change to ``blurb`` + that propagates from release to release! Help break the cycle: if + necessary make the following change:: - - For full details, see the :source:`Misc/NEWS` file. - + For full details, see the :ref:`changelog `. + - For full details, see the :source:`Misc/NEWS` file. + + For full details, see the :ref:`changelog `. - - Update the version number in ``configure.ac`` and re-run ``autoconf``. + - Update the version number in ``configure.ac`` and re-run ``autoconf``. - - Make sure the ``SOURCE_URI`` in ``Doc/tools/extensions/pyspecific.py`` - points to ``main``. + - Make sure the ``SOURCE_URI`` in ``Doc/tools/extensions/pyspecific.py`` + points to ``main``. - - Update the version numbers for the Windows builds in PC/ and - PCbuild/, which have references to python38. - NOTE, check with Steve Dower about this step, it is probably obsolete.:: + - Update the version numbers for the Windows builds in PC/ and + PCbuild/, which have references to python38. + NOTE, check with Steve Dower about this step, it is probably obsolete.:: - $ find PC/ PCbuild/ -type f | xargs sed -i 's/python38/python39/g' - $ git mv -f PC/os2emx/python38.def PC/os2emx/python39.def - $ git mv -f PC/python38stub.def PC/python39stub.def - $ git mv -f PC/python38gen.py PC/python39gen.py + $ find PC/ PCbuild/ -type f | xargs sed -i 's/python38/python39/g' + $ git mv -f PC/os2emx/python38.def PC/os2emx/python39.def + $ git mv -f PC/python38stub.def PC/python39stub.def + $ git mv -f PC/python38gen.py PC/python39gen.py - - Commit these changes to the main branch:: + - Commit these changes to the main branch:: - $ git status - $ git add ... - $ git commit -m 'Bump to 3.9.0a0' + $ git status + $ git add ... + $ git commit -m 'Bump to 3.9.0a0' - Do another ``git status`` in this directory. diff --git a/pep-0102.txt b/pep-0102.txt index 5f7cff22aef..dc3f6455109 100644 --- a/pep-0102.txt +++ b/pep-0102.txt @@ -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 diff --git a/pep-0103.txt b/pep-0103.txt index ff3586e4799..c92469adc7b 100644 --- a/pep-0103.txt +++ b/pep-0103.txt @@ -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. diff --git a/pep-0200.txt b/pep-0200.txt index eb6297d4659..a29e6fd3aa5 100644 --- a/pep-0200.txt +++ b/pep-0200.txt @@ -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 diff --git a/pep-0201.txt b/pep-0201.txt index 9675bc6622d..802eb55650c 100644 --- a/pep-0201.txt +++ b/pep-0201.txt @@ -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 ===================== diff --git a/pep-0203.txt b/pep-0203.txt index 032ef0cc433..a85d4a777e5 100644 --- a/pep-0203.txt +++ b/pep-0203.txt @@ -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: diff --git a/pep-0204.txt b/pep-0204.txt index 1b3da169935..561e83295e2 100644 --- a/pep-0204.txt +++ b/pep-0204.txt @@ -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 - .. diff --git a/pep-0208.txt b/pep-0208.txt index b89e11cc673..6bee6b10872 100644 --- a/pep-0208.txt +++ b/pep-0208.txt @@ -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:: diff --git a/pep-0209.txt b/pep-0209.txt index 9358d6af94d..392c0828bd7 100644 --- a/pep-0209.txt +++ b/pep-0209.txt @@ -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 diff --git a/pep-0211.txt b/pep-0211.txt index d145d6de060..c0e4bc0dbac 100644 --- a/pep-0211.txt +++ b/pep-0211.txt @@ -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 diff --git a/pep-0212.txt b/pep-0212.txt index cf7ab8a8968..1ab3287359c 100644 --- a/pep-0212.txt +++ b/pep-0212.txt @@ -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: diff --git a/pep-0213.txt b/pep-0213.txt index adb484f33d8..fe7c9438aef 100644 --- a/pep-0213.txt +++ b/pep-0213.txt @@ -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:: diff --git a/pep-0218.txt b/pep-0218.txt index 27fe3ba6a03..03c39c72e77 100644 --- a/pep-0218.txt +++ b/pep-0218.txt @@ -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. diff --git a/pep-0219.txt b/pep-0219.txt index 48c9560cd38..64bed7b6e8f 100644 --- a/pep-0219.txt +++ b/pep-0219.txt @@ -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. diff --git a/pep-0225.txt b/pep-0225.txt index 23e8bb62514..4882a9a6afe 100644 --- a/pep-0225.txt +++ b/pep-0225.txt @@ -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 diff --git a/pep-0226.txt b/pep-0226.txt index a1a030c0259..f357b3329e6 100644 --- a/pep-0226.txt +++ b/pep-0226.txt @@ -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. diff --git a/pep-0227.txt b/pep-0227.txt index cca2defbf93..e74ec00cdc0 100644 --- a/pep-0227.txt +++ b/pep-0227.txt @@ -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, diff --git a/pep-0228.txt b/pep-0228.txt index 7469200ab44..9fcc8bab22f 100644 --- a/pep-0228.txt +++ b/pep-0228.txt @@ -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 diff --git a/pep-0231.txt b/pep-0231.txt index 2600bf82dc6..6e8d5d211f4 100644 --- a/pep-0231.txt +++ b/pep-0231.txt @@ -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 diff --git a/pep-0236.txt b/pep-0236.txt index 9cc4d3b44f5..f1043a3c0f0 100644 --- a/pep-0236.txt +++ b/pep-0236.txt @@ -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 diff --git a/pep-0238.txt b/pep-0238.txt index c415d6a6805..7d87cb40381 100644 --- a/pep-0238.txt +++ b/pep-0238.txt @@ -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 ========= diff --git a/pep-0239.txt b/pep-0239.txt index 0ccafaed87a..b56f4d89bee 100644 --- a/pep-0239.txt +++ b/pep-0239.txt @@ -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 diff --git a/pep-0240.txt b/pep-0240.txt index 3d5c40f5fa9..3b38fd31d40 100644 --- a/pep-0240.txt +++ b/pep-0240.txt @@ -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 diff --git a/pep-0241.txt b/pep-0241.txt index 9a99650ce9e..5f197892734 100644 --- a/pep-0241.txt +++ b/pep-0241.txt @@ -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 diff --git a/pep-0243.txt b/pep-0243.txt index 8352846a454..94b20b55aac 100644 --- a/pep-0243.txt +++ b/pep-0243.txt @@ -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: ``---``. -- ``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 ========= diff --git a/pep-0244.txt b/pep-0244.txt index c54924afeeb..9d1628884e7 100644 --- a/pep-0244.txt +++ b/pep-0244.txt @@ -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 ========= diff --git a/pep-0245.txt b/pep-0245.txt index 84fac96ed07..367b3f6392b 100644 --- a/pep-0245.txt +++ b/pep-0245.txt @@ -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/ diff --git a/pep-0246.txt b/pep-0246.txt index 7609d4a66e3..354b33944ce 100644 --- a/pep-0246.txt +++ b/pep-0246.txt @@ -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 diff --git a/pep-0251.txt b/pep-0251.txt index c7de8ad4ff0..ccc2f83f9d8 100644 --- a/pep-0251.txt +++ b/pep-0251.txt @@ -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 diff --git a/pep-0252.txt b/pep-0252.txt index ed250ec03ea..b23fa61a28c 100644 --- a/pep-0252.txt +++ b/pep-0252.txt @@ -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 diff --git a/pep-0253.txt b/pep-0253.txt index a3fb28e5ed1..c4410848e23 100644 --- a/pep-0253.txt +++ b/pep-0253.txt @@ -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 diff --git a/pep-0255.txt b/pep-0255.txt index 9add0610ed0..c6d94c8328f 100644 --- a/pep-0255.txt +++ b/pep-0255.txt @@ -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/ - -.. [6] The concept of iterators is described in PEP 234. See [1] above. - -.. [7] http://python.ca/nas/python/generator.diff +.. [3] http://www.cs.arizona.edu/icon/ -.. [8] PEP 236, Back to the __future__, Peters - http://www.python.org/dev/peps/pep-0236/ +.. [4] http://python.ca/nas/python/generator.diff -.. [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. diff --git a/pep-0256.txt b/pep-0256.txt index ccb5b715e42..c0b72e273e2 100644 --- a/pep-0256.txt +++ b/pep-0256.txt @@ -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 diff --git a/pep-0257.txt b/pep-0257.txt index c70aaa35967..92ab8221d35 100644 --- a/pep-0257.txt +++ b/pep-0257.txt @@ -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. diff --git a/pep-0258.txt b/pep-0258.txt index c6dc60099e2..ac925e26422 100644 --- a/pep-0258.txt +++ b/pep-0258.txt @@ -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 diff --git a/pep-0261.txt b/pep-0261.txt index 1614364e170..14ef780d46b 100644 --- a/pep-0261.txt +++ b/pep-0261.txt @@ -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. diff --git a/pep-0262.txt b/pep-0262.txt index d427e80c381..6b3c71a0ddf 100644 --- a/pep-0262.txt +++ b/pep-0262.txt @@ -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 diff --git a/pep-0264.txt b/pep-0264.txt index 77d94d26eb9..bb53e97a5a1 100644 --- a/pep-0264.txt +++ b/pep-0264.txt @@ -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()``. diff --git a/pep-0267.txt b/pep-0267.txt index 364eb0c1d80..f55d22d96e4 100644 --- a/pep-0267.txt +++ b/pep-0267.txt @@ -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 diff --git a/pep-0268.txt b/pep-0268.txt index a27d7e5178e..0d2b72debf7 100644 --- a/pep-0268.txt +++ b/pep-0268.txt @@ -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 diff --git a/pep-0269.txt b/pep-0269.txt index 10ddf64633a..45229076e21 100644 --- a/pep-0269.txt +++ b/pep-0269.txt @@ -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/ diff --git a/pep-0270.txt b/pep-0270.txt index ad8315718d6..2a5a790c98e 100644 --- a/pep-0270.txt +++ b/pep-0270.txt @@ -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. diff --git a/pep-0272.txt b/pep-0272.txt index d553872391e..b7e2df854b0 100644 --- a/pep-0272.txt +++ b/pep-0272.txt @@ -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 ======= diff --git a/pep-0273.txt b/pep-0273.txt index 5855a4562ae..7565d691e28 100644 --- a/pep-0273.txt +++ b/pep-0273.txt @@ -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 diff --git a/pep-0274.txt b/pep-0274.txt index 10e5639e710..7dd90d0ebd5 100644 --- a/pep-0274.txt +++ b/pep-0274.txt @@ -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 diff --git a/pep-0275.txt b/pep-0275.txt index 4922a2131d4..4b5d397f8e8 100644 --- a/pep-0275.txt +++ b/pep-0275.txt @@ -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 ========= diff --git a/pep-0276.txt b/pep-0276.txt index 37fa385a1f1..3fd0c6b4e5a 100644 --- a/pep-0276.txt +++ b/pep-0276.txt @@ -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 ========= diff --git a/pep-0279.txt b/pep-0279.txt index 8a12fbc41b3..aa617269fe9 100644 --- a/pep-0279.txt +++ b/pep-0279.txt @@ -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 ========= diff --git a/pep-0280.txt b/pep-0280.txt index 843d6d8fcde..3149b78e6bc 100644 --- a/pep-0280.txt +++ b/pep-0280.txt @@ -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 diff --git a/pep-0281.txt b/pep-0281.txt index 7d35a6ae832..ea8d386dc87 100644 --- a/pep-0281.txt +++ b/pep-0281.txt @@ -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 ========= diff --git a/pep-0283.txt b/pep-0283.txt index 0ee2c6d75a9..2d2ed5961a5 100644 --- a/pep-0283.txt +++ b/pep-0283.txt @@ -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 diff --git a/pep-0284.txt b/pep-0284.txt index 2d3355bdd15..48c476f2393 100644 --- a/pep-0284.txt +++ b/pep-0284.txt @@ -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 diff --git a/pep-0286.txt b/pep-0286.txt index 6010f597b88..ae6a15c6ed6 100644 --- a/pep-0286.txt +++ b/pep-0286.txt @@ -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. diff --git a/pep-0287.txt b/pep-0287.txt index d04c0f23205..1fdaa21c92e 100644 --- a/pep-0287.txt +++ b/pep-0287.txt @@ -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_. diff --git a/pep-0288.txt b/pep-0288.txt index 2640fde5497..b727c9e56f5 100644 --- a/pep-0288.txt +++ b/pep-0288.txt @@ -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 diff --git a/pep-0289.txt b/pep-0289.txt index e1d06fb75b7..312677b2c7e 100644 --- a/pep-0289.txt +++ b/pep-0289.txt @@ -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 diff --git a/pep-0290.txt b/pep-0290.txt index b364cf6b354..425d2b8c790 100644 --- a/pep-0290.txt +++ b/pep-0290.txt @@ -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 `__. 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 ========= diff --git a/pep-0292.txt b/pep-0292.txt index f4001d112f4..0aed5bae8cf 100644 --- a/pep-0292.txt +++ b/pep-0292.txt @@ -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 = , sys = -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 diff --git a/pep-0294.txt b/pep-0294.txt index 3558005b832..01a0e68d578 100644 --- a/pep-0294.txt +++ b/pep-0294.txt @@ -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 diff --git a/pep-0296.txt b/pep-0296.txt index cd580b6a755..22bb085af25 100644 --- a/pep-0296.txt +++ b/pep-0296.txt @@ -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 diff --git a/pep-0298.txt b/pep-0298.txt index 28cb1b0d9b7..a62eb6212fd 100644 --- a/pep-0298.txt +++ b/pep-0298.txt @@ -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 ========= diff --git a/pep-0301.txt b/pep-0301.txt index a8bb1259069..71e2eabbc75 100644 --- a/pep-0301.txt +++ b/pep-0301.txt @@ -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) diff --git a/pep-0302.txt b/pep-0302.txt index a998303652f..bdea0a363ec 100644 --- a/pep-0302.txt +++ b/pep-0302.txt @@ -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 diff --git a/pep-0304.txt b/pep-0304.txt index 51979da828b..e21ba570391 100644 --- a/pep-0304.txt +++ b/pep-0304.txt @@ -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) diff --git a/pep-0310.txt b/pep-0310.txt index 29fcf705d36..8275b211bdf 100644 --- a/pep-0310.txt +++ b/pep-0310.txt @@ -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. diff --git a/pep-0313.txt b/pep-0313.txt index 20b9ea46870..c516c614134 100644 --- a/pep-0313.txt +++ b/pep-0313.txt @@ -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 diff --git a/pep-0314.txt b/pep-0314.txt index 6355b4388fc..10930556560 100644 --- a/pep-0314.txt +++ b/pep-0314.txt @@ -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 ========= diff --git a/pep-0317.txt b/pep-0317.txt index f2a78ec1b8b..c2fcd32f26b 100644 --- a/pep-0317.txt +++ b/pep-0317.txt @@ -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 diff --git a/pep-0318.txt b/pep-0318.txt index ea62e16a3bb..056b1e1f471 100644 --- a/pep-0318.txt +++ b/pep-0318.txt @@ -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 ========= diff --git a/pep-0319.txt b/pep-0319.txt index 927e9dfc892..33b1258b28c 100644 --- a/pep-0319.txt +++ b/pep-0319.txt @@ -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 ========= diff --git a/pep-0320.txt b/pep-0320.txt index f46bd47bb0b..82b3be73f4f 100644 --- a/pep-0320.txt +++ b/pep-0320.txt @@ -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 diff --git a/pep-0321.txt b/pep-0321.txt index 6ff32db886d..28199dde539 100644 --- a/pep-0321.txt +++ b/pep-0321.txt @@ -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 diff --git a/pep-0323.txt b/pep-0323.txt index 632146be835..41c8d0c1f58 100644 --- a/pep-0323.txt +++ b/pep-0323.txt @@ -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 ========= diff --git a/pep-0325.txt b/pep-0325.txt index 7dcb2132b25..5bdf8cc78e6 100644 --- a/pep-0325.txt +++ b/pep-0325.txt @@ -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 ========= diff --git a/pep-0326.txt b/pep-0326.txt index 63445c1a1e3..0549eae73b1 100644 --- a/pep-0326.txt +++ b/pep-0326.txt @@ -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 diff --git a/pep-0327.txt b/pep-0327.txt index 7ca5584fbac..17c63de1b25 100644 --- a/pep-0327.txt +++ b/pep-0327.txt @@ -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? diff --git a/pep-0329.txt b/pep-0329.txt index 50d76f47940..8c5e7e1b987 100644 --- a/pep-0329.txt +++ b/pep-0329.txt @@ -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 diff --git a/pep-0331.txt b/pep-0331.txt index 002b34000c0..4b1ffc990c6 100644 --- a/pep-0331.txt +++ b/pep-0331.txt @@ -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 diff --git a/pep-0333.txt b/pep-0333.txt index 37583fb9dec..5372f2ab3b7 100644 --- a/pep-0333.txt +++ b/pep-0333.txt @@ -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) diff --git a/pep-0334.txt b/pep-0334.txt index 0fcd2e914af..519924a6c9b 100644 --- a/pep-0334.txt +++ b/pep-0334.txt @@ -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) diff --git a/pep-0337.txt b/pep-0337.txt index 0f05b69ffb5..8c431d6aafd 100644 --- a/pep-0337.txt +++ b/pep-0337.txt @@ -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 diff --git a/pep-0338.txt b/pep-0338.txt index 678b94e6ba3..82341da1a42 100644 --- a/pep-0338.txt +++ b/pep-0338.txt @@ -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 diff --git a/pep-0339.txt b/pep-0339.txt index eefa01ad29c..f023cda569d 100644 --- a/pep-0339.txt +++ b/pep-0339.txt @@ -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) diff --git a/pep-0340.txt b/pep-0340.txt index f6739ee5607..8c908e7c8df 100644 --- a/pep-0340.txt +++ b/pep-0340.txt @@ -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 diff --git a/pep-0342.txt b/pep-0342.txt index 0c9763d6c2e..4570a1bd1af 100644 --- a/pep-0342.txt +++ b/pep-0342.txt @@ -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 diff --git a/pep-0343.txt b/pep-0343.txt index 787173cd2dc..d7a35652708 100644 --- a/pep-0343.txt +++ b/pep-0343.txt @@ -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, diff --git a/pep-0344.txt b/pep-0344.txt index 5150f60dfdd..c2c4f0efb02 100644 --- a/pep-0344.txt +++ b/pep-0344.txt @@ -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 diff --git a/pep-0345.txt b/pep-0345.txt index 5f73afeda52..0643ecfeb47 100644 --- a/pep-0345.txt +++ b/pep-0345.txt @@ -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 ========= diff --git a/pep-0346.txt b/pep-0346.txt index 2e0ce4f3d6e..4666ff6c91c 100644 --- a/pep-0346.txt +++ b/pep-0346.txt @@ -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/) diff --git a/pep-0348.txt b/pep-0348.txt index 866710d05fa..d722290471b 100644 --- a/pep-0348.txt +++ b/pep-0348.txt @@ -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/ diff --git a/pep-0351.txt b/pep-0351.txt index 0178a78860d..5923d1b0522 100644 --- a/pep-0351.txt +++ b/pep-0351.txt @@ -41,7 +41,7 @@ and immutable counterparts, and it would be useful to have a standard protocol for conversion of such objects. sets.Set objects expose a "protocol for automatic conversion to -immutable" so that you can create sets.Sets of sets.Sets. PEP 218 +immutable" so that you can create sets.Sets of sets.Sets. :pep:`218` deliberately dropped this feature from built-in sets. This PEP advances that the feature is still useful and proposes a standard mechanism for its support. diff --git a/pep-0352.txt b/pep-0352.txt index 3065a21cd8c..1bb21d10956 100644 --- a/pep-0352.txt +++ b/pep-0352.txt @@ -45,7 +45,7 @@ from the common superclass instead of Exception will make it easy for people to write ``except`` clauses that are not overreaching and not catch exceptions that should propagate up. -This PEP is based on previous work done for PEP 348 [#pep348]_. +This PEP is based on previous work done for :pep:`348`. Requiring a Common Superclass @@ -272,9 +272,6 @@ original deprecation of ``args`` has been retracted. References ========== -.. [#pep348] PEP 348 (Exception Reorganization for Python 3.0) - http://www.python.org/dev/peps/pep-0348/ - .. [#hierarchy-good] python-dev Summary for 2004-08-01 through 2004-08-15 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 diff --git a/pep-0354.txt b/pep-0354.txt index 5f9aab091f0..360aabdad67 100644 --- a/pep-0354.txt +++ b/pep-0354.txt @@ -22,7 +22,7 @@ modules. Also, the PEP has generated no widespread interest. For those who need enumerations, there are cookbook recipes and PyPI packages that meet these needs. -*Note: this PEP was superseded by PEP 435, which has been accepted in +*Note: this PEP was superseded by* :pep:`435`, *which has been accepted in May 2013.* Abstract diff --git a/pep-0356.txt b/pep-0356.txt index 1e02cecbdc4..28db5149fae 100644 --- a/pep-0356.txt +++ b/pep-0356.txt @@ -50,18 +50,18 @@ Release Schedule Completed features for 2.5 ========================== -- PEP 308: Conditional Expressions -- PEP 309: Partial Function Application -- PEP 314: Metadata for Python Software Packages v1.1 -- PEP 328: Absolute/Relative Imports -- PEP 338: Executing Modules as Scripts -- PEP 341: Unified try-except/try-finally to try-except-finally -- PEP 342: Coroutines via Enhanced Generators -- PEP 343: The "with" Statement (still need updates in Doc/ref and for the +- :pep:`308`: Conditional Expressions +- :pep:`309`: Partial Function Application +- :pep:`314`: Metadata for Python Software Packages v1.1 +- :pep:`328`: Absolute/Relative Imports +- :pep:`338`: Executing Modules as Scripts +- :pep:`341`: Unified try-except/try-finally to try-except-finally +- :pep:`342`: Coroutines via Enhanced Generators +- :pep:`343`: The "with" Statement (still need updates in Doc/ref and for the ``contextlib`` module) -- PEP 352: Required Superclass for Exceptions -- PEP 353: Using ``ssize_t`` as the index type -- PEP 357: Allowing Any Object to be Used for Slicing +- :pep:`352`: Required Superclass for Exceptions +- :pep:`353`: Using ``ssize_t`` as the index type +- :pep:`357`: Allowing Any Object to be Used for Slicing - ASCII became the default coding @@ -97,7 +97,7 @@ Other notable features: - Added support for the Unicode 4.1 UCD -- Added PEP 302 ``zipfile``/``__loader__`` support to the following modules: +- Added :pep:`302` ``zipfile``/``__loader__`` support to the following modules: ``warnings``, ``linecache``, ``inspect``, ``traceback``, ``site``, and ``doctest`` @@ -171,7 +171,7 @@ Open issues * https://bugs.python.org/issue1467929 - %-formatting and dicts * https://bugs.python.org/issue1446043 - ``unicode()`` does not raise ``LookupError`` -- The PEP 302 changes to (at least) ``pkgutil``, ``runpy`` and ``pydoc`` must +- The :pep:`302` changes to (at least) ``pkgutil``, ``runpy`` and ``pydoc`` must be documented. - ``test_zipfile64`` takes too long and too much disk space for diff --git a/pep-0358.txt b/pep-0358.txt index 01ba06acd1e..feffd98155b 100644 --- a/pep-0358.txt +++ b/pep-0358.txt @@ -14,7 +14,7 @@ Post-History: Update ====== -This PEP has partially been superseded by PEP 3137. +This PEP has partially been superseded by :pep:`3137`. Abstract @@ -190,7 +190,7 @@ Out of Scope Issues byte arrays. This decision is out of scope. * A bytes literal of the form ``b"..."`` is also proposed. This is - the subject of PEP 3112. + the subject of :pep:`3112`. Open Issues diff --git a/pep-0361.txt b/pep-0361.txt index f87782e35b1..6dff21cd5ba 100644 --- a/pep-0361.txt +++ b/pep-0361.txt @@ -89,7 +89,7 @@ Release Schedule Completed features for 3.0 ========================== -See PEP 3000 [pep3000]_ and PEP 3100 [pep3100]_ for details on the +See :pep:`3000` and :pep:`3100` for details on the Python 3.0 project. @@ -98,15 +98,15 @@ Completed features for 2.6 PEPs: -- 352: Raising a string exception now triggers a ``TypeError``. +- :pep:`352`: Raising a string exception now triggers a ``TypeError``. Attempting to catch a string exception raises ``DeprecationWarning``. - ``BaseException.message`` has been deprecated. [pep352]_ -- 358: The "bytes" Object [pep358]_ -- 366: Main module explicit relative imports [pep366]_ -- 370: Per user site-packages directory [pep370]_ -- 3112: Bytes literals in Python 3000 [pep3112]_ -- 3127: Integer Literal Support and Syntax [pep3127]_ -- 371: Addition of the multiprocessing package [pep371]_ + ``BaseException.message`` has been deprecated. +- :pep:`358`: The "bytes" Object +- :pep:`366`: Main module explicit relative imports +- :pep:`370`: Per user site-packages directory +- :pep:`3112`: Bytes literals in Python 3000 +- :pep:`3127`: Integer Literal Support and Syntax +- :pep:`371`: Addition of the multiprocessing package New modules in the standard library: @@ -145,7 +145,7 @@ Warnings for features removed in Py3k: - ``{}.has_key()`` - ``file.xreadlines`` - softspace removal for ``print()`` function -- removal of modules because of PEP 4/3100/3108 +- removal of modules because of :pep:`4`/:pep:`3100`/:pep:`3108` Other major features: @@ -273,36 +273,6 @@ References .. [1] Adding a __dir__() magic method https://mail.python.org/pipermail/python-dev/2006-July/067139.html -.. [pep352] PEP 352 (Required Superclass for Exceptions) - http://www.python.org/dev/peps/pep-0352 - -.. [pep358] PEP 358 (The "bytes" Object) - http://www.python.org/dev/peps/pep-0358 - -.. [pep366] PEP 366 (Main module explicit relative imports) - http://www.python.org/dev/peps/pep-0366 - -.. [pep367] PEP 367 (New Super) - http://www.python.org/dev/peps/pep-0367 - -.. [pep370] PEP 370 (Per user site-packages directory) - http://www.python.org/dev/peps/pep-0370 - -.. [pep371] PEP 371 (Addition of the multiprocessing package) - http://www.python.org/dev/peps/pep-0371 - -.. [pep3000] PEP 3000 (Python 3000) - http://www.python.org/dev/peps/pep-3000 - -.. [pep3100] PEP 3100 (Miscellaneous Python 3.0 Plans) - http://www.python.org/dev/peps/pep-3100 - -.. [pep3112] PEP 3112 (Bytes literals in Python 3000) - http://www.python.org/dev/peps/pep-3112 - -.. [pep3127] PEP 3127 (Integer Literal Support and Syntax) - http://www.python.org/dev/peps/pep-3127 - .. _Google calendar: http://www.google.com/calendar/ical/b6v58qvojllt0i6ql654r1vh00%40group.calendar.google.com/public/basic.ics diff --git a/pep-0362.txt b/pep-0362.txt index 9fdf9d01ace..85e3d22220d 100644 --- a/pep-0362.txt +++ b/pep-0362.txt @@ -545,7 +545,7 @@ Annotation Checker Acceptance ========== -PEP 362 was accepted by Guido, Friday, June 22, 2012 [#accepted]_ . +:pep:`362` was accepted by Guido, Friday, June 22, 2012 [#accepted]_ . The reference implementation was committed to trunk later that day. diff --git a/pep-0364.txt b/pep-0364.txt index 80acf77a9f2..0210ad5caec 100644 --- a/pep-0364.txt +++ b/pep-0364.txt @@ -14,8 +14,8 @@ Post-History: Abstract ======== -PEP 3108 describes the reorganization of the Python standard library -for the Python 3.0 release [1]_. This PEP describes a +:pep:`3108` describes the reorganization of the Python standard library +for the Python 3.0 release. This PEP describes a mechanism for transitioning from the Python 2.x standard library to the Python 3.0 standard library. This transition will allow and encourage Python programmers to use the new Python 3.0 library names @@ -28,22 +28,22 @@ existing Python programs. Rationale ========= -PEP 3108 presents a rationale for Python standard library (stdlib) +:pep:`3108` presents a rationale for Python standard library (stdlib) reorganization. The reader is encouraged to consult that PEP for details about why and how the library will be reorganized. Should -PEP 3108 be accepted in part or in whole, then it is advantageous to +:pep:`3108` be accepted in part or in whole, then it is advantageous to allow Python programmers to begin the transition to the new stdlib module names in Python 2.x, so that they can write forward compatible code starting with Python 2.6. -Note that PEP 3108 proposes to remove some "silly old stuff", +Note that :pep:`3108` proposes to remove some "silly old stuff", i.e. modules that are no longer useful or necessary. The PEP you are reading does not address this because there are no forward compatibility issues for modules that are to be removed, except to stop using such modules. This PEP concerns only the mechanism by which mappings from old stdlib -names to new stdlib names are maintained. Please consult PEP 3108 for +names to new stdlib names are maintained. Please consult :pep:`3108` for all specific module renaming proposals. Specifically see the section titled ``Modules to Rename`` for guidelines on the old name to new name mappings. The few examples in this PEP are given for @@ -70,8 +70,8 @@ Two use cases supported by this PEP include renaming simple top-level modules, such as ``StringIO``, as well as modules within packages, such as ``email.MIMEText``. -In the former case, PEP 3108 currently recommends ``StringIO`` be -renamed to ``stringio``, following PEP 8 recommendations [2]_. +In the former case, :pep:`3108` currently recommends ``StringIO`` be +renamed to ``stringio``, following :pep:`8` recommendations. In the latter case, the email 4.0 package distributed with Python 2.5 already renamed ``email.MIMEText`` to ``email.mime.text``, although it @@ -120,13 +120,13 @@ Implementation Specification This section provides the full specification for how module renamings in Python 2.x are implemented. The central mechanism relies on -various import hooks as described in PEP 302 [3]_. Specifically +various import hooks as described in :pep:`302`. Specifically ``sys.path_importer_cache``, ``sys.path``, and ``sys.meta_path`` are all employed to provide the necessary functionality. When Python's import machinery is initialized, the oldlib package is imported. Inside oldlib there is a class called ``OldStdlibLoader``. -This class implements the PEP 302 interface and is automatically +This class implements the :pep:`302` interface and is automatically instantiated, with zero arguments. The constructor reads all the ``.mv`` files from the oldlib package directory, automatically registering all the remappings found in those ``.mv`` files. This is @@ -137,7 +137,7 @@ modules. Instead, you can access the global OldStdlibLoader instance via the ``sys.stdlib_remapper`` instance. Use this instance if you want programmatic access to the remapping machinery. -One important implementation detail: as needed by the PEP 302 API, a +One important implementation detail: as needed by the :pep:`302` API, a magic string is added to sys.path, and module __path__ attributes in order to hook in our remapping loader. This magic string is currently ```` and some changes were necessary to Python's site.py file @@ -230,25 +230,16 @@ Reference Implementation A reference implementation, in the form of a patch against the current (as of this writing) state of the Python 2.6 svn trunk, is available -as SourceForge patch #1675334 [4]_. Note that this patch includes a +as SourceForge patch #1675334 [1]_. Note that this patch includes a rename of ``cStringIO`` to ``cstringio``, but this is primarily for illustrative and unit testing purposes. Should the patch be accepted, -we might want to split this change off into other PEP 3108 changes. +we might want to split this change off into other :pep:`3108` changes. References ========== -.. [1] PEP 3108, Standard Library Reorganization, Cannon - (http://www.python.org/dev/peps/pep-3108) - -.. [2] PEP 8, Style Guide for Python Code, GvR, Warsaw - (http://www.python.org/dev/peps/pep-0008) - -.. [3] PEP 302, New Import Hooks, JvR, Moore - (http://www.python.org/dev/peps/pep-0302) - -.. [4] Reference implementation +.. [1] Reference implementation (http://bugs.python.org/issue1675334) Copyright diff --git a/pep-0366.txt b/pep-0366.txt index 302835919fd..f0c3156a3cd 100644 --- a/pep-0366.txt +++ b/pep-0366.txt @@ -17,7 +17,7 @@ Abstract This PEP proposes a backwards compatible mechanism that permits the use of explicit relative imports from executable modules within packages. Such imports currently fail due to an awkward interaction -between PEP 328 and PEP 338. +between :pep:`328` and :pep:`338`. By adding a new module level attribute, this PEP allows relative imports to work automatically if the module is executed using the ``-m`` switch. @@ -35,7 +35,7 @@ be based on this attribute rather than the module ``__name__`` attribute. As with the current ``__name__`` attribute, setting ``__package__`` will -be the responsibility of the PEP 302 loader used to import a module. +be the responsibility of the :pep:`302` loader used to import a module. Loaders which use ``imp.new_module()`` to create the module object will have the new attribute set automatically to ``None``. When the import system encounters an explicit relative import in a module without @@ -91,7 +91,7 @@ This PEP is intended to provide a solution which permits explicit relative imports from main modules, without incurring any significant costs during interpreter startup or normal module import. -The section in PEP 338 on relative imports and the main module provides +The section in :pep:`338` on relative imports and the main module provides further details and background on this problem. @@ -108,7 +108,7 @@ Patch 1487 [4] is the proposed implementation for this PEP. Alternative Proposals ===================== -PEP 3122 proposed addressing this problem by changing the way +:pep:`3122` proposed addressing this problem by changing the way the main module is identified. That's a significant compatibility cost to incur to fix something that is a pretty minor bug in the overall scheme of things, and the PEP was rejected [3]_. diff --git a/pep-0367.txt b/pep-0367.txt index 718698c53a4..a70e59f72cb 100644 --- a/pep-0367.txt +++ b/pep-0367.txt @@ -14,7 +14,7 @@ Post-History: 28-Apr-2007, 29-Apr-2007 (1), 29-Apr-2007 (2), 14-May-2007 Numbering Note ============== -This PEP has been renumbered to PEP 3135. The text below is the last +This PEP has been renumbered to :pep:`3135`. The text below is the last version submitted under the old number. Abstract diff --git a/pep-0368.txt b/pep-0368.txt index 82b030a817d..319e7bf6ad2 100644 --- a/pep-0368.txt +++ b/pep-0368.txt @@ -492,7 +492,7 @@ Non-planar images offer the following additional methods: The ``mode``, ``size`` and ``buffer`` (including the address in memory of the ``buffer``) never change after an image is created. -It is expected that, if PEP 3118 is accepted, all the image objects +It is expected that, if :pep:`3118` is accepted, all the image objects will support the new buffer protocol, however this is beyond the scope of this PEP. @@ -797,7 +797,7 @@ compatibility should be considered: functionality, so no major compatibility issues are expected. * **Python 3.0**: the legacy contents of the ``imageop`` module will - be deleted, according to PEP 3108; everything defined in this + be deleted, according to :pep:`3108`; everything defined in this proposal will work like in Python 2.x with the exception of the usual 2.x/3.0 differences (e.g. support for ``long`` integers and for interpreting ``str`` instances as sequences of bytes will be diff --git a/pep-0369.txt b/pep-0369.txt index 6c40112a9b1..40caa8c663c 100644 --- a/pep-0369.txt +++ b/pep-0369.txt @@ -34,7 +34,7 @@ Rationale ========= Python has no API to hook into the import machinery and execute code -*after* a module is successfully loaded. The import hooks of PEP 302 are +*after* a module is successfully loaded. The import hooks of :pep:`302` are about finding modules and loading modules but they were not designed to as post import hooks. diff --git a/pep-0371.txt b/pep-0371.txt index 6b197cf4c03..0b2a32df2ec 100644 --- a/pep-0371.txt +++ b/pep-0371.txt @@ -56,7 +56,7 @@ their programming paradigm (i.e.: dropping threaded programming for another "concurrent" approach - Twisted, Actors, etc). The Processing package offers CPython a "known API" which mirrors -albeit in a PEP 8 compliant manner, that of the threading API, +albeit in a :pep:`8` compliant manner, that of the threading API, with known semantics and easy scalability. In the future, the package might not be as relevant should the @@ -82,7 +82,7 @@ simple change of the import to:: from processing import process as worker The code would now execute through the processing.process class. -Obviously, with the renaming of the API to PEP 8 compliance there +Obviously, with the renaming of the API to :pep:`8` compliance there would be additional renaming which would need to occur within user applications, however minor. @@ -331,9 +331,9 @@ API Naming While the aim of the package's API is designed to closely mimic that of the threading and ``Queue`` modules as of python 2.x, those modules are not -PEP 8 compliant. It has been decided that instead of adding the package -"as is" and therefore perpetuating the non-PEP 8 compliant naming, we -will rename all APIs, classes, etc to be fully PEP 8 compliant. +:pep:`8` compliant. It has been decided that instead of adding the package +"as is" and therefore perpetuating the non-:pep:`8` compliant naming, we +will rename all APIs, classes, etc to be fully :pep:`8` compliant. This change does affect the ease-of-drop in replacement for those using the threading module, but that is an acceptable side-effect in the view @@ -341,11 +341,11 @@ of the authors, especially given that the threading module's own API will change. Issue 3042 in the tracker proposes that for Python 2.6 there will be -two APIs for the threading module - the current one, and the PEP 8 +two APIs for the threading module - the current one, and the :pep:`8` compliant one. Warnings about the upcoming removal of the original java-style API will be issued when -3 is invoked. -In Python 3000, the threading API will become PEP 8 compliant, which +In Python 3000, the threading API will become :pep:`8` compliant, which means that the multiprocessing module and the threading module will again have matching APIs. diff --git a/pep-0372.txt b/pep-0372.txt index ffd102fc0dd..30608d232f3 100644 --- a/pep-0372.txt +++ b/pep-0372.txt @@ -69,7 +69,7 @@ situations: Additionally, many ordered dicts are implemented in an inefficient way, making many operations more complex then they have to be. -- PEP 3115 allows metaclasses to change the mapping object used for +- :pep:`3115` allows metaclasses to change the mapping object used for the class body. An ordered dict could be used to create ordered member declarations similar to C structs. This could be useful, for example, for future ``ctypes`` releases as well as ORMs that define diff --git a/pep-0373.txt b/pep-0373.txt index 2adcb8149c7..c330ee4d407 100644 --- a/pep-0373.txt +++ b/pep-0373.txt @@ -28,14 +28,14 @@ Update (April 2014) The End Of Life date (EOL, sunset date) for Python 2.7 has been moved five years into the future, to 2020. This decision was made to clarify the status of Python 2.7 and relieve worries for those users -who cannot yet migrate to Python 3. See also PEP 466. +who cannot yet migrate to Python 3. See also :pep:`466`. This declaration does not guarantee that bugfix releases will be made on a regular basis, but it should enable volunteers who want to contribute bugfixes for Python 2.7 and it should satisfy vendors who still have to support Python 2 for years to come. -There will be no Python 2.8 (see PEP 404). +There will be no Python 2.8 (see :pep:`404`). Release Manager and Crew diff --git a/pep-0374.txt b/pep-0374.txt index e41ffbfdbfe..6ee1c1ca5b6 100644 --- a/pep-0374.txt +++ b/pep-0374.txt @@ -663,7 +663,7 @@ hg git ''' We assume a patch created by git-format-patch. This is a Unix mbox -file containing one or more patches, each formatted as an RFC 2822 +file containing one or more patches, each formatted as an :rfc:`2822` message. git-am interprets each message as a commit as follows. The author of the patch is taken from the From: header, the date from the Date header. The commit log is created by concatenating the content @@ -1101,7 +1101,7 @@ looms. Doing a Python Release ---------------------- -How does PEP 101 change when using a DVCS? +How does :pep:`101` change when using a DVCS? bzr @@ -1122,7 +1122,7 @@ release off the bzr/hg mirrors. hg '' -Clearly, details specific to Subversion in PEP 101 and in the +Clearly, details specific to Subversion in :pep:`101` and in the release script will need to be updated. In particular, release tagging and maintenance branches creation process will have to be modified to use Mercurial's features; this will simplify and @@ -1508,7 +1508,7 @@ was to be the next version control system for Python. Transition Plan =============== -PEP 385 outlines the transition from svn to hg. +:pep:`385` outlines the transition from svn to hg. Copyright diff --git a/pep-0375.txt b/pep-0375.txt index b3095125143..26b958b15c0 100644 --- a/pep-0375.txt +++ b/pep-0375.txt @@ -67,7 +67,7 @@ Features for 3.1 - importlib - io in C - Update simplejson to the latest external version [#simplejson]_. -- Ordered dictionary for collections [#ordered]_. +- Ordered dictionary for collections (:pep:`372`). - auto-numbered replacement fields in str.format() strings [#strformat]_ - Nested with-statements in one with statement @@ -78,9 +78,6 @@ Footnotes .. [#simplejson] http://bugs.python.org/issue4136 -.. [#ordered] PEP 372 - http://www.python.org/dev/peps/pep-0372/ - .. [#strformat] http://bugs.python.org/issue5237 diff --git a/pep-0376.txt b/pep-0376.txt index 82481aadad4..9372c8b9443 100644 --- a/pep-0376.txt +++ b/pep-0376.txt @@ -21,10 +21,10 @@ To achieve this goal, the PEP proposes a new format to describe installed distributions on a system. It also describes a reference implementation for the standard library. -In the past an attempt was made to create an installation database (see PEP 262 -[#pep262]_). +In the past an attempt was made to create an installation database (see :pep:`262` +). -Combined with PEP 345, the current proposal supersedes PEP 262. +Combined with :pep:`345`, the current proposal supersedes :pep:`262`. Note: the implementation plan didn't go as expected, so it should be considered informative only for this PEP. @@ -61,7 +61,7 @@ extra module and executable scripts, three elements are installed in - ``docutils``: The ``docutils`` package. - ``roman.py``: An extra module used by ``docutils``. - ``docutils-0.5-py2.6.egg-info``: A file containing the distribution metadata - as described in PEP 314 [#pep314]_. This file corresponds to the file + as described in :pep:`314`. This file corresponds to the file called ``PKG-INFO``, built by the ``sdist`` command. Some executable scripts, such as ``rst2html.py``, are also added in the @@ -151,7 +151,7 @@ This distinct directory is named as follows:: This ``.dist-info`` directory can contain these files: -- ``METADATA``: contains metadata, as described in PEP 345, PEP 314 and PEP 241. +- ``METADATA``: contains metadata, as described in :pep:`345`, :pep:`314` and :pep:`241`. - ``RECORD``: records the list of installed files - ``INSTALLER``: records the name of the tool used to install the project - ``REQUESTED``: the presence of this file indicates that the project @@ -187,7 +187,7 @@ should be used when creating system packages. Third-party installation tools also should not overwrite or delete files that are not in a RECORD file without prompting or warning. -This RECORD file is inspired from PEP 262 FILES [#pep262]_. +This RECORD file is inspired from :pep:`262` FILES. The ``RECORD`` file is a CSV file, composed of records, one line per installed file. The ``csv`` module is used to read the file, with @@ -239,7 +239,7 @@ The ``csv`` module is used to generate this file, so the field separator is ``csv``. When the file is read, the ``U`` option is used so the universal newline -support (see PEP 278 [#pep278]_) is activated, avoiding any trouble +support (see :pep:`278`) is activated, avoiding any trouble reading a file produced on a platform that uses a different new line terminator. @@ -443,8 +443,8 @@ And following methods: Notice that the API is organized in five classes that work with directories -and Zip files (so it works with files included in Zip files, see PEP 273 for -more details [#pep273]_). These classes are described in the documentation +and Zip files (so it works with files included in Zip files, see :pep:`273` for +more details). These classes are described in the documentation of the prototype implementation for interested readers [#prototype]_. Examples @@ -498,7 +498,7 @@ Distutils already provides a very basic way to install a distribution, which is running the ``install`` command over the ``setup.py`` script of the distribution. -Distutils2 [#pep262]_ will provide a very basic ``uninstall`` function, that +:pep:`Distutils2 <262>` will provide a very basic ``uninstall`` function, that is added in ``distutils2.util`` and takes the name of the distribution to uninstall as its argument. ``uninstall`` uses the APIs described earlier and remove all unique files, as long as their hash didn't change. Then it removes @@ -610,12 +610,6 @@ References .. [#distutils2] http://hg.python.org/distutils2 -.. [#pep262] - http://www.python.org/dev/peps/pep-0262 - -.. [#pep314] - http://www.python.org/dev/peps/pep-0314 - .. [#setuptools] http://peak.telecommunity.com/DevCenter/setuptools @@ -628,12 +622,6 @@ References .. [#eggformats] http://peak.telecommunity.com/DevCenter/EggFormats -.. [#pep273] - http://www.python.org/dev/peps/pep-0273 - -.. [#pep278] - http://www.python.org/dev/peps/pep-0278 - .. [#fedora] http://fedoraproject.org/wiki/Packaging/Python/Eggs#Providing_Eggs_using_Setuptools diff --git a/pep-0377.txt b/pep-0377.txt index 7f313256ded..ef3184bc399 100644 --- a/pep-0377.txt +++ b/pep-0377.txt @@ -51,7 +51,7 @@ clause unbound in this case, a new ``StatementSkipped`` singleton (similar to the existing ``NotImplemented`` singleton) will be assigned to all names that appear in the ``as`` clause. -The components of the ``with`` statement remain as described in PEP 343 [2]_:: +The components of the ``with`` statement remain as described in :pep:`343`:: with EXPR as VAR: BLOCK @@ -266,9 +266,6 @@ References .. [1] Issue 5251: contextlib.nested inconsistent with nested with statements (http://bugs.python.org/issue5251) -.. [2] PEP 343: The "with" Statement - (http://www.python.org/dev/peps/pep-0343/) - .. [3] Import-style syntax to reduce indentation of nested with statements (https://mail.python.org/pipermail/python-ideas/2009-March/003188.html) diff --git a/pep-0378.txt b/pep-0378.txt index 2eca3133544..da22939155c 100644 --- a/pep-0378.txt +++ b/pep-0378.txt @@ -92,7 +92,7 @@ Current Version of the Mini-Language .. _Python 2.6 docs: https://docs.python.org/2.6/library/string.html#formatstrings -* PEP 3101 Advanced String Formatting +* :pep:`3101` Advanced String Formatting Research into what Other Languages Do diff --git a/pep-0381.txt b/pep-0381.txt index 6af6e5c94ec..f6e0fba7fe5 100644 --- a/pep-0381.txt +++ b/pep-0381.txt @@ -119,7 +119,7 @@ attack, package authors need to sign their packages using PGP keys, so that users verify that the package comes from the author they trust. The central index provides a DSA key at the URL /serverkey, in the PEM -format as generated by "openssl dsa -pubout" (i.e. RFC 3280 +format as generated by "openssl dsa -pubout" (i.e. :rfc:`3280` SubjectPublicKeyInfo, with the algorithm 1.3.14.3.2.12). This URL must *not* be mirrored, and clients must fetch the official serverkey from PyPI directly, or use the copy that came with the PyPI client software. @@ -127,8 +127,8 @@ Mirrors should still download the key, to detect a key rollover. For each package, a mirrored signature is provided at /serversig/. This is the DSA signature of the parallel URL -/simple/, in DER form, using SHA-1 with DSA (i.e. as a RFC -3279 Dsa-Sig-Value, created by algorithm 1.2.840.10040.4.3) +/simple/, in DER form, using SHA-1 with DSA (i.e. as a +:rfc:`3279` Dsa-Sig-Value, created by algorithm 1.2.840.10040.4.3) Clients using a mirror need to perform the following steps to verify a package: @@ -192,7 +192,7 @@ via it. This is used by PyPI to sum up all downloads, to be able to display the grand total. These statistics are in CSV-like form, with a header in the first -line. It needs to obey PEP 305 [#pep305]_. Basically, it should be +line. It needs to obey :pep:`305`. Basically, it should be readable by Python's `csv` module. The fields in this file are: @@ -343,9 +343,6 @@ It is up the client to deal with the merging. References ========== -.. [#pep305] - http://www.python.org/dev/peps/pep-0305/#id19 - .. [#pep381client] http://pypi.python.org/pypi/pep381client diff --git a/pep-0382.txt b/pep-0382.txt index bc18474e69d..520c33c0135 100644 --- a/pep-0382.txt +++ b/pep-0382.txt @@ -14,7 +14,7 @@ Rejection Notice ================ On the first day of sprints at US PyCon 2012 we had a long and -fruitful discussion about PEP 382 and PEP 402. We ended up rejecting +fruitful discussion about :pep:`382` and :pep:`402`. We ended up rejecting both but a new PEP will be written to carry on in the spirit of PEP 402. Martin von Löwis wrote up a summary: [2]_. @@ -131,7 +131,7 @@ this: Impact on Import Hooks ---------------------- -Both loaders and finders as defined in PEP 302 will need to be changed +Both loaders and finders as defined in :pep:`302` will need to be changed to support namespace packages. Failure to conform to the protocol below might cause a package not being recognized as a namespace package; loaders and finders not supporting this protocol must raise @@ -178,9 +178,9 @@ Dinu Gherman then observed that using a marker file is not necessary, and that a directory extension could well serve as a such as a marker. This is what this PEP currently proposes. -Phillip Eby designed PEP 402 as an alternative approach to this PEP, +Phillip Eby designed :pep:`402` as an alternative approach to this PEP, after comparing Python's package syntax with that found in other -languages. PEP 402 proposes not to use a marker file at all. At the +languages. :pep:`402` proposes not to use a marker file at all. At the discussion at PyCon DE 2011, people remarked that having an explicit declaration of a directory as contributing to a package is a desirable property, rather than an obstacle. In particular, Jython developers diff --git a/pep-0383.txt b/pep-0383.txt index f332ae78a79..40ea162889e 100644 --- a/pep-0383.txt +++ b/pep-0383.txt @@ -64,7 +64,7 @@ Specification On Windows, Python uses the wide character APIs to access character-oriented APIs, allowing direct conversion of the -environmental data to Python str objects ([1]_). +environmental data to Python str objects (:pep:`277`). On POSIX systems, Python currently applies the locale's encoding to convert the byte data to Unicode, failing for characters that cannot @@ -72,7 +72,7 @@ be decoded. With this PEP, non-decodable bytes >= 128 will be represented as lone surrogate codes U+DC80..U+DCFF. Bytes below 128 will produce exceptions; see the discussion below. -To convert non-decodable bytes, a new error handler ([2]_) +To convert non-decodable bytes, a new error handler (:pep:`293`) "surrogateescape" is introduced, which produces these surrogates. On encoding, the error handler converts the surrogate back to the corresponding byte. This error handler will be used in any API that @@ -171,14 +171,6 @@ case; other libraries may show similar problems. References ========== -.. [1] PEP 277 - "Unicode file name support for Windows NT" - http://www.python.org/dev/peps/pep-0277/ - -.. [2] PEP 293 - "Codec Error Handling Callbacks" - http://www.python.org/dev/peps/pep-0293/ - .. [3] UTF-8b http://permalink.gmane.org/gmane.comp.internationalization.linux/920 diff --git a/pep-0384.txt b/pep-0384.txt index 9100ddfdb22..95d6c879d69 100644 --- a/pep-0384.txt +++ b/pep-0384.txt @@ -344,7 +344,7 @@ applications conforming to this PEP should then link to the former but rather rely on runtime linking). The ABI version is symbolically available as ``PYTHON_ABI_VERSION``. -Also on Unix, the PEP 3149 tag abi is accepted +Also on Unix, the :pep:`3149` tag abi is accepted in file names of extension modules. No checking is performed that files named in this way are actually restricted to the limited API, and no support for building such files will be added to distutils diff --git a/pep-0385.txt b/pep-0385.txt index 8495717a6c4..6a4d20e7ab2 100644 --- a/pep-0385.txt +++ b/pep-0385.txt @@ -19,7 +19,7 @@ migration still has to be performed. In the case of an important piece of infrastructure like the version control system for a large, distributed project like Python, this is a significant effort. This PEP is an attempt to describe the steps that must be taken for further -discussion. It's somewhat similar to `PEP 347`_, which discussed the +discussion. It's somewhat similar to :pep:`347`, which discussed the migration to SVN. To make the most of hg, we would like to make a high-fidelity @@ -37,7 +37,6 @@ contents of the repository and determine if some things are still valuable. In this spirit, the following sections also propose discarding some of the older metadata. -.. _PEP 347: http://www.python.org/dev/peps/pep-0347/ .. _hgsubversion: http://bitbucket.org/durin42/hgsubversion/ diff --git a/pep-0386.txt b/pep-0386.txt index ba009ff87a5..52917a707ad 100644 --- a/pep-0386.txt +++ b/pep-0386.txt @@ -14,7 +14,7 @@ Abstract ======== Note: This PEP has been superseded by the version identification and -dependency specification scheme defined in PEP 440. +dependency specification scheme defined in :pep:`440`. This PEP proposed a new version comparison schema system in Distutils. @@ -30,7 +30,7 @@ current users, such as PyPI usually consider the latest version pushed as the Distutils will soon extend its capabilities to allow distributions to express a dependency on other distributions through the ``Requires-Dist`` metadata field -(see PEP 345) and it will optionally allow use of that field to +(see :pep:`345`) and it will optionally allow use of that field to restrict the dependency to a set of compatible versions. Notice that this field is replacing ``Requires`` that was expressing dependencies on modules and packages. diff --git a/pep-0387.txt b/pep-0387.txt index 031059c1d42..1e156a4bc59 100644 --- a/pep-0387.txt +++ b/pep-0387.txt @@ -79,7 +79,7 @@ be removed at any time in any way. These include: subdirectories of packages.) - Backward compatibility rules do not apply to any module or API that is - explicitly documented as **Provisional** per PEP 411. + explicitly documented as **Provisional** per :pep:`411`. Basic policy for backwards compatibility diff --git a/pep-0390.txt b/pep-0390.txt index 92605fde1bc..5ad1bdf3863 100644 --- a/pep-0390.txt +++ b/pep-0390.txt @@ -26,7 +26,7 @@ Rejection Notice As distutils2 is no longer going to be incorporated into the standard library, this PEP was rejected by Nick Coghlan in late April, 2013. -A replacement PEP based on PEP 426 (metadata 2.0) will be created that +A replacement PEP based on :pep:`426` (metadata 2.0) will be created that defines the minimum amount of information needed to generate an sdist archive given a source tarball or VCS checkout. @@ -34,7 +34,7 @@ archive given a source tarball or VCS checkout. Rationale ========= -Today, if you want to list all the Metadata of a distribution (see PEP 314) +Today, if you want to list all the Metadata of a distribution (see :pep:`314`) that is not installed, you need to use the ``setup.py`` command line interface. So, basically, you download it, and run:: @@ -86,7 +86,7 @@ Multi-lines values ================== Some Metadata fields can have multiple values. To keep ``setup.cfg`` compatible -with ``ConfigParser`` and the RFC 822 ``LONG HEADER FIELDS`` (see section 3.1.1), +with ``ConfigParser`` and the :rfc:`822` ``LONG HEADER FIELDS`` (see section 3.1.1), these are expressed with ``,``-separated values:: requires = pywin32, bar > 1.0, foo @@ -124,7 +124,7 @@ Every ``[metadata:condition]`` section will be used only if the condition is met when the file is read. The background motivation for these context-dependant sections is to be able to define requirements that varies depending on the platform the distribution might be installed on. -(see PEP 314). +(see :pep:`314`). The micro-language behind this is the simplest possible: it compares only strings, with the ``==`` and ``in`` operators (and their opposites), and @@ -206,7 +206,7 @@ for another environment:: >>> metadata.get_requires() ['bar > 1.0', 'foo', 'bar'] -PEP 314 is changed accordingly, meaning that each field will be able to +:pep:`314` is changed accordingly, meaning that each field will be able to have that extra condition marker. Compatibility @@ -224,7 +224,7 @@ Limitations We are not providing ``<`` and ``>`` operators at this time, and ``python_version`` is a regular string. This implies using ``or`` operators when a section needs to be restricted to a couple of Python versions. -Although, if PEP 386 is accepted, ``python_version`` could be changed +Although, if :pep:`386` is accepted, ``python_version`` could be changed internally into something comparable with strings, and ``<`` and ``>`` operators introduced. diff --git a/pep-0391.txt b/pep-0391.txt index d16dfd3e9b2..d6050e30f27 100644 --- a/pep-0391.txt +++ b/pep-0391.txt @@ -79,9 +79,9 @@ to which it must conform). Naming ------ -Historically, the logging package has not been PEP 8 conformant [1]_. +Historically, the logging package has not been :pep:`8` conformant. At some future time, this will be corrected by changing method and -function names in the package in order to conform with PEP 8. +function names in the package in order to conform with :pep:`8`. However, in the interests of uniformity, the proposed additions to the API use a naming scheme which is consistent with the present scheme used by logging. @@ -678,13 +678,6 @@ http://bitbucket.org/vinay.sajip/dictconfig This incorporates all features other than the socket listener change. -References -========== - -.. [1] PEP 8, Style Guide for Python Code, van Rossum, Warsaw - (http://www.python.org/dev/peps/pep-0008) - - Copyright ========= diff --git a/pep-0392.txt b/pep-0392.txt index 0ce3b5ebab6..82da4323cfa 100644 --- a/pep-0392.txt +++ b/pep-0392.txt @@ -110,20 +110,12 @@ Release Schedule Features for 3.2 ================ -Note that PEP 3003 [#pep3003]_ is in effect: no changes to language +Note that :pep:`3003` is in effect: no changes to language syntax and no additions to the builtins may be made. No large-scale changes have been recorded yet. -References -========== - -.. [#pep3003] - http://www.python.org/dev/peps/pep-3003/ - - - Copyright ========= diff --git a/pep-0393.txt b/pep-0393.txt index 176dd0170c4..75c0aacabcc 100644 --- a/pep-0393.txt +++ b/pep-0393.txt @@ -263,7 +263,7 @@ UCS4 utility functions: Stable ABI ---------- -The following functions are added to the stable ABI (PEP 384), as they +The following functions are added to the stable ABI (:pep:`384`), as they are independent of the actual representation of Unicode objects: PyUnicode_New, PyUnicode_Substring, PyUnicode_GetLength, PyUnicode_ReadChar, PyUnicode_WriteChar, PyUnicode_Find, diff --git a/pep-0394.txt b/pep-0394.txt index c2c83d57e87..10ad8a911ba 100644 --- a/pep-0394.txt +++ b/pep-0394.txt @@ -87,7 +87,7 @@ For Python runtime distributors * Changing ``python3`` shebangs to ``python3.8`` if the software is built with Python 3.8. -* When a virtual environment (created by the PEP 405 ``venv`` package or a +* When a virtual environment (created by the :pep:`405` ``venv`` package or a similar tool such as ``virtualenv`` or ``conda``) is active, the ``python`` command should refer to the virtual environment's interpreter and should always be available. @@ -174,7 +174,7 @@ on the part of distribution maintainers. Simplified, the recommendation was: the version explicitly. However, these recommendations implicitly assumed that Python 2 would always be -available. As Python 2 is nearing its end of life in 2020 (PEP 373, PEP 404), +available. As Python 2 is nearing its end of life in 2020 (:pep:`373`, :pep:`404`), distributions are making Python 2 optional or removing it entirely. This means either removing the ``python`` command or switching it to invoke Python 3. Some distributors also decided that their users were better served by @@ -338,7 +338,7 @@ Exclusion of MS Windows This PEP deliberately excludes any proposals relating to Microsoft Windows, as devising an equivalent solution for Windows was deemed too complex to handle -here. PEP 397 and the related discussion on the python-dev mailing list +here. :pep:`397` and the related discussion on the python-dev mailing list address this issue. @@ -348,13 +348,13 @@ References .. [1] Support the /usr/bin/python2 symlink upstream (with bonus grammar class!) (https://mail.python.org/pipermail/python-dev/2011-March/108491.html) -.. [2] Rebooting \PEP 394 (aka Support the /usr/bin/python2 symlink upstream) +.. [2] Rebooting PEP 394 (aka Support the /usr/bin/python2 symlink upstream) (https://mail.python.org/pipermail/python-dev/2011-July/112322.html) -.. [3] Implement \PEP 394 in the CPython Makefile +.. [3] Implement PEP 394 in the CPython Makefile (http://bugs.python.org/issue12627) -.. [4] \PEP 394 request for pronouncement (python2 symlink in \*nix systems) +.. [4] PEP 394 request for pronouncement (python2 symlink in \*nix systems) (https://mail.python.org/pipermail/python-dev/2012-February/116435.html) .. [5] Arch Linux announcement that their "python" link now refers Python 3 diff --git a/pep-0395.txt b/pep-0395.txt index a67256b2cc0..5466ae4ba99 100644 --- a/pep-0395.txt +++ b/pep-0395.txt @@ -34,7 +34,7 @@ This PEP proposes new mechanisms that eliminate some longstanding traps for the unwary when dealing with Python's import system, as well as serialisation and introspection of functions and classes. -It builds on the "Qualified Name" concept defined in PEP 3155. +It builds on the "Qualified Name" concept defined in :pep:`3155`. Relationship with Other PEPs @@ -42,18 +42,18 @@ Relationship with Other PEPs Most significantly, this PEP is currently deferred as it requires significant changes in order to be made compatible with the removal -of mandatory __init__.py files in PEP 420 (which has been implemented +of mandatory __init__.py files in :pep:`420` (which has been implemented and released in Python 3.3). -This PEP builds on the "qualified name" concept introduced by PEP 3155, and +This PEP builds on the "qualified name" concept introduced by :pep:`3155`, and also shares in that PEP's aim of fixing some ugly corner cases when dealing with serialisation of arbitrary functions and classes. -It also builds on PEP 366, which took initial tentative steps towards making +It also builds on :pep:`366`, which took initial tentative steps towards making explicit relative imports from the main module work correctly in at least *some* circumstances. -Finally, PEP 328 eliminated implicit relative imports from imported modules. +Finally, :pep:`328` eliminated implicit relative imports from imported modules. This PEP proposes that the de facto implicit relative imports from main modules that are provided by the current initialisation behaviour for ``sys.path[0]`` also be eliminated. @@ -173,7 +173,7 @@ executing it directly:: # working directory: project python -c "from package.tests.test_foo import main; main()" -Since the implementation of PEP 366 (which defined a mechanism that allows +Since the implementation of :pep:`366` (which defined a mechanism that allows relative imports to work correctly when a module inside a package is executed via the ``-m`` switch), the following also works properly:: @@ -287,12 +287,12 @@ Qualified Names for Modules To make it feasible to fix these problems once and for all, it is proposed to add a new module level attribute: ``__qualname__``. This abbreviation of -"qualified name" is taken from PEP 3155, where it is used to store the naming +"qualified name" is taken from :pep:`3155`, where it is used to store the naming path to a nested class or function definition relative to the top level module. For modules, ``__qualname__`` will normally be the same as ``__name__``, just -as it is for top-level functions and classes in PEP 3155. However, it will +as it is for top-level functions and classes in :pep:`3155`. However, it will differ in some situations so that the above problems can be addressed. Specifically, whenever ``__name__`` is modified for some other purpose (such @@ -311,22 +311,22 @@ Two alternative names were also considered for the new attribute: "full name" (``__fullname__``) and "implementation name" (``__implname__``). Either of those would actually be valid for the use case in this PEP. -However, as a meta-issue, PEP 3155 is *also* adding a new attribute (for +However, as a meta-issue, :pep:`3155` is *also* adding a new attribute (for functions and classes) that is "like ``__name__``, but different in some cases where ``__name__`` is missing necessary information" and those terms aren't -accurate for the PEP 3155 function and class use case. +accurate for the :pep:`3155` function and class use case. -PEP 3155 deliberately omits the module information, so the term "full name" +:pep:`3155` deliberately omits the module information, so the term "full name" is simply untrue, and "implementation name" implies that it may specify an object other than that specified by ``__name__``, and that is never the -case for PEP 3155 (in that PEP, ``__name__`` and ``__qualname__`` always +case for :pep:`3155` (in that PEP, ``__name__`` and ``__qualname__`` always refer to the same function or class, it's just that ``__name__`` is insufficient to accurately identify nested functions and classes). Since it seems needlessly inconsistent to add *two* new terms for attributes that only exist because backwards compatibility concerns keep us from changing the behaviour of ``__name__`` itself, this PEP instead chose to -adopt the PEP 3155 terminology. +adopt the :pep:`3155` terminology. If the relative inscrutability of "qualified name" and ``__qualname__`` encourages interested developers to look them up at least once rather than @@ -525,7 +525,7 @@ as follows:: Compatibility with PEP 382 ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Making this proposal compatible with the PEP 382 namespace packaging PEP is +Making this proposal compatible with the :pep:`382` namespace packaging PEP is trivial. The semantics of ``_is_package_dir()`` are merely changed to be:: def _is_package_dir(fspath): @@ -537,7 +537,7 @@ trivial. The semantics of ``_is_package_dir()`` are merely changed to be:: Incompatibility with PEP 402 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -PEP 402 proposes the elimination of explicit markers in the file system for +:pep:`402` proposes the elimination of explicit markers in the file system for Python packages. This fundamentally breaks the proposed concept of being able to take a filesystem path and a Python module name and work out an unambiguous mapping to the Python module namespace. Instead, the appropriate mapping @@ -545,7 +545,7 @@ would depend on the current values in ``sys.path``, rendering it impossible to ever fix the problems described above with the calculation of ``sys.path[0]`` when the interpreter is initialised. -While some aspects of this PEP could probably be salvaged if PEP 402 were +While some aspects of this PEP could probably be salvaged if :pep:`402` were adopted, the core concept of making import semantics from main and other modules more consistent would no longer be feasible. diff --git a/pep-0396.txt b/pep-0396.txt index c2e4c0a2d19..3ee9ce371c4 100644 --- a/pep-0396.txt +++ b/pep-0396.txt @@ -76,7 +76,7 @@ ways have grown organically over the years. Often, version numbers can be retrieved from a module programmatically, by importing the module and inspecting an attribute. Classic Python distutils ``setup()`` functions [3]_ describe a ``version`` argument where the -release's version number can be specified. PEP 8 [4]_ describes the +release's version number can be specified. :pep:`8` describes the use of a module attribute called ``__version__`` for recording "Subversion, CVS, or RCS" version strings using keyword expansion. In the PEP author's own email archives, the earliest example of the use @@ -120,14 +120,14 @@ Specification #. The ``__version__`` attribute's value SHOULD be a string. #. Module version numbers SHOULD conform to the normalized version - format specified in PEP 386 [6]_. + format specified in :pep:`386`. #. Module version numbers SHOULD NOT contain version control system supplied revision numbers, or any other semantically different version numbers (e.g. underlying library version number). #. The ``version`` attribute in a classic distutils ``setup.py`` - file, or the PEP 345 [7]_ ``Version`` metadata field SHOULD be + file, or the :pep:`345` ``Version`` metadata field SHOULD be derived from the ``__version__`` field, or vice versa. @@ -256,10 +256,10 @@ programmatically. E.g. in ``elle.py``:: PEP 376 metadata ================ -PEP 376 [10]_ defines a standard for static metadata, but doesn't +:pep:`376` defines a standard for static metadata, but doesn't describe the process by which this metadata gets created. It is highly desirable for the derived version information to be placed into -the PEP 376 ``.dist-info`` metadata at build-time rather than +the :pep:`376` ``.dist-info`` metadata at build-time rather than install-time. This way, the metadata will be available for introspection even when the code is not installed. @@ -275,26 +275,14 @@ References .. [3] http://docs.python.org/distutils/setupscript.html -.. [4] PEP 8, Style Guide for Python Code - (http://www.python.org/dev/peps/pep-0008) - .. [5] sqlite3 module documentation (http://docs.python.org/library/sqlite3.html) -.. [6] PEP 386, Changing the version comparison module in Distutils - (http://www.python.org/dev/peps/pep-0386/) - -.. [7] PEP 345, Metadata for Python Software Packages 1.2 - (http://www.python.org/dev/peps/pep-0345/#version) - .. [8] pkgutil - Package utilities (http://distutils2.notmyidea.org/library/pkgutil.html) .. [9] https://mail.python.org/pipermail/distutils-sig/2011-June/017862.html -.. [10] PEP 376, Database of Installed Python Distributions - (http://www.python.org/dev/peps/pep-0376/) - .. [11] importlib.metadata (https://docs.python.org/3/library/importlib.metadata.html#distribution-versions) diff --git a/pep-0397.txt b/pep-0397.txt index e3d07d62e2c..57b07422806 100644 --- a/pep-0397.txt +++ b/pep-0397.txt @@ -51,8 +51,8 @@ particular version of Python installed under the operating-system. These symbolic links allow Python to be executed without regard for where Python it actually installed on the machine (eg., without requiring the path where Python is actually installed to be -referenced in the shebang line or in the ``PATH``.) PEP 394 'The "python" -command on Unix-Like Systems' [2]_ describes additional conventions +referenced in the shebang line or in the ``PATH``.) :pep:`394` 'The "python" +command on Unix-Like Systems' describes additional conventions for more fine-grained specification of a particular Python version. These 2 facilities combined allow for a portable and somewhat @@ -411,8 +411,6 @@ References .. [1] http://linux.die.net/man/2/execve -.. [2] http://www.python.org/dev/peps/pep-0394/ - .. [3] https://bitbucket.org/vinay.sajip/pylauncher .. [4] https://bitbucket.org/vinay.sajip/pylauncher/src/tip/Doc/launcher.rst diff --git a/pep-0398.txt b/pep-0398.txt index 2ab06965b8f..30d4bf36fe5 100644 --- a/pep-0398.txt +++ b/pep-0398.txt @@ -129,24 +129,24 @@ Features for 3.3 Implemented / Final PEPs: -* PEP 362: Function Signature Object -* PEP 380: Syntax for Delegating to a Subgenerator -* PEP 393: Flexible String Representation -* PEP 397: Python launcher for Windows -* PEP 399: Pure Python/C Accelerator Module Compatibility Requirements -* PEP 405: Python Virtual Environments -* PEP 409: Suppressing exception context -* PEP 412: Key-Sharing Dictionary -* PEP 414: Explicit Unicode Literal for Python 3.3 -* PEP 415: Implement context suppression with exception attributes -* PEP 417: Including mock in the Standard Library -* PEP 418: Add monotonic time, performance counter, and process time functions -* PEP 420: Implicit Namespace Packages -* PEP 421: Adding sys.implementation -* PEP 3118: Revising the buffer protocol (protocol semantics finalised) -* PEP 3144: IP Address manipulation library -* PEP 3151: Reworking the OS and IO exception hierarchy -* PEP 3155: Qualified name for classes and functions +* :pep:`362`: Function Signature Object +* :pep:`380`: Syntax for Delegating to a Subgenerator +* :pep:`393`: Flexible String Representation +* :pep:`397`: Python launcher for Windows +* :pep:`399`: Pure Python/C Accelerator Module Compatibility Requirements +* :pep:`405`: Python Virtual Environments +* :pep:`409`: Suppressing exception context +* :pep:`412`: Key-Sharing Dictionary +* :pep:`414`: Explicit Unicode Literal for Python 3.3 +* :pep:`415`: Implement context suppression with exception attributes +* :pep:`417`: Including mock in the Standard Library +* :pep:`418`: Add monotonic time, performance counter, and process time functions +* :pep:`420`: Implicit Namespace Packages +* :pep:`421`: Adding sys.implementation +* :pep:`3118`: Revising the buffer protocol (protocol semantics finalised) +* :pep:`3144`: IP Address manipulation library +* :pep:`3151`: Reworking the OS and IO exception hierarchy +* :pep:`3155`: Qualified name for classes and functions Other final large-scale changes: @@ -169,9 +169,9 @@ Other planned large-scale changes: Deferred to post-3.3: -* PEP 395: Qualified Names for Modules -* PEP 3143: Standard daemon process library -* PEP 3154: Pickle protocol version 4 +* :pep:`395`: Qualified Names for Modules +* :pep:`3143`: Standard daemon process library +* :pep:`3154`: Pickle protocol version 4 * Breaking out standard library and docs in separate repos * Addition of the "packaging" module, deprecating "distutils" * Addition of the "regex" module diff --git a/pep-0400.txt b/pep-0400.txt index e5a9aeffd55..acb35694c97 100644 --- a/pep-0400.txt +++ b/pep-0400.txt @@ -19,10 +19,10 @@ StreamReaderWriter. Duplicate code means that bugs should be fixed twice and that we may have subtle differences between the two implementations. -The codecs module was introduced in Python 2.0 (see the `PEP 100 -`_). The io module was -introduced in Python 2.6 and 3.0 (see the `PEP 3116 -`_), and reimplemented in C in +The codecs module was introduced in Python 2.0 (see the :pep:`100`). +The io module was +introduced in Python 2.6 and 3.0 (see the :pep:`3116`), +and reimplemented in C in Python 2.7 and 3.1. PEP Deferral @@ -47,9 +47,9 @@ since the release of Python 3.0. This new interface overlaps heavily with the legacy codecs.StreamReader, codecs.StreamWriter and codecs.StreamReaderWriter interfaces that were part of the original codec interface design in -PEP 100. These interfaces are organised around the principle of an +:pep:`100`. These interfaces are organised around the principle of an encoding with an associated stream (i.e. the reverse of arrangement in -the io module), so the original PEP 100 design required that codec +the io module), so the original :pep:`100` design required that codec writers provide appropriate StreamReader and StreamWriter implementations in addition to the core codec encode() and decode() methods. This places a heavy burden on codec authors providing these @@ -312,9 +312,8 @@ writes a new BOM on the second write (`issue #12512 Links ===== -* `PEP 100: Python Unicode Integration - `_ -* `PEP 3116: New I/O `_ +* :pep:`PEP 100: Python Unicode Integration <100>` +* :pep:`PEP 3116: New I/O <3116>` * `Issue #8796: Deprecate codecs.open() `_ * `[python-dev] Deprecate codecs.open() and StreamWriter/StreamReader diff --git a/pep-0402.txt b/pep-0402.txt index f73f954989d..1396118205b 100644 --- a/pep-0402.txt +++ b/pep-0402.txt @@ -15,7 +15,7 @@ Rejection Notice ================ On the first day of sprints at US PyCon 2012 we had a long and -fruitful discussion about PEP 382 and PEP 402. We ended up rejecting +fruitful discussion about :pep:`382` and :pep:`402`. We ended up rejecting both but a new PEP will be written to carry on in the spirit of PEP 402. Martin von Löwis wrote up a summary: [3]_. @@ -28,7 +28,7 @@ to: * Surprise users of other languages less, * Make it easier to convert a module into a package, and * Support dividing packages into separately installed components - (ala "namespace packages", as described in PEP 382) + (ala "namespace packages", as described in :pep:`382`) The proposed enhancements do not change the semantics of any currently-importable directory layouts, but make it possible for @@ -95,7 +95,7 @@ vendors who package up these module distributions must somehow handle the conflict caused by several module distributions installing that ``__init__`` module to the same location in the filesystem. -This led to the proposing of PEP 382 ("Namespace Packages") - a way +This led to the proposing of :pep:`382` ("Namespace Packages") - a way to signal to Python's import machinery that a directory was importable, using unique filenames per module distribution. @@ -454,7 +454,7 @@ self-contained subpackage. Virtual Paths ------------- -A virtual path is created by obtaining a PEP 302 "importer" object for +A virtual path is created by obtaining a :pep:`302` "importer" object for each of the path entries found in ``sys.path`` (for a top-level module) or the parent ``__path__`` (for a submodule). @@ -611,7 +611,7 @@ For users, developers, and distributors of virtual packages: accidentally work. Is that good or bad? -For those implementing PEP 302 importer objects: +For those implementing :pep:`302` importer objects: * Importers that support the ``iter_modules()`` method (used by ``pkgutil`` to locate importable modules and packages) and want to diff --git a/pep-0403.txt b/pep-0403.txt index 5b61712e5f6..a1cade77627 100644 --- a/pep-0403.txt +++ b/pep-0403.txt @@ -27,7 +27,7 @@ statement that uses it actually makes the code harder to read. It also avoids any name shadowing concerns by making sure the new name is visible only to the statement in the ``@in`` clause. -This PEP is based heavily on many of the ideas in PEP 3150 (Statement Local +This PEP is based heavily on many of the ideas in :pep:`3150` (Statement Local Namespaces) so some elements of the rationale will be familiar to readers of that PEP. Both PEPs remain deferred for the time being, primarily due to the lack of compelling real world use cases in either PEP. @@ -110,7 +110,7 @@ those that don't make any sense in that context, such as ``pass`` - while such code would be legal, there wouldn't be any point in writing it). This permissive structure is easier to define and easier to explain, but a more restrictive approach that only permits operations that "make sense" would -also be possible (see PEP 3150 for a list of possible candidates). +also be possible (see :pep:`3150` for a list of possible candidates). The ``@in`` clause will not create a new scope - all name binding operations aside from the trailing function or class definition will affect @@ -201,7 +201,7 @@ decorators, but covering a broader set of applications. Relation to PEP 3150 -------------------- -PEP 3150 (Statement Local Namespaces) describes its primary motivation +:pep:`3150` (Statement Local Namespaces) describes its primary motivation as being to elevate ordinary assignment statements to be on par with ``class`` and ``def`` statements where the name of the item to be defined is presented to the reader in advance of the details of how the value of that item is @@ -210,12 +210,12 @@ the simple name binding of a standard function definition to be replaced with something else (like assigning the result of the function to a value). Despite having the same author, the two PEPs are in direct competition with -each other. PEP 403 represents a minimalist approach that attempts to achieve +each other. :pep:`403` represents a minimalist approach that attempts to achieve useful functionality with a minimum of change from the status quo. This PEP instead aims for a more flexible standalone statement design, which requires a larger degree of change to the language. -Note that where PEP 403 is better suited to explaining the behaviour of +Note that where :pep:`403` is better suited to explaining the behaviour of generator expressions correctly, this PEP is better able to explain the behaviour of decorator clauses in general. Both PEPs support adequate explanations for the semantics of container comprehensions. @@ -255,7 +255,7 @@ promote short, cryptic function names (including this one, which requires that the name of the trailing definition be supplied at least twice, encouraging the use of shorthand placeholder names like ``f``). -However, the introduction of qualified names in PEP 3155 means that even +However, the introduction of qualified names in :pep:`3155` means that even anonymous classes and functions will now have different representations if they occur in different scopes. For example:: @@ -273,7 +273,7 @@ still a major improvement over the historical situation where everything Possible Implementation Strategy -------------------------------- -This proposal has at least one titanic advantage over PEP 3150: +This proposal has at least one titanic advantage over :pep:`3150`: implementation should be relatively straightforward. The ``@in`` clause will be included in the AST for the associated function or @@ -457,12 +457,12 @@ Using a nested suite -------------------- The problems with using a full nested suite are best described in -PEP 3150. It's comparatively difficult to implement properly, the scoping +:pep:`3150`. It's comparatively difficult to implement properly, the scoping semantics are harder to explain and it creates quite a few situations where there are two ways to do it without clear guidelines for choosing between them (as almost any construct that can be expressed with ordinary imperative code could instead be expressed using a given statement). While the PEP does -propose some new PEP 8 guidelines to help address that last problem, the +propose some new :pep:`8` guidelines to help address that last problem, the difficulties in implementation are not so easily dealt with. By contrast, the decorator inspired syntax in this PEP explicitly limits the @@ -473,7 +473,7 @@ binding of the function is completely unnecessary) then it probably *should* be used. Another possible variant of this idea is to keep the decorator based -*semantics* of this PEP, while adopting the prettier syntax from PEP 3150:: +*semantics* of this PEP, while adopting the prettier syntax from :pep:`3150`:: x = weakref.ref(target, report_destruction) given: def report_destruction(obj): @@ -487,7 +487,7 @@ that could potentially be addressed through a suitable definition of the suite-that-is-not-a-suite in the language grammar). However, a nested suite has not yet been ruled out completely. The latest -version of PEP 3150 uses explicit forward reference and name binding +version of :pep:`3150` uses explicit forward reference and name binding schemes that greatly simplify the semantics of the statement, and it does offer the advantage of allowing the definition of arbitrary subexpressions rather than being restricted to a single function or diff --git a/pep-0406.txt b/pep-0406.txt index cad761887ce..b3164dce227 100644 --- a/pep-0406.txt +++ b/pep-0406.txt @@ -37,8 +37,8 @@ The import system has seen substantial changes since this PEP was originally written, as part of :pep:`420` in Python 3.3 and :pep:`451` in Python 3.4. While providing an encapsulation of the import state is still highly -desirable, it is better tackled in a new PEP using PEP 451 as a foundation, -and permitting only the use of PEP 451 compatible finders and loaders (as +desirable, it is better tackled in a new PEP using :pep:`451` as a foundation, +and permitting only the use of :pep:`451` compatible finders and loaders (as those avoid many of the issues of direct manipulation of global state associated with the previous loader API). @@ -66,7 +66,7 @@ over which modules can be imported). The engine would also be subclassed to make it possible to use the import engine API to interact with the existing process-global state. -The namespace PEPs (especially PEP 402) raise a potential need for +The namespace PEPs (especially :pep:`402`) raise a potential need for *additional* process global state, in order to correctly update package paths as ``sys.path`` is modified. @@ -159,7 +159,7 @@ Global variables No changes to finder/loader interfaces ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Rather than attempting to update the PEP 302 APIs to accept additional state, +Rather than attempting to update the :pep:`302` APIs to accept additional state, this PEP proposes that ``ImportEngine`` support the content management protocol (similar to the context substitution mechanisms in the ``decimal`` module). @@ -238,7 +238,7 @@ Brett Cannon's importlib has been developed by Greg Slodkowicz as part of the modifying existing code, and hence duplicates a lot of things unnecessarily. An actual implementation would just modify any such affected code in place. -That earlier draft of the PEP proposed change the PEP 302 APIs to support passing +That earlier draft of the PEP proposed change the :pep:`302` APIs to support passing in an optional engine instance. This had the (serious) downside of not correctly affecting further imports from the imported module, hence the change to the context management based proposal for substituting the global state. @@ -247,9 +247,6 @@ context management based proposal for substituting the global state. References ========== -.. [1] PEP 302, New Import Hooks, J van Rossum, Moore - (http://www.python.org/dev/peps/pep-0302) - .. [2] __import__() builtin function, The Python Standard Library documentation (http://docs.python.org/library/functions.html#__import__) diff --git a/pep-0407.txt b/pep-0407.txt index d1513086827..c313a2cb281 100644 --- a/pep-0407.txt +++ b/pep-0407.txt @@ -144,7 +144,7 @@ These are open issues that should be worked out during discussion: * What is the policy for security fixes? * Restrict new syntax and similar changes (i.e. everything that was - prohibited by PEP 3003) to LTS versions? + prohibited by :pep:`3003`) to LTS versions? * What is the effect on packagers such as Linux distributions? diff --git a/pep-0408.txt b/pep-0408.txt index 333b2545ba5..b568f10415a 100644 --- a/pep-0408.txt +++ b/pep-0408.txt @@ -81,7 +81,7 @@ with an API that has wide acceptance in the Python development community. In any case, modules that are proposed to be added to the standard library, whether via ``__preview__`` or directly, must fulfill the acceptance conditions -set by PEP 2. +set by :pep:`2`. It is important to stress that the aim of this proposal is not to make the process of adding new modules to the standard library more difficult. On the @@ -185,25 +185,25 @@ Candidates for inclusion into __preview__ For Python 3.3, there are a number of clear current candidates: * ``regex`` (http://pypi.python.org/pypi/regex) -* ``daemon`` (PEP 3143) -* ``ipaddr`` (PEP 3144) +* ``daemon`` (:pep:`3143`) +* ``ipaddr`` (:pep:`3144`) Other possible future use cases include: * Improved HTTP modules (e.g. ``requests``) * HTML 5 parsing support (e.g. ``html5lib``) * Improved URL/URI/IRI parsing -* A standard image API (PEP 368) -* Encapsulation of the import state (PEP 368) -* Standard event loop API (PEP 3153) -* A binary version of WSGI for Python 3 (e.g. PEP 444) +* A standard image API (:pep:`368`) +* Encapsulation of the import state (:pep:`368`) +* Standard event loop API (:pep:`3153`) +* A binary version of WSGI for Python 3 (e.g. :pep:`444`) * Generic function support (e.g. ``simplegeneric``) Relationship with PEP 407 ========================= -PEP 407 proposes a change to the core Python release cycle to permit interim +:pep:`407` proposes a change to the core Python release cycle to permit interim releases every 6 months (perhaps limited to standard library updates). If such a change to the release cycle is made, the following policy for the ``__preview__`` namespace is suggested: diff --git a/pep-0409.txt b/pep-0409.txt index 8bf2047f58e..ac0c4c04fbc 100644 --- a/pep-0409.txt +++ b/pep-0409.txt @@ -15,7 +15,7 @@ Resolution: https://mail.python.org/pipermail/python-dev/2012-February/116136.ht Abstract ======== -One of the open issues from PEP 3134 is suppressing context: currently +One of the open issues from :pep:`3134` is suppressing context: currently there is no way to do it. This PEP proposes one. @@ -89,7 +89,7 @@ Implementation Discussion ========================= Note: after acceptance of this PEP, a cleaner implementation mechanism -was proposed and accepted in PEP 415. Refer to that PEP for more +was proposed and accepted in :pep:`415`. Refer to that PEP for more details on the implementation actually used in Python 3.3. Currently, ``None`` is the default for both ``__context__`` and ``__cause__``. diff --git a/pep-0411.txt b/pep-0411.txt index cf5b0276dbd..80c46fd1283 100644 --- a/pep-0411.txt +++ b/pep-0411.txt @@ -72,7 +72,7 @@ The phrase "provisional basis" will then be a link to the glossary term This process allows the standard library to continue to evolve over time, without locking in problematic design errors for extended periods of time. - See PEP 411 for more details. + See :pep:`411` for more details. The following will be added to the start of the package's docstring: @@ -95,7 +95,7 @@ community. In any case, packages that are proposed to be added to the standard library, whether via the provisional state or directly, must fulfill the acceptance -conditions set by PEP 2. +conditions set by :pep:`2`. Criteria for "graduation" ------------------------- @@ -169,25 +169,25 @@ Candidates for provisional inclusion into the standard library For Python 3.3, there are a number of clear current candidates: * ``regex`` (http://pypi.python.org/pypi/regex) - approved by Guido [#]_. -* ``daemon`` (PEP 3143) -* ``ipaddr`` (PEP 3144) +* ``daemon`` (:pep:`3143`) +* ``ipaddr`` (:pep:`3144`) Other possible future use cases include: * Improved HTTP modules (e.g. ``requests``) * HTML 5 parsing support (e.g. ``html5lib``) * Improved URL/URI/IRI parsing -* A standard image API (PEP 368) -* Improved encapsulation of import state (PEP 406) -* Standard event loop API (PEP 3153) -* A binary version of WSGI for Python 3 (e.g. PEP 444) +* A standard image API (:pep:`368`) +* Improved encapsulation of import state (:pep:`406`) +* Standard event loop API (:pep:`3153`) +* A binary version of WSGI for Python 3 (e.g. :pep:`444`) * Generic function support (e.g. ``simplegeneric``) Rejected alternatives and variations ==================================== -See PEP 408. +See :pep:`408`. References diff --git a/pep-0413.txt b/pep-0413.txt index b5da05071a9..11f1104d76f 100644 --- a/pep-0413.txt +++ b/pep-0413.txt @@ -36,13 +36,13 @@ versioning scheme) that allows accelerated releases of the Python standard library, while maintaining (or even slowing down) the current rate of change in the core language definition. -Like PEP 407, it aims to adjust the current balance between measured +Like :pep:`407`, it aims to adjust the current balance between measured change that allows the broader community time to adapt and being able to keep pace with external influences that evolve more rapidly than the current release cycle can handle (this problem is particularly notable for standard library elements that relate to web technologies). -However, it's more conservative in its aims than PEP 407, seeking to +However, it's more conservative in its aims than :pep:`407`, seeking to restrict the increased pace of development to builtin and standard library interfaces, without affecting the rate of change for other elements such as the language syntax and version numbering as well as the CPython @@ -52,7 +52,7 @@ binary API and bytecode format. Rationale ========= -To quote the PEP 407 abstract: +To quote the :pep:`407` abstract: Finding a release cycle for an open-source project is a delicate exercise in managing mutually contradicting constraints: developer manpower, @@ -67,13 +67,13 @@ To quote the PEP 407 abstract: more fluid release of features, by introducing the notion of long-term support versions. -I agree with the PEP 407 authors that the current release cycle of the +I agree with the :pep:`407` authors that the current release cycle of the *standard library* is too slow to effectively cope with the pace of change in some key programming areas (specifically, web protocols and related technologies, including databases, templating and serialisation formats). However, I have written this competing PEP because I believe that the -approach proposed in PEP 407 of offering full, potentially binary +approach proposed in :pep:`407` of offering full, potentially binary incompatible releases of CPython every 6 months places too great a burden on the wider Python ecosystem. @@ -97,7 +97,7 @@ quite some time to catch up with language level changes. At a cultural level, the Python community is also accustomed to a certain meaning for Python version numbers - they're linked to deprecation periods, -support periods, all sorts of things. PEP 407 proposes that collective +support periods, all sorts of things. :pep:`407` proposes that collective knowledge all be swept aside, without offering a compelling rationale for why such a course of action is actually *necessary* (aside from, perhaps, making the lives of the CPython core developers a little easier at the expense of @@ -116,7 +116,7 @@ Proposal ======== This PEP proposes the introduction of a new kind of CPython release: -"standard library releases". As with PEP 407, this will give CPython 3 kinds +"standard library releases". As with :pep:`407`, this will give CPython 3 kinds of release: * Language release: "x.y.0" @@ -142,7 +142,7 @@ release may contain any and all of the following changes: * changes to the AST * any other significant changes to the compilation toolchain * changes to the core interpreter eval loop -* binary incompatible changes to the C ABI (although the PEP 384 stable ABI +* binary incompatible changes to the C ABI (although the :pep:`384` stable ABI must still be preserved) * bug fixes @@ -156,7 +156,7 @@ documenting the standard library version. Standard library releases may include the following changes: * new features in pure Python modules -* new features in C extension modules (subject to PEP 399 compatibility +* new features in C extension modules (subject to :pep:`399` compatibility requirements) * new features in language builtins (provided the C ABI remains unaffected) * bug fixes from the corresponding maintenance release @@ -246,7 +246,7 @@ The versioning scheme proposed above is based on a number of user scenarios that are likely to be encountered if this scheme is adopted. In each case, the scenario is described for both the status quo (i.e. slow release cycle) the versioning scheme in this PEP and the free wheeling minor version number -scheme proposed in PEP 407. +scheme proposed in :pep:`407`. To give away the ending, the point of using a separate version number is that for almost all scenarios, the important number is the *language* version, not @@ -314,7 +314,7 @@ compatibility is important). Extension module author, deciding whether or not to make a binary release ------------------------------------------------------------------------- -**Status quo:** unless using the PEP 384 stable ABI, a new binary release is +**Status quo:** unless using the :pep:`384` stable ABI, a new binary release is needed every time the minor version number changes. **This PEP:** same as status quo. @@ -402,8 +402,8 @@ more explicit about their rate of adoption of standard library features. More conservative projects will likely pin their dependency to the language version and avoid features added in the standard library releases. Faster moving projects could instead declare their dependency on a particular -standard library version. However, since PEP 407 does have the advantage of -preserving the status quo, I'm calling this one for PEP 407 (albeit with a +standard library version. However, since :pep:`407` does have the advantage of +preserving the status quo, I'm calling this one for :pep:`407` (albeit with a slim margin). @@ -421,7 +421,7 @@ proved to be insufficient to reproduce the fault). **PEP 407:** same as the status quo -**Verdict:** another marginal win for PEP 407. The new standard library version +**Verdict:** another marginal win for :pep:`407`. The new standard library version *is* an extra piece of information that users may need to pass back to developers when reporting issues with Python libraries (or Python itself, on our own tracker). However, by including it in ``sys.version``, many @@ -444,7 +444,7 @@ both the former maintenance branch and the standard library update branch. but handling security fixes for non-LTS releases is currently an open question. -**Verdict:** until PEP 407 is updated to actually address this scenario, a +**Verdict:** until :pep:`407` is updated to actually address this scenario, a clear win for this PEP. @@ -454,7 +454,7 @@ Effects Effect on development cycle --------------------------- -Similar to PEP 407, this PEP will break up the delivery of new features into +Similar to :pep:`407`, this PEP will break up the delivery of new features into more discrete chunks. Instead of a whole raft of changes landing all at once in a language release, each language release will be limited to 6 months worth of standard library changes, as well as any changes associated with @@ -518,7 +518,7 @@ releases rather than using the new standard library releases. Effect on the community ----------------------- -PEP 407 has this to say about the effects on the community: +:pep:`407` has this to say about the effects on the community: People who value stability can just synchronize on the LTS releases which, with the proposed figures, would give a similar support cycle (both in @@ -543,7 +543,7 @@ going to ship standard library updates for the next language release in definition update, even those changes that are backwards compatible with the previously released version of Python. -The community benefits listed in PEP 407 are equally applicable to this PEP, +The community benefits listed in :pep:`407` are equally applicable to this PEP, at least as far as the standard library is concerned: People who value reactivity and access to new features (without taking the @@ -719,7 +719,7 @@ to make standard library releases even *faster* than every 6 months? If the practical issues were ever resolved, then the separate standard library versioning scheme in this PEP could handle it. The tagged version -number approach proposed in PEP 407 could not (at least, not without a lot +number approach proposed in :pep:`407` could not (at least, not without a lot of user confusion and uncertainty). @@ -812,7 +812,7 @@ a little tidying up of the What's New document before making the release. Why isn't PEP 384 enough? ------------------------- -PEP 384 introduced the notion of a "Stable ABI" for CPython, a limited +:pep:`384` introduced the notion of a "Stable ABI" for CPython, a limited subset of the full C ABI that is guaranteed to remain stable. Extensions built against the stable ABI should be able to support all subsequent Python versions with the same binary. @@ -853,7 +853,7 @@ library releases: * Standard library updates * new features in pure Python modules - * new features in C extension modules (subject to PEP 399 compatibility + * new features in C extension modules (subject to :pep:`399` compatibility requirements) * new features in language builtins @@ -874,7 +874,7 @@ And the following changes would be acceptable in language releases: * removal of previously deprecated features * changes to the AST * changes to the emitted bytecode that require altering the magic number -* binary incompatible changes to the C ABI (although the PEP 384 stable ABI +* binary incompatible changes to the C ABI (although the :pep:`384` stable ABI must still be preserved) While such an approach could probably be made to work, there does not appear @@ -906,16 +906,13 @@ fraction of the pain. Acknowledgements ================ -Thanks go to the PEP 407 authors for starting this discussion, as well as +Thanks go to the :pep:`407` authors for starting this discussion, as well as to those authors and Larry Hastings for initial discussions of the proposal made in this PEP. References ========== -.. [1] PEP 407: New release cycle and introducing long-term support versions - http://www.python.org/dev/peps/pep-0407/ - .. [2] Twisted's "topfiles" approach to NEWS generation http://twistedmatrix.com/trac/wiki/ReviewProcess#Newsfiles diff --git a/pep-0414.txt b/pep-0414.txt index f303b81bc2d..158b653bfc3 100644 --- a/pep-0414.txt +++ b/pep-0414.txt @@ -115,7 +115,7 @@ Rationale ========= With the release of a Python 3 compatible version of the Web Services Gateway -Interface (WSGI) specification (PEP 3333) for Python 3.2, many parts of the +Interface (WSGI) specification (:pep:`3333`) for Python 3.2, many parts of the Python web ecosystem have been making a concerted effort to support Python 3 without adversely affecting their existing developer and user communities. diff --git a/pep-0415.txt b/pep-0415.txt index 827134c01db..48715a21f43 100644 --- a/pep-0415.txt +++ b/pep-0415.txt @@ -17,9 +17,9 @@ Resolution: https://mail.python.org/pipermail/python-dev/2012-May/119467.html Abstract ======== -PEP 409 introduced support for the ``raise exc from None`` construct to +:pep:`409` introduced support for the ``raise exc from None`` construct to allow the display of the exception context to be explicitly suppressed. -This PEP retains the language level changes already implemented in PEP 409, +This PEP retains the language level changes already implemented in :pep:`409`, but replaces the underlying implementation mechanism with a simpler approach based on a new ``__suppress_context__`` attribute on all ``BaseException`` instances. @@ -34,7 +34,7 @@ This PEP was accepted by Nick Coghlan on the 14th of May, 2012. Rationale ========= -PEP 409 changes ``__cause__`` to be ``Ellipsis`` by default. Then if +:pep:`409` changes ``__cause__`` to be ``Ellipsis`` by default. Then if ``__cause__`` is set to ``None`` by ``raise exc from None``, no context or cause will be printed should the exception be uncaught. @@ -43,9 +43,9 @@ The main problem with this scheme is it complicates the role of whether ``__context__`` should be printed or not. This use of ``__cause__`` is also not easily extended in the future. For example, we may someday want to allow the programmer to select which of ``__context__`` and ``__cause__`` will -be printed. The PEP 409 implementation is not amenable to this. +be printed. The :pep:`409` implementation is not amenable to this. -The use of ``Ellipsis`` is a hack. Before PEP 409, ``Ellipsis`` was used +The use of ``Ellipsis`` is a hack. Before :pep:`409`, ``Ellipsis`` was used exclusively in extended slicing. Extended slicing has nothing to do with exceptions, so it's not clear to someone inspecting an exception object why ``__cause__`` should be set to ``Ellipsis``. Using ``Ellipsis`` by default for diff --git a/pep-0416.txt b/pep-0416.txt index 692855684bb..59e2e4d08b8 100644 --- a/pep-0416.txt +++ b/pep-0416.txt @@ -131,9 +131,9 @@ just need to be practically constant.* If frozendict is used to harden Python (security purpose), it must be implemented in C. A type implemented in C is also faster. -*The PEP 351 was rejected.* +*The* :pep:`351` *was rejected.* -The PEP 351 tries to freeze an object and so may convert a mutable object to an +The :pep:`351` tries to freeze an object and so may convert a mutable object to an immutable object (using a different type). frozendict doesn't convert anything: hash(frozendict) raises a TypeError if a value is not hashable. Freezing an object is not the purpose of this PEP. @@ -233,7 +233,7 @@ Links `_ * PEP 412: Key-Sharing Dictionary (`issue #13903 `_) -* PEP 351: The freeze protocol +* :pep:`351`: The freeze protocol * `The case for immutable dictionaries; and the central misunderstanding of PEP 351 `_ * `make dictproxy object via ctypes.pythonapi and type() (Python recipe diff --git a/pep-0420.txt b/pep-0420.txt index c8335ca103b..0f0baa73319 100644 --- a/pep-0420.txt +++ b/pep-0420.txt @@ -19,7 +19,7 @@ across multiple directories on disk. In current Python versions, an algorithm to compute the packages ``__path__`` must be formulated. With the enhancement proposed here, the import machinery itself will construct the list of directories that make up the package. This PEP builds upon previous work, -documented in PEP 382 and PEP 402. Those PEPs have since been rejected in +documented in :pep:`382` and :pep:`402`. Those PEPs have since been rejected in favor of this one. An implementation of this PEP is at [1]_. @@ -86,8 +86,9 @@ setuptools allows declaring namespace packages in a distribution's ``setup.py``, so that distribution developers don't need to put the magic ``__path__`` modification into ``__init__.py`` themselves. -See PEP 402's "The Problem" section [2]_ for additional motivations -for namespace packages. Note that PEP 402 has been rejected, but the +See :pep:`402`'s :pep:`"The Problem" <402#the-problem>` +section for additional motivations +for namespace packages. Note that :pep:`402` has been rejected, but the motivating use cases are still valid. @@ -213,7 +214,7 @@ path with a new path entry list object. Impact on import finders and loaders ------------------------------------ -PEP 302 defines "finders" that are called to search path elements. +:pep:`302` defines "finders" that are called to search path elements. These finders' ``find_module`` methods return either a "loader" object or ``None``. @@ -242,7 +243,7 @@ back to ``find_module``. Legacy finders which implement ``find_module`` but not ``find_loader`` will be unable to contribute portions to a namespace package. -The specification expands PEP 302 loaders to include an optional method called +The specification expands :pep:`302` loaders to include an optional method called ``module_repr()`` which if present, is used to generate module object reprs. See the section below for further details. @@ -284,9 +285,9 @@ As described above, prior to this PEP ``pkgutil.extend_path()`` was used by legacy portions to create namespace packages. Because it is likely not practical for all existing portions of a namespace package to be migrated to this PEP at once, ``extend_path()`` will be modified -to also recognize PEP 420 namespace packages. This will allow some +to also recognize :pep:`420` namespace packages. This will allow some portions of a namespace to be legacy portions while others are -migrated to PEP 420. These hybrid namespace packages will not have +migrated to :pep:`420`. These hybrid namespace packages will not have the dynamic path computation that normal namespace packages have, since ``extend_path()`` never provided this functionality in the past. @@ -428,7 +429,7 @@ Discussion ========== At PyCon 2012, we had a discussion about namespace packages at which -PEP 382 and PEP 402 were rejected, to be replaced by this PEP [3]_. +:pep:`382` and :pep:`402` were rejected, to be replaced by this PEP [3]_. There is no intention to remove support of regular packages. If a developer knows that her package will never be a portion of a @@ -466,9 +467,9 @@ is summarized here: 2. Minor backward compatibility issues are okay, as long as they are properly documented. -3. This will be addressed in PEP 395. +3. This will be addressed in :pep:`395`. -4. This will also be addressed in PEP 395. +4. This will also be addressed in :pep:`395`. The inclusion of namespace packages in the standard library was motivated by Martin v. Löwis, who wanted the ``encodings`` package to @@ -530,7 +531,7 @@ Module reprs Previously, module reprs were hard coded based on assumptions about a module's ``__file__`` attribute. If this attribute existed and was a string, it was assumed to be a file system path, and the module object's repr would include -this in its value. The only exception was that PEP 302 reserved missing +this in its value. The only exception was that :pep:`302` reserved missing ``__file__`` attributes to built-in modules, and in CPython, this assumption was baked into the module object's implementation. Because of this restriction, some modules contained contrived ``__file__`` values that did not @@ -547,7 +548,7 @@ the definitive way to determine the origin of a module is to check its For example, namespace packages as described in this PEP will have no ``__file__`` attribute because no corresponding file exists. In order to provide flexibility and descriptiveness in the reprs of such modules, a new -optional protocol is added to PEP 302 loaders. Loaders can implement a +optional protocol is added to :pep:`302` loaders. Loaders can implement a ``module_repr()`` method which takes a single argument, the module object. This method should return the string to be used verbatim as the repr of the module. The rules for producing a module repr are now standardized as: @@ -618,9 +619,6 @@ References .. [1] PEP 420 branch (http://hg.python.org/features/pep-420) -.. [2] PEP 402's description of use cases for namespace packages - (http://www.python.org/dev/peps/pep-0402/#the-problem) - .. [3] PyCon 2012 Namespace Package discussion outcome (https://mail.python.org/pipermail/import-sig/2012-March/000421.html) diff --git a/pep-0421.txt b/pep-0421.txt index 28c04cea400..0904fed48dd 100644 --- a/pep-0421.txt +++ b/pep-0421.txt @@ -98,7 +98,7 @@ define them: ``sys.hexversion``. **cache_tag** - A string used for the PEP 3147 cache tag [#cachetag]_. It would + A string used for the :pep:`3147` cache tag. It would normally be a composite of the name and version (e.g. 'cpython-33' for CPython 3.3). However, an implementation may explicitly use a different cache tag. If ``cache_tag`` is set to None, it indicates @@ -240,14 +240,15 @@ in ``platform`` wrapping it). Cache Tag Generation in Frozen Importlib ---------------------------------------- -PEP 3147 defined the use of a module cache and cache tags for file +:pep:`3147` defined the use of a module cache and cache tags for file names. The importlib bootstrap code, frozen into the Python binary as of 3.3, uses the cache tags during the import process. Part of the project to bootstrap importlib has been to clean code out of `Python/import.c`_ that did not need to be there any longer. -The cache tag defined in ``Python/import.c`` was hard-coded to -``"cpython" MAJOR MINOR`` [#cachetag]_. For importlib the options are +The cache tag defined in ``Python/import.c`` was +:pep:`hard-coded <3147#proposal>` +to ``"cpython" MAJOR MINOR``. For importlib the options are either hard-coding it in the same way, or guessing the implementation in the same way as does ``platform.python_implementation()``. @@ -351,21 +352,21 @@ this PEP is a small start, will be considered separately. Past Efforts ============ -``PEP 3139`` ------------- +PEP 3139 +-------- -PEP 3139, from 2008, recommended a clean-up of the ``sys`` module in +:pep:`3139`, from 2008, recommended a clean-up of the ``sys`` module in part by extracting implementation-specific variables and functions -into a separate module. PEP 421 is less ambitious version of that -idea. While PEP 3139 was rejected, its goals are reflected in PEP 421 +into a separate module. :pep:`421` is less ambitious version of that +idea. While :pep:`3139` was rejected, its goals are reflected in :pep:`421` to a large extent, though with a much lighter approach. -``PEP 399`` ------------ +PEP 399 +------- -PEP 399 dictates policy regarding the standard library, helping to make -it friendlier to alternate implementations. PEP 421 is proposed in +:pep:`399` dictates policy regarding the standard library, helping to make +it friendlier to alternate implementations. :pep:`421` is proposed in that same spirit. @@ -381,7 +382,7 @@ data, acting as a nexus for cooperation between the language, the standard library, and the different implementations. As time goes by it is feasible that ``sys.implementation`` will assume current attributes of ``sys`` and other builtin/stdlib modules, where -appropriate. In this way, it is a PEP 3137-lite, but starting as +appropriate. In this way, it is a :pep:`3137`-lite, but starting as small as possible. However, as already noted, many other efforts predate @@ -485,9 +486,6 @@ References .. [#guess] The ``platform`` code which divines the implementation name: http://hg.python.org/cpython/file/2f563908ebc5/Lib/platform.py#l1247 -.. [#cachetag] The definition for cache tags in PEP 3147: - http://www.python.org/dev/peps/pep-3147/#id53 - .. [#tag_impl] The original implementation of the cache tag in CPython: http://hg.python.org/cpython/file/2f563908ebc5/Python/import.c#l121 diff --git a/pep-0422.txt b/pep-0422.txt index c02fa8a5bed..71e76ca2c13 100644 --- a/pep-0422.txt +++ b/pep-0422.txt @@ -32,7 +32,7 @@ PEP Withdrawal ============== This proposal has been withdrawn in favour of Martin Teichmann's proposal -in PEP 487, which achieves the same goals through a simpler, easier to use +in :pep:`487`, which achieves the same goals through a simpler, easier to use ``__init_subclass__`` hook that simply isn't invoked for the base class that defines the hook. @@ -71,13 +71,13 @@ execution of the class body (for example, specifying the use of ``collections.OrderedDict`` instead of a regular ``dict``). In Python 2, there was no ``__prepare__`` method (that API was added for -Python 3 by PEP 3115). Instead, a class body could set the ``__metaclass__`` +Python 3 by :pep:`3115`). Instead, a class body could set the ``__metaclass__`` attribute, and the class creation process would extract that value from the class namespace to use as the metaclass hint. There is `published code`_ that makes use of this feature. Another new feature in Python 3 is the zero-argument form of the ``super()`` -builtin, introduced by PEP 3135. This feature uses an implicit ``__class__`` +builtin, introduced by :pep:`3135`. This feature uses an implicit ``__class__`` reference to the class being defined to replace the "by name" references required in Python 2. Just as code invoked during execution of a Python 2 metaclass could not call methods that referenced the class by name (as the @@ -103,7 +103,7 @@ added to Python 3.4 that meets the following criteria: 1. Integrates nicely with class inheritance structures (including mixins and multiple inheritance) 2. Integrates nicely with the implicit ``__class__`` reference and - zero-argument ``super()`` syntax introduced by PEP 3135 + zero-argument ``super()`` syntax introduced by :pep:`3135` 3. Can be added to an existing base class without a significant risk of introducing backwards compatibility problems 4. Restores the ability for class namespaces to have some influence on the @@ -240,12 +240,12 @@ signature of ``__autodecorate__``, the risk in this case is actually even lower than in the case of ``__init__``. -Integrates cleanly with \PEP 3135 ---------------------------------- +Integrates cleanly with PEP 3135 +-------------------------------- Unlike code that runs as part of the metaclass, code that runs as part of the new hook will be able to freely invoke class methods that rely on the -implicit ``__class__`` reference introduced by PEP 3135, including methods +implicit ``__class__`` reference introduced by :pep:`3135`, including methods that use the zero argument form of ``super()``. @@ -484,7 +484,7 @@ detected anyway in order to give a useful error message. This decision was reinforced after noticing that the user experience of defining ``__prepare__`` and forgetting the ``@classmethod`` method -decorator is singularly incomprehensible (particularly since PEP 3115 +decorator is singularly incomprehensible (particularly since :pep:`3115` documents it as an ordinary method, and the current documentation doesn't explicitly say anything one way or the other). diff --git a/pep-0423.txt b/pep-0423.txt index 43dd9c6b604..b33218797e5 100644 --- a/pep-0423.txt +++ b/pep-0423.txt @@ -32,7 +32,7 @@ PEP Deferral ============ Further consideration of this PEP has been deferred at least until after -PEP 426 (package metadata 2.0) and related updates have been resolved. +:pep:`426` (package metadata 2.0) and related updates have been resolved. Terminology =========== @@ -43,17 +43,18 @@ Reference is `packaging terminology in Python documentation`_. Relationship with other PEPs ============================ -* `PEP 8`_ deals with code style guide, including names of Python +* :pep:`8#package-and-module-names` + deals with code style guide, including names of Python packages and modules. It covers syntax of package/modules names. -* `PEP 345`_ deals with packaging metadata, and defines name argument +* :pep:`345` deals with packaging metadata, and defines name argument of the ``packaging.core.setup()`` function. -* `PEP 420`_ deals with namespace packages. It brings support of +* :pep:`420` deals with namespace packages. It brings support of namespace packages to Python core. Before, namespaces packages were implemented by external libraries. -* `PEP 3108`_ deals with transition between Python 2.x and Python 3.x +* :pep:`3108` deals with transition between Python 2.x and Python 3.x applied to standard library: some modules to be deleted, some to be renamed. It points out that naming conventions matter and is an example of transition plan. @@ -316,9 +317,10 @@ name. Follow PEP 8 for syntax of package and module names =================================================== -`PEP 8`_ applies to names of Python packages and modules. +:pep:`PEP 8 <8#package-and-module-names>` applies to names of Python packages and modules. -If you `Use a single name`_, `PEP 8`_ also applies to project names. +If you `Use a single name`_, :pep:`PEP 8 <8#package-and-module-names>` +also applies to project names. The exceptions are namespace packages, where dots are required in project name. @@ -388,7 +390,7 @@ But it would be possible if all these distributions used Avoid deep nesting ================== -`The Zen of Python`_ says "Flat is better than nested". +:pep:`The Zen of Python <20>` says "Flat is better than nested". Two levels is almost always enough ---------------------------------- @@ -657,7 +659,8 @@ documentation, so that users understand what happened. * import statements in code. #. Assign ``Obsoletes-Dist`` metadata to new distribution in setup.cfg - file. See `PEP 345 about Obsolete-Dist`_ and `setup.cfg + file. See :pep:`PEP 345 about Obsolete-Dist <345#obsoletes-dist-multiple-use>` + and `setup.cfg specification`_. #. Release a new version of the renamed project, then publish it. @@ -760,7 +763,7 @@ As of Python 3.3 being developed: * packaging (aka distutils2) is on the starting blocks. When it is released, projects will be invited to migrate and use new packaging. -* `PEP 420`_ brings official support of namespace packages to Python. +* :pep:`420` brings official support of namespace packages to Python. It means that most active projects should be about to migrate in the next year(s) to support Python 3.x, new packaging or new namespace @@ -788,11 +791,6 @@ References and footnotes: .. _`packaging terminology in Python documentation`: https://packaging.python.org/glossary/ -.. _`PEP 8`: - http://www.python.org/dev/peps/pep-0008/#package-and-module-names -.. _`PEP 345`: http://www.python.org/dev/peps/pep-0345/ -.. _`PEP 420`: http://www.python.org/dev/peps/pep-0420/ -.. _`PEP 3108`: http://www.python.org/dev/peps/pep-3108/ .. _`Python community`: http://www.python.org/community/ .. _`gp.fileupload`: http://pypi.python.org/pypi/gp.fileupload/ .. _`zest.releaser`: http://pypi.python.org/pypi/zest.releaser/ @@ -815,14 +813,11 @@ References and footnotes: .. _`DateUtils`: http://pypi.python.org/pypi/DateUtils/ .. _`Framework :: Twisted`: http://pypi.python.org/pypi?:action=browse&show=all&c=525 -.. _`The Zen of Python`: http://www.python.org/dev/peps/pep-0020/ .. _`Plone community`: http://plone.org/community/develop .. _`Registering with the Package Index`: https://docs.python.org/3/distutils/packageindex.html .. _`Python Standard Library`: http://docs.python.org/library/index.html -.. _`PEP 345 about Obsolete-Dist`: - http://www.python.org/dev/peps/pep-0345/#obsoletes-dist-multiple-use .. _`setup.cfg specification`: http://docs.python.org/dev/packaging/setupcfg.html .. _`Martin Aspeli's article about names`: diff --git a/pep-0425.txt b/pep-0425.txt index 3ae109e5a49..22387cc8e99 100644 --- a/pep-0425.txt +++ b/pep-0425.txt @@ -276,9 +276,6 @@ References .. [2] Creating Built Distributions (http://docs.python.org/distutils/builtdist.html) -.. [3] PEP 3147 -- PYC Repository Directories - (http://www.python.org/dev/peps/pep-3147/) - Acknowledgements ================ diff --git a/pep-0426.txt b/pep-0426.txt index 3826220ad1c..20cae9a249b 100644 --- a/pep-0426.txt +++ b/pep-0426.txt @@ -22,11 +22,11 @@ PEP Withdrawal ============== The ground-up metadata redesign proposed in this PEP has been withdrawn in -favour of the more modest proposal in PEP 566, which retains the basic +favour of the more modest proposal in :pep:`566`, which retains the basic Key:Value format of previous metadata versions, but also defines a standardised mechanism for translating that format to nested JSON-compatible data structures. -Some of the ideas in this PEP (or the related PEP 459) may still be considered +Some of the ideas in this PEP (or the related :pep:`459`) may still be considered as part of later proposals, but they will be handled in a more incremental fashion, rather than as a single large proposed change with no feasible migration plan. @@ -41,9 +41,9 @@ and their semantics and usage. This document specifies the never released version 2.0 of the metadata format. -Version 1.0 is specified in PEP 241. -Version 1.1 is specified in PEP 314. -Version 1.2 is specified in PEP 345. +Version 1.0 is specified in :pep:`241`. +Version 1.1 is specified in :pep:`314`. +Version 1.2 is specified in :pep:`345`. Version 2.0 of the metadata format proposed migrating from directly defining a custom key-value file format to instead defining a JSON-compatible in-memory @@ -62,15 +62,15 @@ This PEP was initially deferred for an extended period, from December 2013 through to March 2017, as distutils-sig worked through a number of other changes. These changes included: -* defining a binary compatibility tagging format in PEP 425 -* defining a binary archive format (``wheel``) in PEP 427 -* explicitly defining versioning and version comparison in PEP 440 -* explicitly defining the PyPI "simple" API in PEP 503 -* explicitly defining dependency specifiers and the extras system in PEP 508 -* declaring static build system dependencies (``pyproject.toml``) in PEP 518 +* defining a binary compatibility tagging format in :pep:`425` +* defining a binary archive format (``wheel``) in :pep:`427` +* explicitly defining versioning and version comparison in :pep:`440` +* explicitly defining the PyPI "simple" API in :pep:`503` +* explicitly defining dependency specifiers and the extras system in :pep:`508` +* declaring static build system dependencies (``pyproject.toml``) in :pep:`518` * migrating PyPI hosting to Rackspace, and placing it behind the Fastly CDN -* shipping ``pip`` with CPython by default in PEP 453, and backporting that - addition to Python 2.7 in PEP 477 +* shipping ``pip`` with CPython by default in :pep:`453`, and backporting that + addition to Python 2.7 in :pep:`477` * establishing `packaging.python.org`_ as the common access point for Python packaging ecosystem documentation * migrating to using the `specifications`_ section of packaging.python.org @@ -81,7 +81,7 @@ metadata format changes were genuinely desirable, and which could be omitted from the revised specification as merely being "change for change's sake". It also allowed a number of features that aren't critical to the core activity -of publishing and distributing software to be moved out to PEP 459, a separate +of publishing and distributing software to be moved out to :pep:`459`, a separate proposal for a number of standard metadata extensions that provide additional optional information about a release. @@ -98,7 +98,7 @@ it doesn't actually help solve any particularly pressing problems: .. _specifications: https://packaging.python.org/specifications/ .. _minor spec version update: https://mail.python.org/pipermail/distutils-sig/2017-September/031465.html -Finally, the PEP was withdrawn in February 2018 in favour of PEP 566 (which +Finally, the PEP was withdrawn in February 2018 in favour of :pep:`566` (which pursues that more incremental strategy). @@ -178,7 +178,7 @@ Supporting definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -document are to be interpreted as described in RFC 2119. +document are to be interpreted as described in :rfc:`2119`. "Projects" are software components that are made available for integration. Projects include Python libraries, frameworks, scripts, plugins, @@ -450,7 +450,7 @@ This schema does NOT currently handle validation of some of the more complex string fields (instead treating them as opaque strings). Except where otherwise noted, all URL fields in the metadata MUST comply -with RFC 3986. +with :rfc:`3986`. .. note:: @@ -486,7 +486,7 @@ Version of the file format; ``"2.0"`` is the only legal value. Automated tools consuming metadata SHOULD warn if ``metadata_version`` is greater than the highest version they support, and MUST fail if ``metadata_version`` has a greater major version than the highest -version they support (as described in PEP 440, the major version is the +version they support (as described in :pep:`440`, the major version is the value before the first dot). For broader compatibility, build tools MAY choose to produce @@ -513,7 +513,7 @@ Examples:: Name ---- -The name of the distribution, as defined in PEP 508. +The name of the distribution, as defined in :pep:`508`. As distribution names are used as part of URLs, filenames, command line parameters and must also interoperate with other packaging systems, the @@ -562,17 +562,17 @@ Example:: Version ------- -The distribution's public or local version identifier, as defined in PEP 440. +The distribution's public or local version identifier, as defined in :pep:`440`. Version identifiers are designed for consumption by automated tools and -support a variety of flexible version specification mechanisms (see PEP 440 +support a variety of flexible version specification mechanisms (see :pep:`440` for details). -Version identifiers MUST comply with the format defined in PEP 440. +Version identifiers MUST comply with the format defined in :pep:`440`. Version identifiers MUST be unique within each project. Index servers MAY place restrictions on the use of local version identifiers -as described in PEP 440. +as described in :pep:`440`. Example:: @@ -758,8 +758,8 @@ other extras: * ``all``: if not otherwise defined, implies all declared extras Dependency management is heavily dependent on the version identification -and specification scheme defined in PEP 440 and the dependency specification, -extra, and environment marker schemes defined in PEP 508. +and specification scheme defined in :pep:`440` and the dependency specification, +extra, and environment marker schemes defined in :pep:`508`. All of these fields are optional. Automated tools MUST operate correctly if a distribution does not provide them, by assuming that a missing field @@ -864,10 +864,10 @@ subfields: and installed together. See `Extras (optional dependencies)`_ for details * ``environment``: an environment marker defining the environment that needs these dependencies. The syntax and capabilities of environment - markers are defined in PEP 508 + markers are defined in :pep:`508` Individual entries in the ``requires`` lists are strings using the dependency -declaration format defined in PEP 508, with the exception that environment +declaration format defined in :pep:`508`, with the exception that environment markers MUST NOT be included in the individual dependency declarations, and are instead supplied in the separate ``environment`` field. @@ -960,7 +960,7 @@ However, if this key is omitted, then the implied version is ``1.0``. Automated tools consuming extension metadata SHOULD warn if ``extension_version`` is greater than the highest version they support, and MUST fail if ``extension_version`` has a greater major version than -the highest version they support (as described in PEP 440, the major +the highest version they support (as described in :pep:`440`, the major version is the value before the first dot). For broader compatibility, build tools MAY choose to produce @@ -990,7 +990,7 @@ back on attempting to install from source rather than failing entirely. Extras (optional dependencies) ============================== -As defined in PEP 508, extras are additional dependencies that enable an +As defined in :pep:`508`, extras are additional dependencies that enable an optional aspect of a project release, often corresponding to a ``try: import optional_dependency ...`` block in the code. They are also used to indicate semantic dependencies for activities other than normal runtime using (such as @@ -1125,8 +1125,8 @@ to manually duplicate any of the upstream metadata in a distribution specific format. -Appendix C: Summary of differences from \PEP 345 -================================================= +Appendix C: Summary of differences from PEP 345 +=============================================== * Metadata-Version is now 2.0, with semantics specified for handling version changes @@ -1145,12 +1145,12 @@ Appendix C: Summary of differences from \PEP 345 exist and how they are intended to be used, rather than being a simple description of the permitted contents -* Changed the version scheme to be based on PEP 440 rather than PEP 386 +* Changed the version scheme to be based on :pep:`440` rather than :pep:`386` -* Added the source label mechanism as described in PEP 440 +* Added the source label mechanism as described in :pep:`440` * Formally defined dependency declarations, extras, and environment markers - in PEP 508 + in :pep:`508` * Support for different kinds of dependencies through additional reserved extra names @@ -1171,13 +1171,13 @@ Metadata-Version semantics The semantics of major and minor version increments are now specified, and follow the same model as the format version semantics specified for -the wheel format in PEP 427: minor version increments must behave +the wheel format in :pep:`427`: minor version increments must behave reasonably when processed by a tool that only understand earlier metadata versions with the same major version, while major version increments may include changes that are not compatible with existing tools. The major version number of the specification has been incremented -accordingly, as interpreting PEP 426 metadata obviously cannot be +accordingly, as interpreting :pep:`426` metadata obviously cannot be interpreted in accordance with earlier metadata specifications. Whenever the major version number of the specification is incremented, it @@ -1228,7 +1228,7 @@ target environment. Changing the version scheme --------------------------- -See PEP 440 for a detailed rationale for the various changes made to the +See :pep:`440` for a detailed rationale for the various changes made to the versioning scheme. @@ -1325,7 +1325,7 @@ Standard extensions ------------------- Some of the information provided by the legacy metadata system has been -moved out to standard extensions defined in PEP 459. +moved out to standard extensions defined in :pep:`459`. This allows publication of the core dependency metadata in a more readily consumable format to proceed even before the full details of those extensions @@ -1472,7 +1472,7 @@ compatibility by the upstream project. Compatible release comparisons in environment markers ----------------------------------------------------- -PEP 440 defines a rich syntax for version comparisons that could +:pep:`440` defines a rich syntax for version comparisons that could potentially be useful with ``python_version`` and ``python_full_version`` in environment markers. However, allowing the full syntax would mean environment markers are no longer a Python subset, while allowing @@ -1499,12 +1499,12 @@ References ========== This document specifies version 2.0 of the metadata format. -Version 1.0 is specified in PEP 241. -Version 1.1 is specified in PEP 314. -Version 1.2 is specified in PEP 345. +Version 1.0 is specified in :pep:`241`. +Version 1.1 is specified in :pep:`314`. +Version 1.2 is specified in :pep:`345`. The initial attempt at a standardised version scheme, along with the -justifications for needing such a standard can be found in PEP 386. +justifications for needing such a standard can be found in :pep:`386`. .. [1] reStructuredText markup: http://docutils.sourceforge.net/ diff --git a/pep-0427.txt b/pep-0427.txt index 2ef81b14f2c..bb770317506 100644 --- a/pep-0427.txt +++ b/pep-0427.txt @@ -26,7 +26,7 @@ This PEP describes a built-package format for Python called "wheel". A wheel is a ZIP-format archive with a specially formatted file name and the ``.whl`` extension. It contains a single distribution nearly as it -would be installed according to PEP 376 with a particular installation +would be installed according to :pep:`376` with a particular installation scheme. Although a specialized installer is recommended, a wheel file may be installed by simply unpacking into site-packages with the standard 'unzip' tool while preserving enough information to spread its contents @@ -160,7 +160,7 @@ on any CPU architecture. The last three components of the filename before the extension are called "compatibility tags." The compatibility tags express the -package's basic interpreter requirements and are detailed in PEP 425. +package's basic interpreter requirements and are detailed in :pep:`425`. Escaping and Unicode '''''''''''''''''''' @@ -241,12 +241,12 @@ The .dist-info directory found at the root of sdists. #. WHEEL is the wheel metadata specific to a build of the package. #. RECORD is a list of (almost) all the files in the wheel and their - secure hashes. Unlike PEP 376, every file except RECORD, which + secure hashes. Unlike :pep:`376`, every file except RECORD, which cannot contain a hash of itself, must include its hash. The hash algorithm must be sha256 or better; specifically, md5 and sha1 are not permitted, as signed wheel files rely on the strong hashes in RECORD to validate the integrity of the archive. -#. PEP 376's INSTALLER and REQUESTED are not included in the archive. +#. :pep:`376`'s INSTALLER and REQUESTED are not included in the archive. #. RECORD.jws is used for digital signatures. It is not mentioned in RECORD. #. RECORD.p7s is allowed as a courtesy to anyone who would prefer to @@ -278,7 +278,7 @@ Signed wheel files ------------------ Wheel files include an extended RECORD that enables digital -signatures. PEP 376's RECORD is altered to include a secure hash +signatures. :pep:`376`'s RECORD is altered to include a secure hash ``digestname=urlsafe_b64encode_nopad(digest)`` (urlsafe base64 encoding with no trailing = characters) as the second column instead of an md5sum. All possible entries are hashed, including any @@ -312,10 +312,10 @@ checker only needs to establish that RECORD matches the signature. See -- http://self-issued.info/docs/draft-ietf-jose-json-web-signature.html -- http://self-issued.info/docs/draft-jones-jose-jws-json-serialization.html -- http://self-issued.info/docs/draft-ietf-jose-json-web-key.html -- http://self-issued.info/docs/draft-jones-jose-json-private-key.html +- https://datatracker.ietf.org/doc/html/rfc7515 +- https://datatracker.ietf.org/doc/html/draft-jones-jose-jws-json-serialization.html +- https://datatracker.ietf.org/doc/html/rfc7517 +- https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key.html Comparison to .egg diff --git a/pep-0429.txt b/pep-0429.txt index 05f4f077cc2..be730a4019e 100644 --- a/pep-0429.txt +++ b/pep-0429.txt @@ -78,28 +78,28 @@ Features for 3.4 Implemented / Final PEPs: -* PEP 428, a "pathlib" module providing object-oriented filesystem paths -* PEP 435, a standardized "enum" module -* PEP 436, a build enhancement that will help generate introspection information for builtins -* PEP 442, improved semantics for object finalization -* PEP 443, adding single-dispatch generic functions to the standard library -* PEP 445, a new C API for implementing custom memory allocators -* PEP 446, changing file descriptors to not be inherited by default in subprocesses -* PEP 450, a new "statistics" module -* PEP 451, standardizing module metadata for Python's module import system -* PEP 453, a bundled installer for the *pip* package manager -* PEP 454, a new "tracemalloc" module for tracing Python memory allocations -* PEP 456, a new hash algorithm for Python strings and binary data -* PEP 3154, a new and improved protocol for pickled objects -* PEP 3156, a new "asyncio" module, a new framework for asynchronous I/O +* :pep:`428`, a "pathlib" module providing object-oriented filesystem paths +* :pep:`435`, a standardized "enum" module +* :pep:`436`, a build enhancement that will help generate introspection information for builtins +* :pep:`442`, improved semantics for object finalization +* :pep:`443`, adding single-dispatch generic functions to the standard library +* :pep:`445`, a new C API for implementing custom memory allocators +* :pep:`446`, changing file descriptors to not be inherited by default in subprocesses +* :pep:`450`, a new "statistics" module +* :pep:`451`, standardizing module metadata for Python's module import system +* :pep:`453`, a bundled installer for the *pip* package manager +* :pep:`454`, a new "tracemalloc" module for tracing Python memory allocations +* :pep:`456`, a new hash algorithm for Python strings and binary data +* :pep:`3154`, a new and improved protocol for pickled objects +* :pep:`3156`, a new "asyncio" module, a new framework for asynchronous I/O Deferred to post-3.4: -* PEP 431, improved support for time zone databases -* PEP 441, improved Python zip application support -* PEP 447, support for __locallookup__ metaclass method -* PEP 448, additional unpacking generalizations -* PEP 455, key transforming dictionary +* :pep:`431`, improved support for time zone databases +* :pep:`441`, improved Python zip application support +* :pep:`447`, support for __locallookup__ metaclass method +* :pep:`448`, additional unpacking generalizations +* :pep:`455`, key transforming dictionary Copyright diff --git a/pep-0431.txt b/pep-0431.txt index 0846647969f..070e41eda0d 100644 --- a/pep-0431.txt +++ b/pep-0431.txt @@ -32,7 +32,7 @@ ambiguous datetimes and will never do so. I therefore withdraw this PEP. -**UPDATE**: The PEP 615 "Support for the IANA Time Zone Database in the +**UPDATE**: The :pep:`615` "Support for the IANA Time Zone Database in the Standard Library" added the ``zoneinfo`` module to Python 3.9 and superseded this PEP. diff --git a/pep-0432.txt b/pep-0432.txt index 2c7ac6e6953..5ae372c309f 100644 --- a/pep-0432.txt +++ b/pep-0432.txt @@ -24,17 +24,17 @@ and the CPython runtime easier to embed as part of a larger application. For most of that time, the changes were maintained either in a separate feature branch, or else as underscore-prefixed private APIs in the main CPython repo. -In 2019, PEP 587 migrated a subset of those API changes to the public CPython +In 2019, :pep:`587` migrated a subset of those API changes to the public CPython API for Python 3.8+ (specifically, the PEP updated the interpreter runtime to offer an explicitly multi-stage struct-based configuration interface). In June 2020, in response to a query from the Steering Council, the PEP authors decided that it made sense to withdraw the original PEP, as enough has changed -since PEP 432 was first written that we think any further changes to the +since :pep:`432` was first written that we think any further changes to the startup sequence and embedding API would be best formulated as a new PEP (or -PEPs) that take into account not only the not-yet-implemented ideas from PEP 432 +PEPs) that take into account not only the not-yet-implemented ideas from :pep:`432` that weren't considered sufficiently well validated to make their way into -PEP 587, but also any feedback on the public PEP 587 API, and any other lessons +:pep:`587`, but also any feedback on the public :pep:`587` API, and any other lessons that have been learned while adjusting the CPython implementation to be more embedding and subinterpreter friendly. @@ -118,7 +118,7 @@ well-defined phases during the initialization sequence: * Initialized - main interpreter fully available, subinterpreter creation available -PEP 587 is a more detailed proposal that covers separating out the +:pep:`587` is a more detailed proposal that covers separating out the Pre-Initialization phase from the last two phases, but doesn't allow embedding applications to run arbitrary code while in the "Runtime Initialized" state (instead, initializing the core runtime will also always fully initialize the @@ -209,7 +209,7 @@ only need to understand: fully configured (which will hopefully be a relatively small subset of the full C API) -The first two aspects of that are covered by PEP 587, while the details of the +The first two aspects of that are covered by :pep:`587`, while the details of the latter distinction are still being considered. By basing the new design on a combination of C structures and Python @@ -261,7 +261,7 @@ sophisticated microbenchmark will be developed to assist in investigation. Required Configuration Settings =============================== -See PEP 587 for a detailed listing of CPython interpreter configuration settings +See :pep:`587` for a detailed listing of CPython interpreter configuration settings and the various means available for setting them. @@ -283,7 +283,7 @@ of exposing the new functions and structures as public API elements in CPython 3.8. After the initial merge, Victor Stinner then proceeded to actually migrate -settings to the new structure in order to successfully implement the PEP 540 +settings to the new structure in order to successfully implement the :pep:`540` UTF-8 mode changes (which required the ability to track all settings that had previously been decoded with the locale encoding, and decode them again using UTF-8 instead). Eric Snow also migrated a number of internal subsystems over as @@ -291,7 +291,7 @@ part of making the subinterpreter feature more robust. That work showed that the detailed design originally proposed in this PEP had a range of practical issues, so Victor designed and implemented an improved -private API (inspired by an earlier iteration of this PEP), which PEP 587 +private API (inspired by an earlier iteration of this PEP), which :pep:`587` proposes to promote to a public API in Python 3.8. @@ -307,7 +307,7 @@ Design Details * https://github.com/python/cpython/blob/master/Include/cpython/pystate.h * https://github.com/python/cpython/blob/master/Include/cpython/pylifecycle.h - PEP 587 covers the aspects of the API that are considered potentially stable + :pep:`587` covers the aspects of the API that are considered potentially stable enough to make public. Where a proposed API is covered by that PEP, "(see PEP 587)" is added to the text below. @@ -319,7 +319,7 @@ simplifying a number of operations that currently need to rely on basic C functionality rather than being able to use the richer data structures provided by the CPython C API. -PEP 587 covers a subset of that task, which is splitting out the components that +:pep:`587` covers a subset of that task, which is splitting out the components that even the existing "May be called before ``Py_Initialize``" interfaces need (like memory allocators and operating system interface encoding details) into a separate pre-configuration step. @@ -343,7 +343,7 @@ The following distinct interpreter initialisation phases are proposed: which encoding to use to access operating system interfaces (or chooses to delegate those decisions to the Python runtime) * Application starts the initialization process by calling one of the - ``Py_PreInitialize`` APIs (see PEP 587) + ``Py_PreInitialize`` APIs (see :pep:`587`) * Runtime Pre-Initialization: @@ -354,7 +354,7 @@ The following distinct interpreter initialisation phases are proposed: * The embedding application determines the settings required to initialize the core CPython runtime and create the main interpreter and moves to the next phase by calling ``Py_InitializeRuntime`` - * Note: as of PEP 587, the embedding application instead calls ``Py_Main()``, + * Note: as of :pep:`587`, the embedding application instead calls ``Py_Main()``, ``Py_UnixMain``, or one of the ``Py_Initialize`` APIs, and hence jumps directly to the Initialized state. @@ -368,7 +368,7 @@ The following distinct interpreter initialisation phases are proposed: * The embedding application determines and applies the settings required to complete the initialization process by calling ``Py_InitializeMainInterpreter`` - * Note: as of PEP 587, this state is not reachable via any public API, it + * Note: as of :pep:`587`, this state is not reachable via any public API, it only exists as an implicit internal state while one of the ``Py_Initialize`` functions is running @@ -396,7 +396,7 @@ over CPython's initial state, it will be able to use the new, finer grained API, which allows the embedding application greater control over the initialization process. -PEP 587 covers an initial iteration of that API, separating out the +:pep:`587` covers an initial iteration of that API, separating out the pre-initialization phase without attempting to separate core runtime initialization from main interpreter initialization. @@ -411,7 +411,7 @@ to the embedded Python runtime. This covers telling Python which memory allocator to use, as well as which text encoding to use when processing provided settings. -PEP 587 defines the settings needed to exit this state in its ``PyPreConfig`` +:pep:`587` defines the settings needed to exit this state in its ``PyPreConfig`` struct. A new query API will allow code to determine if the interpreter hasn't even @@ -426,7 +426,7 @@ The query for a completely uninitialized environment would then be Runtime Pre-Initialization Phase -------------------------------- -.. note:: In PEP 587, the settings for this phase are not yet separated out, +.. note:: In :pep:`587`, the settings for this phase are not yet separated out, and are instead only available through the combined ``PyConfig`` struct The pre-initialization phase is where an embedding application determines @@ -462,9 +462,9 @@ The proposed APIs for this step in the startup sequence are:: If ``Py_IsInitializing()`` is false, the ``Py_InitializeRuntime`` functions will implicitly call the corresponding ``Py_PreInitialize`` function. The ``use_environment`` setting will be passed down, while other settings will be -processed according to their defaults, as described in PEP 587. +processed according to their defaults, as described in :pep:`587`. -The ``PyInitError`` return type is defined in PEP 587, and allows an embedding +The ``PyInitError`` return type is defined in :pep:`587`, and allows an embedding application to gracefully handle Python runtime initialization failures, rather than having the entire process abruptly terminated by ``Py_FatalError``. @@ -653,7 +653,7 @@ application wants to adjust a setting rather than replace it completely, such as removing ``sys.path[0]``). The ``c_config`` argument is an optional pointer to a ``PyConfig`` structure, -as defined in PEP 587. If provided, it is used in preference to reading settings +as defined in :pep:`587`. If provided, it is used in preference to reading settings directly from the environment or process global state. Merely reading the configuration has no effect on the interpreter state: it @@ -675,10 +675,10 @@ or not the interpreter is the main interpreter will be configured on a per interpreter basis. Other fields will be reviewed for whether or not they can feasibly be made interpreter specific over the course of the implementation. -.. note:: The list of config fields below is currently out of sync with PEP 587. - Where they differ, PEP 587 takes precedence. +.. note:: The list of config fields below is currently out of sync with :pep:`587`. + Where they differ, :pep:`587` takes precedence. -The ``PyConfigAsObjects`` struct mirrors the ``PyConfig`` struct from PEP 587, +The ``PyConfigAsObjects`` struct mirrors the ``PyConfig`` struct from :pep:`587`, but uses full Python objects to store values, rather than C level data types. It adds ``raw_argv`` and ``argv`` list fields, so later initialisation steps don't need to accept those separately. @@ -831,7 +831,7 @@ state if ``import site`` is later explicitly executed in the process. Preparing the main module ------------------------- -.. note:: In PEP 587, ``PyRun_PrepareMain`` and ``PyRun_ExecMain`` are not +.. note:: In :pep:`587`, ``PyRun_PrepareMain`` and ``PyRun_ExecMain`` are not exposed separately, and are instead accessed through a ``Py_RunMain`` API that both prepares and executes main, and then finalizes the Python interpreter. @@ -902,7 +902,7 @@ configuration system) Executing the main module ------------------------- -.. note:: In PEP 587, ``PyRun_PrepareMain`` and ``PyRun_ExecMain`` are not +.. note:: In :pep:`587`, ``PyRun_PrepareMain`` and ``PyRun_ExecMain`` are not exposed separately, and are instead accessed through a ``Py_RunMain`` API that both prepares and executes main, and then finalizes the Python interpreter. @@ -971,7 +971,7 @@ settings are part of the CPython implementation, rather than part of the Python language definition. If new settings are needed to support cross-implementation compatibility in the standard library, then those should be agreed with the other implementations and exposed as new required -attributes on ``sys.implementation``, as described in PEP 421. +attributes on ``sys.implementation``, as described in :pep:`421`. These are *snapshots* of the initial configuration settings. They are not modified by the interpreter during runtime (except as noted above). @@ -1112,7 +1112,7 @@ The reference implementation is being developed as a private API refactoring within the CPython reference interpreter (as attempting to maintain it as an independent project proved impractical). -PEP 587 extracts a subset of the proposal that is considered sufficiently stable +:pep:`587` extracts a subset of the proposal that is considered sufficiently stable to be worth proposing as a public API for Python 3.8. @@ -1123,7 +1123,7 @@ The current mechanisms for configuring the interpreter have accumulated in a fairly ad hoc fashion over the past 20+ years, leading to a rather inconsistent interface with varying levels of documentation. -Also see PEP 587 for further discussion of the existing settings and their +Also see :pep:`587` for further discussion of the existing settings and their handling. (Note: some of the info below could probably be cleaned up and added to the @@ -1175,7 +1175,7 @@ The location of the Python binary and the standard library is influenced by several elements. The algorithm used to perform the calculation is not documented anywhere other than in the source code [3_,4_]. Even that description is incomplete, as it failed to be updated for the virtual -environment support added in Python 3.3 (detailed in PEP 405). +environment support added in Python 3.3 (detailed in :pep:`405`). These calculations are affected by the following function calls (made prior to calling ``Py_Initialize()``) and environment variables: @@ -1184,7 +1184,7 @@ prior to calling ``Py_Initialize()``) and environment variables: * ``Py_SetPythonHome()`` * ``PYTHONHOME`` -The filesystem is also inspected for ``pyvenv.cfg`` files (see PEP 405) or, +The filesystem is also inspected for ``pyvenv.cfg`` files (see :pep:`405`) or, failing that, a ``lib/os.py`` (Windows) or ``lib/python$VERSION/os.py`` file. diff --git a/pep-0435.txt b/pep-0435.txt index 79e33087207..b75c7589962 100644 --- a/pep-0435.txt +++ b/pep-0435.txt @@ -28,7 +28,7 @@ enumeration itself can be iterated over. Status of discussions ===================== -The idea of adding an enum type to Python is not new - PEP 354 [2]_ is a +The idea of adding an enum type to Python is not new - :pep:`354` is a previous attempt that was rejected in 2005. Recently a new set of discussions was initiated [3]_ on the ``python-ideas`` mailing list. Many new ideas were proposed in several threads; after a lengthy discussion Guido proposed adding @@ -61,7 +61,7 @@ The PEP was accepted by Guido on May 10th, 2013 [1]_. Motivation ========== -*[Based partly on the Motivation stated in PEP 354]* +*[Based partly on the Motivation stated in* :pep:`354`\ *]* The properties of an enumeration are useful for defining an immutable, related set of constant values that may or may not have a semantic meaning. Classic @@ -581,14 +581,13 @@ Acknowledgments This PEP was initially proposing including the ``flufl.enum`` package [8]_ by Barry Warsaw into the stdlib, and is inspired in large parts by it. -Ben Finney is the author of the earlier enumeration PEP 354. +Ben Finney is the author of the earlier enumeration :pep:`354`. References ========== .. [1] https://mail.python.org/pipermail/python-dev/2013-May/126112.html -.. [2] http://www.python.org/dev/peps/pep-0354/ .. [3] https://mail.python.org/pipermail/python-ideas/2013-January/019003.html .. [4] https://mail.python.org/pipermail/python-ideas/2013-February/019373.html .. [5] To make enums behave similarly to Python classes like bool, and diff --git a/pep-0437.txt b/pep-0437.txt index a6bcb5c3d53..92f0d729a5e 100644 --- a/pep-0437.txt +++ b/pep-0437.txt @@ -22,7 +22,7 @@ definitions in *.pyx* files to generate the required information. However, CPython's C-API functions often require additional initialization and cleanup snippets that would be hard to specify in a *cdef*. -PEP 436 proposes a domain specific language (DSL) enclosed in C comments +:pep:`436` proposes a domain specific language (DSL) enclosed in C comments that largely resembles a per-parameter configuration file. A preprocessor reads the comment and emits an argument parsing function, docstrings and a header for the function that utilizes the results of the parsing step. @@ -42,9 +42,9 @@ designing the `second iteration of the PEP 436 DSL`_. Rationale ========= -Opinions differ regarding the suitability of the PEP 436 DSL in the context +Opinions differ regarding the suitability of the :pep:`436` DSL in the context of a C file. This PEP proposes an alternative DSL. The specific issues with -PEP 436 that spurred the counter proposal will be explained in the final +:pep:`436` that spurred the counter proposal will be explained in the final section of this PEP. @@ -348,7 +348,7 @@ Comparison with PEP 436 ======================= The author of this PEP has the following concerns about the DSL proposed -in PEP 436: +in :pep:`436`: * The whitespace sensitive configuration file like syntax looks out of place in a C file. @@ -360,20 +360,20 @@ in PEP 436: By contrast, in the alternative DSL the structure of the function definition can be understood at a single glance. -* The PEP 436 DSL has 14 documented flags and at least one undocumented +* The :pep:`436` DSL has 14 documented flags and at least one undocumented (allow_fd) flag. Figuring out which of the 2**15 possible combinations are valid places an unnecessary burden on the user. - Experience with the PEP-3118 buffer flags has shown that sorting out + Experience with the :pep:`3118` buffer flags has shown that sorting out (and exhaustively testing!) valid combinations is an extremely tedious - task. The PEP-3118 flags are still not well understood by many people. + task. The :pep:`3118` flags are still not well understood by many people. By contrast, the alternative DSL has a central file Include/converters.h that can be quickly searched for the desired converter. Many of the converters are already known, perhaps even memorized by people (due to frequent use). -* The PEP 436 DSL allows too much freedom. Types can apparently be omitted, +* The :pep:`436` DSL allows too much freedom. Types can apparently be omitted, the preprocessor accepts (and ignores) unknown keywords, sometimes adding white space after a docstring results in an assertion error. diff --git a/pep-0439.txt b/pep-0439.txt index beb804e7aab..aacbc201f79 100644 --- a/pep-0439.txt +++ b/pep-0439.txt @@ -32,7 +32,7 @@ PEP Rejection This PEP has been rejected in favour of a more explicit mechanism that should achieve the same end result in a more reliable fashion. The more -explicit bootstrapping mechanism is described in PEP 453. +explicit bootstrapping mechanism is described in :pep:`453`. Rationale ========= @@ -82,7 +82,7 @@ require the user to install pip. The pip bootstrap ----------------- -The Python installation includes an executable called "pip3" (see PEP 394 for +The Python installation includes an executable called "pip3" (see :pep:`394` for naming rationale etc.) that attempts to import pip machinery. If it can then the pip command proceeds as normal. If it cannot it will bootstrap pip by downloading the pip implementation and setuptools wheel files. Hereafter the @@ -97,10 +97,10 @@ upgrade timeframe and processes. To avoid issues with sudo we will have the bootstrap default to installing the pip implementation to the per-user site-packages -directory defined in PEP 370 and implemented in Python 2.6/3.0. Since +directory defined in :pep:`370` and implemented in Python 2.6/3.0. Since we avoid installing to the system Python we also avoid conflicting with any other packaging system (on Linux systems, for example.) If -the user is inside a virtual environment [1]_ then the pip +the user is inside a :pep:`405` virtual environment then the pip implementation will be installed into that virtual environment. The bootstrap process will proceed as follows: @@ -118,7 +118,7 @@ The bootstrap process will proceed as follows: package. This choice will also be present as a command-line option to pip so non-interactive use is possible. 5. The bootstrap will and contact PyPI to obtain the latest download wheel - file (see PEP 427.) + file (see :pep:`427`.) 6. Upon downloading the file it is installed using "python setup.py install". 7. The pip tool may now import the pip implementation and continues to process the requested user command normally. @@ -223,9 +223,6 @@ now much reduced. References ========== -.. [1] PEP 405, Python Virtual Environments - http://www.python.org/dev/peps/pep-0405/ - .. [2] pip issue tracking work needed for this PEP https://github.com/pypa/pip/issues/863 diff --git a/pep-0440.txt b/pep-0440.txt index 340bba32cc2..0ee1f92a19e 100644 --- a/pep-0440.txt +++ b/pep-0440.txt @@ -24,7 +24,7 @@ This PEP describes a scheme for identifying versions of Python software distributions, and declaring dependencies on particular versions. This document addresses several limitations of the previous attempt at a -standardized approach to versioning, as described in PEP 345 and PEP 386. +standardized approach to versioning, as described in :pep:`345` and :pep:`386`. Definitions @@ -32,7 +32,7 @@ Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -document are to be interpreted as described in RFC 2119. +document are to be interpreted as described in :rfc:`2119`. "Projects" are software components that are made available for integration. Projects include Python libraries, frameworks, scripts, plugins, @@ -701,9 +701,9 @@ The following example covers many of the possible combinations:: Version ordering across different metadata versions --------------------------------------------------- -Metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not specify a standard -version identification or ordering scheme. However metadata v1.2 (PEP 345) -does specify a scheme which is defined in PEP 386. +Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a standard +version identification or ordering scheme. However metadata v1.2 (:pep:`345`) +does specify a scheme which is defined in :pep:`386`. Due to the nature of the simple installer API it is not possible for an installer to be aware of which metadata version a particular distribution was @@ -714,7 +714,7 @@ necessitate a standardization across one parsing mechanism to be used for all versions of a project. Due to the above, this PEP MUST be used for all versions of metadata and -supersedes PEP 386 even for metadata v1.2. Tools SHOULD ignore any versions +supersedes :pep:`386` even for metadata v1.2. Tools SHOULD ignore any versions which cannot be parsed by the rules in this PEP, but MAY fall back to implementation defined version parsing and ordering schemes if no versions complying with this PEP are available. @@ -1217,8 +1217,8 @@ Summary of differences from pkg_resources.parse_version single use of each type and they must exist in a certain order. -Summary of differences from \PEP 386 -==================================== +Summary of differences from PEP 386 +=================================== * Moved the description of version specifiers into the versioning PEP @@ -1263,7 +1263,7 @@ Changing the version scheme --------------------------- One key change in the version scheme in this PEP relative to that in -PEP 386 is to sort top level developmental releases like ``X.Y.devN`` ahead +:pep:`386` is to sort top level developmental releases like ``X.Y.devN`` ahead of alpha releases like ``X.Ya1``. This is a far more logical sort order, as projects already using both development releases and alphas/betas/release candidates do not want their developmental releases sorted in @@ -1306,7 +1306,7 @@ appropriate order as setuptools does). A more opinionated description of the versioning scheme ------------------------------------------------------- -As in PEP 386, the primary focus is on codifying existing practices to make +As in :pep:`386`, the primary focus is on codifying existing practices to make them more amenable to automation, rather than demanding that existing projects make non-trivial changes to their workflow. However, the standard scheme allows significantly more flexibility than is needed @@ -1505,7 +1505,7 @@ effects of each transformation as simple search and replace style transforms increase the likelihood of ambiguous or "junk" versions. For an extended discussion on the various types of normalizations that were -considered, please see the proof of concept for PEP 440 within pip [5]_. +considered, please see the proof of concept for :pep:`440` within pip [5]_. Allowing Underscore in Normalization @@ -1517,8 +1517,8 @@ reason for this is that the Wheel normalization scheme specifies that ``-`` gets normalized to a ``_`` to enable easier parsing of the filename. -Summary of changes to \PEP 440 -============================== +Summary of changes to PEP 440 +============================= The following changes were made to this PEP based on feedback received after the initial reference implementation was released in setuptools 8.0 and pip @@ -1549,7 +1549,7 @@ References ========== The initial attempt at a standardised version scheme, along with the -justifications for needing such a standard can be found in PEP 386. +justifications for needing such a standard can be found in :pep:`386`. .. [1] Reference Implementation of PEP 440 Versions and Specifiers https://github.com/pypa/packaging/pull/1 diff --git a/pep-0443.txt b/pep-0443.txt index 3fcf9930204..5da643a0ae4 100644 --- a/pep-0443.txt +++ b/pep-0443.txt @@ -326,7 +326,7 @@ a common one, opening them up for user extensibility at the same time. Alternative approaches ====================== -In PEP 3124 [#pep-3124]_ Phillip J. Eby proposes a full-grown solution +In :pep:`3124` Phillip J. Eby proposes a full-grown solution with overloading based on arbitrary rule sets (with the default implementation dispatching on argument types), as well as interfaces, adaptation and method combining. PEAK-Rules [#peak-rules]_ is @@ -364,7 +364,7 @@ single-dispatch generics. Acknowledgements ================ -Apart from Phillip J. Eby's work on PEP 3124 [#pep-3124]_ and +Apart from Phillip J. Eby's work on :pep:`3124` and PEAK-Rules, influences include Paul Moore's original issue [#issue-5135]_ that proposed exposing ``pkgutil.simplegeneric`` as part of the ``functools`` API, Guido van Rossum's article on multimethods @@ -379,16 +379,13 @@ References .. [#ref-impl] http://hg.python.org/features/pep-443/file/tip/Lib/functools.py#l359 -.. [#pep-0008] PEP 8 states in the "Programming Recommendations" +.. [#pep-0008] :pep:`8` states in the "Programming Recommendations" section that "the Python standard library will not use function annotations as that would result in a premature commitment to a particular annotation style". - (http://www.python.org/dev/peps/pep-0008) .. [#why-c3] http://bugs.python.org/issue18244 -.. [#pep-3124] http://www.python.org/dev/peps/pep-3124/ - .. [#peak-rules] http://peak.telecommunity.com/DevCenter/PEAK_2dRules .. [#artima2005] diff --git a/pep-0444.txt b/pep-0444.txt index cf5a905b59d..499c98fe5e0 100644 --- a/pep-0444.txt +++ b/pep-0444.txt @@ -26,7 +26,7 @@ for lack of a current champion interested in promoting the goals of the PEP and collecting and incorporating feedback, and with sufficient available time to do so effectively. -Note that since this PEP was first created, PEP 3333 was created as a more +Note that since this PEP was first created, :pep:`3333` was created as a more incremental update that permitted use of WSGI on Python 3.2+. However, an alternative specification that furthers the Python 3 goals of a cleaner separation of binary and text data may still be valuable. @@ -35,10 +35,10 @@ Rationale and Goals =================== This protocol and specification is influenced heavily by the Web -Services Gateway Interface (WSGI) 1.0 standard described in PEP 333 -[1]_. The high-level rationale for having any standard that allows +Services Gateway Interface (WSGI) 1.0 standard described in :pep:`333`. +The high-level rationale for having any standard that allows Python-based web servers and applications to interoperate is outlined -in PEP 333. This document essentially uses PEP 333 as a template, and +in :pep:`333`. This document essentially uses :pep:`333` as a template, and changes its wording in various places for the purpose of forming a different standard. @@ -60,7 +60,7 @@ versions earlier than 2.6 nor Python 3 versions earlier than 3.1. .. note:: Whatever Python 3 version fixed http://bugs.python.org/issue4006 so - ``os.environ['foo']`` returns surrogates (ala PEP 383) when the + ``os.environ['foo']`` returns surrogates (ala :pep:`383`) when the value of 'foo' cannot be decoded using the current locale instead of failing with a KeyError is the *true* minimum Python 3 version. In particular, however, Python 3.0 is not supported. @@ -503,7 +503,7 @@ string. Each value is a bytes instance. ``SERVER_NAME``, ``SERVER_PORT`` When combined with ``SCRIPT_NAME`` and ``PATH_INFO`` (or their raw - equivalents)`, these variables can be used to complete the URL. + equivalents), these variables can be used to complete the URL. Note, however, that ``HTTP_HOST``, if present, should be used in preference to ``SERVER_NAME`` for reconstructing the request URL. See the `URL Reconstruction`_ section below for more detail. @@ -538,7 +538,7 @@ A server or gateway **should** attempt to provide as many other CGI variables as are applicable, each with a string for its key and a bytes instance for its value. 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 +environment variables [4]_ 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 @@ -757,7 +757,7 @@ The ``status`` value is assumed by a gateway or server to be an HTTP "status" bytes instance like ``b'200 OK'`` or ``b'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 +surrounding whitespace or other characters. (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. @@ -765,7 +765,7 @@ linefeed, or combination thereof. The ``headers`` value is assumed by a gateway or server to be a literal Python list of ``(header_name, header_value)`` tuples. Each ``header_name`` must be a bytes instance representing a valid HTTP -header field-name (as defined by RFC 2616, Section 4.2), without a +header field-name (as defined by :rfc:`2616`, Section 4.2), without a trailing colon or other punctuation. Each ``header_value`` must be a bytes instance and **must not** include any control characters, including carriage returns or linefeeds, either embedded or at the @@ -941,9 +941,9 @@ The result of using a textlike object where a byteslike object is required is undefined. Values returned from a Web3 app as a status or as response headers -**must** follow RFC 2616 with respect to encoding. That is, the bytes +**must** follow :rfc:`2616` with respect to encoding. That is, the bytes returned must contain a character stream of ISO-8859-1 characters, or -the character stream should use RFC 2047 MIME encoding. +the character stream should use :rfc:`2047` MIME encoding. On Python platforms which do not have a native bytes-like type (e.g. IronPython, etc.), but instead which generally use textlike @@ -982,8 +982,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 @@ -996,13 +996,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, section 1.3, for the definition of these terms.) +server", with the application being an HTTP "origin server". (See +:rfc:`2616`, section 1.3, for the definition of these terms.) However, because Web3 servers and applications do not communicate via -HTTP, what RFC 2616 calls "hop-by-hop" headers do not apply to Web3 +HTTP, what :rfc:`2616` calls "hop-by-hop" headers do not apply to Web3 internal communications. Web3 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. Web3 servers **must** handle any supported inbound "hop-by-hop" headers on @@ -1407,7 +1408,7 @@ Here are some alternatives to using all bytes: Applications Should be Allowed to Read ``web3.input`` Past ``CONTENT_LENGTH`` ----------------------------------------------------------------------------- -At [6]_, Graham Dumpleton makes the assertion that ``wsgi.input`` +At [5]_, Graham Dumpleton makes the assertion that ``wsgi.input`` should be required to return the empty string as a signifier of out-of-data, and that applications should be allowed to read past the number of bytes specified in ``CONTENT_LENGTH``, depending only upon @@ -1433,7 +1434,7 @@ There's no documented way to indicate that there is content in ``read()`` of ``web3.input`` Should Support No-Size Calling Convention ---------------------------------------------------------------------- -At [6]_, Graham Dumpleton makes the assertion that the ``read()`` +At [5]_, Graham Dumpleton makes the assertion that the ``read()`` method of ``wsgi.input`` should be callable without arguments, and that the result should be "all available request content". Needs discussion. @@ -1446,7 +1447,7 @@ Open for discussions though. Input Filters should set environ ``CONTENT_LENGTH`` to -1 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -At [6]_, Graham Dumpleton suggests that an input filter might set +At [5]_, Graham Dumpleton suggests that an input filter might set ``environ['CONTENT_LENGTH']`` to -1 to indicate that it mutated the input. @@ -1471,7 +1472,7 @@ block iteration waiting for multiple values from an application iterable. If the middleware needs to accumulate more data from the application before it can produce any output, it **must** yield an empty string." This requirement existed to support asynchronous -applications and servers (see PEP 333's "Middleware Handling of Block +applications and servers (see :pep:`333`'s "Middleware Handling of Block Boundaries"). Asynchronous applications are now serviced explicitly by ``web3.async`` capable protocol (a Web3 application callable may itself return a callable). @@ -1491,25 +1492,25 @@ if the server performs URL rewriting. Long Response Headers --------------------- -Bob Brewer notes on Web-SIG [7]_: +Bob Brewer notes on Web-SIG [6]_: Each header_value must not include any control characters, including carriage returns or linefeeds, either embedded or at the end. (These requirements are to minimize the complexity of any parsing that must be performed by servers, gateways, and intermediate response processors that need to inspect or modify - response headers.) [1]_ + response headers.) (:pep:`333`) That's understandable, but HTTP headers are defined as (mostly) \*TEXT, and "words of \*TEXT MAY contain characters from character sets other than ISO-8859-1 only when encoded according to the rules of -RFC 2047." [2]_ And RFC 2047 specifies that "an 'encoded-word' may +:rfc:`2047`." [2]_ And :rfc:`2047` specifies that "an 'encoded-word' may not be more than 75 characters long... If it is desirable to encode more text than will fit in an 'encoded-word' of 75 characters, multiple 'encoded-word's (separated by CRLF SPACE) may be used." [3]_ This satisfies HTTP header folding rules, as well: "Header fields can be extended over multiple lines by preceding each extra line with at -least one SP or HT." [1]_ +least one SP or HT." (:pep:`333`) So in my reading of HTTP, some code somewhere should introduce newlines in longish, encoded response header values. I see three @@ -1543,25 +1544,18 @@ has all been read in. Neither WSGI nor Web3 currently supports them. References ========== -.. [1] PEP 333: Python Web Services Gateway Interface - (http://www.python.org/dev/peps/pep-0333/) - .. [2] The Common Gateway Interface Specification, v 1.1, 3rd Draft - (http://cgi-spec.golux.com/draft-coar-cgi-v11-03.txt) - -.. [3] "Chunked Transfer Coding" -- HTTP/1.1, section 3.6.1 - (http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6.1) + (https://datatracker.ietf.org/doc/html/draft-coar-cgi-v11-03) -.. [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) +.. [3] "Chunked Transfer Coding" -- HTTP/1.1, :rfc:`2616#section-3.6.1` -.. [5] mod_ssl Reference, "Environment Variables" +.. [4] mod_ssl Reference, "Environment Variables" (http://www.modssl.org/docs/2.8/ssl_reference.html#ToC25) -.. [6] Details on WSGI 1.0 amendments/clarifications. +.. [5] Details on WSGI 1.0 amendments/clarifications. (http://blog.dscpl.com.au/2009/10/details-on-wsgi-10-amendmentsclarificat.html) -.. [7] [Web-SIG] WSGI and long response header values +.. [6] [Web-SIG] WSGI and long response header values https://mail.python.org/pipermail/web-sig/2006-September/002244.html Copyright diff --git a/pep-0445.txt b/pep-0445.txt index eea0026c8f5..996a54cdc7d 100644 --- a/pep-0445.txt +++ b/pep-0445.txt @@ -459,8 +459,8 @@ even in release mode: debug checks would always be compiled in, but only enabled when the environment variable is present and non-empty. This alternative was rejected because a new environment variable would -make Python initialization even more complex. `PEP 432 -`_ tries to simplify the +make Python initialization even more complex. :pep:`432` +tries to simplify the CPython startup sequence. diff --git a/pep-0446.txt b/pep-0446.txt index 3b1813d4687..9fd2b05fba9 100644 --- a/pep-0446.txt +++ b/pep-0446.txt @@ -587,7 +587,7 @@ Read the mail thread: `[Python-Dev] Proposal for a new function PEP 433 ------- -PEP 433, "Easier suppression of file descriptor inheritance", +:pep:`433`, "Easier suppression of file descriptor inheritance", was a previous attempt proposing various other alternatives, but no consensus could be reached. diff --git a/pep-0449.txt b/pep-0449.txt index 569ebc31d6f..c383daa0d1b 100644 --- a/pep-0449.txt +++ b/pep-0449.txt @@ -25,7 +25,7 @@ delegating a domain name under pypi.python.org to a third party. Rationale ========= -The PyPI mirroring infrastructure (defined in `PEP381`_) provides a means to +The PyPI mirroring infrastructure (defined in :pep:`381`) provides a means to mirror the content of PyPI used by the automatic installers. It also provides a method for auto discovery of mirrors and a consistent naming scheme. @@ -50,7 +50,7 @@ naming scheme: ever been implemented by one installer (pip), and its implementation, besides being insecure, has serious issues with performance and is slated for removal with its next release (1.5). -* While there are provisions in `PEP381`_ that would solve *some* of these +* While there are provisions in :pep:`381` that would solve *some* of these issues for a dedicated client it would not solve the issues that affect a users browser. Additionally these provisions have not been implemented by any installer to date. @@ -60,7 +60,7 @@ provides most of the benefit of the auto discovery and consistent naming scheme this PEP proposes to first deprecate and then remove the [a..z].pypi.python.org names for mirrors and the last.pypi.python.org name for the auto discovery protocol. The ability to mirror and the method of mirror will not be affected -and will continue to exist as written in `PEP381`_. Operators of existing +and will continue to exist as written in :pep:`381`. Operators of existing mirrors are encouraged to acquire their own domains and certificates to use for their mirrors if they wish to continue hosting them. @@ -131,13 +131,12 @@ the insecurity. Public or Private Mirrors ========================= -The mirroring protocol will continue to exist as defined in `PEP381`_ and +The mirroring protocol will continue to exist as defined in :pep:`381` and people are encouraged to host public and private mirrors if they so desire. The recommended mirroring client is `Bandersnatch`_. .. _PyPI: https://pypi.python.org/ -.. _PEP381: http://www.python.org/dev/peps/pep-0381/ .. _Bandersnatch: https://pypi.python.org/pypi/bandersnatch diff --git a/pep-0451.txt b/pep-0451.txt index 8a258581d70..38b9f1ecd17 100644 --- a/pep-0451.txt +++ b/pep-0451.txt @@ -137,7 +137,7 @@ cache The import system stores compiled modules in the __pycache__ directory as an optimization. This module cache that we use today was provided by -PEP 3147. For this proposal, the relevant API for module caching is the +:pep:`3147`. For this proposal, the relevant API for module caching is the ``__cache__`` attribute of modules and the cache_from_source() function in importlib.util. Loaders are responsible for putting modules into the cache (and loading out of the cache). Currently the cache is only used @@ -160,10 +160,10 @@ Motivation ========== The import system has evolved over the lifetime of Python. In late 2002 -PEP 302 introduced standardized import hooks via finders and +:pep:`302` introduced standardized import hooks via finders and loaders and sys.meta_path. The importlib module, introduced with Python 3.1, now exposes a pure Python implementation of the APIs -described by PEP 302, as well as of the full import system. It is now +described by :pep:`302`, as well as of the full import system. It is now much easier to understand and extend the import system. While a benefit to the Python community, this greater accessibility also presents a challenge. @@ -179,7 +179,7 @@ generally only meaningful to the import system. It would be nice to have a per-module namespace in which to put future import-related information and to pass around within the import system. Secondly, there's an API void between finders and loaders that causes undue -complexity when encountered. The PEP 420 (namespace packages) +complexity when encountered. The :pep:`420` (namespace packages) implementation had to work around this. The complexity surfaced again during recent efforts on a separate proposal. [#ref_files_pep]_ @@ -217,7 +217,7 @@ those details. This is the same gap as before between finders and loaders. As an example of complexity attributable to this flaw, the -implementation of namespace packages in Python 3.3 (see PEP 420) added +implementation of namespace packages in Python 3.3 (see :pep:`420`) added FileFinder.find_loader() because there was no good way for find_module() to provide the namespace search locations. @@ -808,7 +808,7 @@ raising ImportError. Other changes: -PEP 420 introduced the optional module_repr() loader method to limit +:pep:`420` introduced the optional module_repr() loader method to limit the amount of special-casing in the module type's ``__repr__()``. Since this method is part of ModuleSpec, it will be deprecated on loaders. However, if it exists on a loader it will be used exclusively. @@ -856,7 +856,7 @@ Implementation Notes \* The implementation of this PEP needs to be cognizant of its impact on pkgutil (and setuptools). pkgutil has some generic function-based -extensions to PEP 302 which may break if importlib starts wrapping +extensions to :pep:`302` which may break if importlib starts wrapping loaders without the tools' knowledge. \* Other modules to look at: runpy (and pythonrun.c), pickle, pydoc, @@ -900,7 +900,7 @@ module.__spec__ is less than desirable. They would end up being an attractive nuisance, even if only exposed as "private" attributes (as they were in previous versions of this PEP). If someone finds a need for these methods later, we can expose the via an appropriate API -(separate from ModuleSpec) at that point, perhaps relative to PEP 406 +(separate from ModuleSpec) at that point, perhaps relative to :pep:`406` (import engine). Conceivably, the load() method could optionally take a list of diff --git a/pep-0453.txt b/pep-0453.txt index c72ef958a9e..94ee35db6b5 100644 --- a/pep-0453.txt +++ b/pep-0453.txt @@ -120,7 +120,7 @@ third-party packages as well as easier for the people distributing them as they should now be able to safely assume that most users will have the appropriate installation tools available (or access to clear instructions on how to obtain them). This is expected to become more important in the future -as the Wheel_ package format (deliberately) does not have a built in +as the :pep:`Wheel <427>` package format (deliberately) does not have a built in "installer" in the form of ``setup.py`` so users wishing to install from a wheel file will want an installer even in the simplest cases. @@ -435,7 +435,7 @@ into the CPython release is as follows: * ``ensurepip`` updated to use a ``pip`` 1.5 release candidate. - * PEP 101 updated to cover ensuring the bundled version of ``pip`` is up + * :pep:`101` updated to cover ensuring the bundled version of ``pip`` is up to date. * by November 24th (scheduled date of 3.4.0 beta 1) @@ -450,7 +450,7 @@ into the CPython release is as follows: subsequent maintenance release (including a suitably updated vendored copy of ``requests``) -(See PEP 429 for the current official scheduled dates of each release. Dates +(See :pep:`429` for the current official scheduled dates of each release. Dates listed above are accurate as of October 20th, 2013.) If there is no final or maintenance release of ``pip`` 1.5 with a suitable @@ -803,7 +803,8 @@ downstream distributors: * ``pip install --upgrade pip`` in a virtual environment should not affect the global installation. -* Migrate build systems to utilize `pip`_ and `Wheel`_ wherever feasible +* Migrate build systems to utilize `pip`_ and :pep:`Wheel <427>` + wherever feasible and avoid directly invoking ``setup.py``. * This will help ensure a smoother and more timely migration to improved @@ -944,7 +945,7 @@ invoke ``ensurepip`` by default when installing from a custom source build. Implicit bootstrap ------------------ -`PEP439`_, the predecessor for this PEP, proposes its own solution. Its +:pep:`439`, the predecessor for this PEP, proposes its own solution. Its solution involves shipping a fake ``pip`` command that when executed would implicitly bootstrap and install pip if it does not already exist. This has been rejected because it is too "magical". It hides from the end user when @@ -1013,10 +1014,8 @@ which are not handled correctly when pip is installed into the user site-packages directory rather than the system site-packages). -.. _Wheel: http://www.python.org/dev/peps/pep-0427/ .. _pip: http://www.pip-installer.org .. _setuptools: https://pypi.python.org/pypi/setuptools -.. _PEP439: http://www.python.org/dev/peps/pep-0439/ References diff --git a/pep-0454.txt b/pep-0454.txt index 895bced9bbb..7575386af09 100644 --- a/pep-0454.txt +++ b/pep-0454.txt @@ -49,7 +49,7 @@ the diagram is too huge to be analyzed manually. Proposal ======== -Using the customized allocation API from PEP 445, it becomes easy to +Using the customized allocation API from :pep:`445`, it becomes easy to set up a hook on Python memory allocators. A hook can inspect Python internals to retrieve Python tracebacks. The idea of getting the current traceback comes from the faulthandler module. The faulthandler dumps diff --git a/pep-0456.txt b/pep-0456.txt index b7ee2e344f5..240ada26437 100644 --- a/pep-0456.txt +++ b/pep-0456.txt @@ -519,7 +519,7 @@ buffer. Performance =========== -In general the PEP 456 code with SipHash24 is about as fast as the old code +In general the :pep:`456` code with SipHash24 is about as fast as the old code with FNV. SipHash24 seems to make better use of modern compilers, CPUs and large L1 cache. Several benchmarks show a small speed improvement on 64 bit CPUs such as Intel Core i5 and Intel Core i7 processes. 32 bit builds and @@ -633,7 +633,7 @@ for the common case. ASCII str / bytes hash collision -------------------------------- -Since the implementation of [pep-0393]_ bytes and ASCII text have the same +Since the implementation of :pep:`393`, bytes and ASCII text have the same memory layout. Because of this the new hashing API will keep the invariant:: hash("ascii string") == hash(b"ascii string") @@ -678,8 +678,6 @@ References .. [csiphash] https://github.com/majek/csiphash/ -.. [pep-0393] http://www.python.org/dev/peps/pep-0393/ - .. [aes-ni] http://en.wikipedia.org/wiki/AES_instruction_set .. [pluggable] https://mail.python.org/pipermail/python-dev/2013-October/129138.html diff --git a/pep-0457.txt b/pep-0457.txt index 6e4d2e9fb28..8a4123d3500 100644 --- a/pep-0457.txt +++ b/pep-0457.txt @@ -23,7 +23,7 @@ their position. This PEP is an Informational PEP describing the notation for use when describing APIs that use positional-only parameters (e.g. in Argument Clinic, or in the string representation of `inspect.Signature` -objects). A separate PEP, PEP 570, proposes elevation of this notation +objects). A separate PEP, :pep:`570`, proposes elevation of this notation to full Python syntax. ========= @@ -49,7 +49,7 @@ expressible with Python syntax. This PEP proposes a notation for such signatures that could form the basis of a backwards-compatible syntax that should permit implementing -any builtin in pure Python code (see PEP 570 for that proposal). +any builtin in pure Python code (see :pep:`570` for that proposal). ----------------------------------------------------- Positional-Only Parameter Semantics In Current Python diff --git a/pep-0458.txt b/pep-0458.txt index e89f7b1c824..00faedadfc8 100644 --- a/pep-0458.txt +++ b/pep-0458.txt @@ -73,7 +73,7 @@ responsibilities by automating much of the signing process. There is no discussion in *this* PEP of support for project distributions that are signed by developers (maximum security model). This possible future extension -is covered in detail in PEP 480 [21]_. The maximum security model requires more PyPI +is covered in detail in :pep:`480`. The maximum security model requires more PyPI administrative work (though no added work for clients), and also proposes an easy-to-use key management solution for developers/publishers, ideas on how to interface with a potential future build farm on PyPI infrastructure, and the @@ -93,7 +93,7 @@ Non-goals This PEP does not eliminate any existing features from PyPI. In particular, it does not replace existing support for OpenPGP signatures. Developers can continue to upload detached OpenPGP signatures along with distributions. In the future, -PEP 480 may allow developers to directly sign TUF metadata using their OpenPGP keys. +:pep:`480` may allow developers to directly sign TUF metadata using their OpenPGP keys. PEP Status @@ -122,7 +122,7 @@ software repositories are vulnerable to an attacker on the network (MITM) intercepting and changing files. These and other attacks on software repositories are detailed here__. -This PEP, together with the follow-up proposal in PEP 480, aims to protect users +This PEP, together with the follow-up proposal in :pep:`480`, aims to protect users of PyPI from compromises of the integrity, consistency, and freshness properties of PyPI packages, and enhances compromise resilience by mitigating key risk and providing mechanisms to recover from a compromise of PyPI or its signing keys. @@ -157,11 +157,11 @@ possible through other avenues. For example, a public mirror is trusted to honestly mirror PyPI, but some mirrors may misbehave, whether by accident or through malicious intervention. Package managers such as pip are supposed to use signatures from PyPI to verify -distribution files downloaded from a public mirror [9]_, but none are known to actually +distribution files downloaded from a :pep:`public mirror <381>`, but none are known to actually do so [10]_. Therefore, it would be wise to add more security measures to detect attacks from public mirrors or content delivery networks [11]_ (CDNs). -Even though official mirrors have been deprecated on PyPI [12]_, a +Even though official mirrors have been :pep:`deprecated on PyPI <449>`, a wide variety of other attack vectors on package managers remain [13]_. These attacks can crash client systems, cause obsolete distributions to be installed, or even allow an attacker to execute arbitrary code. In `September 2013`__, a post was @@ -188,7 +188,7 @@ __ https://theupdateframework.github.io/audits.html The scope of *this* PEP is protecting users from compromises of PyPI mirrors, and PyPI's own TLS termination and content distribution infrastructure. -Protection from compromises of PyPI itself is discussed in PEP 480. +Protection from compromises of PyPI itself is discussed in :pep:`480`. Threat Model @@ -208,7 +208,7 @@ software distribution file. If the attacker is preventing the installation of updates, they do not want clients to realize there is anything wrong. This threat model describes the minimum security model. The maximum security -model described in PEP 480 also assumes that attackers can compromise PyPI's +model described in :pep:`480` also assumes that attackers can compromise PyPI's online keys. @@ -217,9 +217,7 @@ Definitions The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in RFC 2119__. - -__ http://www.ietf.org/rfc/rfc2119.txt +interpreted as described in :rfc:`2119`. This PEP focuses only on integrating TUF into PyPI. However, the reader is encouraged to review TUF design principles [2]_ and SHOULD be @@ -346,10 +344,9 @@ TUF metadata. This PEP is concerned with the second part of the integration, and the changes on PyPI required to support software updates with TUF. We assume that pip would use TUF to verify distributions downloaded only from PyPI. pip MAY support TAP 4__ in order use TUF to also verify distributions downloaded -from elsewhere__. +from :pep:`elsewhere <470>`. __ https://github.com/theupdateframework/taps/blob/master/tap4.md -__ https://www.python.org/dev/peps/pep-0470/ @@ -562,7 +559,7 @@ one proposed in this PEP is the minimum security model, which supports verification of PyPI distributions signed with private cryptographic keys stored on PyPI. Distributions uploaded by developers are signed by PyPI and immediately available for download. A possible future extension to this -PEP, discussed in PEP 480 [21]_, proposes the maximum security model and allows +PEP, discussed in :pep:`480`, proposes the maximum security model and allows a developer to sign for his/her project. Developer keys are not stored online: therefore, projects are safe from PyPI compromises. @@ -588,7 +585,7 @@ considered to be non-existent on PyPI. Note, the reason why *targets* does not directly delegate to *bin-n*, but instead uses the intermediary *bins* role, is so that other delegations can easily be added or removed, without affecting the *bins*-to-*bin-n* mapping. -This is crucial for the implementation of PEP 480 [21]_. +This is crucial for the implementation of :pep:`480`. Metadata Expiry Times @@ -1094,7 +1091,7 @@ attack, or metadata inconsistency attacks. Note that if the timestamp, snapshot, and bin-n roles are stored in the same online location, a compromise of one means they will all be compromised. Therefore, the table considers these roles together. A version of this table that considers these roles separately -is included in PEP 480 [21]_. +is included in :pep:`480`. +-----------------+-------------------+----------------+--------------------------------+ | Role Compromise | Malicious Updates | Freeze Attack | Metadata Inconsistency Attacks | @@ -1137,7 +1134,7 @@ allow the repository to recover from an attack by revoking the online key(s). The maximum security model shows how TUF mitigates online key compromises by introducing additional roles for end-to-signing. Details about how to generate -developer keys and sign upload distributions are provided in PEP 480 [21]_. +developer keys and sign upload distributions are provided in :pep:`480`. In the Event of a Key Compromise @@ -1359,12 +1356,8 @@ References .. [6] https://mail.python.org/pipermail/distutils-sig/2013-April/020596.html .. [7] https://mail.python.org/pipermail/distutils-sig/2013-May/020701.html .. [8] https://mail.python.org/pipermail/distutils-sig/2013-July/022008.html -.. [9] PEP 381, Mirroring infrastructure for PyPI, Ziadé, Löwis - http://www.python.org/dev/peps/pep-0381/ .. [10] https://mail.python.org/pipermail/distutils-sig/2013-September/022773.html .. [11] https://mail.python.org/pipermail/distutils-sig/2013-May/020848.html -.. [12] PEP 449, Removal of the PyPI Mirror Auto Discovery and Naming Scheme, Stufft - http://www.python.org/dev/peps/pep-0449/ .. [13] https://theupdateframework.github.io/papers/attacks-on-package-managers-ccs2008.pdf .. [14] https://mail.python.org/pipermail/distutils-sig/2013-September/022755.html .. [15] http://ed25519.cr.yp.to/ @@ -1373,7 +1366,6 @@ References .. [18] https://en.wikipedia.org/wiki/Continuous_delivery .. [19] https://mail.python.org/pipermail/distutils-sig/2013-August/022154.html .. [20] https://en.wikipedia.org/wiki/Key-recovery_attack -.. [21] https://www.python.org/dev/peps/pep-0480/ .. [22] https://pyfound.blogspot.com/2019/09/pypi-security-q4-2019-request-for.html Acknowledgements diff --git a/pep-0459.txt b/pep-0459.txt index 66fbdbdc543..4ca1958b9b8 100644 --- a/pep-0459.txt +++ b/pep-0459.txt @@ -16,7 +16,7 @@ Post-History: 21 Dec 2013 PEP Withdrawal ============== -This PEP depends on PEP 426, which has itself been withdrawn. See the +This PEP depends on :pep:`426`, which has itself been withdrawn. See the PEP Withdrawal section in that PEP for details. In the meantime, metadata extensions will continue to be handled as they @@ -112,7 +112,7 @@ Classifiers ----------- A list of strings, with each giving a single classification value -for the distribution. Classifiers are described in PEP 301 [2]. +for the distribution. Classifiers are described in :pep:`301` [2]. Example:: @@ -202,8 +202,8 @@ If no specific role is stated, the default is ``contributor``. Email addresses must be in the form ``local-part@domain`` where the local-part may be up to 64 characters long and the entire email address contains no more than 254 characters. The formal specification of the -format is in RFC 5322 (sections 3.2.3 and 3.4.1) and RFC 5321, with a more -readable form given in the informational RFC 3696 and the associated errata. +format is in :rfc:`5322` (sections 3.2.3 and 3.4.1) and :rfc:`5321`, with a more +readable form given in the informational :rfc:`3696` and the associated errata. The defined contributor roles are as follows: diff --git a/pep-0461.txt b/pep-0461.txt index 7512a02a059..7216fb6c9b0 100644 --- a/pep-0461.txt +++ b/pep-0461.txt @@ -195,7 +195,7 @@ Various new special methods were proposed, such as ``__ascii__``, ``__format_bytes__``, etc.; such methods are not needed at this time, but can be visited again later if real-world use shows deficiencies with this solution. -A competing PEP, ``PEP 460 Add binary interpolation and formatting`` [8]_, +A competing PEP, :pep:`PEP 460 Add binary interpolation and formatting <460>`, also exists. @@ -237,7 +237,6 @@ Footnotes .. [6] https://mail.python.org/pipermail/python-dev/2014-February/132750.html .. [7] http://bugs.python.org/issue23467 -- originally ``%r`` was not allowed, but was added for consistency during the 3.5 alpha stage. -.. [8] http://python.org/dev/peps/pep-0460/ Copyright diff --git a/pep-0462.txt b/pep-0462.txt index 510a9842e62..ba4ae5dc9a8 100644 --- a/pep-0462.txt +++ b/pep-0462.txt @@ -28,7 +28,7 @@ PEP Withdrawal This PEP has been `withdrawn by the author `_ -in favour of the GitLab based proposal in PEP 507. +in favour of the GitLab based proposal in :pep:`507`. If anyone else would like to take over championing this PEP, contact the `core-workflow mailing list `_ @@ -180,7 +180,7 @@ CPython core development workflow. This proposal suggests replacing the use of Rietveld for code review with the more full-featured Kallithea-based forge.python.org service proposed in -PEP 474. Guido has indicated that the original Rietveld implementation was +:pep:`474`. Guido has indicated that the original Rietveld implementation was primarily intended as a public demonstration application for Google App Engine, and switching to Kallithea will address some of the issues with identifying intended target branches that arise when working with patch files @@ -306,7 +306,7 @@ builds without errors. As yet another alternative, it may be reasonable to move some parts of the documentation (such as the tutorial and the HOWTO guides) out of the main source repository and manage them using the simpler pull request based model -described in PEP 474. +described in :pep:`474`. Perceived Benefits @@ -552,7 +552,7 @@ One useful part of the OpenStack workflow is the "git review" plugin, which makes it relatively easy to push a branch from a local git clone up to Gerrit for review. -PEP 474 mentions a draft `custom Mercurial +:pep:`474` mentions a draft `custom Mercurial extension `__ that automates some aspects of the existing CPython core development workflow. @@ -596,7 +596,7 @@ infrastructure primarily due to past experience with unacceptably poor performance and inflexibility of infrastructure provided for free to the general public. CPython development was originally hosted on SourceForge, with source control moved to self hosting when SF was both slow to offer -Subversion support and suffering from CVS performance issues (see PEP 347), +Subversion support and suffering from CVS performance issues (see :pep:`347`), while issue tracking later moved to the open source Roundup issue tracker on dedicated sponsored hosting (from Upfront Systems), due to a combination of both SF performance issues and general usability issues with the SF @@ -633,7 +633,7 @@ Buildbot continuous integration fleet, have taken an extended period of time as volunteers worked their way through the many technical and social challenges involved. -Fortunately, as several aspects of this proposal and PEP 474 align with +Fortunately, as several aspects of this proposal and :pep:`474` align with various workflow improvements under consideration for Red Hat's `Beaker `__ open source hardware integration testing system and other work-related projects, I have arranged to be able @@ -673,7 +673,7 @@ Next Steps ========== If pursued, this will be a follow-on project to the Kallithea-based -forge.python.org proposal in PEP 474. Refer to that PEP for more details +forge.python.org proposal in :pep:`474`. Refer to that PEP for more details on the discussion, review and proof-of-concept pilot process currently under way. @@ -687,7 +687,7 @@ Taylor for additional technical feedback following publication of the initial draft. Thanks to Bradley Kuhn, Mads Kiellerich and other Kallithea developers for -the discussions around PEP 474 that led to a significant revision of this +the discussions around :pep:`474` that led to a significant revision of this proposal to be based on using Kallithea for the review component rather than the existing Rietveld installation. diff --git a/pep-0463.txt b/pep-0463.txt index 30c40d68470..68f1e1f299c 100644 --- a/pep-0463.txt +++ b/pep-0463.txt @@ -46,7 +46,7 @@ your next PEP! Abstract ======== -Just as PEP 308 introduced a means of value-based conditions in an +Just as :pep:`308` introduced a means of value-based conditions in an expression, this system allows exception-based conditions to be used as part of an expression. @@ -833,7 +833,7 @@ that it catch BaseException and be unable to capture it with 'as'). Bare except clauses ------------------- -PEP 8 rightly advises against the use of a bare 'except'. While it is +:pep:`8` rightly advises against the use of a bare 'except'. While it is syntactically legal in a statement, and for backward compatibility must remain so, there is little value in encouraging its use. In an expression except clause, "except:" is a SyntaxError; use the equivalent long-hand @@ -919,7 +919,7 @@ This proposal simply adds a fifth: * except-expression - exception list: result -Style guides and PEP 8 should recommend not having the colon at the end of +Style guides and :pep:`8` should recommend not having the colon at the end of a wrapped line, which could potentially look like the introduction of a suite, but instead advocate wrapping before the exception list, keeping the colon clearly between two expressions. diff --git a/pep-0464.txt b/pep-0464.txt index dd1bf5f2015..89d1b062b4e 100644 --- a/pep-0464.txt +++ b/pep-0464.txt @@ -24,7 +24,7 @@ API, this includes the /serverkey URL and all of the URLs under /serversig. Rationale ========= -The PyPI mirroring infrastructure (defined in PEP 381) provides a means to +The PyPI mirroring infrastructure (defined in :pep:`381`) provides a means to mirror the content of PyPI used by the automatic installers, and as a component of that, it provides a method for verifying the authenticity of the mirrored content. @@ -38,7 +38,7 @@ This PEP proposes the removal of this API due to: there is *any* bias in the random nonce. * This API solves one small corner of the trust problem, however the problem itself is much larger and it would be better to have a fully fledged system, - such as `The Update Framework `_, + such as :pep:`The Update Framework <458>`, instead. Due to the issues it has and the lack of use it is the opinion of this PEP @@ -62,7 +62,7 @@ If PyPI 2.0 has not been deployed in place of PyPI 1.0 by Sept 01 2014 then this PEP will be implemented in the PyPI 1.0 code base instead (by removing the associated code). -No changes will be required in the installers, however PEP 381 compliant +No changes will be required in the installers, however :pep:`381` compliant mirroring clients, such as `bandersnatch `_ and `pep381client `_ will need to be diff --git a/pep-0465.txt b/pep-0465.txt index ebed4df3b44..f6b34760961 100644 --- a/pep-0465.txt +++ b/pep-0465.txt @@ -173,7 +173,7 @@ impossible to get right at any scale. Functions that defensively try to handle both types as input and DTRT, find themselves floundering into a swamp of ``isinstance`` and ``if`` statements. -PEP 238 split ``/`` into two operators: ``/`` and ``//``. Imagine the +:pep:`238` split ``/`` into two operators: ``/`` and ``//``. Imagine the chaos that would have resulted if it had instead split ``int`` into two types: ``classic_int``, whose ``__div__`` implemented floor division, and ``new_int``, whose ``__div__`` implemented true @@ -795,7 +795,7 @@ expression context are: ``@``, backtick, ``$``, ``!``, and ``?``. Of these options, ``@`` is clearly the best; ``!`` and ``?`` are already heavily freighted with inapplicable meanings in the programming context, backtick has been banned from Python by BDFL pronouncement -(see PEP 3099), and ``$`` is uglier, even more dissimilar to ``*`` and +(see :pep:`3099`), and ``$`` is uglier, even more dissimilar to ``*`` and :math:`\cdot`, and has Perl/PHP baggage. ``$`` is probably the second-best option of these, though. @@ -844,7 +844,7 @@ options: be too easy to confuse with ``*+``, which is just multiplication combined with the unary ``+`` operator. -* PEP 211 suggested ``~*``. This has the downside that it sort of +* :pep:`211` suggested ``~*``. This has the downside that it sort of suggests that there is a unary ``*`` operator that is being combined with unary ``~``, but it could work. @@ -1008,12 +1008,12 @@ Rejected alternatives to adding a new operator Over the past few decades, the Python numeric community has explored a variety of ways to resolve the tension between matrix and elementwise -multiplication operations. PEP 211 and PEP 225, both proposed in 2000 +multiplication operations. :pep:`211` and :pep:`225`, both proposed in 2000 and last seriously discussed in 2008 [#threads-2008]_, were early attempts to add new operators to solve this problem, but suffered from serious flaws; in particular, at that time the Python numerical community had not yet reached consensus on the proper API for array -objects, or on what operators might be needed or useful (e.g., PEP 225 +objects, or on what operators might be needed or useful (e.g., :pep:`225` proposes 6 new operators with unspecified semantics). Experience since then has now led to consensus that the best solution, for both numeric Python and core Python, is to add a single infix operator for @@ -1046,13 +1046,13 @@ infix operators:** In addition to being generally un-Pythonic and repeatedly rejected by BDFL fiat, this would be using a sledgehammer to smash a fly. The scientific python community has consensus that adding one operator for matrix multiplication is enough to fix the one -otherwise unfixable pain point. (In retrospect, we all think PEP 225 +otherwise unfixable pain point. (In retrospect, we all think :pep:`225` was a bad idea too -- or at least far more complex than it needed to be.) **Add a new @ (or whatever) operator that has some other meaning in general Python, and then overload it in numeric code:** This was the -approach taken by PEP 211, which proposed defining ``@`` to be the +approach taken by :pep:`211`, which proposed defining ``@`` to be the equivalent of ``itertools.product``. The problem with this is that when taken on its own terms, it's pretty clear that ``itertools.product`` doesn't actually need a dedicated operator. It @@ -1134,11 +1134,11 @@ systems work. **Use a special "facade" type to support syntax like arr.M * arr:** This is very similar to the previous proposal, in that the ``.M`` -attribute would basically return the same object as ``arr *dot` would, +attribute would basically return the same object as ``arr *dot`` would, and thus suffers the same objections about 'magicalness'. This approach also has some non-obvious complexities: for example, while -``arr.M * arr`` must return an array, ``arr.M * arr.M`` and ``arr * -arr.M`` must return facade objects, or else ``arr.M * arr.M * arr`` +``arr.M * arr`` must return an array, ``arr.M * arr.M`` and +``arr * arr.M`` must return facade objects, or else ``arr.M * arr.M * arr`` and ``arr * arr.M * arr`` will not work. But this means that facade objects must be able to recognize both other array objects and other facade objects (which creates additional complexity for writing diff --git a/pep-0467.txt b/pep-0467.txt index 773967f820c..bdac798637c 100644 --- a/pep-0467.txt +++ b/pep-0467.txt @@ -30,7 +30,7 @@ During the initial development of the Python 3 language specification, the core ``bytes`` type for arbitrary binary data started as the mutable type that is now referred to as ``bytearray``. Other aspects of operating in the binary domain in Python have also evolved over the course of the Python -3 series, for example with PEP 461. +3 series, for example with :pep:`461`. Motivation @@ -143,7 +143,7 @@ to handle this use-case:: b'123' Note that ``bytes.ascii()`` would handle simple ascii-encodable text correctly, -unlike the `ascii()`` built-in:: +unlike the ``ascii()`` built-in:: >>> ascii("hello").encode('ascii') b"'hello'" @@ -198,7 +198,7 @@ Zero-initialised sequences can be created via sequence repetition:: However, this was also the case when the ``bytearray`` type was originally designed, and the decision was made to add explicit support for it in the type constructor. The immutable ``bytes`` type then inherited that feature -when it was introduced in PEP 3137. +when it was introduced in :pep:`3137`. This PEP isn't revisiting that original design decision, just changing the spelling as users sometimes find the current behavior of the binary sequence diff --git a/pep-0469.txt b/pep-0469.txt index 5af6b88790a..d916c6974b5 100644 --- a/pep-0469.txt +++ b/pep-0469.txt @@ -14,7 +14,7 @@ Post-History: 2014-04-18, 2014-04-21 Abstract ======== -For Python 3, PEP 3106 changed the design of the ``dict`` builtin and the +For Python 3, :pep:`3106` changed the design of the ``dict`` builtin and the mapping API in general to replace the separate list based and iterator based APIs in Python 2 with a merged, memory efficient set and multiset view based API. This new style of dict iteration was also added to the Python 2.7 diff --git a/pep-0470.txt b/pep-0470.txt index 87b904465a9..53fb707921f 100644 --- a/pep-0470.txt +++ b/pep-0470.txt @@ -19,7 +19,7 @@ Abstract This PEP proposes the deprecation and removal of support for hosting files externally to PyPI as well as the deprecation and removal of the functionality -added by PEP 438, particularly rel information to classify different types of +added by :pep:`438`, particularly rel information to classify different types of links and the meta-tag to indicate API version. @@ -55,14 +55,14 @@ PyPI works, and other projects works, but this one specific one does not. They oftentimes do not realize who they need to contact in order to get this fixed or what their remediation steps are. -PEP 438 attempted to solve this issue by allowing projects to explicitly +:pep:`438` attempted to solve this issue by allowing projects to explicitly declare if they were using the repository features or not, and if they were not, it had the installers classify the links it found as either "internal", -"verifiable external" or "unverifiable external". PEP 438 was accepted and +"verifiable external" or "unverifiable external". :pep:`438` was accepted and implemented in pip 1.4 (released on Jul 23, 2013) with the final transition implemented in pip 1.5 (released on Jan 2, 2014). -PEP 438 was successful in bringing about more people to utilize PyPI's +:pep:`438` was successful in bringing about more people to utilize PyPI's repository features, an altogether good thing given the global CDN powering PyPI providing speed ups for a lot of people, however it did so by introducing a new point of confusion and pain for both the end users and the authors. @@ -119,9 +119,9 @@ Why Not PEP 438 or Similar? --------------------------- While the additional search location support has existed in pip and setuptools -for quite some time support for PEP 438 has only existed in pip since the 1.4 +for quite some time support for :pep:`438` has only existed in pip since the 1.4 version, and still has yet to be implemented in setuptools. The design of -PEP 438 did mean that users still benefited for projects which did not require +:pep:`438` did mean that users still benefited for projects which did not require external files even with older installers, however for projects which *did* require external files, users are still silently being given either potentially unreliable or, even worse, unsafe files to download. This system is also unique @@ -129,7 +129,7 @@ to Python as it arises out of the history of PyPI, this means that it is almost certain that this concept will be foreign to most, if not all users, until they encounter it while attempting to use the Python toolchain. -Additionally, the classification system proposed by PEP 438 has, in practice, +Additionally, the classification system proposed by :pep:`438` has, in practice, turned out to be extremely confusing to end users, so much so that it is a position of this PEP that the situation as it stands is completely untenable. The common pattern for a user with this system is to attempt to install a @@ -146,13 +146,13 @@ This UX failure exists for several reasons. #. If pip can locate files at all for a project on the Simple API it will simply use that instead of attempting to locate more. This is generally the right thing to do as attempting to locate more would erase a large part of - the benefit of PEP 438. This means that if a project *ever* uploaded a file + the benefit of :pep:`438`. This means that if a project *ever* uploaded a file that matches what the user has requested for install that will be used regardless of how old it is. -#. PEP 438 makes an implicit assumption that most projects would either upload +#. :pep:`438` makes an implicit assumption that most projects would either upload themselves to PyPI or would update themselves to directly linking to release files. While a large number of projects did ultimately decide to upload to - PyPI, some of them did so only because the UX around what PEP 438 was so bad + PyPI, some of them did so only because the UX around what :pep:`438` was so bad that they felt forced to do so. More concerning however, is the fact that very few projects have opted to directly and safely link to files and instead they still simply link to pages which must be scraped in order to @@ -162,7 +162,7 @@ This UX failure exists for several reasons. non-obvious. It requires the inclusion of a MD5 hash (for historical reasons) in the hash of the URL. If they do not include this then their files will be considered "unverified". -#. PEP 438 takes a security centric view and disallows any form of a global opt +#. :pep:`438` takes a security centric view and disallows any form of a global opt in for unverified projects. While this is generally a good thing, it creates extremely verbose and repetitive command invocations such as:: @@ -209,7 +209,7 @@ Deprecation and Removal of Link Spidering ========================================= A new hosting mode will be added to PyPI. This hosting mode will be called -``pypi-only`` and will be in addition to the three that PEP 438 has already +``pypi-only`` and will be in addition to the three that :pep:`438` has already given us which are ``pypi-explicit``, ``pypi-scrape``, ``pypi-scrape-crawl``. This new hosting mode will modify a project's simple api page so that it only lists the files which are directly hosted on PyPI and will not link to anything @@ -254,7 +254,7 @@ Summary of Changes Repository side --------------- -#. Deprecate and remove the hosting modes as defined by PEP 438. +#. Deprecate and remove the hosting modes as defined by :pep:`438`. #. Restrict simple API to only list the files that are contained within the repository. @@ -264,7 +264,7 @@ Client side #. Implement multiple repository support. #. Implement some mechanism for removing/disabling the default repository. -#. Deprecate / Remove PEP 438 +#. Deprecate / Remove :pep:`438` Impact @@ -288,7 +288,7 @@ those, 59 of them rely on external files that are safely hosted outside of PyPI and 931 of them rely on external files which are unsafely hosted outside of PyPI. This shows us that 1.5% of projects will be affected in some way by this change while 98.5% will continue to function as they always have. In addition, -only 5% of the projects affected are using the features provided by PEP 438 to +only 5% of the projects affected are using the features provided by :pep:`438` to safely host outside of PyPI while 95% of them are exposing their users to Remote Code Execution via a Man In The Middle attack. @@ -318,9 +318,9 @@ default list of repositories. However, part of this answer will also be explaining that the previous behavior of transparently including external links was both a security hazard (given that in most cases it allowed a MITM to execute arbitrary Python code on the end users machine) and a reliability -concern and that PEP 438 attempted to resolve this by making them explicitly -opt in, but that PEP 438 brought along with it a number of serious usability -issues. PEP 470 represents a simplification of the model to a model that many +concern and that :pep:`438` attempted to resolve this by making them explicitly +opt in, but that :pep:`438` brought along with it a number of serious usability +issues. :pep:`470` represents a simplification of the model to a model that many users will be familiar with, which is common amongst Linux distributions. @@ -386,7 +386,7 @@ can add to their installer to make the installation work. This feature has been removed from the scope of the PEP because it proved too difficult to develop a solution that avoided UX issues similar to those that -caused so many problems with the PEP 438 solution. If needed, a future PEP +caused so many problems with the :pep:`438` solution. If needed, a future PEP could revisit this idea. @@ -395,7 +395,7 @@ Keep the current classification system but adjust the options This PEP rejects several related proposals which attempt to fix some of the usability problems with the current system but while still keeping the general -gist of PEP 438. +gist of :pep:`438`. This includes: @@ -405,12 +405,12 @@ This includes: * Default to disallowing safely externally hosted files with only a global flag to enable them, but disallow unsafely hosted. -* Continue on the suggested path of PEP 438 and remove the option to unsafely +* Continue on the suggested path of :pep:`438` and remove the option to unsafely host externally but continue to allow the option to safely host externally. These proposals are rejected because: -* The classification system introduced in PEP 438 in an entirely unique concept +* The classification system introduced in :pep:`438` in an entirely unique concept to PyPI which is not generically applicable even in the context of Python packaging. Adding additional concepts comes at a cost. @@ -429,7 +429,7 @@ These proposals are rejected because: determine if a link is expected to fail or not. * The mechanism paints a very broad brush when enabling an option, while - PEP 438 attempts to limit this with per package options. However a project + :pep:`438` attempts to limit this with per package options. However a project that has existed for an extended period of time may oftentimes have several different URLs listed in their simple index. It is not unusual for at least one of these to no longer be under control of the project. While an diff --git a/pep-0471.txt b/pep-0471.txt index 52bde075e03..69578d9a1bc 100644 --- a/pep-0471.txt +++ b/pep-0471.txt @@ -293,7 +293,7 @@ direct support for a scandir-like function from core developers and others on the python-dev and python-ideas mailing lists. A sampling: * **python-dev**: a good number of +1's and very few negatives for - scandir and PEP 471 on `this June 2014 python-dev thread + scandir and :pep:`471` on `this June 2014 python-dev thread `_ * **Nick Coghlan**, a core Python developer: "I've had the local Red @@ -562,7 +562,7 @@ methods are enough and this information is already known. See `Ben Hoyt's July 2014 reply `_ to the discussion summarizing this and detailing why he thinks the -original PEP 471 proposal is "the right one" after all. +original :pep:`471` proposal is "the right one" after all. Return values being (name, stat_result) two-tuples @@ -674,11 +674,11 @@ Previous discussion * `First July 2014 thread Ben Hoyt started on python-dev `_ - to discuss his updates to PEP 471 + to discuss his updates to :pep:`471` * `Second July 2014 thread Ben Hoyt started on python-dev `_ - to discuss the remaining decisions needed to finalize PEP 471, + to discuss the remaining decisions needed to finalize :pep:`471`, specifically whether the ``DirEntry`` methods should follow symlinks by default diff --git a/pep-0472.txt b/pep-0472.txt index ddec13dce5e..900e511643c 100644 --- a/pep-0472.txt +++ b/pep-0472.txt @@ -216,7 +216,7 @@ Cons - Very strict. - Destroys ordering of the passed arguments. Preserving the - order would be possible with an OrderedDict as drafted by PEP-468 [#PEP-468]_. + order would be possible with an OrderedDict as drafted by :pep:`468`. - Does not allow use cases with mixed positional/keyword arguments such as ``a[1, 2, default=5]``. @@ -356,7 +356,7 @@ For the C2 case: P1 naturally maps to the traditional ``**kwargs`` behavior, however it breaks the convention that two or more entries for the index produce a tuple. P2 preserves this behavior, and additionally preserves the order. Preserving the -order would also be possible with an OrderedDict as drafted by PEP-468 [#PEP-468]_. +order would also be possible with an OrderedDict as drafted by :pep:`468`. The remaining cases are here shown: @@ -554,7 +554,7 @@ Relevance of ordering of keyword arguments As part of the discussion of this PEP, it's important to decide if the ordering information of the keyword arguments is important, and if indexes and keys can -be ordered in an arbitrary way (e.g. ``a[1,Z=3,2,R=4]``). PEP-468 [#PEP-468]_ +be ordered in an arbitrary way (e.g. ``a[1,Z=3,2,R=4]``). :pep:`468` tries to address the first point by proposing the use of an ordereddict, however one would be inclined to accept that keyword arguments in indexing are equivalent to kwargs in function calls, and therefore as of today equally @@ -635,9 +635,6 @@ References .. [#namedtuple] "namedtuple is not as good as it should be" (https://mail.python.org/pipermail/python-ideas/2013-June/021257.html) -.. [#PEP-468] "Preserving the order of \*\*kwargs in a function." - http://legacy.python.org/dev/peps/pep-0468/ - Copyright ========= diff --git a/pep-0474.txt b/pep-0474.txt index 59bce90ccb4..4e3490e8722 100644 --- a/pep-0474.txt +++ b/pep-0474.txt @@ -20,7 +20,7 @@ more accessible to new contributors, and easier to manage for core developers. This PEP does *not* propose any changes to the core development workflow -for CPython itself (see PEP 462 in relation to that). +for CPython itself (see :pep:`462` in relation to that). PEP Withdrawal @@ -28,7 +28,7 @@ PEP Withdrawal This PEP has been `withdrawn by the author `_ -in favour of the GitLab based proposal in PEP 507. +in favour of the GitLab based proposal in :pep:`507`. If anyone else would like to take over championing this PEP, contact the `core-workflow mailing list `_ @@ -102,7 +102,7 @@ but may be negotiable if a sufficiently compelling alternative is presented: the standard pull request workflows offered by those tools * SHOULD be open to customisation to meet the needs of CPython core development, including providing a potential path forward for the - proposed migration to a core reviewer model in PEP 462 + proposed migration to a core reviewer model in :pep:`462` The preference for self-hosting without ongoing fees rules out the free-as-in-beer providers like GitHub and BitBucket, in addition to the @@ -419,7 +419,7 @@ with the rollout of the following pilot deployment: services) * automatic linking of issue references in code review comments and commit messages to the corresponding issues on bugs.python.org -* draft updates to PEP 1 explaining the Kallithea-based PEP editing and +* draft updates to :pep:`1` explaining the Kallithea-based PEP editing and submission workflow The following items would be needed for a production migration, but there @@ -439,7 +439,7 @@ selected and the proposed pilot deployment is successful): * allowing the use of the GitHub and BitBucket pull request workflows to submit pull requests to the main Kallithea repo * allowing easy triggering of forced BuildBot runs based on Kallithea hosted - repos and pull requests (prior to the implementation of PEP 462, this + repos and pull requests (prior to the implementation of :pep:`462`, this would be intended for use with sandbox repos rather than the main CPython repo) @@ -449,7 +449,7 @@ Future Implications for CPython Core Development The workflow requirements for the main CPython development repository are significantly more complex than those for the repositories being discussed -in this PEP. These concerns are covered in more detail in PEP 462. +in this PEP. These concerns are covered in more detail in :pep:`462`. Given Guido's recommendation to replace Rietveld with a more actively maintained code review system, my current plan is to rewrite that PEP to diff --git a/pep-0477.txt b/pep-0477.txt index bb7520df241..bf121ada811 100644 --- a/pep-0477.txt +++ b/pep-0477.txt @@ -62,14 +62,14 @@ reasons: finally actually installing it first. Furthermore, alternative implementations of Python are recognizing the benefits -of PEP 453 and both PyPy and Jython have plans to backport ensurepip to their +of :pep:`453` and both PyPy and Jython have plans to backport ensurepip to their 2.7 runtimes. Automatic Invocation ==================== -PEP 453 has ``ensurepip`` automatically invoked by default in the ``Makefile`` +:pep:`453` has ``ensurepip`` automatically invoked by default in the ``Makefile`` and the Windows and OSX Installers. This allowed it to ensure that, by default, all users would get Python with pip already installed. This PEP however believes that while this is fine for the Python 2.7 Windows and Mac OS X diff --git a/pep-0478.txt b/pep-0478.txt index e974c2cda52..1aa417c7328 100644 --- a/pep-0478.txt +++ b/pep-0478.txt @@ -80,19 +80,19 @@ including their release dates. Features for 3.5 ================ -* PEP 441, improved Python zip application support -* PEP 448, additional unpacking generalizations -* PEP 461, "%-formatting" for bytes and bytearray objects -* PEP 465, a new operator ("@") for matrix multiplication -* PEP 471, os.scandir(), a fast new directory traversal function -* PEP 475, adding support for automatic retries of interrupted system calls -* PEP 479, change StopIteration handling inside generators -* PEP 484, the typing module, a new standard for type annotations -* PEP 485, math.isclose(), a function for testing approximate equality -* PEP 486, making the Windows Python launcher aware of virtual environments -* PEP 488, eliminating .pyo files -* PEP 489, a new and improved mechanism for loading extension modules -* PEP 492, coroutines with async and await syntax +* :pep:`441`, improved Python zip application support +* :pep:`448`, additional unpacking generalizations +* :pep:`461`, "%-formatting" for bytes and bytearray objects +* :pep:`465`, a new operator ("@") for matrix multiplication +* :pep:`471`, os.scandir(), a fast new directory traversal function +* :pep:`475`, adding support for automatic retries of interrupted system calls +* :pep:`479`, change StopIteration handling inside generators +* :pep:`484`, the typing module, a new standard for type annotations +* :pep:`485`, math.isclose(), a function for testing approximate equality +* :pep:`486`, making the Windows Python launcher aware of virtual environments +* :pep:`488`, eliminating .pyo files +* :pep:`489`, a new and improved mechanism for loading extension modules +* :pep:`492`, coroutines with async and await syntax Copyright diff --git a/pep-0479.txt b/pep-0479.txt index 4bb2e3321b2..c50c7fddae1 100644 --- a/pep-0479.txt +++ b/pep-0479.txt @@ -55,7 +55,7 @@ is raised, a traceback is printed pinpointing the cause of the problem.) This is particularly pernicious in combination with the ``yield from`` -construct of PEP 380 [1]_, as it breaks the abstraction that a +construct of :pep:`380`, as it breaks the abstraction that a subgenerator may be factored out of a generator. That PEP notes this limitation, but notes that "use cases for these [are] rare to non- existent". Unfortunately while intentional use is rare, it is easy to @@ -580,9 +580,6 @@ by a simple ``return``. References ========== -.. [1] PEP 380 - Syntax for Delegating to a Subgenerator - (https://www.python.org/dev/peps/pep-0380) - .. [2] Initial mailing list comment (https://mail.python.org/pipermail/python-ideas/2014-November/029906.html) diff --git a/pep-0480.txt b/pep-0480.txt index d5252f9a494..8f18e132f32 100644 --- a/pep-0480.txt +++ b/pep-0480.txt @@ -17,22 +17,22 @@ Created: 08-Oct-2014 Abstract ======== -Proposed is an extension to PEP 458 that adds support for end-to-end signing +Proposed is an extension to :pep:`458` that adds support for end-to-end signing and the maximum security model. End-to-end signing allows both PyPI and developers to sign for the distributions that are downloaded by clients. The -minimum security model proposed by PEP 458 supports continuous delivery of +minimum security model proposed by :pep:`458` supports continuous delivery of distributions (because they are signed by online keys), but that model does not protect distributions in the event that PyPI is compromised. In the minimum security model, attackers who have compromised the signing keys stored on PyPI Infrastructure may sign for malicious distributions. The maximum security model, -described in this PEP, retains the benefits of PEP 458 (e.g., immediate +described in this PEP, retains the benefits of :pep:`458` (e.g., immediate availability of distributions that are uploaded to PyPI), but additionally ensures that end-users are not at risk of installing forged software if PyPI is compromised. This PEP requires some changes to the PyPI infrastructure, and some suggested changes for developers who wish to participate in end-to-end signing. These -changes include updating the metadata layout from PEP 458 to include delegations +changes include updating the metadata layout from :pep:`458` to include delegations to developer keys, adding a process to register developer keys with PyPI, and a change in the upload workflow for developers who take advantage of end-to-end signing. All of these changes are described in detail later in this PEP. Package @@ -40,10 +40,10 @@ managers that wish to take advantage of end-to-end signing do not need to do any additional work beyond what is required to consume metadata described in PEP 458. -This PEP discusses the changes made to PEP 458 but excludes its informational +This PEP discusses the changes made to :pep:`458` but excludes its informational elements to primarily focus on the maximum security model. For example, an -overview of The Update Framework or the basic mechanisms in PEP 458 are not -covered here. The changes to PEP 458 include modifications to the snapshot +overview of The Update Framework or the basic mechanisms in :pep:`458` are not +covered here. The changes to :pep:`458` include modifications to the snapshot process, key compromise analysis, auditing snapshots, and the steps that should be taken in the event of a PyPI compromise. The signing and key management process that PyPI MAY RECOMMEND is discussed but not strictly defined. How the @@ -58,7 +58,7 @@ PEP Status The community discussed this PEP from 2014 to 2018. Due to the amount of work required to implement this PEP, discussion was deferred until -after approval for the precursor step in PEP 458. As of mid-2020 PEP +after approval for the precursor step in :pep:`458`. As of mid-2020 PEP 458 is approved and implementation is in progress, and the PEP authors aim to gain approval so they can secure appropriate funding for implementation. @@ -67,13 +67,13 @@ implementation. Rationale ========= -PEP 458 [1]_ proposes how PyPI should be integrated with The Update Framework +:pep:`458` proposes how PyPI should be integrated with The Update Framework (TUF) [2]_. It explains how modern package managers like pip can be made more secure, and the types of attacks that can be prevented if PyPI is modified on the server side to include TUF metadata. Package managers can reference the TUF metadata available on PyPI to download distributions more securely. -PEP 458 also describes the metadata layout of the PyPI repository and employs +:pep:`458` also describes the metadata layout of the PyPI repository and employs the minimum security model, which supports continuous delivery of projects and uses online cryptographic keys to sign the distributions uploaded by developers. Although the minimum security model guards against most attacks on @@ -81,9 +81,9 @@ software updaters [5]_ [7]_, such as mix-and-match and extraneous dependencies attacks, it can be improved to support end-to-end signing and to prohibit forged distributions in the event that PyPI is compromised. -PEP 480 builds on PEP 458 by adding support for developer signing, and +:pep:`480` builds on :pep:`458` by adding support for developer signing, and reducing the reliance on online keys to prevent malicious distributions. -The main strength of PEP 458 and the minimum security model is the automated +The main strength of :pep:`458` and the minimum security model is the automated and simplified release process: developers may upload distributions and then have PyPI sign for their distributions. Much of the release process is handled in an automated fashion by online roles and this approach requires storing @@ -122,13 +122,11 @@ Definitions The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in RFC `2119`__. - -__ http://www.ietf.org/rfc/rfc2119.txt +interpreted as described in :rfc:`2119`. This PEP focuses on integrating TUF with PyPI; however, the reader is encouraged to read about TUF's design principles [2]_. It is also RECOMMENDED -that the reader be familiar with the TUF specification [3]_, and PEP 458 [1]_ +that the reader be familiar with the TUF specification [3]_, and :pep:`458` (which this PEP is extending). The following terms used in this PEP are defined in the Python Packaging @@ -200,7 +198,7 @@ developer roles are now supported and that three new delegated roles exist: *claimed*, *recently-claimed*, and *unclaimed*. The *bins* role from the minimum security model has been renamed *unclaimed* and can contain any projects that have not been added to *claimed*. The *unclaimed* role functions -just as before (i.e., as explained in PEP 458, projects added to this role are +just as before (i.e., as explained in :pep:`458`, projects added to this role are signed by PyPI with an online key). Offline keys provided by developers ensure the strength of the maximum security model over the minimum model. Although the minimum security model supports continuous delivery of projects, all @@ -872,7 +870,6 @@ an online key. References ========== -.. [1] https://www.python.org/dev/peps/pep-0458/ .. [2] https://theupdateframework.io/papers/survivable-key-compromise-ccs2010.pdf .. [3] https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt .. [4] https://packaging.python.org/glossary diff --git a/pep-0481.txt b/pep-0481.txt index 6bd6ede5f69..f693e66ff7c 100644 --- a/pep-0481.txt +++ b/pep-0481.txt @@ -14,12 +14,12 @@ Abstract ======== .. note:: This PEP has been withdrawn, if you're looking for the PEP - documenting the move to Github, please refer to PEP 512. + documenting the move to Github, please refer to :pep:`512`. This PEP proposes migrating the repository hosting of CPython and the supporting repositories to Git and Github. It also proposes adding Phabricator as an alternative to Github Pull Requests to handle reviewing changes. This -particular PEP is offered as an alternative to PEP 474 and PEP 462 which aims +particular PEP is offered as an alternative to :pep:`474` and :pep:`462` which aims to achieve the same overall benefits but restricts itself to tools that support Mercurial and are completely Open Source. diff --git a/pep-0482.txt b/pep-0482.txt index b80ca3ed9d8..2f17d5b989a 100644 --- a/pep-0482.txt +++ b/pep-0482.txt @@ -15,7 +15,7 @@ Abstract ======== This PEP is one of three related to type hinting. This PEP gives a -literature overview of related work. The main spec is PEP 484. +literature overview of related work. The main spec is :pep:`484`. Existing Approaches for Python diff --git a/pep-0483.txt b/pep-0483.txt index 35ae23d6771..460f0c64f5a 100644 --- a/pep-0483.txt +++ b/pep-0483.txt @@ -14,7 +14,7 @@ Post-History: Abstract ======== -This PEP lays out the theory referenced by PEP 484. +This PEP lays out the theory referenced by :pep:`484`. Introduction @@ -38,10 +38,10 @@ Notational conventions ``ti`` or ``tj`` to refer to "any of ``t1``, ``t2``, etc." - ``T``, ``U`` etc. are type variables (defined with ``TypeVar()``, see below). - Objects, classes defined with a class statement, and instances are - denoted using standard PEP 8 conventions. + denoted using standard :pep:`8` conventions. - the symbol ``==`` applied to types in the context of this PEP means that two expressions represent the same type. -- Note that PEP 484 makes a distinction between types and classes +- Note that :pep:`484` makes a distinction between types and classes (a type is a concept for the type checker, while a class is a runtime concept). In this PEP we clarify this distinction but avoid unnecessary strictness to allow more @@ -81,7 +81,7 @@ There are several ways to define a particular type: It is important for the user to be able to define types in a form that can be understood by type checkers. The goal of this PEP is to propose such a systematic way of defining types -for type annotations of variables and functions using PEP 3107 syntax. +for type annotations of variables and functions using :pep:`3107` syntax. These annotations can be used to avoid many kind of bugs, for documentation purposes, or maybe even to increase speed of program execution. Here we only focus on avoiding bugs by using a static type checker. @@ -249,8 +249,8 @@ from building blocks described below, and are used by static type checkers. Every class is a type as discussed above. But it is tricky and error prone to implement a class that exactly represents -semantics of a given type, and it is not a goal of PEP 484. -*The static types described in PEP 484, should not be confused with +semantics of a given type, and it is not a goal of :pep:`484`. +*The static types described in* :pep:`484` *should not be confused with the runtime classes.* Examples: - ``int`` is a class and a type. @@ -712,7 +712,7 @@ so that a type checker will also find that, e.g., ``Derived[Manager]`` is a subtype of ``Base[Employee]``. For more information on type variables, generic types, and variance, -see PEP 484, the `mypy docs on +see :pep:`484`, the `mypy docs on generics `_, and `Wikipedia `_. @@ -760,7 +760,7 @@ are still controversial or not fully specified.) zork = cast(Any, frobozz()) -- Other things, e.g. overloading and stub modules, see PEP 484. +- Other things, e.g. overloading and stub modules, see :pep:`484`. Predefined generic types and Protocols in typing.py diff --git a/pep-0484.txt b/pep-0484.txt index 1980e661223..184b05b6279 100644 --- a/pep-0484.txt +++ b/pep-0484.txt @@ -17,7 +17,7 @@ Resolution: https://mail.python.org/pipermail/python-dev/2015-May/140104.html Abstract ======== -PEP 3107 introduced syntax for function annotations, but the semantics +:pep:`3107` introduced syntax for function annotations, but the semantics were deliberately left undefined. There has now been enough 3rd party usage for static type analysis that the community would benefit from a standard vocabulary and baseline tools within the standard library. @@ -29,7 +29,7 @@ where annotations are not available. Note that this PEP still explicitly does NOT prevent other uses of annotations, nor does it require (or forbid) any particular processing of annotations, even when they conform to this specification. It -simply enables better coordination, as PEP 333 did for web frameworks. +simply enables better coordination, as :pep:`333` did for web frameworks. For example, here is a simple function whose argument and return type are declared in the annotations:: @@ -57,16 +57,16 @@ works at runtime by implementing ``__getitem__()`` in the metaclass The type system supports unions, generic types, and a special type named ``Any`` which is consistent with (i.e. assignable to and from) all types. This latter feature is taken from the idea of gradual typing. -Gradual typing and the full type system are explained in PEP 483. +Gradual typing and the full type system are explained in :pep:`483`. Other approaches from which we have borrowed or to which ours can be -compared and contrasted are described in PEP 482. +compared and contrasted are described in :pep:`482`. Rationale and Goals =================== -PEP 3107 added support for arbitrary annotations on parts of a +:pep:`3107` added support for arbitrary annotations on parts of a function definition. Although no meaning was assigned to annotations then, there has always been an implicit goal to use them for type hinting [gvr-artima]_, which is listed as the first possible use case @@ -138,7 +138,7 @@ decorators ``@property``, ``@staticmethod`` and ``@classmethod``. Type Definition Syntax ====================== -The syntax leverages PEP 3107-style annotations with a number of +The syntax leverages :pep:`3107`-style annotations with a number of extensions described in sections below. In its basic form, type hinting is used by filling function annotation slots with classes:: @@ -761,7 +761,7 @@ It turns out such an argument acts *contravariantly*, whereas the intuitive answer (which is correct in case the function doesn't mutate its argument!) requires the argument to act *covariantly*. A longer introduction to these concepts can be found on Wikipedia -[wiki-variance]_ and in PEP 483; here we just show how to control +[wiki-variance]_ and in :pep:`483`; here we just show how to control a type checker's behavior. By default generic types are considered *invariant* in all type variables, @@ -840,7 +840,7 @@ while the following is prohibited:: The numeric tower ----------------- -PEP 3141 defines Python's numeric tower, and the stdlib module +:pep:`3141` defines Python's numeric tower, and the stdlib module ``numbers`` implements the corresponding ABCs (``Number``, ``Complex``, ``Real``, ``Rational`` and ``Integral``). There are some issues with these ABCs, but the built-in concrete numeric classes @@ -1381,7 +1381,7 @@ return_type]`` provided by ``typing.py`` module:: res = yield round(res) return 'OK' -Coroutines introduced in PEP 492 are annotated with the same syntax as +Coroutines introduced in :pep:`492` are annotated with the same syntax as ordinary functions. However, the return type annotation corresponds to the type of ``await`` expression, not to the coroutine type:: @@ -1473,7 +1473,7 @@ Examples of type comments on ``with`` and ``for`` statements:: ... In stubs it may be useful to declare the existence of a variable -without giving it an initial value. This can be done using PEP 526 +without giving it an initial value. This can be done using :pep:`526` variable annotation syntax:: from typing import IO @@ -1517,7 +1517,7 @@ other comments and linting markers: If type hinting proves useful in general, a syntax for typing variables may be provided in a future Python version. (**UPDATE**: This syntax -was added in Python 3.6 through PEP 526.) +was added in Python 3.6 through :pep:`526`.) Casts ===== @@ -1764,7 +1764,7 @@ implementation using this syntax, its implementation would require using ``sys._getframe()``, which is frowned upon. Also, designing and implementing an efficient multiple dispatch mechanism is hard, which is why previous attempts were abandoned in favor of -``functools.singledispatch()``. (See PEP 443, especially its section +``functools.singledispatch()``. (See :pep:`443`, especially its section "Alternative approaches".) In the future we may come up with a satisfactory multiple dispatch design, but we don't want such a design to be constrained by the overloading syntax defined for type hints in @@ -1853,7 +1853,7 @@ Stub file package authors might use the following snippet in ``setup.py``:: (*UPDATE:* As of June 2018 the recommended way to distribute type hints for third-party packages has changed -- in addition to typeshed (see the next section) there is now a standard for distributing type -hints, PEP 561. It supports separately installable packages containing +hints, :pep:`561`. It supports separately installable packages containing stubs, stub files included in the same distribution as the executable code of a package, and inline type hints, the latter two options enabled by including a file named ``py.typed`` in the package.) @@ -2238,7 +2238,7 @@ Scala also use square brackets. What about existing uses of annotations? ---------------------------------------- -One line of argument points out that PEP 3107 explicitly supports +One line of argument points out that :pep:`3107` explicitly supports the use of arbitrary expressions in function annotations. The new proposal is then considered incompatible with the specification of PEP 3107. @@ -2252,7 +2252,7 @@ We do hope that type hints will eventually become the sole use for annotations, but this will require additional discussion and a deprecation period after the initial roll-out of the typing module with Python 3.5. The current PEP will have provisional status (see -PEP 411) until Python 3.6 is released. The fastest conceivable scheme +:pep:`411`) until Python 3.6 is released. The fastest conceivable scheme would introduce silent deprecation of non-type-hint annotations in 3.6, full deprecation in 3.7, and declare type hints as the only allowed use of annotations in Python 3.8. This should give authors of @@ -2262,7 +2262,7 @@ approach, even if type hints become an overnight success. (*UPDATE:* As of fall 2017, the timeline for the end of provisional status for this PEP and for the ``typing.py`` module has changed, and so has the deprecation schedule for other uses of annotations. For -the updated schedule see PEP 563.) +the updated schedule see :pep:`563`.) Another possible outcome would be that type hints will eventually become the default meaning for annotations, but that there will always @@ -2299,7 +2299,7 @@ a problem: "use" here means "look up at runtime", and with most "forward" references there is no problem in ensuring that a name is defined before the function using it is called. -The problem with type hints is that annotations (per PEP 3107, and +The problem with type hints is that annotations (per :pep:`3107`, and similar to default values) are evaluated at the time a function is defined, and thus any names used in an annotation must be already defined when the function is being defined. A common scenario is a @@ -2345,7 +2345,7 @@ Such a ``__future__`` import statement may be proposed in a separate PEP. (*UPDATE:* That ``__future__`` import statement and its consequences -are discussed in PEP 563.) +are discussed in :pep:`563`.) The double colon @@ -2366,7 +2366,7 @@ evaluation. There are several things wrong with this idea, however. used as a scoping operator, which is a very different beast. In contrast, the single colon for type hints reads naturally -- and no wonder, since it was carefully designed for this purpose (the idea - long predates PEP 3107 [gvr-artima]_). It is also used in the same + long predates :pep:`3107` [gvr-artima]_). It is also used in the same fashion in other languages from Pascal to Swift. * What would you do for return type annotations? @@ -2410,7 +2410,7 @@ The ideas put forward include: * A decorator, e.g. ``@typehints(name=str, returns=str)``. This could work, but it's pretty verbose (an extra line, and the argument names - must be repeated), and a far cry in elegance from the PEP 3107 + must be repeated), and a far cry in elegance from the :pep:`3107` notation. * Stub files. We do want stub files, but they are primarily useful @@ -2451,7 +2451,7 @@ Vitousek, Andrey Vlasovskikh, Radomir Dopieralski, Peter Ludemann, and the BDFL-Delegate, Mark Shannon. Influences include existing languages, libraries and frameworks -mentioned in PEP 482. Many thanks to their creators, in alphabetical +mentioned in :pep:`482`. Many thanks to their creators, in alphabetical order: Stefan Behnel, William Edwards, Greg Ewing, Larry Hastings, Anders Hejlsberg, Alok Menghrajani, Travis E. Oliphant, Joe Pamer, Raoul-Gabriel Urma, and Julien Verlaguet. diff --git a/pep-0486.txt b/pep-0486.txt index c36e4b3f45c..a785a8f2a6b 100644 --- a/pep-0486.txt +++ b/pep-0486.txt @@ -16,7 +16,7 @@ Abstract ======== The Windows installers for Python include a launcher that locates the -correct Python interpreter to run (see PEP 397). However, the +correct Python interpreter to run (see :pep:`397`). However, the launcher is not aware of virtual environments (virtualenv [1]_ or PEP 405 based), and so cannot be used to run commands from the active virtualenv. @@ -74,7 +74,7 @@ the system (i.e., when no specific version flags such as ``py -2.7`` are used) and if present, run the Python interpreter for the virtualenv rather than the default system Python. -The "default" Python interpreter referred to above is (as per PEP 397) +The "default" Python interpreter referred to above is (as per :pep:`397`) either the latest version of Python installed on the system, or a version configured via the ``py.ini`` configuration file. When the user specifies an explicit Python version on the command line, this diff --git a/pep-0487.txt b/pep-0487.txt index 558afb3b855..20e270ad606 100644 --- a/pep-0487.txt +++ b/pep-0487.txt @@ -62,7 +62,7 @@ into the class creation: 2. upon class creation, a ``__set_name__`` hook is called on all the attribute (descriptors) defined in the class, and -The third category is the topic of another PEP, PEP 520. +The third category is the topic of another PEP, :pep:`520`. As an example, the first use case looks as follows:: @@ -381,7 +381,7 @@ Calling the hook on the class itself ------------------------------------ Adding an ``__autodecorate__`` hook that would be called on the class -itself was the proposed idea of PEP 422. Most examples work the same +itself was the proposed idea of :pep:`422`. Most examples work the same way or even better if the hook is called only on strict subclasses. In general, it is much easier to arrange to explicitly call the hook on the class in which it is defined (to opt-in to such a behavior) than to opt-out (by remember to check for @@ -434,14 +434,14 @@ to be detected anyway in order to give a useful error message. This decision was reinforced after noticing that the user experience of defining ``__prepare__`` and forgetting the ``@classmethod`` method -decorator is singularly incomprehensible (particularly since PEP 3115 +decorator is singularly incomprehensible (particularly since :pep:`3115` documents it as an ordinary method, and the current documentation doesn't explicitly say anything one way or the other). A more ``__new__``-like hook ---------------------------- -In PEP 422 the hook worked more like the ``__new__`` method than the +In :pep:`422` the hook worked more like the ``__new__`` method than the ``__init__`` method, meaning that it returned a class instead of modifying one. This allows a bit more flexibility, but at the cost of much harder implementation and undesired side effects. @@ -449,15 +449,15 @@ of much harder implementation and undesired side effects. Adding a class attribute with the attribute order ------------------------------------------------- -This got its own PEP 520. +This got its own :pep:`520`. History ======= -This used to be a competing proposal to PEP 422 by Nick Coghlan and Daniel -Urban. PEP 422 intended to achieve the same goals as this PEP, but with a -different way of implementation. In the meantime, PEP 422 has been withdrawn +This used to be a competing proposal to :pep:`422` by Nick Coghlan and Daniel +Urban. :pep:`422` intended to achieve the same goals as this PEP, but with a +different way of implementation. In the meantime, :pep:`422` has been withdrawn favouring this approach. References diff --git a/pep-0488.txt b/pep-0488.txt index d8f7ef58f83..022a87e2be7 100644 --- a/pep-0488.txt +++ b/pep-0488.txt @@ -91,7 +91,7 @@ based on the interpreter's optimization level (none, ``-O``, and Currently bytecode file names are created by ``importlib.util.cache_from_source()``, approximately using the -following expression defined by PEP 3147 [3]_, [4]_, [5]_:: +following expression defined by :pep:`3147` [3]_, [4]_:: '{name}.{cache_tag}.pyc'.format(name=module_name, cache_tag=sys.implementation.cache_tag) @@ -236,7 +236,7 @@ of any use. Since people typically only distribute bytecode files for code obfuscation purposes or smaller distribution size then only having to distribute a single ``.pyc`` should actually be beneficial to these use-cases. And since the magic number for bytecode files -changed in Python 3.5 to support PEP 465 there is no need to support +changed in Python 3.5 to support :pep:`465` there is no need to support pre-existing ``.pyo`` files [8]_. @@ -318,9 +318,6 @@ References .. [4] Implementation of ``importlib.util.cache_from_source()`` from CPython 3.4.3rc1 (https://hg.python.org/cpython/file/038297948389/Lib/importlib/_bootstrap.py#l437) -.. [5] PEP 3147, PYC Repository Directories, Warsaw - (http://www.python.org/dev/peps/pep-3147) - .. [6] The py_compile module (https://docs.python.org/3/library/compileall.html#module-compileall) diff --git a/pep-0489.txt b/pep-0489.txt index 0daf966d79a..b6fcf844280 100644 --- a/pep-0489.txt +++ b/pep-0489.txt @@ -24,9 +24,9 @@ interact with the import machinery. This was last revised for Python 3.0 in PEP 3121, but did not solve all problems at the time. The goal is to solve import-related problems by bringing extension modules closer to the way Python modules behave; specifically to hook into the ModuleSpec-based loading -mechanism introduced in PEP 451. +mechanism introduced in :pep:`451`. -This proposal draws inspiration from PyType_Spec of PEP 384 to allow extension +This proposal draws inspiration from PyType_Spec of :pep:`384` to allow extension authors to only define features they need, and to allow future additions to extension module declarations. @@ -41,7 +41,7 @@ when using the new API. The proposal also allows extension modules with non-ASCII names. -Not all problems tackled in PEP 3121 are solved in this proposal. +Not all problems tackled in :pep:`3121` are solved in this proposal. In particular, problems with run-time module lookup (PyState_FindModule) are left to a future PEP. @@ -51,8 +51,8 @@ Motivation Python modules and extension modules are not being set up in the same way. For Python modules, the module object is created and set up first, then the -module code is being executed (PEP 302). -A ModuleSpec object (PEP 451) is used to hold information about the module, +module code is being executed (:pep:`302`). +A ModuleSpec object (:pep:`451`) is used to hold information about the module, and passed to the relevant hooks. For extensions (i.e. shared libraries) and built-in modules, the module @@ -76,7 +76,7 @@ Furthermore, the majority of currently existing extension modules has problems with sub-interpreter support and/or interpreter reloading, and, while it is possible with the current infrastructure to support these features, it is neither easy nor efficient. -Addressing these issues was the goal of PEP 3121, but many extensions, +Addressing these issues was the goal of :pep:`3121`, but many extensions, including some in the standard library, took the least-effort approach to porting to Python 3, leaving these issues unresolved. This PEP keeps backwards compatibility, which should reduce pressure and give @@ -119,7 +119,7 @@ object, will still be accepted, so existing code will work unchanged, including binary compatibility. The PyModuleDef structure will be changed to contain a list of slots, -similarly to PEP 384's PyType_Spec for types. +similarly to :pep:`384`'s PyType_Spec for types. To keep binary compatibility, and avoid needing to introduce a new structure (which would introduce additional supporting functions and per-module storage), the currently unused m_reload pointer of PyModuleDef will be changed to @@ -188,8 +188,8 @@ Here is an overview of how the modified importers will operate. Details such as logging or handling of errors and invalid states are left out, and C code is presented with a concise Python-like syntax. -The framework that calls the importers is explained in PEP 451 -[#pep-0451-loading]_. +The framework that calls the importers is explained in +:pep:`451#how-loading-will-work`. importlib/_bootstrap.py: @@ -347,13 +347,13 @@ The value pointer must point to a function with the following signature:: PyObject* (*PyModuleCreateFunction)(PyObject *spec, PyModuleDef *def) -The function receives a ModuleSpec instance, as defined in PEP 451, +The function receives a ModuleSpec instance, as defined in :pep:`451`, and the PyModuleDef structure. It should return a new module object, or set an error and return NULL. This function is not responsible for setting import-related attributes -specified in PEP 451 [#pep-0451-attributes]_ (such as ``__name__`` or +specified in :pep:`451#attributes` (such as ``__name__`` or ``__loader__``) on the new module. There is no requirement for the returned object to be an instance of @@ -412,7 +412,7 @@ PyModule_GetDef would fail), the execution phase is skipped. Execution slots may be specified multiple times, and are processed in the order they appear in the slots array. When using the default import machinery, they are processed after -import-related attributes specified in PEP 451 [#pep-0451-attributes]_ +import-related attributes specified in :pep:`451#attributes` (such as ``__name__`` or ``__loader__``) are set and the module is added to sys.modules. @@ -620,7 +620,7 @@ PyInit_, where is the name of the module. For module names containing non-ASCII characters, the import hook is named PyInitU_, where the name is encoded using CPython's -"punycode" encoding (Punycode [#rfc-3492]_ with a lowercase suffix), +"punycode" encoding (:rfc:`Punycode <3492>` with a lowercase suffix), with hyphens ("-") replaced by underscores ("_"). @@ -768,7 +768,7 @@ Internal functions of Python/import.c and Python/importdl.c will be removed. Possible Future Extensions ========================== -The slots mechanism, inspired by PyType_Slot from PEP 384, +The slots mechanism, inspired by PyType_Slot from :pep:`384`, allows later extensions. Some extension modules exports many constants; for example _ssl has @@ -790,7 +790,7 @@ beneficial, though.) Another possibility is providing a "main" function that would be run when the module is given to Python's -m switch. For this to work, the runpy module will need to be modified to take -advantage of ModuleSpec-based loading introduced in PEP 451. +advantage of ModuleSpec-based loading introduced in :pep:`451`. Also, it will be necessary to add a mechanism for setting up a module according to slots it wasn't originally defined with. @@ -808,13 +808,13 @@ Previous Approaches Stefan Behnel's initial proto-PEP [#stefans_protopep]_ had a "PyInit_modulename" hook that would create a module class, whose ``__init__`` would be then called to create the module. -This proposal did not correspond to the (then nonexistent) PEP 451, +This proposal did not correspond to the (then nonexistent) :pep:`451`, where module creation and initialization is broken into distinct steps. It also did not support loading an extension into pre-existing module objects. Nick Coghlan proposed "Create" and "Exec" hooks, and wrote a prototype implementation [#nicks-prototype]_. -At this time PEP 451 was still not implemented, so the prototype +At this time :pep:`451` was still not implemented, so the prototype does not use ModuleSpec. The original version of this PEP used Create and Exec hooks, and allowed @@ -834,18 +834,12 @@ exporting a definition, yielded a much simpler solution. References ========== -.. [#pep-0451-attributes] - https://www.python.org/dev/peps/pep-0451/#attributes - .. [#stefans_protopep] https://mail.python.org/pipermail/python-dev/2013-August/128087.html .. [#nicks-prototype] https://mail.python.org/pipermail/python-dev/2013-August/128101.html -.. [#rfc-3492] - http://tools.ietf.org/html/rfc3492 - .. [#gh-repo] https://github.com/encukou/cpython/commits/pep489 @@ -855,9 +849,6 @@ References .. [#findmodule-discussion] https://mail.python.org/pipermail/import-sig/2015-April/000959.html -.. [#pep-0451-loading] - https://www.python.org/dev/peps/pep-0451/#how-loading-will-work] - .. [#subinterpreter-docs] https://docs.python.org/3/c-api/init.html#sub-interpreter-support diff --git a/pep-0490.txt b/pep-0490.txt index 3105f1b3a2d..3514860d372 100644 --- a/pep-0490.txt +++ b/pep-0490.txt @@ -20,7 +20,7 @@ Rationale ========= Python 3 introduced a new killer feature: exceptions are chained by -default, PEP 3134. +default, :pep:`3134`. Example:: @@ -215,15 +215,14 @@ Appendix PEPs ---- -* `PEP 3134 -- Exception Chaining and Embedded Tracebacks - `_ (Python 3.0): +* :pep:`3134` -- Exception Chaining and Embedded Tracebacks + (Python 3.0): new ``__context__`` and ``__cause__`` attributes for exceptions -* `PEP 415 - Implement context suppression with exception attributes - `_ (Python 3.3): +* :pep:`415` -- Implement context suppression with exception attributes + (Python 3.3): ``raise exc from None`` -* `PEP 409 - Suppressing exception context - `_ - (superseded by the PEP 415) +* :pep:`409` -- Suppressing exception context + (superseded by the :pep:`415`) Python C API diff --git a/pep-0491.txt b/pep-0491.txt index 71a77b99c71..79436b8aa2b 100644 --- a/pep-0491.txt +++ b/pep-0491.txt @@ -19,7 +19,7 @@ re-building from source each time. A wheel is a ZIP-format archive with a specially formatted file name and the ``.whl`` extension. It contains a single distribution nearly as it -would be installed according to PEP 376 with a particular installation +would be installed according to :pep:`376` with a particular installation scheme. Simple wheels can be unpacked onto ``sys.path`` and used directly but wheels are usually installed with a specialized installer. @@ -39,11 +39,11 @@ Some specific elements to be addressed when work on this PEP is resumed in the future: - migrating the official wheel format definition to - https://packaging.python.org/specifications/ (similar to what PEP 566 did for + https://packaging.python.org/specifications/ (similar to what :pep:`566` did for https://packaging.python.org/specifications/core-metadata/) - updating the PEP itself to focus on the *changes* being made between the two versions of the format and the rationale for those changes, rather than - having to repeat all the information that is unchanged from PEP 427 + having to repeat all the information that is unchanged from :pep:`427` - clarifying that the PEP is deliberately written to allow existing installers to be compliant with the specification when using existing install scheme definitions, while also allowing the creation of new install scheme @@ -169,7 +169,7 @@ on any CPU architecture. The last three components of the filename before the extension are called "compatibility tags." The compatibility tags express the -package's basic interpreter requirements and are detailed in PEP 425. +package's basic interpreter requirements and are detailed in :pep:`425`. Escaping and Unicode '''''''''''''''''''' @@ -249,12 +249,12 @@ The .dist-info directory found at the root of sdists. #. WHEEL is the wheel metadata specific to a build of the package. #. RECORD is a list of (almost) all the files in the wheel and their - secure hashes. Unlike PEP 376, every file except RECORD, which + secure hashes. Unlike :pep:`376`, every file except RECORD, which cannot contain a hash of itself, must include its hash. The hash algorithm must be sha256 or better; specifically, md5 and sha1 are not permitted, as signed wheel files rely on the strong hashes in RECORD to validate the integrity of the archive. -#. PEP 376's INSTALLER and REQUESTED are not included in the archive. +#. :pep:`376`'s INSTALLER and REQUESTED are not included in the archive. #. RECORD.jws is used for digital signatures. It is not mentioned in RECORD. #. RECORD.p7s is allowed as a courtesy to anyone who would prefer to @@ -360,7 +360,7 @@ Signed wheel files ------------------ Wheel files include an extended RECORD that enables digital -signatures. PEP 376's RECORD is altered to include a secure hash +signatures. :pep:`376`'s RECORD is altered to include a secure hash ``digestname=urlsafe_b64encode_nopad(digest)`` (urlsafe base64 encoding with no trailing = characters) as the second column instead of an md5sum. All possible entries are hashed, including any @@ -394,10 +394,10 @@ checker only needs to establish that RECORD matches the signature. See -- http://self-issued.info/docs/draft-ietf-jose-json-web-signature.html -- http://self-issued.info/docs/draft-jones-jose-jws-json-serialization.html -- http://self-issued.info/docs/draft-ietf-jose-json-web-key.html -- http://self-issued.info/docs/draft-jones-jose-json-private-key.html +- https://datatracker.ietf.org/doc/html/rfc7515 +- https://datatracker.ietf.org/doc/html/draft-jones-jose-jws-json-serialization.html +- https://datatracker.ietf.org/doc/html/rfc7517 +- https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key.html Comparison to .egg diff --git a/pep-0492.txt b/pep-0492.txt index e5122b47966..ed8db52bad5 100644 --- a/pep-0492.txt +++ b/pep-0492.txt @@ -112,9 +112,9 @@ This proposal introduces new syntax and semantics to enhance coroutine support in Python. This specification presumes knowledge of the implementation of -coroutines in Python (PEP 342 and PEP 380). Motivation for the syntax -changes proposed here comes from the asyncio framework (PEP 3156) and -the "Cofunctions" proposal (PEP 3152, now rejected in favor of this +coroutines in Python (:pep:`342` and :pep:`380`). Motivation for the syntax +changes proposed here comes from the asyncio framework (:pep:`3156`) and +the "Cofunctions" proposal (:pep:`3152`, now rejected in favor of this specification). From this point in this document we use the word *native coroutine* to @@ -154,7 +154,7 @@ Key properties of *coroutines*: * ``StopIteration`` exceptions are not propagated out of coroutines, and are replaced with a ``RuntimeError``. For regular generators - such behavior requires a future import (see PEP 479). + such behavior requires a future import (see :pep:`479`). * When a *native coroutine* is garbage collected, a ``RuntimeWarning`` is raised if it was never awaited on (see also @@ -217,7 +217,7 @@ can be one of: fundamental mechanism of how *Futures* are implemented. Since, internally, coroutines are a special kind of generators, every ``await`` is suspended by a ``yield`` somewhere down the chain of - ``await`` calls (please refer to PEP 3156 for a detailed + ``await`` calls (please refer to :pep:`3156` for a detailed explanation). To enable this behavior for coroutines, a new magic method called @@ -598,7 +598,7 @@ and yield from fut raise StopIteration('spam') -And since PEP 479 is accepted and enabled by default for coroutines, +And since :pep:`479` is accepted and enabled by default for coroutines, the following example will have its ``StopIteration`` wrapped into a ``RuntimeError`` @@ -612,7 +612,7 @@ The only way to tell the outside code that the iteration has ended is to raise something other than ``StopIteration``. Therefore, a new built-in exception class ``StopAsyncIteration`` was added. -Moreover, with semantics from PEP 479, all ``StopIteration`` exceptions +Moreover, with semantics from :pep:`479`, all ``StopIteration`` exceptions raised in coroutines are wrapped in ``RuntimeError``. @@ -658,7 +658,7 @@ Coroutines are based on generators internally, thus they share the implementation. Similarly to generator objects, *coroutines* have ``throw()``, ``send()`` and ``close()`` methods. ``StopIteration`` and ``GeneratorExit`` play the same role for coroutines (although -PEP 479 is enabled by default for coroutines). See PEP 342, PEP 380, +:pep:`479` is enabled by default for coroutines). See :pep:`342`, :pep:`380`, and Python Documentation [11]_ for details. ``throw()``, ``send()`` methods for *coroutines* are used to push @@ -943,7 +943,7 @@ Design Considerations PEP 3152 -------- -PEP 3152 by Gregory Ewing proposes a different mechanism for coroutines +:pep:`3152` by Gregory Ewing proposes a different mechanism for coroutines (called "cofunctions"). Some key points: 1. A new keyword ``codef`` to declare a *cofunction*. *Cofunction* is @@ -980,7 +980,7 @@ Differences from this proposal: ``async def``). It is possible to simply write ``await future``, whereas ``cocall`` always requires parentheses. -3. To make asyncio work with PEP 3152 it would be required to modify +3. To make asyncio work with :pep:`3152` it would be required to modify ``@asyncio.coroutine`` decorator to wrap all functions in an object with a ``__cocall__`` method, or to implement ``__cocall__`` on generators. To call *cofunctions* from existing generator-based @@ -1065,11 +1065,11 @@ project easier (Python with ECMAScript 7 for instance). Why "__aiter__" does not return an awaitable -------------------------------------------- -PEP 492 was accepted in CPython 3.5.0 with ``__aiter__`` defined as +:pep:`492` was accepted in CPython 3.5.0 with ``__aiter__`` defined as a method, that was expected to return an awaitable resolving to an asynchronous iterator. -In 3.5.2 (as PEP 492 was accepted on a provisional basis) the +In 3.5.2 (as :pep:`492` was accepted on a provisional basis) the ``__aiter__`` protocol was updated to return asynchronous iterators directly. @@ -1388,7 +1388,7 @@ tested. Acceptance ========== -PEP 492 was accepted by Guido, Tuesday, May 5, 2015 [14]_. +:pep:`492` was accepted by Guido, Tuesday, May 5, 2015 [14]_. Implementation diff --git a/pep-0493.txt b/pep-0493.txt index 5947180adcb..a286091faf2 100644 --- a/pep-0493.txt +++ b/pep-0493.txt @@ -18,7 +18,7 @@ Resolution: https://mail.python.org/pipermail/python-dev/2016-March/143450.html Abstract ======== -PEP 476 updated Python's default handling of HTTPS certificates in client +:pep:`476` updated Python's default handling of HTTPS certificates in client modules to align with certificate handling in web browsers, by validating that the certificates received belonged to the server the client was attempting to contact. The Python 2.7 long term maintenance series was judged to be in @@ -35,7 +35,7 @@ from the decision to update to newer Python 2.7 maintenance releases. Rationale ========= -PEP 476 changed Python's default behaviour to align with expectations +:pep:`476` changed Python's default behaviour to align with expectations established by web browsers in regards to the semantics of HTTPS URLs: starting with Python 2.7.9 and 3.4.3, HTTPS clients in the standard library validate server certificates by default. @@ -58,7 +58,7 @@ offer relatively straightforward mechanisms for turning them off. At the moment, no such convenient mechanisms exist to disable Python's default certificate checking for a whole process. -PEP 476 did attempt to address this question, by covering how to revert to the +:pep:`476` did attempt to address this question, by covering how to revert to the old settings process wide by monkeypatching the ``ssl`` module to restore the old behaviour. Unfortunately, the ``sitecustomize.py`` based technique proposed to allow system administrators to disable the feature by default in their @@ -86,7 +86,7 @@ redistributors will still make their own design decisions in the interests of their customers. The main approaches available are: * Continuing to rebase on new Python 2.7.x releases, while providing no - additional assistance beyond the mechanisms defined in PEP 476 in migrating + additional assistance beyond the mechanisms defined in :pep:`476` in migrating from unchecked to checked hostnames in standard library HTTPS clients * Gating availability of the changes in default handling of HTTPS connections on upgrading from Python 2 to Python 3 @@ -128,7 +128,7 @@ The feature detection attributes defined by this PEP are: * ``ssl._https_verify_certificates``: runtime configuration API * ``ssl._https_verify_envvar``: environment based configuration -* ``ssl._cert_verification_config``: file based configuration (PEP 476 opt-in) +* ``ssl._cert_verification_config``: file based configuration (:pep:`476` opt-in) The marker attributes are prefixed with an underscore to indicate the implementation dependent and security sensitive nature of these capabilities. @@ -281,7 +281,7 @@ Backporting this PEP to earlier Python versions If this PEP is accepted, then commercial Python redistributors may choose to backport the per-process configuration mechanisms defined in this PEP to base -versions older than Python 2.7.9, *without* also backporting PEP 476's change +versions older than Python 2.7.9, *without* also backporting :pep:`476`'s change to the default behaviour of the overall Python installation. Such a backport would differ from the mechanism proposed in this PEP solely in @@ -303,7 +303,7 @@ is nominally older than Python 2.7.12. Specification ------------- -Implementing this backport involves backporting the changes in PEP 466, 476 and +Implementing this backport involves backporting the changes in :pep:`466`, 476 and this PEP, with the following change to the handling of the ``PYTHONHTTPSVERIFY`` environment variable in the ``ssl`` module: @@ -342,7 +342,7 @@ Security Considerations This change would be a strict security upgrade for any Python version that currently defaults to skipping certificate validation in standard library HTTPS clients. The technical trade-offs to be taken into account relate largely -to the magnitude of the PEP 466 backport also required rather than to anything +to the magnitude of the :pep:`466` backport also required rather than to anything security related. Interaction with Python virtual environments @@ -408,9 +408,9 @@ relevant configuration file name. Recommended modifications to the Python standard library -------------------------------------------------------- -The recommended approach to backporting the PEP 476 modifications to an earlier +The recommended approach to backporting the :pep:`476` modifications to an earlier point release is to implement the following changes relative to the default -PEP 476 behaviour implemented in Python 2.7.9+: +:pep:`476` behaviour implemented in Python 2.7.9+: * modify the ``ssl`` module to read a system wide configuration file when the module is first imported into a Python process @@ -544,7 +544,7 @@ Recommendation for combined feature backports If a redistributor chooses to backport the environment variable based configuration setting from this PEP to a modified Python version that also -implements the configuration file based PEP 476 backport, then the environment +implements the configuration file based :pep:`476` backport, then the environment variable should take precedence over the system-wide configuration setting. This allows the setting to be changed for a given user or application, regardless of the installation-wide default behaviour. diff --git a/pep-0496.txt b/pep-0496.txt index 52826711938..556c370ce77 100644 --- a/pep-0496.txt +++ b/pep-0496.txt @@ -12,10 +12,10 @@ Created: 03-Jul-2015 PEP Status ========== -After this PEP was initially drafted, PEP 508 was developed and submitted to +After this PEP was initially drafted, :pep:`508` was developed and submitted to fully specify the dependency declaration syntax, including environment markers. As a result, this PEP ended up being rejected in favour of the more comprehensive -PEP 508. +:pep:`508`. Abstract ======== @@ -26,8 +26,8 @@ required in particular environments, and to indicate supported platforms for distributions with additional constraints beyond the availability of a Python runtime. -Environment markers were first specified in PEP-0345 [#pep345]_. PEP-0426 -[#pep426]_ (which would replace PEP-0345) proposed extensions to the markers. +Environment markers were first specified in :pep:`345`. :pep:`426` +(which would replace :pep:`345`) proposed extensions to the markers. When 2.7.10 was released, even these extensions became insufficient due to their reliance on simple lexical comparisons, and thus this PEP has been born. @@ -97,9 +97,9 @@ The pseudo-grammar is :: ``SUBEXPR`` is either a Python string (such as ``'win32'``) or one of the ``Strings`` marker variables listed below. -``VEREXPR`` is a PEP-0440 [#pep440]_ version identifier, or one of the +``VEREXPR`` is a :pep:`440` version identifier, or one of the ``Version number`` marker variables listed below. Comparisons between -version numbers are done using PEP-0440 semantics. +version numbers are done using :pep:`440` semantics. Strings @@ -147,18 +147,6 @@ respectively, in accordance with the following algorithm:: ``python_full_version`` will typically correspond to ``sys.version.split()[0]``. -References -========== - -.. [#pep345] PEP 345, Metadata for Python Software Packages 1.2, Jones - (http://www.python.org/dev/peps/pep-0345) - -.. [#pep426] PEP 426, Metadata for Python Software Packages 2.0, Coghlan, Holth, Stufft - (http://www.python.org/dev/peps/pep-0426) - -.. [#pep440] PEP 440, Version Identification and Dependency Specification, Coghlan, Stufft - (https://www.python.org/dev/peps/pep-0440/) - Copyright ========= diff --git a/pep-0497.txt b/pep-0497.txt index bc6fa24b5f5..505fe5d4feb 100644 --- a/pep-0497.txt +++ b/pep-0497.txt @@ -14,7 +14,7 @@ Rejection Notice ================ The steering council decided that the `__past__` aspect of this proposal was too complicated for the potential benefit. The other aspect of stronger -requirements for backwards-compatibility should be addressed by PEP 387. +requirements for backwards-compatibility should be addressed by :pep:`387`. Scope @@ -24,14 +24,14 @@ This PEP is complementary to PEPs 5, 236, and 387, and shares similar goals. This PEP explains the need for an additional compatibility mechanism -in support of PEP 5, "Guidelines for Language Evolution". PEP 236, -"Back to the __future__", introduced a mechanism for forward -compatibility in support of PEP 5 but noted that a new mechanism for +in support of :pep:`5`, "Guidelines for Language Evolution". :pep:`236`, +"Back to the ``__future__``", introduced a mechanism for forward +compatibility in support of :pep:`5` but noted that a new mechanism for backward compatibility was outside the scope of that PEP. A related PEP (in progress) introduces such a mechanism for backward compatibility. -PEP 5, "Guidelines for Language Evolution", notes that "This PEP [PEP 5] +:pep:`5`, "Guidelines for Language Evolution", notes that "This PEP [:pep:`5`] does not replace or preclude other compatibility strategies such as dynamic loading of backwards-compatible parsers." @@ -39,16 +39,16 @@ dynamic loading of backwards-compatible parsers." Context ======= -From PEP 236: "From time to time, Python makes an incompatible change +From :pep:`236`: "From time to time, Python makes an incompatible change to the advertised semantics of core language constructs, or changes their accidental (implementation-dependent) behavior in some way. While 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 5, Guidelines for Language Evolution, -suggests ways to ease the pain, and this PEP [236] introduces some +contentious and disrupting. :pep:`5`, Guidelines for Language Evolution, +suggests ways to ease the pain, and this PEP [:pep:`236`] introduces some machinery in support of that." -Also from PEP 236: "The purpose of future_statement is to make life +Also from :pep:`236`: "The purpose of future_statement is to make life easier for people who keep current with the latest release in a timely fashion. We don't hate you if you don't, but your problems are much harder to solve, and somebody with those problems will need to write a @@ -77,8 +77,8 @@ the newer interpreter is only capable of using code that has been upgraded to support the changed feature. As an example, consider the changes to the division operator -introduced in PEP 238 in 2001, soon after PEP 236 introduced the -future_statement mechanism. PEP 238 outlines a suite of useful +introduced in :pep:`238` in 2001, soon after :pep:`236` introduced the +future_statement mechanism. :pep:`238` outlines a suite of useful forward-compatibility mechanisms for "true division" in the Python 2.x series but omits to include any backward-compatibility mechanisms for after "true division" was first enforced in Python 3.0. Python versions @@ -127,14 +127,14 @@ Proposal - part 1 This PEP makes two specific, related proposals. The first is that: - PEP 5 be augmented with a 6th step in the section "Steps for + :pep:`5` be augmented with a 6th step in the section "Steps for Introducing Backwards-Incompatible Features" to indicate that, when an incompatible change to core language syntax or semantics is being made, Python-dev's policy is to prefer and expect that, wherever possible, a mechanism for backward compatibility be considered and provided for future Python versions after the breaking change is adopted by default, in addition to any mechanisms proposed for forward - compatibility such as new future_statements. Furthermore, PEP 387, + compatibility such as new future_statements. Furthermore, :pep:`387`, "Backwards Compatibility Policy" (if accepted) would be augmented with the same 6th step. @@ -144,7 +144,7 @@ Example As an example of how this PEP is to be applied, if the latest revision of the "true division" PEP (238) were proposed today, it would be -considered incomplete. PEP 238 notes the "severe backwards +considered incomplete. :pep:`238` notes the "severe backwards compatibility issues" raised by the proposal and describes several measures for forward compatibility in the Abstract and API Changes sections. It also mentions some backward compatibility ideas raised on @@ -153,7 +153,7 @@ classic division semantics in a module", but it does not put forward any backward compatibility plan as part of the proposal. If this PEP is accepted, it would be expected that a proposal such as -PEP 238, because of its large-scale compatibility implications, would +:pep:`238`, because of its large-scale compatibility implications, would also be accompanied by a backward compatibility plan that enables users of future Python versions after the breaking change has come into effect to re-enable the classic division behaviour easily in @@ -176,7 +176,7 @@ of the ``__future__`` module and ``future_statement`` mechanism. The specific form and implementation of the ``__past__`` mechanism is the subject of a separate PEP (in progress). However, this PEP recommends that this ``__past__`` mechanism be designed to meet -similar criteria to those outlined in PEP 296 for ``__future__``. +similar criteria to those outlined in :pep:`296` for ``__future__``. Specifically: a. It should enable individual modules to specify obsolete behaviours diff --git a/pep-0498.txt b/pep-0498.txt index 071081f2ca8..22fc2689273 100644 --- a/pep-0498.txt +++ b/pep-0498.txt @@ -42,10 +42,10 @@ their values. Some examples are:: >>> f'He said his name is {name!r}.' "He said his name is 'Fred'." -A similar feature was proposed in PEP 215. PEP 215 proposed to support +A similar feature was proposed in :pep:`215`. :pep:`215` proposed to support a subset of Python expressions, and did not support the type-specific string formatting (the ``__format__()`` method) which was introduced -with PEP 3101. +with :pep:`3101`. Rationale ========= @@ -80,7 +80,7 @@ To be defensive, the following code should be used:: %-formatting. In particular, it uses normal function call syntax (and therefore supports multiple parameters) and it is extensible through the ``__format__()`` method on the object being converted to a -string. See PEP 3101 for a detailed rationale. This PEP reuses much of +string. See :pep:`3101` for a detailed rationale. This PEP reuses much of the ``str.format()`` syntax and machinery, in order to provide continuity with an existing Python string formatting mechanism. @@ -613,7 +613,7 @@ is not compatible with a bytes string. Binary f-strings would first require a solution for ``bytes.format()``. This idea has been proposed in the past, most -recently in PEP 461 [#]_. The discussions of such a feature usually +recently in :pep:`461#proposed-variations`. The discussions of such a feature usually suggest either - adding a method such as ``__bformat__()`` so an object can control @@ -667,7 +667,7 @@ If you feel you must use lambdas, they may be used inside of parentheses:: Can't combine with 'u' -------------------------- -The 'u' prefix was added to Python 3.3 in PEP 414 as a means to ease +The 'u' prefix was added to Python 3.3 in :pep:`414` as a means to ease source compatibility with Python 2.7. Because Python 2.7 will never support f-strings, there is nothing to be gained by being able to combine the 'f' prefix with 'u'. @@ -734,9 +734,6 @@ References .. [#] Differences in str.format() and f-string expressions (https://mail.python.org/pipermail/python-ideas/2015-July/034726.html) -.. [#] PEP 461 rejects bytes.format() - (https://www.python.org/dev/peps/pep-0461/#proposed-variations) - Copyright ========= diff --git a/pep-0499.txt b/pep-0499.txt index b75f527ef7e..9cbf6f8c3f0 100644 --- a/pep-0499.txt +++ b/pep-0499.txt @@ -147,7 +147,7 @@ Therefore, ``__name__`` is no longer the canonical name for some normal imports. Some counter arguments follow: -- As of PEP 451 a module's canonical name is stored at ``__spec__.name``. +- As of :pep:`451` a module's canonical name is stored at ``__spec__.name``. - Very little code should actually care about ``__name__`` being the canonical name and any that does should arguably be updated to consult ``__spec__.name`` with fallback to ``__name__`` for older Pythons, should that be relevant. @@ -220,8 +220,9 @@ However, the problem has been around as long as the ``-m`` command line option and is encountered regularly, if infrequently, by others. In addition to `issue 19702`_, the discrepancy around `__main__` -is alluded to in PEP 451 and a similar proposal (predating PEP 451) -is described in PEP 395 under `Fixing dual imports of the main module`_. +is alluded to in :pep:`451` and a similar proposal (predating :pep:`451`) +is described in :pep:`395` under +:pep:`Fixing dual imports of the main module <395#fixing-dual-imports-of-the-main-module>`. References @@ -231,8 +232,6 @@ References .. _I tripped over this issue: https://mail.python.org/pipermail/python-list/2015-August/694905.html -.. _Fixing dual imports of the main module: https://www.python.org/dev/peps/pep-0395/#fixing-dual-imports-of-the-main-module - Copyright ========= diff --git a/pep-0501.txt b/pep-0501.txt index e623c28ed51..65614613f56 100644 --- a/pep-0501.txt +++ b/pep-0501.txt @@ -14,7 +14,7 @@ Post-History: 08-Aug-2015, 23-Aug-2015, 30-Aug-2015 Abstract ======== -PEP 498 proposes new syntactic support for string interpolation that is +:pep:`498` proposes new syntactic support for string interpolation that is transparent to the compiler, allow name references from the interpolation operation full access to containing namespaces (as with any other expression), rather than being limited to explicit name references. These are referred @@ -47,7 +47,7 @@ Some possible examples of the proposed syntax:: PEP Deferral ============ -This PEP is currently deferred pending further experience with PEP 498's +This PEP is currently deferred pending further experience with :pep:`498`'s simpler approach of only supporting eager rendering without the additional complexity of also supporting deferred rendering. @@ -55,7 +55,7 @@ complexity of also supporting deferred rendering. Summary of differences from PEP 498 =================================== -The key additions this proposal makes relative to PEP 498: +The key additions this proposal makes relative to :pep:`498`: * the "i" (interpolation template) prefix indicates delayed rendering, but otherwise uses the same syntax and semantics as formatted strings @@ -70,7 +70,7 @@ The key additions this proposal makes relative to PEP 498: NOTE: This proposal spells out a draft API for ``types.InterpolationTemplate``. The precise details of the structures and methods exposed by this type would -be informed by the reference implementation of PEP 498, so it makes sense to +be informed by the reference implementation of :pep:`498`, so it makes sense to gain experience with that as an internal API before locking down a public API (if this extension proposal is accepted). @@ -120,7 +120,7 @@ strings that are not present directly in the source code of the application. Rationale ========= -PEP 498 makes interpolating values into strings with full access to Python's +:pep:`498` makes interpolating values into strings with full access to Python's lexical namespace semantics simpler, but it does so at the cost of creating a situation where interpolating values into sensitive targets like SQL queries, shell commands and HTML templates will enjoy a much cleaner syntax when handled @@ -148,7 +148,7 @@ permitted), and string literal concatenation operates as normal, with the entire combined literal forming the interpolation template. The template string is parsed into literals, expressions and format specifiers -as described for f-strings in PEP 498. Conversion specifiers are handled +as described for f-strings in :pep:`498`. Conversion specifiers are handled by the compiler, and appear as part of the field text in interpolation templates. @@ -264,7 +264,7 @@ NOTE: interpolation templates. The ``!a``, ``!r`` and ``!s`` conversion specifiers supported by ``str.format`` -and hence PEP 498 are handled in interpolation templates as follows: +and hence :pep:`498` are handled in interpolation templates as follows: * they're included unmodified in the raw template to ensure no information is lost @@ -334,7 +334,7 @@ Is essentially equivalent to:: Handling code injection attacks ------------------------------- -The PEP 498 formatted string syntax makes it potentially attractive to write +The :pep:`498` formatted string syntax makes it potentially attractive to write code like the following:: runquery(f"SELECT {column} FROM {table};") @@ -396,7 +396,7 @@ Invalid expressions:: SyntaxError: invalid syntax Run time errors occur when evaluating the expressions inside a -template string before creating the interpolation template object. See PEP 498 +template string before creating the interpolation template object. See :pep:`498` for some examples. Different renderers may also impose additional runtime @@ -456,7 +456,7 @@ that happen to be passed in as data values in a normal field. Discussion ========== -Refer to PEP 498 for additional discussion, as several of the points there +Refer to :pep:`498` for additional discussion, as several of the points there also apply to this PEP. Deferring support for binary interpolation @@ -480,7 +480,7 @@ For interoperability with interfaces that only accept strings, interpolation templates can still be prerendered with ``format``, rather than delegating the rendering to the called function. -This reflects the key difference from PEP 498, which *always* eagerly applies +This reflects the key difference from :pep:`498`, which *always* eagerly applies the default rendering, without any way to delegate the choice of renderer to another section of the code. @@ -503,10 +503,9 @@ made it much easier to support customisation of the semantics of interpolation. Building atop PEP 498, rather than competing with it ---------------------------------------------------- - Earlier versions of this PEP attempted to serve as a complete substitute for -PEP 498, rather than building a more flexible delayed rendering capability on -top of PEP 498's eager rendering. +:pep:`498`, rather than building a more flexible delayed rendering capability on +top of :pep:`498`'s eager rendering. Assuming the presence of f-strings as a supporting capability simplified a number of aspects of the proposal in this PEP (such as how to handle substitution @@ -527,9 +526,9 @@ contexts (like HTML, system shells, and database queries), or producing application debugging messages in the preferred language of the development team (rather than the native language of end users). -Due to the original design of the ``str.format`` substitution syntax in PEP -3101 being inspired by C#'s string formatting syntax, the specific field -substitution syntax used in PEP 498 is consistent not only with Python's own ``str.format`` syntax, but also with string formatting in C#, including the +Due to the original design of the ``str.format`` substitution syntax in :pep:`3101` +being inspired by C#'s string formatting syntax, the specific field +substitution syntax used in :pep:`498` is consistent not only with Python's own ``str.format`` syntax, but also with string formatting in C#, including the native "$-string" interpolation syntax introduced in C# 6.0 (released in July 2015). The related ``IFormattable`` interface in C# forms the basis of a `number of elements `__ of C#'s internationalization and localization @@ -545,7 +544,7 @@ format for translating C# applications). Acknowledgements ================ -* Eric V. Smith for creating PEP 498 and demonstrating the feasibility of +* Eric V. Smith for creating :pep:`498` and demonstrating the feasibility of arbitrary expression substitution in string interpolation * Barry Warsaw, Armin Ronacher, and Mike Miller for their contributions to exploring the feasibility of using this model of delayed rendering in i18n @@ -564,17 +563,13 @@ References .. [#] string.Template documentation (https://docs.python.org/3/library/string.html#template-strings) -.. [#] PEP 215: String Interpolation - (https://www.python.org/dev/peps/pep-0215/) +.. [#] :pep:`215`: String Interpolation -.. [#] PEP 292: Simpler String Substitutions - (https://www.python.org/dev/peps/pep-0292/) +.. [#] :pep:`292`: Simpler String Substitutions -.. [#] PEP 3101: Advanced String Formatting - (https://www.python.org/dev/peps/pep-3101/) +.. [#] :pep:`3101`: Advanced String Formatting -.. [#] PEP 498: Literal string formatting - (https://www.python.org/dev/peps/pep-0498/) +.. [#] :pep:`498`: Literal string formatting .. [#] FormattableString and C# native string interpolation (https://msdn.microsoft.com/en-us/library/dn961160.aspx) diff --git a/pep-0502.txt b/pep-0502.txt index 5e6855d3fae..cc73fdaafa8 100644 --- a/pep-0502.txt +++ b/pep-0502.txt @@ -13,7 +13,7 @@ Python-Version: 3.6 Abstract ======== -PEP 498: *Literal String Interpolation*, which proposed "formatted strings" was +:pep:`498`: *Literal String Interpolation*, which proposed "formatted strings" was accepted September 9th, 2015. Additional background and rationale given during its design phase is detailed below. @@ -46,7 +46,7 @@ PEP Status ========== This PEP was rejected based on its using an opinion-based tone rather than a factual one. -This PEP was also deemed not critical as PEP 498 was already written and should be the place +This PEP was also deemed not critical as :pep:`498` was already written and should be the place to house design decision details. @@ -64,10 +64,10 @@ or identifier duplication. These difficulties are described at moderate length in the original `post to python-ideas`_ -that started the snowball (that became PEP 498) rolling. [1]_ +that started the snowball (that became :pep:`498`) rolling. [1]_ Furthermore, replacement of the print statement with the more consistent print -function of Python 3 (PEP 3105) has added one additional minor burden, +function of Python 3 (:pep:`3105`) has added one additional minor burden, an additional set of parentheses to type and read. Combined with the verbosity of current string formatting solutions, this puts an otherwise simple language at an unfortunate disadvantage to its @@ -192,7 +192,7 @@ or forget the trailing type, e.g. (``s`` or ``d``). string.Template Class ''''''''''''''''''''' -The ``string.Template`` `class from`_ PEP 292 +The ``string.Template`` `class from`_ :pep:`292` (Simpler String Substitutions) is a purposely simplified design, using familiar shell interpolation syntax, @@ -220,7 +220,7 @@ unless encapsulated in a `convenience library`_ such as ``flufl.i18n``. PEP 215 - String Interpolation '''''''''''''''''''''''''''''' -PEP 215 was a former proposal of which this one shares a lot in common. +:pep:`215` was a former proposal of which this one shares a lot in common. Apparently, the world was not ready for it at the time, but considering recent support in a number of other languages, its day may have come. @@ -234,7 +234,7 @@ It was superseded by the following proposal. str.format() Method ''''''''''''''''''' -The ``str.format()`` `syntax of`_ PEP 3101 is the most recent and modern of the +The ``str.format()`` `syntax of`_ :pep:`3101` is the most recent and modern of the existing options. It is also more powerful and usually easier to read than the others. It avoids many of the drawbacks and limits of the previous techniques. @@ -260,7 +260,7 @@ The verbosity of the method-based approach is illustrated here. PEP 498 -- Literal String Formatting '''''''''''''''''''''''''''''''''''' -PEP 498 defines and discusses format strings, +:pep:`498` defines and discusses format strings, as also described in the `Abstract`_ above. It also, somewhat controversially to those first exposed, @@ -273,7 +273,7 @@ Restricting Syntax section under PEP 501 -- Translation ready string interpolation ''''''''''''''''''''''''''''''''''''''''''''''''' -The complimentary PEP 501 brings internationalization into the discussion as a +The complimentary :pep:`501` brings internationalization into the discussion as a first-class concern, with its proposal of the i-prefix, ``string.Template`` syntax integration compatible with ES6 (Javascript), deferred rendering, @@ -463,7 +463,7 @@ the existing choices, >>> f'Hello, {location} !' # new prefix: f'' 'Hello, World !' # interpolated result -PEP 498 -- Literal String Formatting, delves into the mechanics and +:pep:`498` -- Literal String Formatting, delves into the mechanics and implementation of this design. @@ -565,7 +565,7 @@ Internationalization '''''''''''''''''''' Though it was highly desired to integrate internationalization support, -(see PEP 501), +(see :pep:`501`), the finer details diverge at almost every point, making a common solution unlikely: [15]_ @@ -640,7 +640,7 @@ which could encourage bad habits. [13]_ Acknowledgements ================ -* Eric V. Smith for the authoring and implementation of PEP 498. +* Eric V. Smith for the authoring and implementation of :pep:`498`. * Everyone on the python-ideas mailing list for rejecting the various crazy ideas that came up, helping to keep the final design in focus. diff --git a/pep-0503.txt b/pep-0503.txt index ad8e42d3049..ba567b6b5d1 100644 --- a/pep-0503.txt +++ b/pep-0503.txt @@ -98,7 +98,7 @@ In addition to the above, the following constraints are placed on the API: GPG signature. Repositories that do this **SHOULD** include it on every link. * A repository **MAY** include a ``data-requires-python`` attribute on a file - link. This exposes the *Requires-Python* metadata field, specified in PEP 345, + link. This exposes the *Requires-Python* metadata field, specified in :pep:`345`, for the corresponding release. Where this is present, installer tools **SHOULD** ignore the download when installing to a Python version that doesn't satisfy the requirement. For example:: @@ -111,7 +111,7 @@ In addition to the above, the following constraints are placed on the API: Normalized Names ---------------- -This PEP references the concept of a "normalized" project name. As per PEP 426 +This PEP references the concept of a "normalized" project name. As per :pep:`426` the only valid characters in a name are the ASCII alphabet, ASCII numbers, ``.``, ``-``, and ``_``. The name should be lowercased with all runs of the characters ``.``, ``-``, or ``_`` replaced with a single ``-`` character. This diff --git a/pep-0504.txt b/pep-0504.txt index a1317b589dd..d893596b64f 100644 --- a/pep-0504.txt +++ b/pep-0504.txt @@ -50,7 +50,7 @@ Steven's proposal has the desired effect of aligning the easy way to generate such tokens and the right way to generate them, without introducing any compatibility risks for the existing ``random`` module API, so this PEP has been withdrawn in favour of further work on refining Steven's proposal as -PEP 506. +:pep:`506`. Proposal diff --git a/pep-0505.rst b/pep-0505.rst index 108efead993..9c2272772a1 100644 --- a/pep-0505.rst +++ b/pep-0505.rst @@ -572,8 +572,8 @@ Rejected Ideas The first three ideas in this section are oft-proposed alternatives to treating ``None`` as special. For further background on why these are rejected, see their -treatment in `PEP 531 `_ and -`PEP 532 `_ and the associated +treatment in :pep:`531` and +:pep:`532` and the associated discussions. No-Value Protocol @@ -751,7 +751,7 @@ Going back to one of the motivating examples above, consider the following:: >>> import json >>> created = None - >>> json.dumps({'created': created?.isoformat()})`` + >>> json.dumps({'created': created?.isoformat()}) The JSON serializer does not know how to serialize ``NoneQuestion``, nor will any other API. This proposal actually requires *lots of specialized logic* diff --git a/pep-0506.txt b/pep-0506.txt index ab4f8d5f26f..bd170f4ae9c 100644 --- a/pep-0506.txt +++ b/pep-0506.txt @@ -226,8 +226,9 @@ module [#]_. This received considerable scepticism and outright opposition: without a proven attack against Python applications, many people object to a backwards-incompatible change. -Nick Coghlan made an earlier suggestion for a globally configurable PRNG -which uses the system CSPRNG by default [#]_, but has since withdrawn it +Nick Coghlan made an :pep:`earlier suggestion <504>` +for a globally configurable PRNG +which uses the system CSPRNG by default, but has since withdrawn it in favour of this proposal. @@ -412,8 +413,6 @@ References output from the system CSPRNG, which is believed to be much harder to exploit. -.. [#] http://legacy.python.org/dev/peps/pep-0504/ - .. [#] http://php.net/manual/en/function.uniqid.php .. [#] http://php.net/manual/en/function.openssl-random-pseudo-bytes.php diff --git a/pep-0507.txt b/pep-0507.txt index 9c363fba679..b12f57c70db 100644 --- a/pep-0507.txt +++ b/pep-0507.txt @@ -17,10 +17,10 @@ Abstract This PEP proposes migrating the repository hosting of CPython and the supporting repositories to Git. Further, it proposes adopting a hosted GitLab instance as the primary way of handling merge requests, -code reviews, and code hosting. It is similar in intent to PEP 481 +code reviews, and code hosting. It is similar in intent to :pep:`481` but proposes an open source alternative to GitHub and omits the -proposal to run Phabricator. As with PEP 481, this particular PEP is -offered as an alternative to PEP 474 and PEP 462. +proposal to run Phabricator. As with :pep:`481`, this particular PEP is +offered as an alternative to :pep:`474` and :pep:`462`. Rationale diff --git a/pep-0508.txt b/pep-0508.txt index 23556bce82b..7c02041da6f 100644 --- a/pep-0508.txt +++ b/pep-0508.txt @@ -31,8 +31,8 @@ acceptable, so the language permits describing all these cases. The language defined is a compact line based format which is already in widespread use in pip requirements files, though we do not specify the command line option handling that those files permit. There is one caveat - the -URL reference form, specified in PEP-440 [#pep440]_ is not actually -implemented in pip, but since PEP-440 is accepted, we use that format rather +URL reference form, specified in :pep:`440` is not actually +implemented in pip, but since :pep:`440` is accepted, we use that format rather than pip's current native format. Motivation @@ -40,7 +40,7 @@ Motivation Any specification in the Python packaging ecosystem that needs to consume lists of dependencies needs to build on an approved PEP for such, but -PEP-426 [#pep426]_ is mostly aspirational - and there are already existing +:pep:`426` is mostly aspirational - and there are already existing implementations of the dependency specification which we can instead adopt. The existing implementations are battle proven and user friendly, so adopting them is arguably much better than approving an aspirational, unconsumed, format. @@ -82,8 +82,8 @@ as comments, multiple line support via continuations, or other such features. The full grammar including annotations to build a useful parse tree is included at the end of the PEP. -Versions may be specified according to the PEP-440 [#pep440]_ rules. (Note: -URI is defined in std-66 [#std66]_):: +Versions may be specified according to the :pep:`440` rules. (Note: +URI is defined in :rfc:`std-66 <3986>`):: version_cmp = wsp* '<' | '<=' | '!=' | '==' | '>=' | '>' | '~=' | '===' version = wsp* ( letterOrDigit | '-' | '_' | '.' | '*' | '+' | '!' )+ @@ -151,7 +151,7 @@ sole exception is detecting the end of a URL requirement. Names ----- -Python distribution names are currently defined in PEP-345 [#pep345]_. Names +Python distribution names are currently defined in :pep:`345`. Names act as the primary identifier for distributions. They are present in all dependency specifications, and are sufficient to be a specification on their own. However, PyPI places strict restrictions on names - they must match a @@ -182,12 +182,12 @@ If multiple extras are listed, all the dependencies are unioned together. Versions -------- -See PEP-440 [#pep440]_ for more detail on both version numbers and version +See :pep:`440` for more detail on both version numbers and version comparisons. Version specifications limit the versions of a distribution that can be used. They only apply to distributions looked up by name, rather than via a URL. Version comparison are also used in the markers feature. The -optional brackets around a version are present for compatibility with PEP-345 -[#pep345]_ but should not be generated, only accepted. +optional brackets around a version are present for compatibility with :pep:`345` +but should not be generated, only accepted. Environment Markers ------------------- @@ -204,15 +204,14 @@ False, the dependency specification should be ignored. The marker language is inspired by Python itself, chosen for the ability to safely evaluate it without running arbitrary code that could become a security -vulnerability. Markers were first standardised in PEP-345 [#pep345]_. This PEP -fixes some issues that were observed in the design described in PEP-426 -[#pep426]_. +vulnerability. Markers were first standardised in :pep:`345`. This PEP +fixes some issues that were observed in the design described in :pep:`426`. Comparisons in marker expressions are typed by the comparison operator. The operators that are not in perform the same as they -do for strings in Python. The operators use the PEP-440 -[#pep440]_ version comparison rules when those are defined (that is when both -sides have a valid version specifier). If there is no defined PEP-440 +do for strings in Python. The operators use the :pep:`440` +version comparison rules when those are defined (that is when both +sides have a valid version specifier). If there is no defined :pep:`440` behaviour and the operator exists in Python, then the operator falls back to the Python behaviour. Otherwise an error should be raised. e.g. the following will result in errors:: @@ -241,7 +240,7 @@ variables. The "extra" variable is special. It is used by wheels to signal which specifications apply to a given extra in the wheel ``METADATA`` file, but -since the ``METADATA`` file is based on a draft version of PEP-426, there is +since the ``METADATA`` file is based on a draft version of :pep:`426`, there is no current specification for this. Regardless, outside of a context where this special handling is taking place, the "extra" variable should result in an error like all other unknown variables. @@ -316,13 +315,13 @@ concerns. There are however a few points where the PEP differs from the deployed base. -Firstly, PEP-440 direct references haven't actually been deployed in the wild, +Firstly, :pep:`440` direct references haven't actually been deployed in the wild, but they were designed to be compatibly added, and there are no known obstacles to adding them to pip or other tools that consume the existing dependency metadata in distributions - particularly since they won't be permitted to be present in PyPI uploaded distributions anyway. -Secondly, PEP-426 markers which have had some reasonable deployment, +Secondly, :pep:`426` markers which have had some reasonable deployment, particularly in wheels and pip, will handle version comparisons with ``python_full_version`` "2.7.10" differently. Specifically in 426 "2.7.10" is less than "2.7.9". This backward incompatibility is deliberate. We are also @@ -334,8 +333,8 @@ both features will need to make a judgement as to when support has become sufficiently widespread in the ecosystem that using them will not cause compatibility issues. -Thirdly, PEP-345 required brackets around version specifiers. In order to -accept PEP-345 dependency specifications, brackets are accepted, but they +Thirdly, :pep:`345` required brackets around version specifiers. In order to +accept :pep:`345` dependency specifications, brackets are accepted, but they should not be generated. Rationale @@ -545,18 +544,6 @@ References .. [#pip] pip, the recommended installer for Python packages (http://pip.readthedocs.org/en/stable/) -.. [#pep345] PEP-345, Python distribution metadata version 1.2. - (https://www.python.org/dev/peps/pep-0345/) - -.. [#pep426] PEP-426, Python distribution metadata. - (https://www.python.org/dev/peps/pep-0426/) - -.. [#pep440] PEP-440, Python distribution metadata. - (https://www.python.org/dev/peps/pep-0440/) - -.. [#std66] The URL specification. - (https://tools.ietf.org/html/rfc3986) - .. [#parsley] The parsley PEG library. (https://pypi.python.org/pypi/parsley/) diff --git a/pep-0509.txt b/pep-0509.txt index b9e94a012b7..2f672d3e5bf 100644 --- a/pep-0509.txt +++ b/pep-0509.txt @@ -55,8 +55,8 @@ is modified, the function uses a regular lookup, and maybe also deoptimizes the function (to remove the overhead of the guard check for next function calls). -See the `PEP 510 -- Specialized functions with guards -`_ for concrete usage of +See the :pep:`510 -- Specialized functions with guards <510>` +for concrete usage of guards to specialize functions and for a more general rationale on Python static optimizers. @@ -122,8 +122,7 @@ must also be invalidated. Specialized functions using guards ---------------------------------- -The `PEP 510 -- Specialized functions with guards -`_ proposes an API to support +:pep:`510` proposes an API to support specialized functions with guards. It allows to implement static optimizers for Python without breaking the Python semantics. @@ -408,10 +407,8 @@ example, it increases the size of each dictionary entry by 8 bytes on In Python, the memory footprint matters and the trend is to reduce it. Examples: -* `PEP 393 -- Flexible String Representation - `_ -* `PEP 412 -- Key-Sharing Dictionary - `_ +* :pep:`393` -- Flexible String Representation +* :pep:`412` -- Key-Sharing Dictionary Add a new dict subtype diff --git a/pep-0511.txt b/pep-0511.txt index 29282b95c8b..22368071673 100644 --- a/pep-0511.txt +++ b/pep-0511.txt @@ -79,8 +79,7 @@ Example of optimizations which can be implemented with an AST optimizer: * `Dead code elimination `_ -Using guards (see the `PEP 510 -`_), it is possible to +Using guards (see :pep:`510`), it is possible to implement a much wider choice of optimizations. Examples: * Simplify iterable: replace ``range(3)`` with ``(0, 1, 2)`` when used @@ -137,11 +136,11 @@ Some examples: `_ * Domain Specific Language (DSL) like SQL queries. The Python language itself doesn't need to be modified. Previous attempts - to implement DSL for SQL like `PEP 335 - Overloadable Boolean - Operators `_ was rejected. + to implement DSL for SQL like :pep:`PEP 335 - Overloadable Boolean + Operators <335>` was rejected. * Pattern Matching of functional languages -* String Interpolation, but `PEP 498 -- Literal String Interpolation - `_ was merged into Python +* String Interpolation, but :pep:`498` + was merged into Python 3.6. `MacroPy `_ has a long list of @@ -549,7 +548,7 @@ Output:: Other Python implementations ============================ -The PEP 511 should be implemented by all Python implementation, but the +The :pep:`511` should be implemented by all Python implementation, but the bytecode and the AST are not standardized. By the way, even between minor version of CPython, there are changes on diff --git a/pep-0512.txt b/pep-0512.txt index b9e118470d2..5f67af44417 100644 --- a/pep-0512.txt +++ b/pep-0512.txt @@ -69,7 +69,7 @@ burdensome as it gets for a core developer to work with. Hence the decision was made in late 2014 that a move to a new development process was needed. A request for PEPs proposing new workflows was made, in the end leading to two: -PEP 481 and PEP 507 proposing GitHub [#github]_ and +:pep:`481` and :pep:`507` proposing GitHub [#github]_ and GitLab [#gitlab]_, respectively. The year 2015 was spent off-and-on working on those proposals and diff --git a/pep-0513.txt b/pep-0513.txt index dd1f5f93f89..7e3d2b7949d 100644 --- a/pep-0513.txt +++ b/pep-0513.txt @@ -29,7 +29,8 @@ Rationale ========= Currently, distribution of binary Python extensions for Windows and OS X is -straightforward. Developers and packagers build wheels [1]_ [2]_, which are +straightforward. Developers and packagers build wheels (:pep:`427`, :pep:`491`), +which are assigned platform tags such as ``win32`` or ``macosx_10_6_intel``, and upload these wheels to PyPI. Users can download and install these wheels using tools such as ``pip``. @@ -39,7 +40,7 @@ extension modules built on one Linux distribution will not work on other Linux distributions, or even on different machines running the same Linux distribution with different system libraries installed. -Build tools using PEP 425 platform tags [3]_ do not track information about the +Build tools using :pep:`425` platform tags do not track information about the particular Linux distribution or installed system libraries, and instead assign all wheels the too-vague ``linux_i686`` or ``linux_x86_64`` tags. Because of this ambiguity, there is no expectation that ``linux``-tagged built @@ -593,12 +594,6 @@ defer specifying these until we have more experience with the initial References ========== -.. [1] PEP 427 -- The Wheel Binary Package Format 1.0 - (https://www.python.org/dev/peps/pep-0427/) -.. [2] PEP 491 -- The Wheel Binary Package Format 1.9 - (https://www.python.org/dev/peps/pep-0491/) -.. [3] PEP 425 -- Compatibility Tags for Built Distributions - (https://www.python.org/dev/peps/pep-0425/) .. [4] Enthought Canopy Python Distribution (https://store.enthought.com/downloads/) .. [5] Continuum Analytics Anaconda Python Distribution diff --git a/pep-0514.txt b/pep-0514.txt index 98ad939a7ce..dd1b63a0a0f 100644 --- a/pep-0514.txt +++ b/pep-0514.txt @@ -38,7 +38,7 @@ Motivation When installed on Windows, the official Python installer creates a registry key for discovery and detection by other applications. This allows tools such as installers or IDEs to automatically detect and display a user's Python -installations. For example, the PEP 397 ``py.exe`` launcher and editors such as +installations. For example, the :pep:`397` ``py.exe`` launcher and editors such as PyCharm and Visual Studio already make use of this information. Third-party installers, such as those used by distributions, typically create @@ -171,7 +171,7 @@ name (preferred), a hostname, or as a last resort, a UUID would be appropriate:: HKEY_CURRENT_USER\Software\Python\www.example.com HKEY_CURRENT_USER\Software\Python\6C465E66-5A8C-4942-9E6A-D29159480C60 -The company name ``PyLauncher`` is reserved for the PEP 397 launcher +The company name ``PyLauncher`` is reserved for the :pep:`397` launcher (``py.exe``). It does not follow this convention and should be ignored by tools. If a string value named ``DisplayName`` exists, it should be used to identify diff --git a/pep-0516.txt b/pep-0516.txt index ee267aebc2b..f9341a5bf3d 100644 --- a/pep-0516.txt +++ b/pep-0516.txt @@ -36,14 +36,14 @@ install build time requirements for packages which is an important step in getting pip to full feature parity with the installation components of easy-install. -As PEP-426 [#pep426]_ is draft, we cannot utilise the metadata format it -defined. However PEP-427 wheels are in wide use and fairly well specified, so +As :pep:`426` is draft, we cannot utilise the metadata format it +defined. However :pep:`427` wheels are in wide use and fairly well specified, so we have adopted the METADATA format from that for specifying distribution -dependencies and general project metadata. PEP-0508 [#pep508] provides a +dependencies and general project metadata. :pep:`508` provides a self-contained language for describing a dependency, which we encapsulate in a thin JSON schema to describe bootstrap dependencies. -Since Python sdists specified in PEP-0314 [#pep314] are also source trees, this +Since Python sdists specified in :pep:`314` are also source trees, this PEP is updating the definition of sdists. @@ -51,7 +51,7 @@ PEP Rejection ============= The CLI based approach proposed in this PEP has been rejected in favour of the -Python API based approach proposed in PEP 517. The specific CLI used to +Python API based approach proposed in :pep:`517`. The specific CLI used to communicate with build backends running as isolated subprocesses will be considered an implementation detail of front-end developer tool implementations. @@ -97,7 +97,7 @@ schema schema version. bootstrap_requires - Optional list of dependency specifications [#pep508] that must be + Optional list of :pep:`508` dependency specifications that must be installed before running the build tool. For instance, if using flit, then the requirements might be:: @@ -164,7 +164,7 @@ The examples below use a build_command of ``flit`` for illustrative purposes. build_requires Query build requirements. Build requirements are returned as a UTF-8 encoded JSON document with one key ``build_requires`` consisting of a list - of dependency specifications [#pep508]_. Additional keys must be + of :pep:`508` dependency specifications. Additional keys must be ignored. The build_requires command is the only command run without setting up a build environment. @@ -176,7 +176,7 @@ metadata Query project metadata. The metadata and only the metadata should be output on stdout in UTF-8 encoding. pip would run metadata just once to determine what other packages need to be downloaded and installed. The - metadata is output as a wheel METADATA file per PEP-427 [#pep427]_. + metadata is output as a wheel METADATA file per :pep:`427`. Note that the metadata generated by the metadata command, and the metadata present in a generated wheel must be identical. @@ -382,7 +382,7 @@ a dependency, but otherwise deferred such to future iterations. We chose wheel METADATA files rather than defining a new specification, because pip can already handle wheel .dist-info directories which encode all -the necessary data in a METADATA file. PEP-426 can't be used as it's still +the necessary data in a METADATA file. :pep:`426` can't be used as it's still draft, and defining a new metadata format, while we should do that, is a separate problem. Using a directory on disk would not add any value to the interface (pip has to do that today due to limitations in the setuptools @@ -418,7 +418,7 @@ learning how to invoke a custom build tool. The metadata and wheel commands are required to have consistent metadata to avoid a race condition that could otherwise happen where pip reads the metadata, acts on it, and then the resulting wheel has incompatible -requirements. That race is exploited today by packages using PEP-426 +requirements. That race is exploited today by packages using :pep:`426` environment markers, to work with older pip versions that do not support environment markers. That exploit is not needed with this PEP, because either the setuptools shim is in use (with older pip versions), or an environment @@ -434,10 +434,10 @@ does today, and while there is a PR to do that as part of building from source, it is contentious and lacks consensus. Rather than impose a requirement on all build systems, we are treating it as a YAGNI, and will add such a verb in a future version of the interface if required. The existing -PEP-314 [#pep314] requirements for sdists still apply, and distutils or setuptools +:pep:`314` requirements for sdists still apply, and distutils or setuptools users can use ``setup.py sdist`` to create an sdist. Other tools should create -sdists compatible with PEP-314 [#pep314]. Note that pip itself does not require -PEP-314 compatibility - it does not use any of the metadata from sdists - they +sdists compatible with :pep:`314`. Note that pip itself does not require +:pep:`314` compatibility - it does not use any of the metadata from sdists - they are treated like source trees from disk or version control. References @@ -458,12 +458,6 @@ References .. [#shellvars] Shellvars, an implementation of shell variable rules for Python. (https://github.com/testing-cabal/shellvars) -.. [#pep426] PEP-426, Python distribution metadata. - (https://www.python.org/dev/peps/pep-0426/) - -.. [#pep427] PEP-427, Python distribution metadata. - (https://www.python.org/dev/peps/pep-0427/) - .. [#thread] The kick-off thread. (https://mail.python.org/pipermail/distutils-sig/2015-October/026925.html) @@ -473,12 +467,6 @@ References .. [#strformat] The Python string formatting syntax. (https://docs.python.org/3.1/library/string.html#format-string-syntax) -.. [#pep314] Metadata for Python Software Packages v1.1 - (https://www.python.org/dev/peps/pep-0314/) - -.. [#pep508] Dependency specification language PEP. - (https://www.python.org/dev/peps/pep-0508/) - Copyright ========= diff --git a/pep-0517.txt b/pep-0517.txt index 7b32471ff6a..ceb05bc346c 100644 --- a/pep-0517.txt +++ b/pep-0517.txt @@ -111,7 +111,7 @@ specification is encoded in the source code and documentation of to it as the ``setup.py``\-style. Here we define a new style of source tree based around the -``pyproject.toml`` file defined in PEP 518, extending the +``pyproject.toml`` file defined in :pep:`518`, extending the ``[build-system]`` table in that file with one additional key, ``build-backend``. Here's an example of how it would look:: @@ -273,7 +273,7 @@ A .tar.gz source distribution (sdist) contains a single top-level directory call package. This directory must also contain the ``pyproject.toml`` from the build directory, and a PKG-INFO file containing metadata in the format described in -`PEP 345 `_. Although historically +:pep:`345`. Although historically zip files have also been used as sdists, this hook should produce a gzipped tarball. This is already the more common format for sdists, and having a consistent format makes for simpler tooling. @@ -305,7 +305,7 @@ get_requires_for_build_wheel def get_requires_for_build_wheel(config_settings=None): ... -This hook MUST return an additional list of strings containing PEP 508 +This hook MUST return an additional list of strings containing :pep:`508` dependency specifications, above and beyond those specified in the ``pyproject.toml`` file, to be installed when calling the ``build_wheel`` or ``prepare_metadata_for_build_wheel`` hooks. @@ -352,7 +352,7 @@ get_requires_for_build_sdist def get_requires_for_build_sdist(config_settings=None): ... -This hook MUST return an additional list of strings containing PEP 508 +This hook MUST return an additional list of strings containing :pep:`508` dependency specifications, above and beyond those specified in the ``pyproject.toml`` file. These dependencies will be installed when calling the ``build_sdist`` hook. @@ -600,7 +600,7 @@ Integration frontends require that an sdist named ``{NAME}-{VERSION}.{EXT}`` will generate a wheel named ``{NAME}-{VERSION}-{COMPAT-INFO}.whl``. -The new restrictions for sdists built by PEP 517 backends are: +The new restrictions for sdists built by :pep:`517` backends are: - They will be gzipped tar archives, with the ``.tar.gz`` extension. Zip archives, or other compression formats for tarballs, are not allowed at @@ -698,7 +698,7 @@ implementation was released in pip 19.0. * Support for in-tree backends and self-hosting of backends was added by the introduction of the ``backend-path`` key in the ``[build-system]`` table. -* Clarified that the ``setuptools.build_meta:__legacy__`` PEP 517 backend is +* Clarified that the ``setuptools.build_meta:__legacy__`` :pep:`517` backend is an acceptable alternative to directly invoking ``setup.py`` for source trees that don't specify ``build-backend`` explicitly. @@ -712,7 +712,7 @@ has now been rejected in favour of this PEP. The primary difference is that our build backend is defined via a Python hook-based interface rather than a command-line based interface. -This appendix documents the arguments advanced for this PEP over PEP 516. +This appendix documents the arguments advanced for this PEP over :pep:`516`. We do *not* expect that specifying Python hooks rather than command line interfaces will, by itself, reduce the @@ -940,7 +940,7 @@ process, it can easily write it to do something like:: In the alternative where the public interface boundary is placed at the subprocess call, this is not possible -- either we need to spawn an extra process just to query what interfaces are supported (as was -included in an earlier draft of PEP 516, an alternative to this), or +included in an earlier draft of :pep:`516`, an alternative to this), or else we give up on autonegotiation entirely (as in the current version of that PEP), meaning that any changes in the interface will require N individual packages to update their ``pyproject.toml`` files before diff --git a/pep-0518.txt b/pep-0518.txt index 820d018d856..b9f6a67f108 100644 --- a/pep-0518.txt +++ b/pep-0518.txt @@ -119,7 +119,7 @@ To provide more context and motivation for this PEP, think of the 2. Installation of the build system. 3. Execute the build system. -This PEP covers step #2. PEP 517 covers step #3, including how to have +This PEP covers step #2. :pep:`517` covers step #3, including how to have the build system dynamically specify more dependencies that the build system requires to perform its job. The purpose of this PEP though, is to specify the minimal set of requirements for the build system to @@ -157,7 +157,7 @@ build-system table The ``[build-system]`` table is used to store build-related data. Initially only one key of the table will be valid and is mandatory for the table: ``requires``. This key must have a value of a list -of strings representing PEP 508 dependencies required to execute the +of strings representing :pep:`508` dependencies required to execute the build system (currently that means what dependencies are required to execute a ``setup.py`` file). diff --git a/pep-0519.txt b/pep-0519.txt index af3583c5d8d..576c19e506e 100644 --- a/pep-0519.txt +++ b/pep-0519.txt @@ -44,7 +44,7 @@ file system path whether it actually represents a path or not. To help elevate the representation of file system paths from their representation as strings and bytes to a richer object representation, the pathlib module [#pathlib]_ was provisionally introduced in -Python 3.4 through PEP 428. While considered by some as an improvement +Python 3.4 through :pep:`428`. While considered by some as an improvement over strings and bytes for file system paths, it has suffered from a lack of adoption. Typically the key issue listed for the low adoption rate has been the lack of support in the standard library. This lack @@ -415,7 +415,7 @@ Much of the discussion that led to this PEP revolved around whether ``__fspath__()`` should be polymorphic and return ``bytes`` as well as ``str`` or only return ``str``. The general sentiment for this view was that ``bytes`` are difficult to work with due to their -inherent lack of information about their encoding and PEP 383 makes +inherent lack of information about their encoding and :pep:`383` makes it possible to represent all file system paths using ``str`` with the ``surrogateescape`` handler. Thus, it would be better to forcibly promote the use of ``str`` as the low-level path representation for diff --git a/pep-0520.txt b/pep-0520.txt index 6fd52fdb3a0..5c63464e8fe 100644 --- a/pep-0520.txt +++ b/pep-0520.txt @@ -93,7 +93,7 @@ with that: First, it requires the use of a metaclass. Metaclasses introduce an extra level of complexity to code and in some cases (e.g. conflicts) are a problem. So reducing the need for them is worth doing when the -opportunity presents itself. PEP 422 and PEP 487 discuss this at +opportunity presents itself. :pep:`422` and :pep:`487` discuss this at length. We have such an opportunity by using an ordered mapping (e.g. ``OrderedDict`` for CPython at least) for the default class definition namespace, virtually eliminating the need for ``__prepare__()``. @@ -373,9 +373,10 @@ as a pain point. A "namespace" Keyword Arg for Class Definition ---------------------------------------------- -PEP 422 introduced a new "namespace" keyword arg to class definitions -that effectively replaces the need to ``__prepare__()``. [pep422_] -However, the proposal was withdrawn in favor of the simpler PEP 487. +:pep:`PEP 422 <422#order-preserving-classes>` +introduced a new "namespace" keyword arg to class definitions +that effectively replaces the need to ``__prepare__()``. +However, the proposal was withdrawn in favor of the simpler :pep:`487`. A stdlib Metaclass that Implements __prepare__() with OrderedDict ----------------------------------------------------------------- @@ -415,12 +416,6 @@ References .. [nick_concern] Nick's concerns about mutability (https://mail.python.org/pipermail/python-dev/2016-June/144883.html) -.. [pep422] PEP 422 - (https://www.python.org/dev/peps/pep-0422/#order-preserving-classes) - -.. [pep487] PEP 487 - (https://www.python.org/dev/peps/pep-0487/#defining-arbitrary-namespaces) - .. [orig] original discussion (https://mail.python.org/pipermail/python-ideas/2013-February/019690.html) diff --git a/pep-0521.txt b/pep-0521.txt index fc671570288..e31cf36cd6e 100644 --- a/pep-0521.txt +++ b/pep-0521.txt @@ -13,7 +13,7 @@ Post-History: 29-Apr-2015 PEP Withdrawal ============== -Withdrawn in favor of PEP 567. +Withdrawn in favor of :pep:`567`. Abstract @@ -68,7 +68,7 @@ More formally, consider the following code:: f((yield foo)) PARTIAL-BLOCK-2 -Currently this is equivalent to the following code (copied from PEP 343):: +Currently this is equivalent to the following code (copied from :pep:`343`):: mgr = (EXPR) exit = type(mgr).__exit__ # Not calling it yet @@ -308,7 +308,7 @@ down to a single C-level ``if (frame->needs_suspend_resume_calls) { Interaction with PEP 492 ======================== -PEP 492 added new asynchronous context managers, which are like +:pep:`492` added new asynchronous context managers, which are like regular context managers, but instead of having regular methods ``__enter__`` and ``__exit__`` they have coroutine methods ``__aenter__`` and ``__aexit__``. diff --git a/pep-0522.txt b/pep-0522.txt index f60a26b125d..be3690e7532 100644 --- a/pep-0522.txt +++ b/pep-0522.txt @@ -60,9 +60,9 @@ potentially be encountered in the following situations: Relationship with other PEPs ============================ -This PEP depends on the Accepted PEP 506, which adds the ``secrets`` module. +This PEP depends on the Accepted :pep:`506`, which adds the ``secrets`` module. -This PEP competes with Victor Stinner's PEP 524, which proposes to make +This PEP competes with Victor Stinner's :pep:`524`, which proposes to make ``os.urandom`` itself implicitly block when the system RNG is not ready. @@ -70,7 +70,7 @@ PEP Rejection ============= For the reference implementation, Guido rejected this PEP in favour of the -unconditional implicit blocking proposal in PEP 524 (which brings CPython's +unconditional implicit blocking proposal in :pep:`524` (which brings CPython's behaviour on Linux into line with its behaviour on other operating systems). This means any further discussion of appropriate default behaviour for @@ -86,7 +86,7 @@ CPython interpreter initialization and ``random`` module initialization have already been updated to gracefully fall back to alternative seeding options if the system random number generator is not ready. -This PEP does not compete with the proposal in PEP 524 to add an +This PEP does not compete with the proposal in :pep:`524` to add an ``os.getrandom()`` API to expose the ``getrandom`` syscall on platforms that offer it. There is sufficient motive for adding that API in the ``os`` module's role as a thin wrapper around potentially platform dependent operating system @@ -109,7 +109,7 @@ This behaviour will then propagate through to the existing ``random.SystemRandom``, which provides a relatively thin wrapper around ``os.urandom()`` that matches the ``random.Random()`` API. -However, the new ``secrets`` module introduced by PEP 506 will be updated to +However, the new ``secrets`` module introduced by :pep:`506` will be updated to catch the new exception and implicitly wait for the system random number generator if the exception is ever encountered. @@ -288,7 +288,7 @@ security sensitive operations in Python. To help improve API discoverability and make it clearer that secrecy and simulation are not the same problem (even though they both involve -random numbers), PEP 506 collected several of the one line recipes based +random numbers), :pep:`506` collected several of the one line recipes based on the lower level ``os.urandom()`` API into a new ``secrets`` module. However, this guidance has also come with a longstanding caveat: developers @@ -355,7 +355,7 @@ might unexpectedly start blocking waiting for the system RNG to be available. Backwards Compatibility Impact Assessment ========================================= -Similar to PEP 476, this is a proposal to turn a previously silent security +Similar to :pep:`476`, this is a proposal to turn a previously silent security failure into a noisy exception that requires the application developer to make an explicit decision regarding the behaviour they desire. @@ -675,7 +675,7 @@ decision has to be made: imported) * servicing user calls to the ``os.urandom`` public API * the higher level ``random.SystemRandom`` public API -* the new ``secrets`` module public API added by PEP 506 +* the new ``secrets`` module public API added by :pep:`506` Previously, these five places all used the same underlying code, and thus made this decision in the same way. @@ -714,7 +714,7 @@ as a side-effect of importing the random module. Independently of this PEP, the first two cases have already been updated to never block, regardless of the behaviour of ``os.urandom()``. -Where PEP 524 proposes to make all 3 of the latter cases block implicitly, +Where :pep:`524` proposes to make all 3 of the latter cases block implicitly, this PEP proposes that approach only for the last case (the ``secrets``) module, with ``os.urandom()`` and ``random.SystemRandom()`` instead raising an exception when they detect that the underlying operating system call diff --git a/pep-0524.txt b/pep-0524.txt index 6719fcd6a44..03ff8d89c40 100644 --- a/pep-0524.txt +++ b/pep-0524.txt @@ -46,8 +46,8 @@ counter-measure against the hash denial-of-service (hash DoS), see: * `Issue #13703: Hash collision security issue `_ -* `PEP 456: Secure and interchangeable hash algorithm - `_ +* :pep:`PEP 456: Secure and interchangeable hash algorithm + <456>` Importing the ``random`` module creates an instance of ``random.Random``: ``random._inst``. On Python 3.5, random.Random @@ -405,8 +405,8 @@ Raise BlockingIOError in os.urandom() Proposition ^^^^^^^^^^^ -`PEP 522: Allow BlockingIOError in security sensitive APIs on Linux -`_. +:pep:`PEP 522: Allow BlockingIOError in security sensitive APIs on Linux +<522>`. Python should not decide for the developer how to handle `The bug`_: raising immediately a ``BlockingIOError`` if ``os.urandom()`` is going to diff --git a/pep-0525.txt b/pep-0525.txt index e8e64179ac8..58a63d37d13 100644 --- a/pep-0525.txt +++ b/pep-0525.txt @@ -15,7 +15,7 @@ Post-History: 02-Aug-2016, 23-Aug-2016, 01-Sep-2016, 06-Sep-2016 Abstract ======== -PEP 492 introduced support for native coroutines and ``async``/``await`` +:pep:`492` introduced support for native coroutines and ``async``/``await`` syntax to Python 3.5. It is proposed here to extend Python's asynchronous capabilities by adding support for *asynchronous generators*. @@ -24,7 +24,7 @@ asynchronous capabilities by adding support for Rationale and Goals =================== -Regular generators (introduced in PEP 255) enabled an elegant way of +Regular generators (introduced in :pep:`255`) enabled an elegant way of writing complex *data producers* and have them behave like an iterator. However, currently there is no equivalent concept for the *asynchronous @@ -33,7 +33,7 @@ data producers unnecessarily complex, as one must define a class that implements ``__aiter__`` and ``__anext__`` to be able to use it in an ``async for`` statement. -Essentially, the goals and rationale for PEP 255, applied to the +Essentially, the goals and rationale for :pep:`255`, applied to the asynchronous execution case, hold true for this proposal as well. Performance is an additional point for this proposal: in our testing of @@ -80,7 +80,7 @@ This proposal introduces the concept of *asynchronous generators* to Python. This specification presumes knowledge of the implementation of -generators and coroutines in Python (PEP 342, PEP 380 and PEP 492). +generators and coroutines in Python (:pep:`342`, :pep:`380` and :pep:`492`). Asynchronous Generators @@ -107,7 +107,7 @@ We propose to use the same approach to define The result of calling an *asynchronous generator function* is an *asynchronous generator object*, which implements the asynchronous -iteration protocol defined in PEP 492. +iteration protocol defined in :pep:`492`. It is a ``SyntaxError`` to have a non-empty ``return`` statement in an asynchronous generator. @@ -143,7 +143,7 @@ iterate over a simple asynchronous generator:: Finalization ------------ -PEP 492 requires an event loop or a scheduler to run coroutines. +:pep:`492` requires an event loop or a scheduler to run coroutines. Because asynchronous generators are meant to be used from coroutines, they also require an event loop to run and finalize them. @@ -517,7 +517,7 @@ Design Considerations ``aiter()`` and ``anext()`` builtins ------------------------------------ -Originally, PEP 492 defined ``__aiter__`` as a method that should +Originally, :pep:`492` defined ``__aiter__`` as a method that should return an *awaitable* object, resulting in an asynchronous iterator. However, in CPython 3.5.2, ``__aiter__`` was redefined to return @@ -618,7 +618,7 @@ print numbers from 0 to 9 with one second delay):: Acceptance ========== -PEP 525 was accepted by Guido, September 6, 2016 [2]_. +:pep:`525` was accepted by Guido, September 6, 2016 [2]_. Implementation diff --git a/pep-0526.txt b/pep-0526.txt index 6308b329068..5e440ebf298 100644 --- a/pep-0526.txt +++ b/pep-0526.txt @@ -36,7 +36,7 @@ read the summary of `rejected`_ ideas listed at the end of this PEP. Abstract ======== -PEP 484 introduced type hints, a.k.a. type annotations. While its +:pep:`484` introduced type hints, a.k.a. type annotations. While its main focus was function annotations, it also introduced the notion of type comments to annotate variables:: @@ -61,7 +61,7 @@ instead of expressing them through comments:: class Starship: stats: ClassVar[Dict[str, int]] = {} -PEP 484 explicitly states that type comments are intended to help with +:pep:`484` explicitly states that type comments are intended to help with type inference in complex cases, and this PEP does not change this intention. However, since in practice type comments have also been adopted for class variables and instance variables, this PEP also @@ -107,7 +107,7 @@ The majority of these issues can be alleviated by making the syntax a core part of the language. Moreover, having a dedicated annotation syntax for class and instance variables (in addition to method annotations) will pave the way to static duck-typing as a complement to nominal typing defined -by PEP 484. +by :pep:`484`. Non-goals ********* @@ -141,7 +141,7 @@ party type checker:: other_var: int = 'a' # Flagged as error by type checker, # but OK at runtime. -This syntax does not introduce any new semantics beyond PEP 484, so that +This syntax does not introduce any new semantics beyond :pep:`484`, so that the following three statements are equivalent:: var = value # type: annotation @@ -153,7 +153,7 @@ in different contexts and their runtime effects. We also suggest how type checkers might interpret annotations, but compliance to these suggestions is not mandatory. (This is in line -with the attitude towards compliance in PEP 484.) +with the attitude towards compliance in :pep:`484`.) Global and local variable annotations ************************************* @@ -407,7 +407,7 @@ Changes to Standard Library and Documentation - Recommended guidelines for using annotations will be added to the documentation, containing a pedagogical recapitulation of specifications - described in this PEP and in PEP 484. In addition, a helper script for + described in this PEP and in :pep:`484`. In addition, a helper script for translating type comments into type annotations will be published separately from the standard library. @@ -517,7 +517,7 @@ Rejected/Postponed Proposals - **Should we introduce variable annotations at all?** Variable annotations have *already* been around for almost two years - in the form of type comments, sanctioned by PEP 484. They are + in the form of type comments, sanctioned by :pep:`484`. They are extensively used by third party type checkers (mypy, pytype, PyCharm, etc.) and by projects using the type checkers. However, the comment syntax has many downsides listed in Rationale. This PEP is @@ -632,11 +632,11 @@ Rejected/Postponed Proposals - **Do not evaluate annotations, treat them as strings:** This would be inconsistent with the behavior of function annotations that are always evaluated. Although this might be reconsidered in future, - it was decided in PEP 484 that this would have to be a separate PEP. + it was decided in :pep:`484` that this would have to be a separate PEP. - **Annotate variable types in class docstring:** Many projects already use various docstring conventions, often without - much consistency and generally without conforming to the PEP 484 annotation + much consistency and generally without conforming to the :pep:`484` annotation syntax yet. Also this would require a special sophisticated parser. This, in turn, would defeat the purpose of the PEP -- collaborating with the third party type checking tools. diff --git a/pep-0527.txt b/pep-0527.txt index 53205c730ce..9eb4ffaa824 100644 --- a/pep-0527.txt +++ b/pep-0527.txt @@ -96,7 +96,7 @@ a library using Python 3.5, then ``bdist_dumb`` will produce a ``.tar.gz`` file named something like ``exampleproject-1.0.macosx-10.11-x86_64.tar.gz``. Right off the bat this file name is somewhat difficult to differentiate from an ``sdist`` since they both use the same file extension (and with the legacy pre -PEP 440 versions, ``1.0-macosx-10.11-x86_64`` is a valid, although quite silly, +:pep:`440` versions, ``1.0-macosx-10.11-x86_64`` is a valid, although quite silly, version number). However, once you open up the created ``.tar.gz``, you'd find that there is no metadata inside that could be used for things like dependency discovery and in fact, it is quite simply a tarball containing hardcoded paths diff --git a/pep-0530.txt b/pep-0530.txt index 34b62b3f2f7..8968e0ce2ee 100644 --- a/pep-0530.txt +++ b/pep-0530.txt @@ -15,7 +15,7 @@ Post-History: 03-Sep-2016 Abstract ======== -PEP 492 and PEP 525 introduce support for native coroutines and +:pep:`492` and :pep:`525` introduce support for native coroutines and asynchronous generators using ``async`` / ``await`` syntax. This PEP proposes to add asynchronous versions of list, set, dict comprehensions and generator expressions. @@ -55,7 +55,7 @@ Asynchronous Comprehensions --------------------------- We propose to allow using ``async for`` inside list, set and dict -comprehensions. Pending PEP 525 approval, we can also allow creation +comprehensions. Pending :pep:`525` approval, we can also allow creation of asynchronous generator expressions. Examples: @@ -131,7 +131,7 @@ The proposal is fully backwards compatible. Acceptance ========== -PEP 530 was accepted by Guido, September 6, 2016 [1]_. +:pep:`530` was accepted by Guido, September 6, 2016 [1]_. Implementation diff --git a/pep-0531.txt b/pep-0531.txt index c7eef2e1ae1..f7ed2d237d2 100644 --- a/pep-0531.txt +++ b/pep-0531.txt @@ -13,7 +13,7 @@ Post-History: 28-Oct-2016 Abstract ======== -Inspired by PEP 505 and the related discussions, this PEP proposes the addition +Inspired by :pep:`505` and the related discussions, this PEP proposes the addition of two new control flow operators to Python: * Existence-checking precondition ("exists-then"): ``expr1 ?then expr2`` @@ -97,14 +97,14 @@ make sense, and it is accordingly withdrawn. However, the discussion of the proposal did prompt consideration of a potential protocol based approach to make the existing ``and``, ``or`` and ``if-else`` operators more flexible [6_] without introducing any new syntax, so I'll be -writing that up as another possible alternative to PEP 505. +writing that up as another possible alternative to :pep:`505`. Relationship with other PEPs ============================ While this PEP was inspired by and builds on Mark Haase's excellent work in -putting together PEP 505, it ultimately competes with that PEP due to +putting together :pep:`505`, it ultimately competes with that PEP due to significant differences in the specifics of the proposed syntax and semantics for the feature. @@ -313,7 +313,7 @@ truth check". Taking that path would also have the advantage of aligning Python's syntax with corresponding syntax in other languages that offer similar features. -Drawing from the existing summary in PEP 505 and the Wikipedia articles on +Drawing from the existing summary in :pep:`505` and the Wikipedia articles on the "safe navigation operator [1]_ and the "null coalescing operator" [2]_, we see: @@ -608,7 +608,7 @@ sufficient to guide the creation of a reference implementation. Implementation ============== -As with PEP 505, actual implementation has been deferred pending in-principle +As with :pep:`505`, actual implementation has been deferred pending in-principle interest in the idea of adding these operators - the implementation isn't the hard part of these proposals, the hard part is deciding whether or not this is a change where the long term benefits for new and existing Python users diff --git a/pep-0532.txt b/pep-0532.txt index fa92016d38e..e086c5de18c 100644 --- a/pep-0532.txt +++ b/pep-0532.txt @@ -20,7 +20,7 @@ earliest. Abstract ======== -Inspired by PEP 335, PEP 505, PEP 531, and the related discussions, this PEP +Inspired by :pep:`335`, :pep:`505`, :pep:`531`, and the related discussions, this PEP proposes the definition of a new circuit breaking protocol (using the method names ``__then__`` and ``__else__``) that provides a common underlying semantic foundation for: @@ -28,8 +28,8 @@ semantic foundation for: * conditional expressions: ``LHS if COND else RHS`` * logical conjunction: ``LHS and RHS`` * logical disjunction: ``LHS or RHS`` -* the None-aware operators proposed in PEP 505 -* the rich comparison chaining model proposed in PEP 535 +* the None-aware operators proposed in :pep:`505` +* the rich comparison chaining model proposed in :pep:`535` Taking advantage of the new protocol, it further proposes that the definition of conditional expressions be revised to also permit the use of ``if`` and @@ -69,7 +69,7 @@ the key proposals are discussed below. PEP 531: Existence checking protocol ------------------------------------ -This PEP is a direct successor to PEP 531, replacing the existence checking +This PEP is a direct successor to :pep:`531`, replacing the existence checking protocol and the new ``?then`` and ``?else`` syntactic operators defined there with the new circuit breaking protocol and adjustments to conditional expressions and the ``not`` operator. @@ -78,7 +78,7 @@ expressions and the ``not`` operator. PEP 505: None-aware operators ----------------------------- -This PEP complements the None-aware operator proposals in PEP 505, by offering +This PEP complements the None-aware operator proposals in :pep:`505`, by offering an underlying protocol-driven semantic framework that explains their short-circuiting behaviour as highly optimised syntactic sugar for particular uses of conditional expressions. @@ -102,24 +102,24 @@ more general protocol-driven proposal in this PEP. PEP 335: Overloadable Boolean operators --------------------------------------- -PEP 335 proposed the ability to overload the short-circuiting ``and`` and +:pep:`335` proposed the ability to overload the short-circuiting ``and`` and ``or`` operators directly, with the ability to overload the semantics of comparison chaining being one of the consequences of that change. The proposal in an earlier version of this PEP to instead handle the element-wise comparison use case by changing the semantic definition of comparison chaining -is drawn directly from Guido's rejection of PEP 335 [1_]. +is drawn directly from Guido's rejection of :pep:`335` [1_]. However, initial feedback on this PEP indicated that the number of different proposals that it covered made it difficult to read, so that part of the -proposal has been separated out as PEP 535. +proposal has been separated out as :pep:`535`. PEP 535: Rich comparison chaining --------------------------------- -As noted above, PEP 535 is a proposal to build on the circuit breaking protocol +As noted above, :pep:`535` is a proposal to build on the circuit breaking protocol defined in this PEP in order to expand the rich comparison support introduced -in PEP 207 to also handle comparison chaining operations like +in :pep:`207` to also handle comparison chaining operations like ``LEFT_BOUND < VALUE < RIGHT_BOUND``. @@ -167,7 +167,7 @@ the semantics of conditional expressions. Rather, it comes from the proposed addition of ``if`` and ``else`` as general purpose protocol driven short-circuiting operators to complement the existing ``True`` and ``False`` based short-circuiting operators (``or`` and ``and``, respectively) as well -as the ``None`` based short-circuiting operator proposed in PEP 505 (``??``). +as the ``None`` based short-circuiting operator proposed in :pep:`505` (``??``). Together, these two operators would be known as the circuit breaking operators. @@ -192,7 +192,7 @@ expressions themselves do. This grammar definition means precedence/associativity in the otherwise ambiguous case of ``expr1 if cond else expr2 else expr3`` resolves as ``(expr1 if cond else expr2) else epxr3``. However, a guideline will also be -added to PEP 8 to say "don't do that", as such a construct will be inherently +added to :pep:`8` to say "don't do that", as such a construct will be inherently confusing for readers, regardless of how the interpreter executes it. The right-associative circuit breaking operator (``LHS if RHS``) would then @@ -397,7 +397,7 @@ breaking operator instead: None-aware operators -------------------- -If both this PEP and PEP 505's None-aware operators were accepted, then the +If both this PEP and :pep:`505`'s None-aware operators were accepted, then the proposed ``is_sentinel`` and ``is_not_sentinel`` circuit breaker factories would be used to encapsulate the notion of "None checking": seeing if a value is ``None`` and either falling back to an alternative value (an operation known @@ -438,7 +438,7 @@ behaviour of the operators at runtime. Rich chained comparisons ------------------------ -Refer to PEP 535 for a detailed discussion of this possible use case. +Refer to :pep:`535` for a detailed discussion of this possible use case. Other conditional constructs @@ -471,7 +471,7 @@ rather than assigning ``CONDITION`` to the given name directly. Style guide recommendations --------------------------- -The following additions to PEP 8 are proposed in relation to the new features +The following additions to :pep:`8` are proposed in relation to the new features introduced by this PEP: * Avoid combining conditional expressions (``if-else``) and the standalone @@ -490,7 +490,7 @@ Rationale Adding new operators -------------------- -Similar to PEP 335, early drafts of this PEP focused on making the existing +Similar to :pep:`335`, early drafts of this PEP focused on making the existing ``and`` and ``or`` operators less rigid in their interpretation, rather than proposing new operators. However, this proved to be problematic for a few key reasons: @@ -554,7 +554,7 @@ operators are combined with the explicit ``if-else`` conditional expression syntax. The PEP handles that ambiguity by explicitly specifying how it should be -handled by interpreter implementers, but proposing to point out in PEP 8 +handled by interpreter implementers, but proposing to point out in :pep:`8` that even though interpreters will understand it, human readers probably won't, and hence it won't be a good idea to use both conditional expressions and the circuit breaking operators in a single expression. @@ -660,12 +660,12 @@ raised when discussing PEPs 335, 505 and 531. One consequence of this approach is that this PEP *on its own* doesn't produce much in the way of direct benefits to end users aside from making it possible -to omit some common ``None if `` prefixes and `` else None`` suffixes from +to omit some common ``None if`` prefixes and ``else None`` suffixes from particular forms of conditional expression. Instead, what it mainly provides is a common foundation that would allow the -None-aware operator proposals in PEP 505 and the rich comparison chaining -proposal in PEP 535 to be pursued atop a common underlying semantic framework +None-aware operator proposals in :pep:`505` and the rich comparison chaining +proposal in :pep:`535` to be pursued atop a common underlying semantic framework that would also be shared with conditional expressions and the existing ``and`` and ``or`` operators. @@ -759,13 +759,13 @@ expression as follows:: >>> maybe_value = is_not_none(data.get("key")) >>> maybe_value if maybe_value else y -If `bool(maybe_value)`` is ``True``, then the expression short-circuits and +If ``bool(maybe_value)`` is ``True``, then the expression short-circuits and the interpreter calls ``type(maybe_value).__else__(maybe_value, maybe_value)``. The implementation of ``types.CircuitBreaker.__then__`` detects that the instance method has received itself as its argument and returns the wrapped value (i.e. ``data.get("key")``) rather than the circuit breaker. -If `bool(maybe_value)`` is ``True``, the interpreter calls +If ``bool(maybe_value)`` is ``True``, the interpreter calls ``type(maybe_value).__else__(maybe_value, y)``. The implementation of ``types.CircuitBreaker.__else__`` doesn't see anything that indicates short-circuiting has taken place, and hence returns ``y``. @@ -865,7 +865,7 @@ created explicitly via API calls, and are never produced implicitly. Implementation ============== -As with PEP 505, actual implementation has been deferred pending in-principle +As with :pep:`505`, actual implementation has been deferred pending in-principle interest in the idea of making these changes. ...TBD... diff --git a/pep-0533.txt b/pep-0533.txt index f7c6df031d5..1299a03d185 100644 --- a/pep-0533.txt +++ b/pep-0533.txt @@ -37,13 +37,13 @@ Background and motivation ========================= Python iterables often hold resources which require cleanup. For -example: ``file`` objects need to be closed; the `WSGI spec -`_ adds a ``close`` method +example: ``file`` objects need to be closed; the :pep:`WSGI spec +<333>` adds a ``close`` method on top of the regular iterator protocol and demands that consumers call it at the appropriate time (though forgetting to do so is a `frequent source of bugs `_); -and PEP 342 (based on PEP 325) extended generator objects to add a +and :pep:`342` (based on :pep:`325`) extended generator objects to add a ``close`` method to allow generators to clean up after themselves. Generally, objects that need to clean up after themselves also define @@ -59,12 +59,12 @@ several cases: file descriptor exhaustion, or WSGI timing middleware that collects bogus times. -- Async generators (PEP 525) can only perform cleanup under the +- Async generators (:pep:`525`) can only perform cleanup under the supervision of the appropriate coroutine runner. ``__del__`` doesn't have access to the coroutine runner; indeed, the coroutine runner might be garbage collected before the generator object. So relying on the garbage collector is effectively impossible without some kind - of language extension. (PEP 525 does provide such an extension, but + of language extension. (:pep:`525` does provide such an extension, but it has a number of limitations that this proposal fixes; see the "alternatives" section below for discussion.) @@ -180,14 +180,14 @@ Alternatives PEP 525 asyncgen hooks ---------------------- -PEP 525 `proposes a set of global thread-local hooks -`_ +:pep:`PEP 525 proposes a set of global thread-local hooks +<525#finalization>` managed by new ``sys.{get/set}_asyncgen_hooks()`` functions, which allow event loops to integrate with the garbage collector to run -cleanup for async generators. In principle, this proposal and PEP 525 +cleanup for async generators. In principle, this proposal and :pep:`525` are complementary, in the same way that ``with`` blocks and ``__del__`` are complementary: this proposal takes care of ensuring -deterministic cleanup in most cases, while PEP 525's GC hooks clean up +deterministic cleanup in most cases, while :pep:`525`'s GC hooks clean up anything that gets missed. But ``__aiterclose__`` provides a number of advantages over GC hooks alone: @@ -730,7 +730,7 @@ very soon), so the async changes do not produce any backwards incompatibilities. (There is existing code using async iterators, but using the new async for loop on an old async iterator is harmless, because old async iterators don't have ``__aiterclose__``.) In -addition, PEP 525 was accepted on a provisional basis, and async +addition, :pep:`525` was accepted on a provisional basis, and async generators are by far the biggest beneficiary of this PEP's proposed changes. Therefore, I think we should strongly consider enabling ``__aiterclose__`` for ``async for`` loops and async generators ASAP, diff --git a/pep-0535.txt b/pep-0535.txt index ccb028f043b..7d410a15188 100644 --- a/pep-0535.txt +++ b/pep-0535.txt @@ -20,8 +20,8 @@ earliest. Abstract ======== -Inspired by PEP 335, and building on the circuit breaking protocol described -in PEP 532, this PEP proposes a change to the definition of chained comparisons, +Inspired by :pep:`335`, and building on the circuit breaking protocol described +in :pep:`532`, this PEP proposes a change to the definition of chained comparisons, where the comparison chaining will be updated to use the left-associative circuit breaking operator (``else``) rather than the logical disjunction operator (``and``) if the left hand comparison returns a circuit breaker as @@ -37,13 +37,13 @@ or tautologically returning ``True`` (indicating a non-empty matrix). Relationship with other PEPs ============================ -This PEP has been extracted from earlier iterations of PEP 532, as a +This PEP has been extracted from earlier iterations of :pep:`532`, as a follow-on use case for the circuit breaking protocol, rather than an essential part of its introduction. The specific proposal in this PEP to handle the element-wise comparison use case by changing the semantic definition of comparison chaining is drawn -directly from Guido's rejection of PEP 335. +directly from Guido's rejection of :pep:`335`. Specification @@ -59,7 +59,7 @@ is currently roughly semantically equivalent to:: _lhs_result = LEFT_BOUND LEFT_OP _expr _expr_result = _lhs_result and (_expr RIGHT_OP RIGHT_BOUND) -Using the circuit breaking concepts introduced in PEP 532, this PEP proposes +Using the circuit breaking concepts introduced in :pep:`532`, this PEP proposes that comparison chaining be changed to explicitly check if the left comparison returns a circuit breaker, and if so, use ``else`` rather than ``and`` to implement the comparison chaining:: @@ -81,7 +81,7 @@ operations would be the same as the existing expansion for ``and``. Rationale ========= -In ultimately rejecting PEP 335, Guido van Rossum noted [1_]: +In ultimately rejecting :pep:`335`, Guido van Rossum noted [1_]: The NumPy folks brought up a somewhat separate issue: for them, the most common use case is chained comparisons (e.g. A < B < C). @@ -171,7 +171,7 @@ Implementation ============== Actual implementation has been deferred pending in-principle interest in the -idea of making the changes proposed in PEP 532. +idea of making the changes proposed in :pep:`532`. ...TBD... diff --git a/pep-0536.txt b/pep-0536.txt index db012665d79..f4a6ba3c690 100644 --- a/pep-0536.txt +++ b/pep-0536.txt @@ -13,13 +13,13 @@ Post-History: 12-Dec-2016 Abstract ======== -PEP 498 introduced Literal String Interpolation (or “f-strings”). +:pep:`498` introduced Literal String Interpolation (or “f-strings”). The expression portions of those literals however are subject to certain restrictions. This PEP proposes a formal grammar lifting those restrictions, promoting “f-strings” to “f expressions” or f-literals. -This PEP expands upon the f-strings introduced by PEP 498, -so this text requires familiarity with PEP 498. +This PEP expands upon the f-strings introduced by :pep:`498`, +so this text requires familiarity with :pep:`498`. PEP Status ========== @@ -81,7 +81,7 @@ Rationale The restrictions mentioned in Motivation_ are non-obvious and counter-intuitive unless the user is familiar with the f-literals’ implementation details. -As mentioned, a previous version of PEP 498 allowed escape sequences +As mentioned, a previous version of :pep:`498` allowed escape sequences anywhere in f-strings, including as ways to encode the braces delimiting the expression portions and in their code. They would be expanded before the code is parsed, which would have had several important ramifications: @@ -124,7 +124,7 @@ expressions instead of just variable names. [2]_ Specification ============= -PEP 498 specified f-strings as the following, but places restrictions on it:: +:pep:`498` specified f-strings as the following, but places restrictions on it:: f ' { } ... ' @@ -143,7 +143,7 @@ as explained below: syntactically valid. The first ``':'`` or ``'!'`` that is not part of an expression has to be followed a valid coercion or format specifier. -A remaining restriction not explicitly mentioned by PEP 498 is line breaks +A remaining restriction not explicitly mentioned by :pep:`498` is line breaks in expression portions. Since strings delimited by single ``'`` or ``"`` characters are expected to be single line, line breaks remain illegal in expression portions of single line strings. diff --git a/pep-0538.txt b/pep-0538.txt index 1fca7afc3ba..687bc4618d4 100644 --- a/pep-0538.txt +++ b/pep-0538.txt @@ -26,7 +26,7 @@ implies a default text encoding of ASCII, which is entirely inadequate for the development of networked services and client applications in a multilingual world. -PEP 540 proposes a change to CPython's handling of the legacy C locale such +:pep:`540` proposes a change to CPython's handling of the legacy C locale such that CPython will assume the use of UTF-8 in such environments, rather than persisting with the demonstrably problematic assumption of ASCII as an appropriate encoding for communicating with operating system interfaces. @@ -46,7 +46,7 @@ works, rather than relying primarily on existing configuration settings that are supported by Python versions prior to Python 3.7. Accordingly, this PEP proposes that independently of the UTF-8 mode proposed -in PEP 540, the way the CPython implementation handles the default C locale be +in :pep:`540`, the way the CPython implementation handles the default C locale be changed to be roughly equivalent to the following existing configuration settings (supported since Python 3.1):: @@ -70,7 +70,7 @@ With this change, any \*nix platform that does *not* offer at least one of the ``C.UTF-8``, ``C.utf8`` or ``UTF-8`` locales as part of its standard configuration would only be considered a fully supported platform for CPython 3.7+ deployments when a suitable locale other than the default ``C`` locale is -configured explicitly (e.g. ``en_AU.UTF-8``, ``zh_CN.gb18030``). If PEP 540 is +configured explicitly (e.g. ``en_AU.UTF-8``, ``zh_CN.gb18030``). If :pep:`540` is accepted in addition to this PEP, then pure Python modules would also be supported when using the proposed ``PYTHONUTF8`` mode, but expectations for full Unicode compatibility in extension modules would continue to be limited @@ -113,7 +113,7 @@ reported by ``sys.getfilesystemencoding()`` matches the encoding used during this early bootstrapping process. On Windows, the limitations of the ``mbcs`` format used by default in these -conversions proved sufficiently problematic that PEP 528 and PEP 529 were +conversions proved sufficiently problematic that :pep:`528` and :pep:`529` were implemented to bypass the operating system supplied interfaces for binary data handling and force the use of UTF-8 instead. @@ -149,7 +149,7 @@ following key calls to ``setlocale``: (This summary of the locale handling omits several technical details related to exactly where and when the text encoding declared as part of the locale -settings is used - see PEP 540 for further discussion, as these particular +settings is used - see :pep:`540` for further discussion, as these particular details matter more when decoupling CPython from the declared C locale than they do when overriding the locale with one based on UTF-8) @@ -197,11 +197,11 @@ more narrowly scoped ``LC_MESSAGES=C`` or ``LANGUAGE=en``. Relationship with other PEPs ============================ -This PEP shares a common problem statement with PEP 540 (improving Python 3's +This PEP shares a common problem statement with :pep:`540` (improving Python 3's behaviour in the default C locale), but diverges markedly in the proposed solution: -* PEP 540 proposes to entirely decouple CPython's default text encoding from +* :pep:`540` proposes to entirely decouple CPython's default text encoding from the C locale system in that case, allowing text handling inconsistencies to arise between CPython and other locale-aware components running in the same process and in subprocesses. This approach aims to make CPython behave less @@ -219,7 +219,7 @@ solution: in the wider C/C++ ecosystem After reviewing both PEPs, it became clear that they didn't actually conflict -at a technical level, and the proposal in PEP 540 offered a superior option in +at a technical level, and the proposal in :pep:`540` offered a superior option in cases where no suitable locale was available, as well as offering a better reference behaviour for platforms where the notion of a "locale encoding" doesn't make sense (for example, embedded systems running MicroPython rather @@ -229,13 +229,13 @@ Meanwhile, this PEP offered improved compatibility with other locale-aware components, and an approach more amenable to being backported to Python 3.6 by downstream redistributors. -As a result, this PEP was amended to refer to PEP 540 as a complementary +As a result, this PEP was amended to refer to :pep:`540` as a complementary solution that offered improved behaviour when none of the standard UTF-8 based locales were available, as well as extending the changes in the default settings to APIs that aren't currently independently configurable (such as the default encoding and error handler for ``open()``). -The availability of PEP 540 also meant that the ``LC_CTYPE=en_US.UTF-8`` legacy +The availability of :pep:`540` also meant that the ``LC_CTYPE=en_US.UTF-8`` legacy fallback was removed from the list of UTF-8 locales tried as a coercion target, with the expectation being that CPython will instead rely solely on the proposed PYTHONUTF8 mode in such cases. @@ -331,7 +331,7 @@ universally available for use by glibc based applications like CPython [6_], this unfortunately doesn't help on platforms that ship older versions of glibc without that feature, and also don't provide C.UTF-8 (or an equivalent) as an on-disk locale the way Debian and Fedora do. These platforms are considered -out of scope for this PEP - see PEP 540 for further discussion of possible +out of scope for this PEP - see :pep:`540` for further discussion of possible options for improving CPython's default behaviour in such environments. @@ -592,7 +592,7 @@ Android-specific details: Platform Support Changes ======================== -A new "Legacy C Locale" section will be added to PEP 11 that states: +A new "Legacy C Locale" section will be added to :pep:`11` that states: * as of CPython 3.7, \*nix platforms are expected to provide at least one of ``C.UTF-8`` (full locale), ``C.utf8`` (full locale) or ``UTF-8`` ( @@ -650,7 +650,7 @@ By coercing the locale away from the legacy C default and its assumption of ASCII as the preferred text encoding, this PEP also disables the implicit use of the "surrogateescape" error handler on the standard IO streams that was introduced in Python 3.5 ([15_]), as well as the automatic use of -``surrogateescape`` when operating in PEP 540's proposed UTF-8 mode. +``surrogateescape`` when operating in :pep:`540`'s proposed UTF-8 mode. Rather than introducing yet another configuration option to adjust that behaviour, this PEP instead proposes to extend the "surrogateescape" default @@ -794,7 +794,7 @@ legacy C locale for over a decade at this point. Not only haven't we been able to get it to work, neither has anyone else - the only viable alternatives identified have been to pass the bytes along verbatim without eagerly decoding them to text (C/C++, Python 2.x, Ruby, etc), or else to largely ignore the -nominal C/C++ locale encoding and assume the use of either UTF-8 (PEP 540, +nominal C/C++ locale encoding and assume the use of either UTF-8 (:pep:`540`, Rust, Go, Node.js, etc) or UTF-16-LE (JVM, .NET CLR). While this PEP ensures that developers that genuinely need to do so can still @@ -803,7 +803,7 @@ opt-in to running their Python code in the legacy C locale (by setting ``--without-c-locale-coercion``), it also makes it clear that we *don't* expect Python 3's Unicode handling to be completely reliable in that configuration, and the recommended alternative is to use a more appropriate -locale setting (potentially in combination with PEP 540's UTF-8 mode, if that +locale setting (potentially in combination with :pep:`540`'s UTF-8 mode, if that is available). @@ -954,15 +954,15 @@ coercion notice in that case, coercion is instead skipped entirely. Considering locale coercion independently of "UTF-8 mode" --------------------------------------------------------- -With both this PEP's locale coercion and PEP 540's UTF-8 mode under +With both this PEP's locale coercion and :pep:`540`'s UTF-8 mode under consideration for Python 3.7, it makes sense to ask whether or not we can limit ourselves to only doing one or the other, rather than making both changes. -The UTF-8 mode proposed in PEP 540 has two major limitations that make it a +The UTF-8 mode proposed in :pep:`540` has two major limitations that make it a potential complement to this PEP rather than a potential replacement. -First, unlike this PEP, PEP 540's UTF-8 mode makes it possible to change default +First, unlike this PEP, :pep:`540`'s UTF-8 mode makes it possible to change default behaviours that are not currently configurable at all. While that's exactly what makes the proposal interesting, it's also what makes it an entirely unproven approach. By contrast, the approach proposed in this PEP builds @@ -975,7 +975,7 @@ Secondly, one of the things we know based on that experience is that the proposed locale coercion can resolve problems not only in CPython itself, but also in extension modules that interact with the standard streams, like GNU readline. As an example, consider the following interactive session -from a PEP 538 enabled CPython build, where each line after the first is +from a :pep:`538` enabled CPython build, where each line after the first is executed by doing "up-arrow, left-arrow x4, delete, enter":: $ LANG=C ./python @@ -1018,7 +1018,7 @@ locale settings:: That particular misbehaviour is coming from GNU readline, *not* CPython - because the command history editing wasn't UTF-8 aware, it corrupted the history buffer and fed such nonsense to stdin that even the surrogateescape error -handler was bypassed. While PEP 540's UTF-8 mode could technically be updated +handler was bypassed. While :pep:`540`'s UTF-8 mode could technically be updated to also reconfigure readline, that's just *one* extension module that might be interacting with the standard streams without going through the CPython C API, and any change made by CPython would only apply when readline is running @@ -1165,7 +1165,7 @@ practical viability of the proposed changes. The initial draft was posted to the Python Linux SIG for discussion [10_] and then amended based on both that discussion and Victor Stinner's work in -PEP 540 [11_]. +:pep:`540` [11_]. The "ℙƴ☂ℌøἤ" string used in the Unicode handling examples throughout this PEP is taken from Ned Batchelder's excellent "Pragmatic Unicode" presentation [9_]. diff --git a/pep-0539.txt b/pep-0539.txt index ad0b821e6ba..2aa74fc8a96 100644 --- a/pep-0539.txt +++ b/pep-0539.txt @@ -207,7 +207,7 @@ When ``Py_LIMITED_API`` is defined, a TSS key must be dynamically allocated:: Platform Support Changes ======================== -A new "Native Thread Implementation" section will be added to PEP 11 that +A new "Native Thread Implementation" section will be added to :pep:`11` that states: * As of CPython 3.7, all platforms are required to provide a native thread @@ -252,7 +252,7 @@ with Python's API because their ``pthread_key_t`` is defined in a way that cannot be safely cast to ``int``. In fact, the possibility of running into this problem was raised by MvL at the time pthreads TLS was added [2]_. -It could be argued that PEP-11 makes specific requirements for supporting a +It could be argued that :pep:`11` makes specific requirements for supporting a new, not otherwise officially-support platform (such as CloudABI), and that the status of Cygwin support is currently dubious. However, this creates a very high barrier to supporting platforms that are otherwise Linux- and/or @@ -316,7 +316,7 @@ Rejected Ideas * Do nothing: The status quo is fine because it works on Linux, and platforms wishing to be supported by CPython should follow the requirements of - PEP-11. As explained above, while this would be a fair argument if + :pep:`11`. As explained above, while this would be a fair argument if CPython were being to asked to make changes to support particular quirks or features of a specific platform, in this case it is a quirk of CPython that prevents it from being used to its full potential on otherwise @@ -382,8 +382,7 @@ References and Footnotes .. [10] https://github.com/python/cpython/compare/master...ma8ma:pep539-tss-api .. [11] https://github.com/python/cpython/pull/1362 .. [12] https://docs.python.org/3/c-api/init.html#c.Py_FinalizeEx -.. [13] It is also called as "stable ABI" - (https://www.python.org/dev/peps/pep-0384/) +.. [13] It is also called as "stable ABI" (:pep:`384`) .. [14] http://pubs.opengroup.org/onlinepubs/009695399/functions/pthread_key_create.html .. [15] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf#page=404 .. [16] https://bugs.python.org/issue31370 diff --git a/pep-0540.txt b/pep-0540.txt index 296852530ad..fd6f492048e 100644 --- a/pep-0540.txt +++ b/pep-0540.txt @@ -274,13 +274,13 @@ Links * `bpo-29240: Implementation of the PEP 540: Add a new UTF-8 Mode `_ -* `PEP 538 `_: +* :pep:`538`: "Coercing the legacy C locale to C.UTF-8" -* `PEP 529 `_: +* :pep:`529`: "Change Windows filesystem encoding to UTF-8" -* `PEP 528 `_: +* :pep:`528`: "Change Windows console encoding to UTF-8" -* `PEP 383 `_: +* :pep:`383`: "Non-decodable Bytes in System Character Interfaces" diff --git a/pep-0544.txt b/pep-0544.txt index 80830b72f4e..f547e2e46ac 100644 --- a/pep-0544.txt +++ b/pep-0544.txt @@ -16,8 +16,8 @@ Resolution: https://mail.python.org/archives/list/typing-sig@python.org/message/ Abstract ======== -Type hints introduced in PEP 484 can be used to specify type metadata -for static type checkers and other third party tools. However, PEP 484 +Type hints introduced in :pep:`484` can be used to specify type metadata +for static type checkers and other third party tools. However, :pep:`484` only specifies the semantics of *nominal* subtyping. In this PEP we specify static and runtime semantics of protocol classes that will provide a support for *structural* subtyping (static duck typing). @@ -28,12 +28,12 @@ for *structural* subtyping (static duck typing). Rationale and Goals =================== -Currently, PEP 484 and the ``typing`` module [typing]_ define abstract +Currently, :pep:`484` and the ``typing`` module [typing]_ define abstract base classes for several common Python protocols such as ``Iterable`` and ``Sized``. The problem with them is that a class has to be explicitly marked to support them, which is unpythonic and unlike what one would normally do in idiomatic dynamically typed Python code. For example, -this conforms to PEP 484:: +this conforms to :pep:`484`:: from typing import Sized, Iterable, Iterator @@ -80,9 +80,9 @@ Nominal vs structural subtyping Structural subtyping is natural for Python programmers since it matches the runtime semantics of duck typing: an object that has certain properties is treated independently of its actual runtime class. -However, as discussed in PEP 483, both nominal and structural +However, as discussed in :pep:`483`, both nominal and structural subtyping have their strengths and weaknesses. Therefore, in this PEP we -*do not propose* to replace the nominal subtyping described by PEP 484 with +*do not propose* to replace the nominal subtyping described by :pep:`484` with structural subtyping completely. Instead, protocol classes as specified in this PEP complement normal classes, and users are free to choose where to apply a particular solution. See section on `rejected`_ ideas at the @@ -95,7 +95,7 @@ Non-goals At runtime, protocol classes will be simple ABCs. There is no intent to provide sophisticated runtime instance and class checks against protocol classes. This would be difficult and error-prone and will contradict the logic -of PEP 484. As well, following PEP 484 and PEP 526 we state that protocols are +of :pep:`484`. As well, following :pep:`484` and :pep:`526` we state that protocols are **completely optional**: * No runtime semantics will be imposed for variables or parameters annotated @@ -330,7 +330,7 @@ Protocol members All methods defined in the protocol class body are protocol members, both normal and decorated with ``@abstractmethod``. If any parameters of a protocol method are not annotated, then their types are assumed to be ``Any`` -(see PEP 484). Bodies of protocol methods are type checked. +(see :pep:`484`). Bodies of protocol methods are type checked. An abstract method that should not be called via ``super()`` ought to raise ``NotImplementedError``. Example:: @@ -348,7 +348,7 @@ An abstract method that should not be called via ``super()`` ought to raise Static methods, class methods, and properties are equally allowed in protocols. -To define a protocol variable, one can use PEP 526 variable +To define a protocol variable, one can use :pep:`526` variable annotations in the class body. Additional attributes *only* defined in the body of a method by assignment via ``self`` are not allowed. The rationale for this is that the protocol class implementation is often not shared by @@ -376,7 +376,7 @@ Examples:: To distinguish between protocol class variables and protocol instance variables, the special ``ClassVar`` annotation should be used as specified -by PEP 526. By default, protocol variables as defined above are considered +by :pep:`526`. By default, protocol variables as defined above are considered readable and writable. To define a read-only protocol variable, one can use an (abstract) property. @@ -563,7 +563,7 @@ Recursive protocols ------------------- Recursive protocols are also supported. Forward references to the protocol -class names can be given as strings as specified by PEP 484. Recursive +class names can be given as strings as specified by :pep:`484`. Recursive protocols are useful for representing self-referential data structures like trees in an abstract fashion:: @@ -594,8 +594,9 @@ Continuing the previous example:: Self-types in protocols ----------------------- -The self-types in protocols follow the corresponding specification -[self-types]_ of PEP 484. For example:: +The self-types in protocols follow the +:pep:`corresponding specification <484#annotating-instance-and-class-methods>` +of :pep:`484`. For example:: C = TypeVar('C', bound='Copyable') class Copyable(Protocol): @@ -620,7 +621,7 @@ Callback protocols Protocols can be used to define flexible callback types that are hard (or even impossible) to express using the ``Callable[...]`` syntax -specified by PEP 484, such as variadic, overloaded, and complex generic +specified by :pep:`484`, such as variadic, overloaded, and complex generic callbacks. They can be defined as protocols with a ``__call__`` member:: from typing import Optional, List, Protocol @@ -729,7 +730,7 @@ Example:: cached_func((1, 2, 3)) # OK, tuple is both hashable and iterable If this will prove to be a widely used scenario, then a special -intersection type construct could be added in future as specified by PEP 483, +intersection type construct could be added in future as specified by :pep:`483`, see `rejected`_ ideas for more details. @@ -943,7 +944,7 @@ Properties can be settable and/or abstract if needed:: def d(self) -> int: # ... or it can be abstract return 0 -Also function type comments can be used as per PEP 484 (for example +Also function type comments can be used as per :pep:`484` (for example to provide compatibility with Python 2). The ``typing`` module changes proposed in this PEP will also be backported to earlier versions via the backport currently available on PyPI. @@ -1116,7 +1117,7 @@ variables. However, using getters and setters in cases where only a simple variable is needed would be quite unpythonic. Moreover, the widespread use of properties (that often act as type validators) in large code bases is partially due to previous absence of static type checkers for Python, -the problem that PEP 484 and this PEP are aiming to solve. For example:: +the problem that :pep:`484` and this PEP are aiming to solve. For example:: # without static types @@ -1178,7 +1179,7 @@ complicate both the concept and the implementation. On the other hand, Zope interfaces are conceptually a superset of protocols defined here, but using an incompatible syntax to define them, -because before PEP 526 there was no straightforward way to annotate attributes. +because before :pep:`526` there was no straightforward way to annotate attributes. In the 3.6+ world, ``zope.interface`` might potentially adopt the ``Protocol`` syntax. In this case, type checkers could be taught to recognize interfaces as protocols and make simple structural checks with respect to them. @@ -1332,7 +1333,7 @@ Overriding inferred variance of protocol classes ------------------------------------------------ It was proposed to allow declaring protocols as invariant if they are actually -covariant or contravariant (as it is possible for nominal classes, see PEP 484). +covariant or contravariant (as it is possible for nominal classes, see :pep:`484`). However, it was decided not to do this because of several downsides: * Declared protocol invariance breaks transitivity of sub-typing. Consider @@ -1375,9 +1376,9 @@ However, it was decided not to do this because of several downsides: Support adapters and adaptation ------------------------------- -Adaptation was proposed by PEP 246 (rejected) and is supported by +Adaptation was proposed by :pep:`246` (rejected) and is supported by ``zope.interface``, see https://docs.zope.org/zope.interface/adapter.html. -Adapters is quite an advanced concept, and PEP 484 supports unions and +Adapters is quite an advanced concept, and :pep:`484` supports unions and generic aliases that can be used instead of adapters. This can be illustrated with an example of ``Iterable`` protocol, there is another way of supporting iteration by providing ``__getitem__`` and ``__len__``. If a function @@ -1490,9 +1491,6 @@ References .. [elsewhere] https://github.com/python/peps/pull/224 -.. [self-types] - https://www.python.org/dev/peps/pep-0484/#annotating-instance-and-class-methods - Copyright ========= diff --git a/pep-0545.txt b/pep-0545.txt index ea2b1ed8c12..b4c7c971f17 100644 --- a/pep-0545.txt +++ b/pep-0545.txt @@ -40,14 +40,14 @@ meet people who don't speak English and so are unable to read the Python official documentation. Python wants to be widely available to all users in any language: this is also why Python 3 supports any non-ASCII identifiers: -https://www.python.org/dev/peps/pep-3131/#rationale +:pep:`3131#rationale` There are at least 4 groups of people who are translating the Python documentation to their native language (French [16]_ [17]_ [18]_, -Japanese [19]_ [20]_, Spanish [21]_, Hungarian [27]_ [28]_) even +Japanese [19]_ [20]_, Spanish [21]_, Hungarian [26]_ [27]_) even though their translations are not visible on d.p.o. Other, less visible and less organized groups, are also translating the -documentation, we've heard of Russian [26]_, Chinese and +documentation, we've heard of Russian [25]_, Chinese and Korean. Others we haven't found yet might also exist. This PEP defines rules describing how to move translations on docs.python.org so they can easily be found by developers, newcomers and potential @@ -140,7 +140,7 @@ possible but confusing ("is it `es.docs.python.org` or `docs.es.python.org`?"). Hyphens in subdomains like `pt-br.doc.python.org` is uncommon and SEOMoz [23]_ correlated the presence of hyphens as a negative factor. Usage of underscores in -subdomain is prohibited by the RFC1123 [24]_, section 2.1. Finally, +subdomain is prohibited by the :rfc:`1123`, section 2.1. Finally, using subdomains means creating TLS certificates for each language. This not only requires more maintenance but will also cause issues in language switcher if, as for version switcher, we want a @@ -153,7 +153,7 @@ request and ``Vary: Accept-Language``) leads to a bad user experience where they can't easily change the language. According to Mozilla: "This header is a hint to be used when the server has no way of determining the language via another way, like a specific URL, that is -controlled by an explicit user decision." [25]_. As we want to be +controlled by an explicit user decision." [24]_. As we want to be able to easily change the language, we should not use the content negotiation as a main language determination, so we need something else. @@ -188,7 +188,7 @@ The current documentation is not moved to "/en/", instead Language Tag '''''''''''' -A common notation for language tags is the IETF Language Tag [3]_ +A common notation for language tags is the :rfc:`IETF Language Tag <5646>` [4]_ based on ISO 639, although gettext uses ISO 639 tags with underscores (ex: ``pt_BR``) instead of dashes to join tags [5]_ (ex: ``pt-BR``). Examples of IETF Language Tags: ``fr`` (French), @@ -202,7 +202,8 @@ internally: URLs are not meant to leak the underlying implementation. It's uncommon to see capitalized letters in URLs, and docs.python.org doesn't use any, so it may hurt readability by attracting the eye on it, like in: "https://docs.python.org/pt-BR/3.6/library/stdtypes.html". -RFC 5646 (Tags for Identifying Languages (IETF)) section-2.1 [7]_ +:rfc:`5646#section-2.1.1` +(Tags for Identifying Languages (IETF)) section-2.1 states that tags are not case sensitive. As the RFC allows lower case, and it enhances readability, we should use lowercased tags like ``pt-br``. @@ -416,7 +417,7 @@ Setup a GitHub bot for Documentation Contribution Agreement To help ensuring contributors from GitHub have signed the Documentation Contribution Agreement, We can setup the "The Knights Who Say Ni" GitHub bot customized for this agreement on the migrated -repositories [29]_. +repositories [28]_. Patch docsbuild-scripts to Compile Translations @@ -572,9 +573,6 @@ References .. [2] [Doc-SIG] Localization of Python docs (https://mail.python.org/pipermail/doc-sig/2013-September/003948.html) -.. [3] Tags for Identifying Languages - (http://tools.ietf.org/html/rfc5646) - .. [4] IETF language tag (https://en.wikipedia.org/wiki/IETF_language_tag) @@ -584,9 +582,6 @@ References .. [6] Semantic URL: Slug (https://en.wikipedia.org/wiki/Semantic_URL#Slug) -.. [7] Tags for Identifying Languages: Formatting of Language Tags - (https://tools.ietf.org/html/rfc5646#section-2.1.1) - .. [8] Docsbuild-scripts GitHub repository (https://github.com/python/docsbuild-scripts/) @@ -635,22 +630,19 @@ References .. [23] Domains - SEO Best Practices | Moz (https://moz.com/learn/seo/domain) -.. [24] Requirements for Internet Hosts -- Application and Support - (https://www.ietf.org/rfc/rfc1123.txt) - -.. [25] Accept-Language +.. [24] Accept-Language (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) -.. [26] Документация Python 2.7! +.. [25] Документация Python 2.7! (http://python-lab.ru/documentation/index.html) -.. [27] Python-oktató +.. [26] Python-oktató (http://harp.pythonanywhere.com/python_doc/tutorial/index.html) -.. [28] The Python-hu Archives +.. [27] The Python-hu Archives (https://mail.python.org/pipermail/python-hu/) -.. [29] [Python-Dev] PEP 545: Python Documentation Translations +.. [28] [Python-Dev] PEP 545: Python Documentation Translations (https://mail.python.org/pipermail/python-dev/2017-April/147752.html) diff --git a/pep-0546.txt b/pep-0546.txt index c25654f70ca..867d4f175da 100644 --- a/pep-0546.txt +++ b/pep-0546.txt @@ -109,7 +109,7 @@ bundling PyOpenSSL. Only backporting ``ssl.MemoryBIO`` and ``ssl.SSLObject`` would avoid the need to embed pyOpenSSL, and would fix the bootstrap issue (python -> ensurepip -> pip -> requests -> MemoryBIO). -This situation is less problematic than the barrier to adoption of PEP 543, as +This situation is less problematic than the barrier to adoption of :pep:`543`, as naturally Requests does not have to move to an event loop model before it drops support for Python 2.7. However, it does make it painful for Requests (and pip) to embrace both asyncio and the ``async`` and ``await`` keywords for as long as diff --git a/pep-0547.rst b/pep-0547.rst index 4dff27c266a..51d524a1f36 100644 --- a/pep-0547.rst +++ b/pep-0547.rst @@ -28,7 +28,7 @@ Abstract This PEP proposes implementation that allows built-in and extension modules to be executed in the ``__main__`` namespace using -the PEP 489 multi-phase initialization. +the :pep:`489` multi-phase initialization. With this, a multi-phase initialization enabled module can be run using following command:: @@ -45,7 +45,7 @@ Python source modules. Specifically, it is not possible to run extension modules as scripts using Python's ``-m`` option. -The technical groundwork to make this possible has been done for PEP 489, +The technical groundwork to make this possible has been done for :pep:`489`, and enabling the ``-m`` option is listed in that PEP's “Possible Future Extensions” section. Technically, the additional changes proposed here are relatively small. @@ -91,7 +91,7 @@ This is not the case for extension modules, whose ``PyInit_*`` entry point traditionally both created a new module object (using ``PyModule_Create``), and initialized it. -Since Python 3.5, extension modules can use PEP 489 multi-phase initialization. +Since Python 3.5, extension modules can use :pep:`489` multi-phase initialization. In this scenario, the ``PyInit_*`` entry point returns a ``PyModuleDef`` structure: a description of how the module should be created and initialized. The extension can choose to customize creation of the module object using @@ -128,7 +128,7 @@ its ``md_state`` is normally ``NULL``. Before initializing an extension module in ``__main__``'s context, its module state will be allocated according to the ``PyModuleDef`` of that module. -While PEP 489 was designed to make these changes generally possible, +While :pep:`489` was designed to make these changes generally possible, it's necessary to decouple module discovery, creation, and initialization steps for extension modules, so that another module can be used instead of a newly initialized one, and the functionality needs to be added to @@ -161,7 +161,7 @@ importlib's ``ExtensionFileLoader`` will get an implementation of extension module's ``PyInit_*`` function. The ``PyInit_*`` function can return either a fully initialized module -(single-phase initialization) or a ``PyModuleDef`` (for PEP 489 multi-phase +(single-phase initialization) or a ``PyModuleDef`` (for :pep:`489` multi-phase initialization). In the single-phase initialization case, ``_imp.exec_in_module`` will raise @@ -196,7 +196,6 @@ References .. _GitHub: https://github.com/python/cpython/pull/1761 .. _Cython issue 1715: https://github.com/cython/cython/issues/1715 -.. _Possible Future Extensions section: https://www.python.org/dev/peps/pep-0489/#possible-future-extensions .. _Cython issue 1923: https://github.com/cython/cython/pull/1923 diff --git a/pep-0550.rst b/pep-0550.rst index 4cb7bba1ddf..558f5578b31 100644 --- a/pep-0550.rst +++ b/pep-0550.rst @@ -1309,7 +1309,7 @@ execution state:: def __exit__(self, *err): self.var.set(self.old_x) -An equivalent implementation with PEP 521:: +An equivalent implementation with :pep:`521`:: local = threading.local() @@ -1715,8 +1715,6 @@ References .. [11] https://github.com/1st1/cpython/tree/pep550 -.. [12] https://www.python.org/dev/peps/pep-0492/#async-await - .. [13] https://github.com/MagicStack/uvloop/blob/master/examples/bench/echoserver.py .. [14] https://github.com/MagicStack/pgbench diff --git a/pep-0551.rst b/pep-0551.rst index 3ac8d5bf066..616eec36327 100644 --- a/pep-0551.rst +++ b/pep-0551.rst @@ -20,7 +20,7 @@ Relationship to PEP 578 This PEP has been split into two since its original posting. -See `PEP 578 `_ for the +See :pep:`578` for the auditing APIs proposed for addition to the next version of Python. This is now an informational PEP, providing guidance to those planning @@ -34,7 +34,7 @@ applies to the Python runtime. Visibility into actions taken by the runtime is invaluable in integrating Python into an otherwise secure and/or monitored environment. -The audit hooks described in PEP-578 are an essential component in +The audit hooks described in :pep:`578` are an essential component in detecting, identifying and analyzing misuse of Python. While the hooks themselves are neutral (in that not every reported event is inherently misuse), they provide essential context to those who are responsible @@ -140,14 +140,14 @@ tools, most network access and DNS resolution, and attempts to create and hide files or configuration settings on the local machine. To summarize, defenders have a need to audit specific uses of Python in -order to detect abnormal or malicious usage. With PEP 578, the Python +order to detect abnormal or malicious usage. With :pep:`578`, the Python runtime gains the ability to provide this. The aim of this PEP is to assist system administrators with deploying a security transparent version of Python that can integrate with their existing auditing and protection systems. On Windows, some specific features that may be integrated through the -hooks added by PEP 578 include: +hooks added by :pep:`578` include: * Script Block Logging [3]_ * DeviceGuard [4]_ diff --git a/pep-0553.rst b/pep-0553.rst index 1ca7eefe97d..ec93a2ab62f 100644 --- a/pep-0553.rst +++ b/pep-0553.rst @@ -217,7 +217,7 @@ existing keyword such as ``break here``. This is rejected on several fronts. * An extended keyword such as ``break here``, while more readable and not requiring a ``__future__`` would tie the keyword extension to this new feature, preventing more useful extensions such as those proposed in - PEP 548. + :pep:`548`. * A new keyword would require a modified grammar and likely a new bytecode. Each of these makes the implementation more complex. A new built-in breaks diff --git a/pep-0554.rst b/pep-0554.rst index 8e7b4c66f09..5c2af7a0991 100644 --- a/pep-0554.rst +++ b/pep-0554.rst @@ -69,7 +69,7 @@ At first only the following types will be supported for sharing: * bytes * str * int -* PEP 554 channels +* :pep:`554` channels Support for other basic types (e.g. bool, float, Ellipsis) will be added later. @@ -196,7 +196,7 @@ following: * be clear that extension modules are *not* required to support use in subinterpreters -* raise ``ImportError`` when an incompatible (no PEP 489 support) module +* raise ``ImportError`` when an incompatible (no :pep:`489` support) module is imported in a subinterpreter * provide resources (e.g. docs) to help maintainers reach compatibility * reach out to the maintainers of Cython and of the most used extension @@ -491,9 +491,9 @@ will appeal to some Python users. That is the core value that the In the `Interpreter Isolation`_ section below we identify ways in which isolation in CPython's subinterpreters is incomplete. Most notable is extension modules that use C globals to store internal -state. PEP 3121 and PEP 489 provide a solution for most of the +state. :pep:`3121` and :pep:`489` provide a solution for most of the problem, but one still remains. [petr-c-ext]_ Until that is resolved -(see PEP 573), C extension authors will face extra difficulty +(see :pep:`573`), C extension authors will face extra difficulty to support subinterpreters. Consequently, projects that publish extension modules may face an @@ -684,7 +684,7 @@ Provisional Status ================== The new ``interpreters`` module will be added with "provisional" status -(see PEP 411). This allows Python users to experiment with the feature +(see :pep:`411`). This allows Python users to experiment with the feature and provide feedback while still allowing us to adjust to that feedback. The module will be provisional in Python 3.9 and we will make a decision before the 3.10 release whether to keep it provisional, graduate it, or @@ -878,7 +878,7 @@ with unbuffered semantics). Python objects are not shared between interpreters. However, in some cases data those objects wrap is actually shared and not just copied. -One example might be PEP 3118 buffers. In those cases the object in the +One example might be :pep:`3118` buffers. In those cases the object in the original interpreter is kept alive until the shared data in the other interpreter is no longer used. Then object destruction can happen like normal in the original interpreter, along with the previously shared @@ -972,7 +972,7 @@ has specific restrictions on any code it runs. This includes the following: * importing an extension module fails if it does not implement the - PEP 489 API + :pep:`489` API * new threads of any kind are not allowed * ``os.fork()`` is not allowed (so no ``multiprocessing``) * ``os.exec*()``, AKA "fork+exec", is not allowed (so no ``subprocess``) @@ -984,7 +984,7 @@ keyword-only argument set to ``True`` (the default). If restrictions is applied. One advantage of this approach is that it allows extension maintainers -to check subinterpreter compatibility before they implement the PEP 489 +to check subinterpreter compatibility before they implement the :pep:`489` API. Also note that ``isolated=False`` represents the historical behavior when using the existing subinterpreters C-API, thus providing backward compatibility. For the existing C-API itself, the default @@ -993,7 +993,7 @@ existing use of Python will not change. We may choose to later loosen some of the above restrictions or provide a way to enable/disable granular restrictions individually. Regardless, -requiring PEP 489 support from extension modules will always be a +requiring :pep:`489` support from extension modules will always be a default restriction. @@ -1020,10 +1020,10 @@ will include the following information: * a summary about subinterpreters (similar to the same in the new ``interpreters`` module page and in the C-API docs) * an explanation of how extension modules can be impacted -* how to implement PEP 489 support +* how to implement :pep:`489` support * how to move from global module state to per-interpreter -* how to take advantage of PEP 384 (heap types), PEP 3121 - (module state), and PEP 573 +* how to take advantage of :pep:`384` (heap types), :pep:`3121` + (module state), and :pep:`573` * strategies for dealing with 3rd party C libraries that keep their own subinterpreter-incompatible global state @@ -1114,7 +1114,7 @@ request. However, it is outside the narrow scope of this PEP. C-extension opt-in/opt-out -------------------------- -By using the ``PyModuleDef_Slot`` introduced by PEP 489, we could easily +By using the ``PyModuleDef_Slot`` introduced by :pep:`489`, we could easily add a mechanism by which C-extension modules could opt out of support for subinterpreters. Then the import machinery, when operating in a subinterpreter, would need to check the module for support. It would @@ -1122,7 +1122,7 @@ raise an ImportError if unsupported. Alternately we could support opting in to subinterpreter support. However, that would probably exclude many more modules (unnecessarily) -than the opt-out approach. Also, note that PEP 489 defined that an +than the opt-out approach. Also, note that :pep:`489` defined that an extension's use of the PEP's machinery implies support for subinterpreters. @@ -1412,7 +1412,7 @@ Add SendChannel.send_buffer() ----------------------------- This method would allow no-copy sending of an object through a channel -if it supports the PEP 3118 buffer protocol (e.g. memoryview). +if it supports the :pep:`3118` buffer protocol (e.g. memoryview). Support for this is not fundamental to channels and can be added on later without much disruption. @@ -1629,7 +1629,7 @@ you go: * all necessary C-API work has been finished * all anticipated work in the runtime has been finished -The implementation effort for PEP 554 is being tracked as part of +The implementation effort for :pep:`554` is being tracked as part of a larger project aimed at improving multi-core support in CPython. [multi-core-project]_ diff --git a/pep-0557.rst b/pep-0557.rst index 9520272d87c..d30d302efd1 100644 --- a/pep-0557.rst +++ b/pep-0557.rst @@ -28,7 +28,7 @@ inheritance, metaclasses, docstrings, user-defined methods, class factories, and other Python class features. A class decorator is provided which inspects a class definition for -variables with type annotations as defined in PEP 526, "Syntax for +variables with type annotations as defined in :pep:`526`, "Syntax for Variable Annotations". In this document, such variables are called fields. Using these fields, the decorator adds generated method definitions to the class to support instance initialization, a repr, @@ -108,7 +108,7 @@ Some examples include: So, why is this PEP needed? -With the addition of PEP 526, Python has a concise way to specify the +With the addition of :pep:`526`, Python has a concise way to specify the type of class members. This PEP leverages that syntax to provide a simple, unobtrusive way to describe Data Classes. With two exceptions, the specified attribute type annotation is completely ignored by Data @@ -121,7 +121,7 @@ interference from Data Classes. The decorated classes are truly interfere with any usage of the class. One main design goal of Data Classes is to support static type -checkers. The use of PEP 526 syntax is one example of this, but so is +checkers. The use of :pep:`526` syntax is one example of this, but so is the design of the ``fields()`` function and the ``@dataclass`` decorator. Due to their very dynamic nature, some of the libraries mentioned above are difficult to use with static type checkers. @@ -400,7 +400,7 @@ Class variables --------------- One place where ``dataclass`` actually inspects the type of a field is -to determine if a field is a class variable as defined in PEP 526. It +to determine if a field is a class variable as defined in :pep:`526`. It does this by checking if the type of the field is ``typing.ClassVar``. If a field is a ``ClassVar``, it is excluded from consideration as a field and is ignored by the Data Class mechanisms. For more @@ -676,7 +676,7 @@ python-ideas discussion This discussion started on python-ideas [#]_ and was moved to a GitHub repo [#]_ for further discussion. As part of this discussion, we made -the decision to use PEP 526 syntax to drive the discovery of fields. +the decision to use :pep:`526` syntax to drive the discovery of fields. Support for automatically setting ``__slots__``? ------------------------------------------------ @@ -810,7 +810,7 @@ asdict and astuple function names --------------------------------- The names of the module-level helper functions ``asdict()`` and -``astuple()`` are arguably not PEP 8 compliant, and should be +``astuple()`` are arguably not :pep:`8` compliant, and should be ``as_dict()`` and ``as_tuple()``, respectively. However, after discussion [#]_ it was decided to keep consistency with ``namedtuple._asdict()`` and ``attr.asdict()``. @@ -949,8 +949,7 @@ References .. [#] Python documentation for __hash__ (https://docs.python.org/3/reference/datamodel.html#object.__hash__) -.. [#] ClassVar discussion in PEP 526 - (https://www.python.org/dev/peps/pep-0526/#class-and-instance-variable-annotations) +.. [#] :pep:`ClassVar discussion in PEP 526 <526#class-and-instance-variable-annotations>` .. [#] Start of python-ideas discussion (https://mail.python.org/pipermail/python-ideas/2017-May/045618.html) @@ -964,7 +963,7 @@ References .. [#] why not just attrs? (https://github.com/ericvsmith/dataclasses/issues/19) -.. [#] PEP 8 names for asdict and astuple +.. [#] :pep:`8` names for asdict and astuple (https://github.com/ericvsmith/dataclasses/issues/110) .. [#] Copying mutable defaults diff --git a/pep-0558.rst b/pep-0558.rst index f69a606c2bc..b8a39f1d62a 100644 --- a/pep-0558.rst +++ b/pep-0558.rst @@ -422,7 +422,7 @@ underlying frame or code object: write access through a fast locals proxy, rather than being eagerly populated as soon as the first fast locals proxy is created. Since the mapping is identical for all frames running a given code object, a single copy is stored - on the code object, rather than each frame object populating its own mapping + on the code object, rather than each frame object populating its own mapping * *locals*: the internal frame value cache returned by the ``PyEval_GetLocals()`` C API and updated by the ``PyFrame_FastToLocals()`` C API. This is the mapping that the ``locals()`` builtin returns in Python 3.10 and earlier. @@ -476,7 +476,7 @@ variables, it doesn't clear the cells themselves. This PEP could be a potential opportunity to narrow the scope of attempts to clear the frame variables directly by leaving cells belonging to outer frames alone, and only clearing local variables and cells belonging directly to the frame underlying the proxy -(this issue affects PEP 667 as well, as the question relates to the handling of +(this issue affects :pep:`667` as well, as the question relates to the handling of cell variables, and is entirely independent of the internal frame value cache). @@ -742,7 +742,7 @@ function, but finish running after the rebinding operation has taken place (in which case the rebinding will be reverted, which is the bug reported in [1]_). In addition to preserving the de facto semantics which have been in place since -PEP 227 introduced nested scopes in Python 2.1, the other benefit of restricting +:pep:`227` introduced nested scopes in Python 2.1, the other benefit of restricting the write-through proxy support to the implementation-defined frame object API is that it means that only interpreter implementations which emulate the full frame API need to offer the write-through capability at all, and that @@ -939,22 +939,22 @@ flexibility in how they provide those capabilities. Comparison with PEP 667 ----------------------- -PEP 667 offers a partially competing proposal for this PEP that suggests it +:pep:`667` offers a partially competing proposal for this PEP that suggests it would be reasonable to eliminate the internal frame value cache on optimised frames entirely. -These changes were originally offered as amendments to PEP 558, and the PEP +These changes were originally offered as amendments to :pep:`558`, and the PEP author rejected them for three main reasons: * the initial claim that ``PyEval_GetLocals()`` was unfixable because it returns - a borrowed reference was simply false, as it is still working in the PEP 558 + a borrowed reference was simply false, as it is still working in the :pep:`558` reference implementation. All that is required to keep it working is to retain the internal frame value cache and design the fast locals proxy in such a way that it is reasonably straightforward to keep the cache up to date with changes in the frame state without incurring significant runtime overhead when the cache isn't needed. Given that this claim is false, the proposal to require that all code using the ``PyEval_GetLocals()`` API be rewritten to use - a new API with different refcounting semantics fails PEP 387's requirement + a new API with different refcounting semantics fails :pep:`387`'s requirement that API compatibility breaks should have a large benefit to breakage ratio (since there's no significant benefit gained from dropping the cache, no code breakage can be justified). The only genuinely unfixable public API is @@ -970,10 +970,10 @@ author rejected them for three main reasons: initial implicit O(n) cache refresh that runs the first time an operation that relies on the cache being up to date is executed. * the claim that a cache-free implementation would be simpler is highly suspect, - as PEP 667 includes only a pure Python sketch of a subset of a mutable mapping + as :pep:`667` includes only a pure Python sketch of a subset of a mutable mapping implementation, rather than a full-fledged C implementation of a new mapping type integrated with the underlying data storage for optimised frames. - PEP 558's fast locals proxy implementation delegates heavily to the + :pep:`558`'s fast locals proxy implementation delegates heavily to the frame value cache for the operations needed to fully implement the mutable mapping API, allowing it to re-use the existing dict implementations of the following operations: @@ -993,7 +993,7 @@ author rejected them for three main reasons: Of the three reasons, the first is the most important (since we need compelling reasons to break API backwards compatibility, and we don't have them). -However, after reviewing PEP 667's proposed Python level semantics, the author +However, after reviewing :pep:`667`'s proposed Python level semantics, the author of this PEP eventually agreed that they *would* be simpler for users of the Python ``locals()`` API, so this distinction between the two PEPs has been eliminated: regardless of which PEP and implementation is accepted, the fast @@ -1012,18 +1012,18 @@ C APIs were also removed from the proposal in this PEP. This leaves the only remaining points of distinction between the two PEPs as specifically related to the C API: -* PEP 667 still proposes completely unnecessary C API breakage (the programmatic +* :pep:`667` still proposes completely unnecessary C API breakage (the programmatic deprecation and eventual removal of ``PyEval_GetLocals()``, ``PyFrame_FastToLocalsWithError()``, and ``PyFrame_FastToLocals()``) without justification, when it is entirely possible to keep these working indefintely (and interoperably) given a suitably designed fast locals proxy implementation * the fast locals proxy handling of additional variables is defined in this PEP in a way that is fully interoperable with the existing ``PyEval_GetLocals()`` - API. In the proxy implementation proposed in PEP 667, users of the new frame + API. In the proxy implementation proposed in :pep:`667`, users of the new frame API will not see changes made to additional variables by users of the old API, and changes made to additional variables via the old API will be overwritten on subsequent calls to ``PyEval_GetLocals()``. -* the ``PyLocals_Get()`` API in this PEP is called ``PyEval_Locals()`` in PEP 667. +* the ``PyLocals_Get()`` API in this PEP is called ``PyEval_Locals()`` in :pep:`667`. This function name is a bit strange as it lacks a verb, making it look more like a type name than a data access API. * this PEP adds ``PyLocals_GetCopy()`` and ``PyFrame_GetLocalsCopy()`` APIs to @@ -1038,14 +1038,14 @@ specifically related to the C API: ``_PyFrame_GetCode(PyEval_GetFrame())->co_flags & CO_OPTIMIZED`` is set) The Python pseudo-code below is based on the implementation sketch presented -in PEP 667 as of the time of writing (2021-10-24). The differences that +in :pep:`667` as of the time of writing (2021-10-24). The differences that provide the improved interoperability between the new fast locals proxy API and the existing ``PyEval_GetLocals()`` API are noted in comments. -As in PEP 667, all attributes that start with an underscore are invisible and +As in :pep:`667`, all attributes that start with an underscore are invisible and cannot be accessed directly. They serve only to illustrate the proposed design. -For simplicity (and as in PEP 667), the handling of module and class level +For simplicity (and as in :pep:`667`), the handling of module and class level frames is omitted (they're much simpler, as ``_locals`` *is* the execution namespace, so no translation is required). @@ -1206,7 +1206,7 @@ namespace, so no translation is required). self._sync_frame_cache() return len(self._locals) -Note: the simplest way to convert the earlier iterations of the PEP 558 +Note: the simplest way to convert the earlier iterations of the :pep:`558` reference implementation into a preliminary implementation of the now proposed semantics is to remove the ``frame_cache_updated`` checks in affected operations, and instead always sync the frame cache in those methods. Adopting that approach @@ -1228,7 +1228,7 @@ cache, the only way to know how many variables are currently bound is to iterate over all of them and check, and if the implementation is going to be spending that many cycles on an operation anyway, it may as well spend it updating the frame value cache and then consuming the result. These operations are O(n) in -both this PEP and in PEP 667. Customised implementations could be provided that +both this PEP and in :pep:`667`. Customised implementations could be provided that *are* faster than updating the frame cache, but it's far from clear that the extra code complexity needed to speed these operations up would be worthwhile when it only offers a linear performance improvement rather than an algorithmic @@ -1239,8 +1239,8 @@ code that doesn't rely on the value cache being up to date. Keeping the iterator/iterable retrieval methods as ``O(1)`` will involve writing custom replacements for the corresponding builtin dict helper types, -just as proposed in PEP 667. As illustrated above, the implementations would -be similar to the pseudo-code presented in PEP 667, but not identical (due to +just as proposed in :pep:`667`. As illustrated above, the implementations would +be similar to the pseudo-code presented in :pep:`667`, but not identical (due to the improved ``PyEval_GetLocals()`` interoperability offered by this PEP affecting the way it stores extra variables). @@ -1283,7 +1283,7 @@ Thanks to Mark Shannon for pushing for further simplification of the C level API and semantics, as well as significant clarification of the PEP text (and for restarting discussion on the PEP in early 2021 after a further year of inactivity) [10,11,12]_. Mark's comments that were ultimately published as -PEP 667 also directly resulted in several implementation efficiency improvements +:pep:`667` also directly resulted in several implementation efficiency improvements that avoid incurring the cost of redundant O(n) mapping refresh operations when the relevant mappings aren't used, as well as the change to ensure that the state reported through the Python level ``f_locals`` API is never stale. diff --git a/pep-0559.rst b/pep-0559.rst index 4c99f2fe33b..63574e256ce 100644 --- a/pep-0559.rst +++ b/pep-0559.rst @@ -24,7 +24,7 @@ It is trivial to implement a no-op function in Python. It's so easy in fact that many people do it many times over and over again. It would be useful in many cases to have a common built-in function that does nothing. -One use case would be for PEP 553, where you could set the breakpoint +One use case would be for :pep:`553`, where you could set the breakpoint environment variable to the following in order to effectively disable it:: $ setenv PYTHONBREAKPOINT=noop diff --git a/pep-0560.rst b/pep-0560.rst index d3bcd481143..f94589463f0 100644 --- a/pep-0560.rst +++ b/pep-0560.rst @@ -13,10 +13,10 @@ Resolution: https://mail.python.org/pipermail/python-dev/2017-December/151038.ht Abstract ======== -Initially PEP 484 was designed in such way that it would not introduce +Initially :pep:`484` was designed in such way that it would not introduce *any* changes to the core CPython interpreter. Now type hints and -the ``typing`` module are extensively used by the community, e.g. PEP 526 -and PEP 557 extend the usage of type hints, and the backport of ``typing`` +the ``typing`` module are extensively used by the community, e.g. :pep:`526` +and :pep:`557` extend the usage of type hints, and the backport of ``typing`` on PyPI has 1M downloads/month. Therefore, this restriction can be removed. It is proposed to add two special methods ``__class_getitem__`` and ``__mro_entries__`` to the core CPython for better support of @@ -38,7 +38,7 @@ Performance The ``typing`` module is one of the heaviest and slowest modules in the standard library even with all the optimizations made. Mainly this is -because subscripted generic types (see PEP 484 for definition of terms used +because subscripted generic types (see :pep:`484` for definition of terms used in this PEP) are class objects (see also [1]_). There are three main ways how the performance can be improved with the help of the proposed special methods: @@ -244,7 +244,7 @@ and deferring all check to static type checkers only:: Such class can be used as a normal generic in Python type annotations (a corresponding stub file should be provided for static type checkers, -see PEP 484 for details):: +see :pep:`484` for details):: from simple_extension import SimpleGeneric from typing import TypeVar diff --git a/pep-0561.rst b/pep-0561.rst index 31aaae236a5..80880d95617 100644 --- a/pep-0561.rst +++ b/pep-0561.rst @@ -12,7 +12,7 @@ Post-History: 10-Sep-2017, 12-Sep-2017, 06-Oct-2017, 26-Oct-2017, 12-Apr-2018 Abstract ======== -PEP 484 introduced type hinting to Python, with goals of making typing +:pep:`484` introduced type hinting to Python, with goals of making typing gradual and easy to adopt. Currently, typing information must be distributed manually. This PEP provides a standardized means to leverage existing tooling to package and distribute type information with minimal work and an ordering @@ -34,8 +34,9 @@ typeshed [1]_. However, this does not scale and becomes a burden on the maintainers of typeshed. In addition, it ties bug fixes in stubs to releases of the tool using typeshed. -PEP 484 has a brief section on distributing typing information. In this -section [2]_ the PEP recommends using ``shared/typehints/pythonX.Y/`` for +:pep:`484` has a brief section on distributing typing information. In this +:pep:`section <484#storing-and-distributing-stub-files>` +the PEP recommends using ``shared/typehints/pythonX.Y/`` for shipping stub files. However, manually adding a path to stub files for each third party library does not scale. The simplest approach people have taken is to add ``site-packages`` to their ``MYPYPATH``, but this causes type @@ -47,16 +48,16 @@ Definition of Terms =================== The definition of "MAY", "MUST", and "SHOULD", and "SHOULD NOT" are -to be interpreted as described in RFC 2119. +to be interpreted as described in :rfc:`2119`. -"inline" - the types are part of the runtime code using PEP 526 and -PEP 3107 syntax (the filename ends in ``.py``). +"inline" - the types are part of the runtime code using :pep:`526` and +:pep:`3107` syntax (the filename ends in ``.py``). "stubs" - files containing only type information, empty of runtime code (the filename ends in ``.pyi``). "Distributions" are the packaged files which are used to publish and distribute -a release. [3]_ +a release. (:pep:`426`) "Module" a file containing Python runtime code or stubbed type information. @@ -86,8 +87,8 @@ packaging and deployment. The two major parts of this specification are the packaging specifications and the resolution order for resolving module type information. The type -checking spec is meant to replace the ``shared/typehints/pythonX.Y/`` spec -of PEP 484 [2]_. +checking spec is meant to replace the ``shared/typehints/pythonX.Y/`` +:pep:`spec of PEP 484 <484#storing-and-distributing-stub-files>`. New third party stub libraries SHOULD distribute stubs via the third party packaging methods proposed in this PEP in place of being added to typeshed. @@ -119,7 +120,7 @@ Distutils option example:: ..., ) -For namespace packages (see PEP 420), the ``py.typed`` file should be in the +For namespace packages (see :pep:`420`), the ``py.typed`` file should be in the submodules of the namespace, to avoid conflicts and for clarity. This PEP does not support distributing typing information as part of @@ -158,7 +159,7 @@ in pip 9.0, if you update ``flyingcircus-stubs``, it will update ``--upgrade-strategy=only-if-needed`` flag. In pip 10.0 this is the default behavior. -For namespace packages (see PEP 420), stub-only packages should +For namespace packages (see :pep:`420`), stub-only packages should use the ``-stubs`` suffix on only the root namespace package. All stub-only namespace packages should omit ``__init__.pyi`` files. ``py.typed`` marker files are not necessary for stub-only packages, but similarly @@ -235,7 +236,7 @@ checkers MUST maintain the normal resolution order of checking ``*.pyi`` before If a stub package distribution is partial it MUST include ``partial\n`` in a ``py.typed`` file. For stub-packages distributing within a namespace -package (see PEP 420), the ``py.typed`` file should be in the +package (see :pep:`420`), the ``py.typed`` file should be in the submodules of the namespace. Type checkers should treat namespace packages within stub-packages as @@ -254,7 +255,7 @@ sample package checker [pkg_checker]_ which reads the metadata of installed packages and reports on their status as either not typed, inline typed, or a stub package. -The mypy type checker has an implementation of PEP 561 searching which can be +The mypy type checker has an implementation of :pep:`561` searching which can be read about in the mypy docs [4]_. [numpy-stubs]_ is an example of a real stub-only package for the numpy @@ -334,12 +335,6 @@ References ========== .. [1] Typeshed (https://github.com/python/typeshed) -.. [2] PEP 484, Storing and Distributing Stub Files - (https://www.python.org/dev/peps/pep-0484/#storing-and-distributing-stub-files) - -.. [3] PEP 426 definitions - (https://www.python.org/dev/peps/pep-0426/) - .. [4] Example implementation in a type checker (https://mypy.readthedocs.io/en/latest/installed_packages.html) diff --git a/pep-0562.rst b/pep-0562.rst index c16712955c6..d353e97cb38 100644 --- a/pep-0562.rst +++ b/pep-0562.rst @@ -74,12 +74,12 @@ imports. Consider a simple example:: import lib lib.submod.HeavyClass # prints "Submodule loaded" -There is a related proposal PEP 549 that proposes to support instance +There is a related proposal :pep:`549` that proposes to support instance properties for a similar functionality. The difference is this PEP proposes a faster and simpler mechanism, but provides more basic customization. -An additional motivation for this proposal is that PEP 484 already defines +An additional motivation for this proposal is that :pep:`484` already defines the use of module ``__getattr__`` for this purpose in Python stub files, -see [1]_. +see :pep:`484#stub-files`. In addition, to allow modifying result of a ``dir()`` call on a module to show deprecated and other dynamically generated attributes, it is @@ -184,9 +184,6 @@ called only once. References ========== -.. [1] PEP 484 section about ``__getattr__`` in stub files - (https://www.python.org/dev/peps/pep-0484/#stub-files) - .. [2] The reference implementation (https://github.com/ilevkivskyi/cpython/pull/3/files) diff --git a/pep-0563.rst b/pep-0563.rst index 270b0429de4..e6e64a6975a 100644 --- a/pep-0563.rst +++ b/pep-0563.rst @@ -16,9 +16,9 @@ Resolution: https://mail.python.org/pipermail/python-dev/2017-December/151042.ht Abstract ======== -PEP 3107 introduced syntax for function annotations, but the semantics -were deliberately left undefined. PEP 484 introduced a standard meaning -to annotations: type hints. PEP 526 defined variable annotations, +:pep:`3107` introduced syntax for function annotations, but the semantics +were deliberately left undefined. :pep:`484` introduced a standard meaning +to annotations: type hints. :pep:`526` defined variable annotations, explicitly tying them with the type hinting use case. This PEP proposes changing function annotations and variable annotations @@ -32,7 +32,7 @@ This change is being introduced gradually, starting with a Rationale and Goals =================== -PEP 3107 added support for arbitrary annotations on parts of a function +:pep:`3107` added support for arbitrary annotations on parts of a function definition. Just like default values, annotations are evaluated at function definition time. This creates a number of issues for the type hinting use case: @@ -45,13 +45,13 @@ hinting use case: computationally free. Postponing the evaluation of annotations solves both problems. -NOTE: PEP 649 proposes an alternative solution to the above issues, +NOTE: :pep:`649` proposes an alternative solution to the above issues, putting this PEP in danger of being superseded. Non-goals --------- -Just like in PEP 484 and PEP 526, it should be emphasized that **Python +Just like in :pep:`484` and :pep:`526`, it should be emphasized that **Python will remain a dynamically typed language, and the authors have no desire to ever make type hints mandatory, even by convention.** @@ -69,14 +69,14 @@ Non-typing usage of annotations While annotations are still available for arbitrary use besides type checking, it is worth mentioning that the design of this PEP, as well -as its precursors (PEP 484 and PEP 526), is predominantly motivated by +as its precursors (:pep:`484` and :pep:`526`), is predominantly motivated by the type hinting use case. -In Python 3.8 PEP 484 will graduate from provisional status. Other -enhancements to the Python programming language like PEP 544, PEP 557, -or PEP 560, are already being built on this basis as they depend on -type annotations and the ``typing`` module as defined by PEP 484. -In fact, the reason PEP 484 is staying provisional in Python 3.7 is to +In Python 3.8 :pep:`484` will graduate from provisional status. Other +enhancements to the Python programming language like :pep:`544`, :pep:`557`, +or :pep:`560`, are already being built on this basis as they depend on +type annotations and the ``typing`` module as defined by :pep:`484`. +In fact, the reason :pep:`484` is staying provisional in Python 3.7 is to enable rapid evolution for another release cycle that some of the aforementioned enhancements require. @@ -104,7 +104,7 @@ Annotations can only use names present in the module scope as postponed evaluation using local names is not reliable (with the sole exception of class-level names resolved by ``typing.get_type_hints()``). -Note that as per PEP 526, local variable annotations are not evaluated +Note that as per :pep:`526`, local variable annotations are not evaluated at all since they are not accessible outside of the function's closure. Enabling the future behavior in Python 3.7 @@ -286,7 +286,7 @@ Starting with Python 3.7, a ``__future__`` import is required to use the described functionality. No warnings are raised. NOTE: Whether this will eventually become the default behavior is currently unclear -pending decision on PEP 649. In any case, use of annotations that depend upon +pending decision on :pep:`649`. In any case, use of annotations that depend upon their eager evaluation is incompatible with both proposals and is no longer supported. @@ -424,7 +424,7 @@ never be able to use forward references since that would force the library users to use this new hypothetical -O switch. Second, this throws the baby out with the bath water. Now *no* runtime -annotation use can be performed. PEP 557 is one example of a recent +annotation use can be performed. :pep:`557` is one example of a recent development where evaluating type annotations at runtime is useful. All that being said, a granular -O option to drop annotations is @@ -475,7 +475,7 @@ Prior discussion In PEP 484 ---------- -The forward reference problem was discussed when PEP 484 was originally +The forward reference problem was discussed when :pep:`484` was originally drafted, leading to the following statement in the document: A compromise is possible where a ``__future__`` import could enable @@ -527,7 +527,7 @@ beginners: While typing usability is an interesting problem, it is out of scope of this PEP. Specifically, any extensions of the typing syntax -standardized in PEP 484 will require their own respective PEPs and +standardized in :pep:`484` will require their own respective PEPs and approval. Issue 400 ultimately suggests postponing evaluation of annotations and @@ -641,7 +641,7 @@ introspectable as strings. Most importantly, Guido van Rossum explicitly stated interest in gradually restricting the use of annotations to static typing (with an optional runtime component). -Nick Coghlan got convinced to PEP 563, too, promptly beginning +Nick Coghlan got convinced to :pep:`563`, too, promptly beginning the mandatory bike shedding session on the name of the ``__future__`` import. Many debaters agreed that ``annotations`` seems like an overly broad name for the feature name. Guido van Rossum briefly diff --git a/pep-0564.rst b/pep-0564.rst index 2be6b8c68c3..447bd4e63b7 100644 --- a/pep-0564.rst +++ b/pep-0564.rst @@ -66,7 +66,7 @@ precision:: Previous rejected PEP --------------------- -Five years ago, the PEP 410 proposed a large and complex change in all +Five years ago, the :pep:`410` proposed a large and complex change in all Python functions returning time to support nanosecond resolution using the ``decimal.Decimal`` type. @@ -124,13 +124,13 @@ with nanosecond resolution. CPython enhancements of the last 5 years ---------------------------------------- -Since the PEP 410 was rejected: +Since the :pep:`410` was rejected: * The ``os.stat_result`` structure got 3 new fields for timestamps as nanoseconds (Python ``int``): ``st_atime_ns``, ``st_ctime_ns`` and ``st_mtime_ns``. -* The PEP 418 was accepted, Python 3.3 got 3 new clocks: +* The :pep:`418` was accepted, Python 3.3 got 3 new clocks: ``time.monotonic()``, ``time.perf_counter()`` and ``time.process_time()``. @@ -244,7 +244,7 @@ Modifying time.time() result type It was proposed to modify ``time.time()`` to return a different number type with better precision. -The PEP 410 proposed to return ``decimal.Decimal`` which already exists and +The :pep:`410` proposed to return ``decimal.Decimal`` which already exists and supports arbitrary precision, but it was rejected. Apart from ``decimal.Decimal``, no portable real number type with better precision is currently available in Python. @@ -264,7 +264,7 @@ Many ideas of new types were proposed to support larger or arbitrary precision: fractions, structures or 2-tuple using integers, fixed-point number, etc. -See also the PEP 410 for a previous long discussion on other types. +See also the :pep:`410` for a previous long discussion on other types. Adding a new type requires more effort to support it, than reusing the existing ``int`` type. The standard library, third party code and diff --git a/pep-0566.rst b/pep-0566.rst index fee303543bc..7c54352d6b9 100644 --- a/pep-0566.rst +++ b/pep-0566.rst @@ -79,7 +79,7 @@ Name :::: The specification for the format of this field is now identical to the -distribution name specification defined in PEP 508. +distribution name specification defined in :pep:`508`. Description ::::::::::: @@ -104,7 +104,7 @@ also be able to handle version specifiers in parentheses. Further, public index servers MAY prohibit strict version matching clauses or direct references in these fields. -Usage of version specifiers is otherwise unchanged from PEP 345. +Usage of version specifiers is otherwise unchanged from :pep:`345`. Environment markers =================== @@ -114,9 +114,9 @@ field after a semi-colon (";"), to add a condition about the execution environment. The environment marker format used to declare such a condition is defined in -the environment markers section of PEP 508. +the environment markers section of :pep:`508`. -Usage of environment markers is otherwise unchanged from PEP 345. +Usage of environment markers is otherwise unchanged from :pep:`345`. JSON-compatible Metadata ======================== @@ -148,7 +148,7 @@ Summary of Differences From PEP 345 * Added two new fields: ``Description-Content-Type`` and ``Provides-Extra`` -* Acceptable values for the ``Name`` field are now specified as per PEP 508. +* Acceptable values for the ``Name`` field are now specified as per :pep:`508`. * Added canonical method of transformation into JSON-compatible data structure. @@ -156,10 +156,10 @@ References ========== This document specifies version 2.1 of the metadata format. -Version 1.0 is specified in PEP 241. -Version 1.1 is specified in PEP 314. -Version 1.2 is specified in PEP 345. -Version 2.0, while not formally accepted, was specified in PEP 426. +Version 1.0 is specified in :pep:`241`. +Version 1.1 is specified in :pep:`314`. +Version 1.2 is specified in :pep:`345`. +Version 2.0, while not formally accepted, was specified in :pep:`426`. .. _`Core Metadata Specification`: https://packaging.python.org/specifications/core-metadata/ diff --git a/pep-0567.rst b/pep-0567.rst index 3dec79b2e53..4c65142933e 100644 --- a/pep-0567.rst +++ b/pep-0567.rst @@ -859,16 +859,16 @@ See also issue 32436 [4]_. Acceptance ========== -PEP 567 was accepted by Guido on Monday, January 22, 2018 [5]_. +:pep:`567` was accepted by Guido on Monday, January 22, 2018 [5]_. The reference implementation was merged on the same day. References ========== -.. [1] https://www.python.org/dev/peps/pep-0550/#appendix-hamt-performance-analysis +.. [1] :pep:`550#appendix-hamt-performance-analysis` -.. [2] https://www.python.org/dev/peps/pep-0550/#replication-of-threading-local-interface +.. [2] :pep:`550#replication-of-threading-local-interface` .. [3] https://github.com/python/cpython/pull/5027 diff --git a/pep-0568.rst b/pep-0568.rst index d7dc3b95153..7f288ae7d86 100644 --- a/pep-0568.rst +++ b/pep-0568.rst @@ -15,10 +15,10 @@ Abstract Context variables provide a generic mechanism for tracking dynamic, context-local state, similar to thread-local storage but generalized to cope work with other kinds of thread-like contexts, such as asyncio -Tasks. PEP 550 proposed a mechanism for context-local state that was +Tasks. :pep:`550` proposed a mechanism for context-local state that was also sensitive to generator context, but this was pretty complicated, -so the BDFL requested it be simplified. The result was PEP 567, which -is targeted for inclusion in 3.7. This PEP then extends PEP 567's +so the BDFL requested it be simplified. The result was :pep:`567`, which +is targeted for inclusion in 3.7. This PEP then extends :pep:`567`'s machinery to add generator context sensitivity. This PEP is starting out in the "deferred" status, because there isn't @@ -57,10 +57,10 @@ Specification Review of PEP 567 ----------------- -Let's start by reviewing how PEP 567 works, and then in the next +Let's start by reviewing how :pep:`567` works, and then in the next section we'll describe the differences. -In PEP 567, a ``Context`` is a ``Mapping`` from ``ContextVar`` objects +In :pep:`567`, a ``Context`` is a ``Mapping`` from ``ContextVar`` objects to arbitrary values. In our pseudo-code here we'll pretend that it uses a ``dict`` for backing storage. (The real implementation uses a HAMT, which is semantically equivalent to a ``dict`` but with @@ -301,7 +301,7 @@ That's all. Comparison to PEP 550 ===================== -The main difference from PEP 550 is that it reified what we're calling +The main difference from :pep:`550` is that it reified what we're calling "contexts" and "context stacks" as two different concrete types (``LocalContext`` and ``ExecutionContext`` respectively). This led to lots of confusion about what the differences were, and which object @@ -331,7 +331,7 @@ else an intrusive linked list (``PyThreadState`` → ``Context`` → ``Context`` → ...), with the "top" of the stack at the beginning of the list to allow efficient push/pop. -A critical optimization in PEP 567 is the caching of values inside +A critical optimization in :pep:`567` is the caching of values inside ``ContextVar``. Switching from a single context to a context stack makes this a little bit more complicated, but not too much. Currently, we invalidate the cache whenever the threadstate's current ``Context`` diff --git a/pep-0569.rst b/pep-0569.rst index b0cf4891449..6a87bd8a951 100644 --- a/pep-0569.rst +++ b/pep-0569.rst @@ -99,14 +99,14 @@ Features for 3.8 Some of the notable features of Python 3.8 include: -* PEP 570, Positional-only arguments -* PEP 572, Assignment Expressions -* PEP 574, Pickle protocol 5 with out-of-band data -* PEP 578, Runtime audit hooks -* PEP 587, Python Initialization Configuration -* PEP 590, Vectorcall: a fast calling protocol for CPython -* Typing-related: PEP 591 (Final qualifier), PEP 586 (Literal types), - and PEP 589 (TypedDict) +* :pep:`570`, Positional-only arguments +* :pep:`572`, Assignment Expressions +* :pep:`574`, Pickle protocol 5 with out-of-band data +* :pep:`578`, Runtime audit hooks +* :pep:`587`, Python Initialization Configuration +* :pep:`590`, Vectorcall: a fast calling protocol for CPython +* Typing-related: :pep:`591` (Final qualifier), :pep:`586` (Literal types), + and :pep:`589` (TypedDict) * Parallel filesystem cache for compiled bytecode * Debug builds share ABI as release builds * f-strings support a handy ``=`` specifier for debugging diff --git a/pep-0570.rst b/pep-0570.rst index 7beb389e5c2..b3855d4a17a 100644 --- a/pep-0570.rst +++ b/pep-0570.rst @@ -264,7 +264,7 @@ the positional syntax would improve consistency. The ``/`` syntax is already exp in the existing documentation such as when builtins and interfaces are generated by the argument clinic. -Another essential aspect to consider is PEP 399, which mandates that +Another essential aspect to consider is :pep:`399`, which mandates that pure Python versions of modules in the standard library *must* have the same interface and semantics that the accelerator modules implemented in C. For example, if ``collections.defaultdict`` were to have a pure Python @@ -282,7 +282,7 @@ The new syntax will enable library authors to further control how their API can be called. It will allow designating which parameters must be called as positional-only, while preventing them from being called as keyword arguments. -Previously, (informational) PEP 457 defined the syntax, but with a much more vague +Previously, (informational) :pep:`457` defined the syntax, but with a much more vague scope. This PEP takes the original proposal a step further by justifying the syntax and providing an implementation for the ``/`` syntax in function definitions. @@ -349,7 +349,7 @@ intended order:: Compatibility for Pure Python and C Modules ------------------------------------------- -Another critical motivation for positional-only parameters is PEP 399: +Another critical motivation for positional-only parameters is :pep:`399`: Pure Python/C Accelerator Module Compatibility Requirements. This PEP states that: @@ -373,7 +373,7 @@ other Python implementations. For example:: 2918445923 Other Python implementations can reproduce the CPython APIs manually, but this -goes against the spirit of PEP 399 to avoid duplication of effort by +goes against the spirit of :pep:`399` to avoid duplication of effort by mandating that all modules added to Python's standard library **must** have a pure Python implementation with the same interface and semantics. @@ -655,7 +655,7 @@ passed by position or keyword:: >>> standard_arg(arg=2) 2 -The second function ``pos_only_arg` is restricted to only use positional +The second function ``pos_only_arg`` is restricted to only use positional parameters as there is a ``/`` in the function definition:: >>> pos_only_arg(1) @@ -824,7 +824,7 @@ unpacked automatically. An example is:: def fxn(a, (b, c), d): pass -Tuple argument unpacking was removed in Python 3 (PEP 3113). There has been a +Tuple argument unpacking was removed in Python 3 (:pep:`3113`). There has been a proposition to reuse this syntax to implement positional-only parameters. We have rejected this syntax for indicating positional only parameters for several reasons: @@ -861,7 +861,7 @@ Thanks ====== Credit for some of the content of this PEP is contained in Larry Hastings’s -PEP 457. +:pep:`457`. Credit for the use of ``/`` as the separator between positional-only and positional-or-keyword parameters go to Guido van Rossum, in a proposal from @@ -900,9 +900,6 @@ Braulio Valdivieso. and https://mail.python.org/pipermail/python-ideas/2012-March/014417.html -.. [#PEP399] - https://www.python.org/dev/peps/pep-0399/ - .. [#python-ideas-decorator-based] https://mail.python.org/pipermail/python-ideas/2017-February/044888.html diff --git a/pep-0571.rst b/pep-0571.rst index 433d53d79c8..446ca2e01c8 100644 --- a/pep-0571.rst +++ b/pep-0571.rst @@ -20,7 +20,7 @@ Abstract ======== This PEP proposes the creation of a ``manylinux2010`` platform tag to -succeed the ``manylinux1`` tag introduced by PEP 513 [1]_. It also +succeed the ``manylinux1`` tag introduced by :pep:`513`. It also proposes that PyPI and ``pip`` both be updated to support uploading, downloading, and installing ``manylinux2010`` distributions on compatible platforms. @@ -44,7 +44,7 @@ built against version 2.5 or earlier; they may then be run systems that provide more recent ``glibc`` version that still export the required symbols at version 2.5. -PEP 513 drew its whitelisted shared libraries and their symbol +:pep:`513` drew its whitelisted shared libraries and their symbol versions from CentOS 5.11, which was the oldest supported CentOS release at the time of its writing. Unfortunately, CentOS 5.11 reached its end-of-life on March 31st, 2017 with a clear warning @@ -55,7 +55,7 @@ packagers who use the ``manylinux1`` Docker image. CentOS 6 is now the oldest supported CentOS release, and will receive maintenance updates through November 30th, 2020. [5]_ We propose that -a new PEP 425-style [6]_ platform tag called ``manylinux2010`` be derived +a new :pep:`425`-style platform tag called ``manylinux2010`` be derived from CentOS 6 and that the ``manylinux`` toolchain, PyPI, and ``pip`` be updated to support it. @@ -109,7 +109,7 @@ the ``manylinux2010`` tag: This list is identical to the externally-provided libraries whitelisted for ``manylinux1``, minus ``libncursesw.so.5`` and ``libpanelw.so.5``. [7]_ ``libpythonX.Y`` remains ineligible for - inclusion for the same reasons outlined in PEP 513. + inclusion for the same reasons outlined in :pep:`513`. ``libcrypt.so.1`` was retrospectively removed from the whitelist after Fedora 30 was released with ``libcrypt.so.2`` instead. @@ -167,7 +167,7 @@ the ``manylinux2010`` tag: against Python 2, then, must include either the ``cpy27mu`` tag indicating it was built against an interpreter with the UCS-4 ABI or the ``cpy27m`` tag indicating an interpreter with the UCS-2 - ABI. [8]_ [9]_ + ABI. (:pep:`3149`, [9]_) 5. A wheel *must not* require the ``PyFPE_jbuf`` symbol. This is achieved by building it against a Python compiled *without* the ``--with-fpectl`` ``configure`` flag. @@ -257,14 +257,14 @@ Auditwheel The ``auditwheel`` tool has also been updated to produce ``manylinux2010`` wheels. [21]_ Its behavior and purpose are otherwise -unchanged from PEP 513. +unchanged from :pep:`513`. Platform Detection for Installers ================================= Platforms may define a ``manylinux2010_compatible`` boolean attribute on -the ``_manylinux`` module described in PEP 513. A platform is +the ``_manylinux`` module described in :pep:`513`. A platform is considered incompatible with ``manylinux2010`` if the attribute is ``False``. @@ -297,7 +297,7 @@ Specifically, the algorithm we propose is:: Backwards compatibility with ``manylinux1`` wheels ================================================== -As explained in PEP 513, the specified symbol versions for +As explained in :pep:`513`, the specified symbol versions for ``manylinux1`` whitelisted libraries constitute an *upper bound*. The same is true for the symbol versions defined for ``manylinux2010`` in this PEP. As a result, ``manylinux1`` wheels are considered @@ -314,8 +314,8 @@ to be uploaded in the same way that it permits ``manylinux1``. It should not attempt to verify the compatibility of ``manylinux2010`` wheels. -Summary of changes to \PEP 571 -============================== +Summary of changes to PEP 571 +============================= The following changes were made to this PEP based on feedback received after it was approved: @@ -328,8 +328,6 @@ it was approved: References ========== -.. [1] PEP 513 -- A Platform Tag for Portable Linux Built Distributions - (https://www.python.org/dev/peps/pep-0513/) .. [2] pyca/cryptography (https://cryptography.io/) .. [3] numpy @@ -338,13 +336,9 @@ References (https://lists.centos.org/pipermail/centos-announce/2017-April/022350.html) .. [5] CentOS Product Specifications (https://web.archive.org/web/20180108090257/https://wiki.centos.org/About/Product) -.. [6] PEP 425 -- Compatibility Tags for Built Distributions - (https://www.python.org/dev/peps/pep-0425/) .. [7] ncurses 5 -> 6 transition means we probably need to drop some libraries from the manylinux whitelist (https://github.com/pypa/manylinux/issues/94) -.. [8] PEP 3149 - https://www.python.org/dev/peps/pep-3149/ .. [9] SOABI support for Python 2.X and PyPy https://github.com/pypa/pip/pull/3075 .. [10] manylinux2010 Docker image diff --git a/pep-0572.rst b/pep-0572.rst index aaba4f6374a..f22c415a111 100644 --- a/pep-0572.rst +++ b/pep-0572.rst @@ -388,7 +388,7 @@ may miss the distinction. But simple cases are not objectionable:: print("Extremely long line:", longline) This PEP recommends always putting spaces around ``:=``, similar to -PEP 8's recommendation for ``=`` when used for assignment, whereas the +:pep:`8`'s recommendation for ``=`` when used for assignment, whereas the latter disallows spaces around ``=`` used for keyword arguments.) Change to evaluation order @@ -765,7 +765,7 @@ Broadly the same semantics as the current proposal, but spelled differently. Execution order is inverted (the indented body is performed first, followed by the "header"). This requires a new keyword, unless an existing keyword - is repurposed (most likely ``with:``). See PEP 3150 for prior discussion + is repurposed (most likely ``with:``). See :pep:`3150` for prior discussion on this subject (with the proposed keyword being ``given:``). 5. ``TARGET from EXPR``:: @@ -955,7 +955,7 @@ Style guide recommendations As expression assignments can sometimes be used equivalently to statement assignments, the question of which should be preferred will arise. For the -benefit of style guides such as PEP 8, two recommendations are suggested. +benefit of style guides such as :pep:`8`, two recommendations are suggested. 1. If either assignment statements or assignment expressions can be used, prefer statements; they are a clear declaration of intent. diff --git a/pep-0573.rst b/pep-0573.rst index 20d5fb6e1c3..c1698af1195 100644 --- a/pep-0573.rst +++ b/pep-0573.rst @@ -27,12 +27,12 @@ rather than PyState_FindModule for looking up module state, reducing or eliminating the performance cost of using module-scoped state over process global state. -This fixes one of the remaining roadblocks for adoption of PEP 3121 (Extension -module initialization and finalization) and PEP 489 +This fixes one of the remaining roadblocks for adoption of :pep:`3121` (Extension +module initialization and finalization) and :pep:`489` (Multi-phase extension module initialization). While this PEP takes an additional step towards fully solving the problems that -PEP 3121 and PEP 489 started tackling, it does not attempt to resolve *all* +:pep:`3121` and :pep:`489` started tackling, it does not attempt to resolve *all* remaining concerns. In particular, access to the module state from slot methods (``nb_add``, etc) is not solved. @@ -101,7 +101,7 @@ CPython implements the C-API, but other implementations exist. Rationale ========= -PEP 489 introduced a new way to initialize extension modules, which brings +:pep:`489` introduced a new way to initialize extension modules, which brings several advantages to extensions that implement it: * The extension modules behave more like their Python counterparts. @@ -112,7 +112,7 @@ several advantages to extensions that implement it: makes it possible to test module isolation (a key feature for proper sub-interpreter support) from a single interpreter. -The biggest hurdle for adoption of PEP 489 is allowing access to module state +The biggest hurdle for adoption of :pep:`489` is allowing access to module state from methods of extension types. Currently, the way to access this state from extension methods is by looking up the module via ``PyState_FindModule`` (in contrast to module level functions in @@ -124,7 +124,7 @@ deterring module authors from using it. Also, ``PyState_FindModule`` relies on the assumption that in each subinterpreter, there is at most one module corresponding to a given ``PyModuleDef``. This assumption does not hold for modules that use -PEP 489's multi-phase initialization, so ``PyState_FindModule`` is unavailable +:pep:`489`'s multi-phase initialization, so ``PyState_FindModule`` is unavailable for these modules. A faster, safer way of accessing module-level state from extension methods @@ -182,7 +182,7 @@ their shared state in C-level process globals, causing problems when: * reloading modules (e.g. to test conditional imports) * loading extension modules in subinterpreters -PEP 3121 attempted to resolve this by offering the ``PyState_FindModule`` API, +:pep:`3121` attempted to resolve this by offering the ``PyState_FindModule`` API, but this still has significant problems when it comes to extension methods (rather than module level functions): @@ -435,7 +435,7 @@ Solving this problem is left to future discussions. Easy creation of types with module references --------------------------------------------- -It would be possible to add a PEP 489 execution slot type to make +It would be possible to add a :pep:`489` execution slot type to make creating heap types significantly easier than calling ``PyType_FromModuleAndSpec``. This is left to a future PEP. @@ -470,9 +470,6 @@ References .. [#gh-patch] https://github.com/Dormouse759/cpython/compare/master...Dormouse759:pep-c-rebase_newer -.. [#pep-590] - https://www.python.org/dev/peps/pep-0590/ - Copyright ========= diff --git a/pep-0574.rst b/pep-0574.rst index d665e5f0cf1..891ca3fb32a 100644 --- a/pep-0574.rst +++ b/pep-0574.rst @@ -185,7 +185,7 @@ PickleBuffer objects -------------------- The ``PickleBuffer`` class supports a very simple Python API. Its constructor -takes a single PEP 3118-compatible object [#pep-3118]_. ``PickleBuffer`` +takes a single :pep:`3118`-compatible object. ``PickleBuffer`` objects themselves support the buffer protocol, so consumers can call ``memoryview(...)`` on them to get additional information about the underlying buffer (such as the original type, shape, etc.). @@ -207,7 +207,7 @@ PickleBuffer objects: ``PyObject *PyPickleBuffer_FromObject(PyObject *obj)`` - Create a ``PickleBuffer`` object holding a view over the PEP 3118-compatible + Create a ``PickleBuffer`` object holding a view over the :pep:`3118`-compatible *obj*. ``PyPickleBuffer_Check(PyObject *obj)`` @@ -229,7 +229,7 @@ Buffer requirements ``PickleBuffer`` can wrap any kind of buffer, including non-contiguous buffers. However, it is required that ``__reduce__`` only returns a -contiguous ``PickleBuffer`` (*contiguity* here is meant in the PEP 3118 +contiguous ``PickleBuffer`` (*contiguity* here is meant in the :pep:`3118` sense: either C-ordered or Fortran-ordered). Non-contiguous buffers will raise an error when pickled. @@ -347,7 +347,7 @@ Caveats Mutability ---------- -PEP 3118 buffers [#pep-3118]_ can be readonly or writable. Some objects, +:pep:`3118` buffers can be readonly or writable. Some objects, such as Numpy arrays, need to be backed by a mutable buffer for full operation. Pickle consumers that use the ``buffer_callback`` and ``buffers`` arguments will have to be careful to recreate mutable buffers. When doing @@ -504,9 +504,9 @@ to pickle [#dask-serialization]_. PyArrow implements zero-copy component-based serialization for a few selected types [#pyarrow-serialization]_. -PEP 554 proposes hosting multiple interpreters in a single process, with +:pep:`554` proposes hosting multiple interpreters in a single process, with provisions for transferring buffers between interpreters as a communication -scheme [#pep-554]_. +scheme. Acknowledgements @@ -538,12 +538,6 @@ References .. [#pyarrow-serialization] PyArrow IPC and component-based serialization https://arrow.apache.org/docs/python/ipc.html#component-based-serialization -.. [#pep-3118] PEP 3118 -- Revising the buffer protocol - https://www.python.org/dev/peps/pep-3118/ - -.. [#pep-554] PEP 554 -- Multiple Interpreters in the Stdlib - https://www.python.org/dev/peps/pep-0554/ - .. [#pickle5-git] ``pickle5`` branch on GitHub https://github.com/pitrou/cpython/tree/pickle5 diff --git a/pep-0575.rst b/pep-0575.rst index 407b5131722..4725754821a 100644 --- a/pep-0575.rst +++ b/pep-0575.rst @@ -12,9 +12,9 @@ Post-History: 31-Mar-2018, 12-Apr-2018, 27-Apr-2018, 5-May-2018 Withdrawal notice ================= -See PEP 580 for a better solution to allowing fast calling of custom classes. +See :pep:`580` for a better solution to allowing fast calling of custom classes. -See PEP 579 for a broader discussion of some of the other issues from this PEP. +See :pep:`579` for a broader discussion of some of the other issues from this PEP. Abstract @@ -67,7 +67,7 @@ subclasses are also allowed for functions implemented in C. In the latter case, this can be done with the same performance as true built-in functions. All functions can access the function object -(the ``self`` in ``__call__``), paving the way for PEP 573. +(the ``self`` in ``__call__``), paving the way for :pep:`573`. New classes @@ -121,7 +121,7 @@ but with the following differences and new features: This is meant to be backwards compatible with ``method_descriptor``. #. The field ``ml_doc`` and the attributes ``__doc__`` and - ``__text_signature__`` (see Argument Clinic [#clinic]_) + ``__text_signature__`` (see :pep:`Argument Clinic <436>`) are not supported. #. A new flag ``METH_PASS_FUNCTION`` for ``ml_flags``. @@ -203,11 +203,11 @@ The class ``cfunction`` is a copy of ``base_function``, with the following diffe const char *ml_doc; } PyMethodDef; - Note that ``PyMethodDef`` is part of the Python Stable ABI [#ABI]_ + Note that ``PyMethodDef`` is part of the :pep:`Python Stable ABI <384>` and it is used by practically all extension modules, so we absolutely cannot change this structure. -#. Argument Clinic [#clinic]_ is supported. +#. :pep:`Argument Clinic <436>` is supported. #. ``__self__`` always exists. In the cases where ``base_function.__self__`` would raise ``AttributeError``, instead ``None`` is returned. @@ -792,7 +792,7 @@ to use the ``base_function`` implementation instead. It also makes sense to use ``METH_PASS_FUNCTION`` without ``METH_CALL_UNBOUND`` in cases where the C function simply needs access to additional metadata from the function, such as the ``__parent__``. -This is for example needed to support PEP 573. +This is for example needed to support :pep:`573`. Converting existing methods to use ``METH_PASS_FUNCTION`` is trivial: it only requires adding an extra argument to the C function. @@ -1097,10 +1097,6 @@ References .. [#bpo33265] Python bug 33265, contextlib.ExitStack abuses __self__ (https://bugs.python.org/issue33265 and https://github.com/python/cpython/pull/6456) -.. [#ABI] PEP 384, Defining a Stable ABI, Löwis (https://www.python.org/dev/peps/pep-0384) - -.. [#clinic] PEP 436, The Argument Clinic DSL, Hastings (https://www.python.org/dev/peps/pep-0436) - .. [#methoddoc] PyMethodDef documentation (https://docs.python.org/3.7/c-api/structures.html#c.PyMethodDef) .. [#proposal] PEP proposal: unifying function/method classes (https://mail.python.org/pipermail/python-ideas/2018-March/049398.html) diff --git a/pep-0576.rst b/pep-0576.rst index bd0f4c95fc3..9088bc8a4e2 100644 --- a/pep-0576.rst +++ b/pep-0576.rst @@ -136,7 +136,7 @@ Adding a function pointer to each callable, rather than each class of callable, Alternative Suggestions ======================= -PEP 580 is an alternative approach to solving the same problem as this PEP. +:pep:`580` is an alternative approach to solving the same problem as this PEP. diff --git a/pep-0577.rst b/pep-0577.rst index b605c76f710..13e2568a29a 100644 --- a/pep-0577.rst +++ b/pep-0577.rst @@ -13,13 +13,13 @@ PEP Withdrawal ============== While working on this PEP, I realised that it didn't really address what was -actually bothering me about PEP 572's proposed scoping rules for previously +actually bothering me about :pep:`572`'s proposed scoping rules for previously unreferenced assignment targets, and also had some significant undesirable -consequences (most notably, allowing ``>>=` and ``<<=`` as inline augmented +consequences (most notably, allowing ``>>=`` and ``<<=`` as inline augmented assignment operators that meant something entirely different from the ``>=`` and ``<=`` comparison operators). -I also realised that even without dedicated syntax of their own, PEP 572 +I also realised that even without dedicated syntax of their own, :pep:`572` technically allows inline augmented assignments to be written using the ``operator`` module:: @@ -39,7 +39,7 @@ the time I also started writing a replacement PEP that focused specifically on the handling of assignment targets which hadn't already been declared as local variables in the current scope (for both regular block scopes, and for scoped expressions), but that draft never even reached a stage where *I* liked it -better than the ultimately accepted proposal in PEP 572, so it was never +better than the ultimately accepted proposal in :pep:`572`, so it was never posted anywhere, nor assigned a PEP number. @@ -56,7 +56,7 @@ statements do. The question of allowing expression level local variable declarations at function scope is deliberately separated from the question of allowing expression level name bindings, and deferred to a later PEP. -This PEP is a direct competitor to PEP 572 (although it borrows heavily from that +This PEP is a direct competitor to :pep:`572` (although it borrows heavily from that PEP's motivation, and even shares the proposed syntax for inline assignments). See `Relationship with PEP 572`_ for more details on the connections between the two PEPs. @@ -145,7 +145,7 @@ used today (in combination with ``operator.itemsetter``) to work around the lack of expression level assignments. Rather than requiring such workarounds, this PEP instead proposes that -PEP 572's "NAME := EXPR" syntax be adopted as a new inline assignment +:pep:`572`'s "NAME := EXPR" syntax be adopted as a new inline assignment expression that uses the augmented assignment scoping rules described below. This cleanly handles cases where only the new value is of interest, and the @@ -169,12 +169,12 @@ that when used as a top level expression the entire right hand side of the expression is still interpreted as the value to be processed (even when that value is a tuple without parentheses). -The difference this introduces relative to PEP 572 is that where -``(n := first, second)`` sets ``n = first`` in PEP 572, in this PEP it would set -``n = (first, second)`, and getting the first meaning would require an extra +The difference this introduces relative to :pep:`572` is that where +``(n := first, second)`` sets ``n = first`` in :pep:`572`, in this PEP it would set +``n = (first, second)``, and getting the first meaning would require an extra set of parentheses (``((n := first), second)``). -PEP 572 quite reasonably notes that this results in ambiguity when assignment +:pep:`572` quite reasonably notes that this results in ambiguity when assignment expressions are used as function call arguments. This PEP resolves that concern a different way by requiring that assignment expressions be parenthesised when used as arguments to a function call (unless they're the sole argument). @@ -368,7 +368,7 @@ Design discussion Allowing complex assignment targets ----------------------------------- -The initial drafts of this PEP kept PEP 572's restriction to single name targets +The initial drafts of this PEP kept :pep:`572`'s restriction to single name targets when augmented assignments were used as expressions, allowing attribute and subscript targets solely for the statement form. @@ -385,7 +385,7 @@ that also gained support for assignment and subscript targets. Augmented assignment or name binding only? ------------------------------------------ -PEP 572 makes a reasonable case that the potential use cases for inline +:pep:`572` makes a reasonable case that the potential use cases for inline augmented assignment are notably weaker than those for inline assignment in general, so it's acceptable to require that they be spelled as ``x := x + 1``, bypassing any in-place augmented assignment methods. @@ -442,7 +442,7 @@ currently executing module and modifying its attributes). For class scopes, the answer to both questions is also "Yes" in practice, although less unequivocally so, since the semantics of ``locals()`` are currently formally unspecified. However, if the current behaviour of ``locals()`` -at class scope is taken as normative (as PEP 558 proposes), then this is +at class scope is taken as normative (as :pep:`558` proposes), then this is essentially the same scenario as manipulating the module globals, just using ``locals()`` instead. @@ -489,7 +489,7 @@ level bindings are sufficient. Ignoring scoped expressions when determining augmented assignment targets ------------------------------------------------------------------------- -When discussing possible binding semantics for PEP 572's assignment expressions, +When discussing possible binding semantics for :pep:`572`'s assignment expressions, Tim Peters made a plausible case [1_,2_,3_] for assignment expressions targeting the containing block scope, essentially ignoring any intervening scoped expressions. @@ -531,12 +531,12 @@ to detect it), so there's also no need to tinker with that. Treating inline assignment as an augmented assignment variant ------------------------------------------------------------- -One of the challenges with PEP 572 is the fact that ``NAME = EXPR`` and +One of the challenges with :pep:`572` is the fact that ``NAME = EXPR`` and ``NAME := EXPR`` are entirely semantically equivalent at every scope. This makes the two forms hard to teach, since there's no inherent nudge towards choosing one over the other at the statement level, so you end up having to resort to "``NAME = EXPR`` is preferred because it's been around longer" -(and PEP 572 proposes to enfore that historical idiosyncrasy at the compiler +(and :pep:`572` proposes to enfore that historical idiosyncrasy at the compiler level). That semantic equivalence is difficult to avoid at module and class scope while @@ -554,7 +554,7 @@ design requirement, then this PEP would be updated to propose that ``EXPR given NAME`` also be introduced as a way to support inline name declarations after arbitrary expressions (this would allow the inline name declarations to be deferred until the end of a complex expression rather than needing to be -embedded in the middle of it, and PEP 8 would gain a recommendation encouraging +embedded in the middle of it, and :pep:`8` would gain a recommendation encouraging that style). @@ -586,7 +586,7 @@ operation:: x >= y # Greater-than-or-equal-to x <= y # Less-than-or-equal-to -Both this PEP and PEP 572 propose adding at least one operator that's somewhat +Both this PEP and :pep:`572` propose adding at least one operator that's somewhat similar in appearance, but defines an assignment instead:: x := y # Becomes @@ -687,7 +687,7 @@ be written using nested if-else statements:: else: ... -As with PEP 572, this PEP allows the else/if portions of that chain to be +As with :pep:`572`, this PEP allows the else/if portions of that chain to be condensed, making their consistent and mutually exclusive structure more readily apparent:: @@ -701,7 +701,7 @@ readily apparent:: else: ... -Unlike PEP 572, this PEP requires that the assignment target be explicitly +Unlike :pep:`572`, this PEP requires that the assignment target be explicitly indicated as local before the first use as a ``:=`` target, either by binding it to a value (as shown above), or else by including an appropriate explicit type declaration:: @@ -761,27 +761,27 @@ practice. Relationship with PEP 572 ========================= -The case for allowing inline assignments at all is made in PEP 572. This +The case for allowing inline assignments at all is made in :pep:`572`. This competing PEP was initially going to propose an alternate surface syntax (``EXPR given NAME = EXPR``), while retaining the expression semantics from -PEP 572, but that changed when discussing one of the initial motivating use +:pep:`572`, but that changed when discussing one of the initial motivating use cases for allowing embedded assignments at all: making it possible to easily calculate cumulative sums in comprehensions and generator expressions. -As a result of that, and unlike PEP 572, this PEP focuses primarily on use +As a result of that, and unlike :pep:`572`, this PEP focuses primarily on use cases for inline augmented assignment. It also has the effect of converting cases that currently inevitably raise ``UnboundLocalError`` at function call time to report a new compile time ``TargetNameError``. New syntax for a name rebinding expression (``NAME := TARGET``) is then added -not only to handle the same use cases as are identified in PEP 572, but also +not only to handle the same use cases as are identified in :pep:`572`, but also as a lower level primitive to help illustrate, implement and explain the new augmented assignment semantics, rather than being the sole change being proposed. The author of this PEP believes that this approach makes the value of the new flexibility in name rebinding clearer, while also mitigating many of the -potential concerns raised with PEP 572 around explaining when to use +potential concerns raised with :pep:`572` around explaining when to use ``NAME = EXPR`` over ``NAME := EXPR`` (and vice-versa), without resorting to prohibiting the bare statement form of ``NAME := EXPR`` outright (such that ``NAME := EXPR`` is a compile error, but ``(NAME := EXPR)`` is permitted). @@ -790,7 +790,7 @@ that ``NAME := EXPR`` is a compile error, but ``(NAME := EXPR)`` is permitted). Acknowledgements ================ -The PEP author wishes to thank Chris Angelico for his work on PEP 572, and his +The PEP author wishes to thank Chris Angelico for his work on :pep:`572`, and his efforts to create a coherent summary of the great many sprawling discussions that spawned on both python-ideas and python-dev, as well as Tim Peters for the in-depth discussion of parent local scoping that prompted the above diff --git a/pep-0578.rst b/pep-0578.rst index c1c63f5e0cf..a1d7b58c475 100644 --- a/pep-0578.rst +++ b/pep-0578.rst @@ -29,7 +29,7 @@ are unspecified here to allow implementations the freedom to determine how best to provide information to their users. Some examples likely to be used in CPython are provided for explanatory purposes. -See PEP 551 for discussion and recommendations on enhancing the +See :pep:`551` for discussion and recommendations on enhancing the security of a Python runtime making use of these auditing APIs. Background @@ -545,13 +545,13 @@ Relationship to PEP 551 ======================= This API was originally presented as part of -`PEP 551 `_ Security +:pep:`551` Security Transparency in the Python Runtime. For simpler review purposes, and due to the broader applicability of these APIs beyond security, the API design is now presented separately. -PEP 551 is an informational PEP discussing how to integrate Python into +:pep:`551` is an informational PEP discussing how to integrate Python into a secure or audited environment. References diff --git a/pep-0579.rst b/pep-0579.rst index 800695714a8..6edaac6e299 100644 --- a/pep-0579.rst +++ b/pep-0579.rst @@ -12,10 +12,10 @@ Post-History: 20-Jun-2018 Approval Notice =============== -This PEP describes design issues addressed in PEP 575, PEP 580, PEP 590 +This PEP describes design issues addressed in :pep:`575`, :pep:`580`, :pep:`590` (and possibly later proposals). -As noted in `PEP 1 `_: +As noted in :pep:`PEP 1 <1#pep-types>`: Informational PEPs do not necessarily represent a Python community consensus or recommendation, so users and implementers are free to @@ -119,7 +119,7 @@ be the *only* remaining purpose of the ``PyMethodDef`` structure. Additionally, we can also make some function classes subclassable. However, this seems less important once we have ``tp_ccalloffset``. -**Reference**: PEP 580 +**Reference**: :pep:`580` 3. cfunctions do not become methods @@ -158,7 +158,7 @@ should be part of the new C call protocol. For backwards compatibility, we would keep the existing non-binding behavior of cfunctions. We would just allow it in custom classes. -**Reference**: PEP 580 +**Reference**: :pep:`580` 4. Semantics of inspect.isfunction @@ -195,7 +195,7 @@ C call protocol for Python functions (``types.FunctionType``): the C function which implements calling Python functions needs access to the ``__code__`` attribute of the function. -This is also needed for PEP 573 +This is also needed for :pep:`573` where all cfunctions require access to their "parent" (the module for functions of a module or the defining class for methods). @@ -204,7 +204,7 @@ for methods). that the C function takes an additional argument (as first argument), namely the function object. -**References**: PEP 580, PEP 573 +**References**: :pep:`580`, :pep:`573` 6. METH_FASTCALL is private and undocumented @@ -226,7 +226,7 @@ As part of the C call protocol, we should also add a C API function :: PyObject *PyCCall_FastCall(PyObject *func, PyObject *const *args, Py_ssize_t nargs, PyObject *keywords) -**Reference**: PEP 580 +**Reference**: :pep:`580` 7. Allowing native C arguments @@ -303,7 +303,7 @@ instead of doing type checks. Furthermore, it should be investigated whether some of these classes can be merged and whether ``method`` can be re-used also for bound methods of extension types -(see PEP 576 for the latter, +(see :pep:`576` for the latter, keeping in mind that this may have some minor backwards compatibility issues). This is not a goal by itself but just something to keep in mind when working on these classes. @@ -316,7 +316,7 @@ The typical way to create a cfunction or cmethod in an extension module is by using a ``PyMethodDef`` to define it. These are then stored in an array ``PyModuleDef.m_methods`` (for cfunctions) or ``PyTypeObject.tp_methods`` (for cmethods). -However, because of the stable ABI (PEP 384), +However, because of the stable ABI (:pep:`384`), we cannot change the ``PyMethodDef`` structure. So, this means that we cannot add new fields for creating cfunctions/cmethods diff --git a/pep-0580.rst b/pep-0580.rst index 9b95abe2241..d2822a43bde 100644 --- a/pep-0580.rst +++ b/pep-0580.rst @@ -13,7 +13,7 @@ Post-History: 20-Jun-2018, 22-Jun-2018, 16-Jul-2018 Rejection Notice ================ -This PEP is rejected in favor of PEP 590, which proposes a simpler public +This PEP is rejected in favor of :pep:`590`, which proposes a simpler public C API for callable objects. @@ -63,7 +63,7 @@ enabling even further simplifications. We also design the C call protocol such that it can easily be extended with new features in the future. -For more background and motivation, see PEP 579. +For more background and motivation, see :pep:`579`. Overview @@ -176,7 +176,7 @@ For methods of extension types, ``cc_parent`` points to the class that defines the method (which may be a superclass of ``type(self)``). This is currently non-trivial to retrieve from a method's code. In the future, this can be used to access the module state via -the defining class. See the rationale of PEP 573 for details. +the defining class. See the rationale of :pep:`573` for details. When the flag ``CCALL_OBJCLASS`` is set (as it will be for methods of extension types), ``cc_parent`` is used for type checks like the following:: @@ -212,7 +212,7 @@ becomes ``tp_ccalloffset`` unconditionally, drop the ``Py_TPFLAGS_HAVE_CCALL`` flag and instead check for ``tp_ccalloffset != 0``. -**NOTE**: the exact layout of ``PyTypeObject`` is not part of the stable ABI ([#pep384]_). +**NOTE**: the exact layout of ``PyTypeObject`` is not part of the :pep:`stable ABI <384>`). Therefore, changing the ``tp_print`` field from a ``printfunc`` (a function pointer) to a ``Py_ssize_t`` should not be a problem, even if this changes the memory layout of the ``PyTypeObject`` structure. @@ -479,7 +479,7 @@ compatibility problems. C API functions --------------- -The following function is added (also to the stable ABI [#pep384]_): +The following function is added (also to the :pep:`stable ABI <384>`): - ``PyObject * PyCFunction_ClsNew(PyTypeObject *cls, PyMethodDef *ml, PyObject *self, PyObject *module, PyObject *parent)``: create a new object with object structure ``PyCFunctionObject`` and class ``cls``. @@ -497,7 +497,7 @@ and ``PyCFunction_GET_FLAGS`` are deprecated. They are still artificially supported by storing the original ``METH_...`` flags in a bitfield inside ``cc_flags``. Despite the fact that ``PyCFunction_GetFlags`` is technically -part of the stable ABI [#pep384]_, +part of the :pep:`stable ABI <384>`, it is highly unlikely to be used that way: first of all, it is not even documented. Second, the flag ``METH_FASTCALL`` @@ -544,7 +544,7 @@ performance improvements are discussed: Stable ABI ========== -The function ``PyCFunction_ClsNew`` is added to the stable ABI [#pep384]_. +The function ``PyCFunction_ClsNew`` is added to the :pep:`stable ABI <384>`. None of the functions, structures or constants dealing with the C call protocol are added to the stable ABI. @@ -552,7 +552,7 @@ are added to the stable ABI. There are two reasons for this: first of all, the most useful feature of the C call protocol is probably the ``METH_FASTCALL`` calling convention. -Given that this is not even part of the public API (see also PEP 579, issue 6), +Given that this is not even part of the public API (see also :pep:`579`, issue 6), it would be strange to add anything else from the C call protocol to the stable ABI. @@ -579,7 +579,7 @@ Rationale Why is this better than PEP 575? -------------------------------- -One of the major complaints of PEP 575 was that is was coupling +One of the major complaints of :pep:`575` was that is was coupling functionality (the calling and introspection protocol) with the class hierarchy: a class could only benefit from the new features @@ -587,7 +587,7 @@ if it was a subclass of ``base_function``. It may be difficult for existing classes to do that because they may have other constraints on the layout of the C object structure, coming from an existing base class or implementation details. -For example, ``functools.lru_cache`` cannot implement PEP 575 as-is. +For example, ``functools.lru_cache`` cannot implement :pep:`575` as-is. It also complicated the implementation precisely because changes were needed both in the implementation details and in the class hierarchy. @@ -687,7 +687,7 @@ Why CCALL_DEFARG? The flag ``CCALL_DEFARG`` gives the callee access to the ``PyCCallDef *``. There are various use cases for this: -1. The callee can use the ``cc_parent`` field, which is useful for PEP 573. +1. The callee can use the ``cc_parent`` field, which is useful for :pep:`573`. 2. Applications are free to extend the ``PyCCallDef`` structure with user-defined fields, which can then be accessed analogously. @@ -720,9 +720,9 @@ In particular, the Cython project has shown interest in doing that Alternative suggestions ======================= -PEP 576 is an alternative approach to solving the same problem as this PEP. +:pep:`576` is an alternative approach to solving the same problem as this PEP. See https://mail.python.org/pipermail/python-dev/2018-July/154238.html -for comments on the difference between PEP 576 and PEP 580. +for comments on the difference between :pep:`576` and :pep:`580`. Discussion @@ -757,16 +757,13 @@ The reference implementation can be found at https://github.com/jdemeyer/cpython/tree/pep580 For an example of using the C call protocol, -the following branch implements ``functools.lru_cache`` using PEP 580: +the following branch implements ``functools.lru_cache`` using :pep:`580`: https://github.com/jdemeyer/cpython/tree/lru580 References ========== -.. [#pep384] Löwis, PEP 384 – Defining a Stable ABI, - https://www.python.org/dev/peps/pep-0384/ - .. [#bpo29259] Add tp_fastcall to PyTypeObject: support FASTCALL calling convention for all callable objects, https://bugs.python.org/issue29259 diff --git a/pep-0581.rst b/pep-0581.rst index 71f65eb5425..869c87d5bab 100644 --- a/pep-0581.rst +++ b/pep-0581.rst @@ -17,7 +17,7 @@ Abstract ======== This PEP outlines the rationale for migration from Python's issue -tracker on Roundup to GitHub issues. See PEP 588 for the detailed +tracker on Roundup to GitHub issues. See :pep:`588` for the detailed migration plan. @@ -111,10 +111,10 @@ Issues with Roundup / bpo - Note: Exposing email address to registered and logged in users was a decision taken when bpo instance was setup. This behavior has been recently modified - after PEP 581's acceptance. + after :pep:`581`'s acceptance. - REST API is not currently available in bpo. There was an open issue in Roundup - for adding REST API [#]_. At the time PEP 581 was proposed, the ticket received + for adding REST API [#]_. At the time :pep:`581` was proposed, the ticket received no activity since 2016. REST API has been integrated in Roundup in February 2019, however it is not yet integrated to bpo. @@ -188,7 +188,7 @@ GitHub is not the perfect issue tracker. Several issues we need to be aware of: - Using GitHub could possibly increase the triaging effort. This was first raised as a Zulip topic [#]_, and also brought up during Core Python sprint in September 2018 [#]_. A few solutions have been proposed and considered, such as - creating a special triage team [#]_. After PEP 581's acceptance, GitHub released a + creating a special triage team [#]_. After :pep:`581`'s acceptance, GitHub released a new triaging role, currently in beta. The PSF has been in touch with GitHub to have this enabled for Python organization. This is pending GitHub's review [#]_. @@ -208,7 +208,7 @@ GitHub is not the perfect issue tracker. Several issues we need to be aware of: - bpo uses a number of fields to specify several metadata, and these might not be easily transferable to GitHub. The intended way to handle custom metadata on GitHub is by using labels. The details of which labels to create will be - further discussed in PEP 588. + further discussed in :pep:`588`. Further questions and discussions diff --git a/pep-0584.rst b/pep-0584.rst index bd15bae5898..d0a002a7798 100644 --- a/pep-0584.rst +++ b/pep-0584.rst @@ -987,7 +987,7 @@ The above examples show that sometimes the ``|`` operator leads to a clear increase in readability, reducing the number of lines of code and improving clarity. However other examples using the ``|`` operator lead to long, complex single expressions, possibly well over -the PEP 8 maximum line length of 80 columns. As with any other +the :pep:`8` maximum line length of 80 columns. As with any other language feature, the programmer should use their own judgement about whether ``|`` improves their code. diff --git a/pep-0585.rst b/pep-0585.rst index 2b1b08158e6..1c284404d48 100644 --- a/pep-0585.rst +++ b/pep-0585.rst @@ -68,7 +68,7 @@ collections directly. Example:: def find(haystack: dict[str, list[int]]) -> int: ... -Usefulness of this syntax before PEP 585 is limited as external tooling +Usefulness of this syntax before :pep:`585` is limited as external tooling like Mypy does not recognize standard collections as generic. Moreover, certain features of typing like type aliases or casting require putting types outside of annotations, in runtime context. While these are @@ -116,7 +116,7 @@ Python 3.9, the following collections become generic using * ``re.Pattern`` # typing.Pattern, typing.re.Pattern * ``re.Match`` # typing.Match, typing.re.Match -Importing those from ``typing`` is deprecated. Due to PEP 563 and the +Importing those from ``typing`` is deprecated. Due to :pep:`563` and the intention to minimize the runtime impact of typing, this deprecation will not generate DeprecationWarnings. Instead, type checkers may warn about such deprecated usage when the target version of the checked diff --git a/pep-0586.rst b/pep-0586.rst index 564b1c18424..2983f40e48e 100644 --- a/pep-0586.rst +++ b/pep-0586.rst @@ -15,7 +15,7 @@ Resolution: https://mail.python.org/archives/list/typing-sig@python.org/message/ Abstract ======== -This PEP proposes adding *Literal types* to the PEP 484 ecosystem. +This PEP proposes adding *Literal types* to the :pep:`484` ecosystem. Literal types indicate that some expression has literally a specific value. For example, the following function will accept only expressions that have literally the value "4":: @@ -55,7 +55,7 @@ The typing issue tracker contains some `additional examples and discussion `_. There is currently no way of expressing the type signatures of these -functions: PEP 484 does not include any mechanism for writing signatures +functions: :pep:`484` does not include any mechanism for writing signatures where the return type varies depending on the value passed in. Note that this problem persists even if we redesign these APIs to instead accept enums: ``MyEnum.FOO`` and ``MyEnum.BAR`` are both @@ -94,7 +94,7 @@ it’s safe to do things like ``foo + 5`` since ``foo`` inherits int’s ``__add__`` method. The resulting type of ``foo + 5`` is ``int``. This "inheriting" behavior is identical to how we -`handle NewTypes. `_. +:pep:`handle NewTypes <484#newtype-helper-function>`. Equivalence of two Literals --------------------------- @@ -223,7 +223,7 @@ The following parameters are intentionally disallowed by design: ``Literal["foo".replace("o", "b")]``. - Rationale: Literal types are meant to be a - minimal extension to the PEP 484 typing ecosystem and requiring type + minimal extension to the :pep:`484` typing ecosystem and requiring type checkers to interpret potentially expressions inside types adds too much complexity. Also see `Rejected or out-of-scope ideas`_. @@ -527,7 +527,8 @@ values of the ``Status`` enum have already been exhausted:: print("Got custom status: " + s) The interaction described above is not new: it's already -`already codified within PEP 484 `_. However, many type +:pep:`codified within PEP 484 <484#support-for-singleton-types-in-unions>`. +However, many type checkers (such as mypy) do not yet implement this due to the expected complexity of the implementation work. @@ -585,7 +586,7 @@ involving Literal bools. For example, we can combine ``Literal[True]``, Interactions with Final ----------------------- -`PEP 591 `_ proposes adding a "Final" qualifier to the typing +:pep:`591` proposes adding a "Final" qualifier to the typing ecosystem. This qualifier can be used to declare that some variable or attribute cannot be reassigned:: @@ -603,7 +604,7 @@ is valid to use in any context that expects a ``Literal[3]``:: The ``Final`` qualifier serves as a shorthand for declaring that a variable is *effectively Literal*. -If both this PEP and PEP 591 are accepted, type checkers are expected to +If both this PEP and :pep:`591` are accepted, type checkers are expected to support this shortcut. Specifically, given a variable or attribute assignment of the form ``var: Final = value`` where ``value`` is a valid parameter for ``Literal[...]``, type checkers should understand that ``var`` may be used in @@ -629,7 +630,7 @@ True dependent types/integer generics ------------------------------------- This proposal is essentially describing adding a very simplified -dependent type system to the PEP 484 ecosystem. One obvious extension +dependent type system to the :pep:`484` ecosystem. One obvious extension would be to implement a full-fledged dependent type system that lets users predicate types based on their values in arbitrary ways. That would let us write signatures like the below:: @@ -734,11 +735,6 @@ something similar to how .. _typescript-index-types: https://www.typescriptlang.org/docs/handbook/advanced-types.html#index-types -.. _newtypes: https://www.python.org/dev/peps/pep-0484/#newtype-helper-function - -.. _pep-484-enums: https://www.python.org/dev/peps/pep-0484/#support-for-singleton-types-in-unions - -.. _pep-591: https://www.python.org/dev/peps/pep-0591/ Acknowledgements ================ diff --git a/pep-0587.rst b/pep-0587.rst index 430c8f11a81..134d1248dfb 100644 --- a/pep-0587.rst +++ b/pep-0587.rst @@ -32,7 +32,7 @@ easier using the new ``Py_RunMain()`` function. Moreover, using the same way the regular Python parses command line arguments, and ``PyConfig.xoptions`` are handled as ``-X opt`` command line options. -This extracts a subset of the API design from the PEP 432 development +This extracts a subset of the API design from the :pep:`432` development and refactoring work that is now considered sufficiently stable to make public (allowing 3rd party embedding applications access to the same configuration APIs that the native CPython CLI is now using). @@ -71,7 +71,7 @@ Moreover, ``Py_Main()`` could exit directly the process rather than returning an exit code. Proposed new API reports the error or exit code to the caller which can decide how to handle it. -Implementing the PEP 540 (UTF-8 Mode) and the new ``-X dev`` correctly +Implementing the :pep:`540` (UTF-8 Mode) and the new ``-X dev`` correctly was almost impossible in Python 3.6. The code base has been deeply reworked in Python 3.7 and then in Python 3.8 to read the configuration into a structure with no side effect. It becomes possible to clear the @@ -88,9 +88,9 @@ behavior way more easily, especially for corner cases like that, and ensure that the configuration remains consistent: see `Priority and Rules`_. -This PEP is a partial implementation of PEP 432 which is the overall +This PEP is a partial implementation of :pep:`432` which is the overall design. New fields can be added later to ``PyConfig`` structure to -finish the implementation of the PEP 432 (e.g. by adding a new partial +finish the implementation of the :pep:`432` (e.g. by adding a new partial initialization API which allows to configure Python using Python objects to finish the full initialization). However, those features are omitted from this PEP as even the native CPython CLI doesn't work that way - the public API @@ -447,7 +447,7 @@ exceptions (error or exit) using ``PyStatus_Exception()`` and ``bytearray`` with ``str``, or comparing ``bytes`` with ``int``. If equal or greater to 2, raise a ``BytesWarning`` exception. * ``check_hash_pycs_mode`` (``wchar_t*``): - ``--check-hash-based-pycs`` command line option value (see PEP 552). + ``--check-hash-based-pycs`` command line option value (see :pep:`552`). Valid values: ``always``, ``never`` and ``default``. The default value is ``default``. * ``configure_c_stdio`` (``int``): @@ -585,7 +585,7 @@ Options`_. Install importlib? * ``_init_main`` (``int``): If equal to 0, stop Python initialization before the "main" phase - (see PEP 432). + (see :pep:`432`). More complete example modifying the default configuration, read the configuration, and then override some parameters:: @@ -669,7 +669,7 @@ behaves as the regular Python. Environments variables and command line arguments are used to configure Python, whereas global configuration variables are ignored. -This function enables C locale coercion (PEP 538) and UTF-8 Mode (PEP +This function enables C locale coercion (:pep:`538`) and UTF-8 Mode (PEP 540) depending on the LC_CTYPE locale, ``PYTHONUTF8`` and ``PYTHONCOERCECLOCALE`` environment variables. @@ -710,7 +710,7 @@ Example of customized Python always running in isolated mode:: } This example is a basic implementation of the "System Python Executable" -discussed in PEP 432. +discussed in :pep:`432`. Path Configuration @@ -801,7 +801,7 @@ Multi-Phase Initialization Private Provisional API -------------------------------------------------- This section is a private provisional API introducing multi-phase -initialization, the core feature of the PEP 432: +initialization, the core feature of the :pep:`432`: * "Core" initialization phase, "bare minimum Python": @@ -890,7 +890,7 @@ This PEP only adds a new API: it leaves the existing API unchanged and has no impact on the backwards compatibility. The Python 3.7 ``Py_Initialize()`` function now disable the C locale -coercion (PEP 538) and the UTF-8 Mode (PEP 540) by default to prevent +coercion (:pep:`538`) and the UTF-8 Mode (:pep:`540`) by default to prevent mojibake. The new API using the `Python Configuration`_ is needed to enable them automatically. @@ -1528,7 +1528,7 @@ Version History Acceptance ========== -PEP 587 was `accepted by Thomas Wouters on May 26, 2019 +:pep:`587` was `accepted by Thomas Wouters on May 26, 2019 `_. diff --git a/pep-0588.rst b/pep-0588.rst index fac37f52c1e..003909680ca 100644 --- a/pep-0588.rst +++ b/pep-0588.rst @@ -13,8 +13,8 @@ Abstract ======== This PEP describes the detailed plan for migrating from Python's issue -tracker on Roundup to GitHub issues. See PEP 581 for rationale and -background. PEP 588 also describes the detailed timeline for the +tracker on Roundup to GitHub issues. See :pep:`581` for rationale and +background. :pep:`588` also describes the detailed timeline for the migration. diff --git a/pep-0589.rst b/pep-0589.rst index dd7550e31b8..77b2e92cd12 100644 --- a/pep-0589.rst +++ b/pep-0589.rst @@ -16,7 +16,7 @@ Resolution: https://mail.python.org/archives/list/typing-sig@python.org/message/ Abstract ======== -PEP 484 [#PEP-484]_ defines the type ``Dict[K, V]`` for uniform +:pep:`484` defines the type ``Dict[K, V]`` for uniform dictionaries, where each value has the same type, and arbitrary key values are supported. It doesn't properly support the common pattern where the type of a dictionary value depends on the string value of @@ -24,7 +24,7 @@ the key. This PEP proposes a type constructor ``typing.TypedDict`` to support the use case where a dictionary object has a specific set of string keys, each with a value of a specific type. -Here is an example where PEP 484 doesn't allow us to annotate +Here is an example where :pep:`484` doesn't allow us to annotate satisfactorily:: movie = {'name': 'Blade Runner', @@ -63,10 +63,10 @@ when not using JSON. They trivially support various useful operations with no extra effort, including pretty-printing (through ``str()`` and the ``pprint`` module), iteration, and equality comparisons. -PEP 484 doesn't properly support the use cases mentioned above. Let's +:pep:`484` doesn't properly support the use cases mentioned above. Let's consider a dictionary object that has exactly two valid string keys, ``'name'`` with value type ``str``, and ``'year'`` with value type -``int``. The PEP 484 type ``Dict[str, Any]`` would be suitable, but +``int``. The :pep:`484` type ``Dict[str, Any]`` would be suitable, but it is too lenient, as arbitrary string keys can be used, and arbitrary values are valid. Similarly, ``Dict[str, Union[str, int]]`` is too general, as the value for key ``'name'`` could be an ``int``, and @@ -95,7 +95,7 @@ This PEP proposes two ways of defining TypedDict types. The first uses a class-based syntax. The second is an alternative assignment-based syntax that is provided for backwards compatibility, to allow the feature to be backported to older Python versions. The -rationale is similar to why PEP 484 supports a comment-based +rationale is similar to why :pep:`484` supports a comment-based annotation syntax for Python 2.7: type hinting is particularly useful for large existing codebases, and these often need to run on older Python versions. The two syntax options parallel the syntax variants @@ -105,7 +105,7 @@ required or not). This PEP also provides a sketch of how a type checker is expected to support type checking operations involving TypedDict objects. -Similar to PEP 484, this discussion is left somewhat vague on purpose, +Similar to :pep:`484`, this discussion is left somewhat vague on purpose, to allow experimentation with a wide variety of different type checking approaches. In particular, type compatibility should be based on structural compatibility: a more specific TypedDict type can @@ -224,7 +224,7 @@ are the only uses of the type a type checker is expected to allow: In particular, TypedDict type objects cannot be used in ``isinstance()`` tests such as ``isinstance(d, Movie)``. The reason is that there is no existing support for checking types of dictionary -item values, since ``isinstance()`` does not work with many PEP 484 +item values, since ``isinstance()`` does not work with many :pep:`484` types, including common ones like ``List[str]``. This would be needed for cases like this:: @@ -336,7 +336,7 @@ Alternative Syntax This PEP also proposes an alternative syntax that can be backported to older Python versions such as 3.5 and 2.7 that don't support the -variable definition syntax introduced in PEP 526 [#PEP-526]_. It +variable definition syntax introduced in :pep:`526`. It resembles the traditional syntax for defining named tuples:: Movie = TypedDict('Movie', {'name': str, 'year': int}) @@ -364,7 +364,7 @@ Type Consistency Informally speaking, *type consistency* is a generalization of the is-subtype-of relation to support the ``Any`` type. It is defined -more formally in PEP 483 [#PEP-483]_. This section introduces the +more formally in :pep:`483`. This section introduces the new, non-trivial rules needed to support type consistency for TypedDict types. @@ -566,7 +566,7 @@ alternative is to generate false positive errors for idiomatic code. Use of Final Values and Literal Types ------------------------------------- -Type checkers should allow final names (PEP 591 [#PEP-591]_) with +Type checkers should allow final names (:pep:`591`) with string values to be used instead of string literals in operations on TypedDict objects. For example, this is valid:: @@ -576,7 +576,7 @@ TypedDict objects. For example, this is valid:: years_since_epoch = m[YEAR] - 1970 Similarly, an expression with a suitable literal type -(PEP 586 [#PEP-586]_) can be used instead of a literal value:: +(:pep:`586`) can be used instead of a literal value:: def get_value(movie: Movie, key: Literal['year', 'name']) -> Union[int, str]: @@ -658,7 +658,7 @@ extensions to be added in the future: * TypedDict can't be used for specifying the type of a ``**kwargs`` argument. This would allow restricting the allowed keyword - arguments and their types. According to PEP 484, using a TypedDict + arguments and their types. According to :pep:`484`, using a TypedDict type as the type of ``**kwargs`` means that the TypedDict is valid as the *value* of arbitrary keyword arguments, but it doesn't restrict which keyword arguments should be allowed. The syntax @@ -677,25 +677,9 @@ Michael Lee, Dominik Miedzinski, Roy Williams and Max Moroz. References ========== -.. [#PEP-484] PEP 484, Type Hints, van Rossum, Lehtosalo, Langa - (http://www.python.org/dev/peps/pep-0484) - .. [#dataclasses-json] Dataclasses JSON (https://github.com/lidatong/dataclasses-json) -.. [#PEP-526] PEP 526, Syntax for Variable Annotations, Gonzalez, - House, Levkivskyi, Roach, van Rossum - (http://www.python.org/dev/peps/pep-0484) - -.. [#PEP-483] PEP 483, The Theory of Type Hints, van Rossum, Levkivskyi - (http://www.python.org/dev/peps/pep-0483) - -.. [#PEP-591] PEP 591, Adding a final qualifier to typing, Sullivan, - Levkivskyi (http://www.python.org/dev/peps/pep-0591) - -.. [#PEP-586] PEP 586, Literal Types, Lee, Levkivskyi, Lehtosalo - (http://www.python.org/dev/peps/pep-0586) - .. [#mypy] http://www.mypy-lang.org/ .. [#typing_extensions] diff --git a/pep-0590.rst b/pep-0590.rst index fabd4df7b71..41298d5534e 100644 --- a/pep-0590.rst +++ b/pep-0590.rst @@ -250,7 +250,7 @@ Performance of functions using ``METH_VARARGS`` will become slightly worse. Stable ABI ========== -Nothing from this PEP is added to the stable ABI (PEP 384). +Nothing from this PEP is added to the stable ABI (:pep:`384`). Alternative Suggestions @@ -259,7 +259,7 @@ Alternative Suggestions bpo-29259 --------- -PEP 590 is close to what was proposed in bpo-29259 [#bpo29259]_. +:pep:`590` is close to what was proposed in bpo-29259 [#bpo29259]_. The main difference is that this PEP stores the function pointer in the instance rather than in the class. This makes more sense for implementing functions in C, @@ -269,15 +269,15 @@ It also allows optimizing ``type.__call__``, which is not possible with bpo-2925 PEP 576 and PEP 580 ------------------- -Both PEP 576 and PEP 580 are designed to enable 3rd party objects to be both expressive and performant (on a par with +Both :pep:`576` and :pep:`580` are designed to enable 3rd party objects to be both expressive and performant (on a par with CPython objects). The purpose of this PEP is provide a uniform way to call objects in the CPython ecosystem that is both expressive and as performant as possible. -This PEP is broader in scope than PEP 576 and uses variable rather than fixed offset function-pointers. -The underlying calling convention is similar. Because PEP 576 only allows a fixed offset for the function pointer, +This PEP is broader in scope than :pep:`576` and uses variable rather than fixed offset function-pointers. +The underlying calling convention is similar. Because :pep:`576` only allows a fixed offset for the function pointer, it would not allow the improvements to any objects with constraints on their layout. -PEP 580 proposes a major change to the ``PyMethodDef`` protocol used to define builtin functions. +:pep:`580` proposes a major change to the ``PyMethodDef`` protocol used to define builtin functions. This PEP provides a more general and simpler mechanism in the form of a new calling convention. This PEP also extends the ``PyMethodDef`` protocol, but merely to formalise existing conventions. diff --git a/pep-0591.rst b/pep-0591.rst index 6b6bacffcf5..5d5f8e0d408 100644 --- a/pep-0591.rst +++ b/pep-0591.rst @@ -62,7 +62,7 @@ situations: * Allowing a name to be used in situations where ordinarily a literal is expected (for example as a field name for ``NamedTuple``, a tuple of types passed to ``isinstance``, or an argument to a function - with arguments of ``Literal`` type [#PEP-586]_). + with arguments of ``Literal`` type (:pep:`586`)). Specification ============= @@ -279,16 +279,6 @@ desired is to use this idiom (possibly in a support module):: References ========== -.. [#PEP-484] PEP 484, Type Hints, van Rossum, Lehtosalo, Langa - (http://www.python.org/dev/peps/pep-0484) - -.. [#PEP-526] PEP 526, Syntax for Variable Annotations, Gonzalez, - House, Levkivskyi, Roach, van Rossum - (http://www.python.org/dev/peps/pep-0526) - -.. [#PEP-586] PEP 586, Literal Types, Lee, Levkivskyi, Lehtosalo - (http://www.python.org/dev/peps/pep-0586) - .. [#mypy] http://www.mypy-lang.org/ .. [#typing_extensions] https://github.com/python/typing/tree/master/typing_extensions diff --git a/pep-0592.rst b/pep-0592.rst index 961b6d7c6a1..1b433e5dcd3 100644 --- a/pep-0592.rst +++ b/pep-0592.rst @@ -108,7 +108,7 @@ suggested approaches to take: matches a version specifier that "pins" to an exact version using either ``==`` (without any modifiers that make it a range, such as ``.*``) or ``===``. Matching this version specifier should otherwise - be done as per PEP 440 for things like local versions, zero padding, + be done as per :pep:`440` for things like local versions, zero padding, etc. 2. Yanked files are always ignored, unless they are the only file that matches what a lock file (such as ``Pipfile.lock`` or ``poetry.lock``) diff --git a/pep-0593.rst b/pep-0593.rst index 2a8da4bc1f7..409f0281ce7 100644 --- a/pep-0593.rst +++ b/pep-0593.rst @@ -19,12 +19,12 @@ This PEP introduces a mechanism to extend the type annotations from PEP Motivation ---------- -PEP 484 provides a standard semantic for the annotations introduced in -PEP 3107. PEP 484 is prescriptive but it is the de facto standard +:pep:`484` provides a standard semantic for the annotations introduced in +:pep:`3107`. :pep:`484` is prescriptive but it is the de facto standard for most of the consumers of annotations; in many statically checked code bases, where type annotations are widely used, they have effectively crowded out any other form of annotation. Some of the use -cases for annotations described in PEP 3107 (database mapping, +cases for annotations described in :pep:`3107` (database mapping, foreign languages bridge) are not currently realistic given the prevalence of type annotations. Furthermore, the standardisation of type annotations rules out advanced features only supported by specific type @@ -266,7 +266,7 @@ References https://docs.python.org/3/library/struct.html#examples .. [mypy] - http://www.mypy-lang.org/ + http://www.mypy-lang.org/ .. [pyre] https://pyre-check.org/ diff --git a/pep-0595.rst b/pep-0595.rst index 61964da0126..98ae9a082c7 100644 --- a/pep-0595.rst +++ b/pep-0595.rst @@ -20,7 +20,7 @@ switching to GitHub Issues, as proposed by :pep:`581`. Resolution ========== -2020-06-25: With the acceptance of PEP 581, the move to GitHub for +2020-06-25: With the acceptance of :pep:`581`, the move to GitHub for issues is proceeding, this PEP is being marked as a withdrawn informational PEP. @@ -190,7 +190,7 @@ PEP 581 issues This section addresses some errors and inaccuracies found in :pep:`581`. -The "Why GitHub?" section of PEP 581 lists features currently +The "Why GitHub?" section of :pep:`581` lists features currently available on GitHub Issues but not on Roundup. Some of this features are currently supported: diff --git a/pep-0596.rst b/pep-0596.rst index 8f65b00c47d..32614e15651 100644 --- a/pep-0596.rst +++ b/pep-0596.rst @@ -40,7 +40,7 @@ Release Schedule Note: the dates below use a 17-month development period that results in a 12-month release cadence between major versions, as defined by -PEP 602. +:pep:`602`. Actual: diff --git a/pep-0598.rst b/pep-0598.rst index 2a6feabf5cb..e36fea94fd9 100644 --- a/pep-0598.rst +++ b/pep-0598.rst @@ -14,7 +14,7 @@ Python-Version: 3.9 Abstract ======== -PEP 602 proposes reducing the feature delivery latency for the Python +:pep:`602` proposes reducing the feature delivery latency for the Python standard library and CPython reference interpreter by increasing the frequency of CPython feature releases from every 18-24 months to instead occur every 9-12 months. @@ -31,7 +31,7 @@ PEP Withdrawal ============== This PEP has been withdrawn in favour of the rolling beta release stream -proposal in PEP 605. +proposal in :pep:`605`. However, the concerns raised in this PEP are likely to apply to any other "Long Term Support branch" proposals that allow feature backports to improve @@ -221,7 +221,7 @@ The pre-release beta period would be relaxed to use the incremental feature release policy for changes, rather than the stricter maintenance release policy. For governance purposes, baseline feature releases are the only releases that -would qualify as a "feature release" in the PEP 13 sense (incremental feature +would qualify as a "feature release" in the :pep:`13` sense (incremental feature releases wouldn't count). @@ -516,11 +516,11 @@ Motivation ========== The motivation for change in this PEP is essentially the same as the motivation -for change in PEP 596: the current 18-24 month gap between feature releases has +for change in :pep:`596`: the current 18-24 month gap between feature releases has a lot of undesirable consequences, especially for the standard library (see -PEP 596 for further articulation of the details). +:pep:`596` for further articulation of the details). -This PEP's concern with the specific proposal in PEP 596 is that it doubles the +This PEP's concern with the specific proposal in :pep:`596` is that it doubles the number of actively supported Python branches, increasing the complexity of compatibility testing matrices for the entire Python community, increasing the number of binary Python wheels to be uploaded to PyPI when not using the stable @@ -734,7 +734,7 @@ from the 2019-10 release of Python 3.8.0 and a final Python 3.9.x incremental feature release in 2021-10 evenly between pre-release development and subsequent incremental feature releases. -This is an area where this PEP could adopt part of the proposal in PEP 596, +This is an area where this PEP could adopt part of the proposal in :pep:`596`, by instead making that split ~9 months of pre-release development, and ~15 months of incremental feature releases: @@ -799,7 +799,7 @@ branched. An alternative way of handling this would be to start publishing alpha releases for the next baseline feature release during the feature addition period (similar -to the way that PEP 596 proposes to starting publishing Python 3.9.0 alpha +to the way that :pep:`596` proposes to starting publishing Python 3.9.0 alpha releases during the Python 3.8.0 release candidate period). However, rather than setting specific timelines for that at a policy level, diff --git a/pep-0599.rst b/pep-0599.rst index 676484ebf67..b03056dfe41 100644 --- a/pep-0599.rst +++ b/pep-0599.rst @@ -35,7 +35,7 @@ patches will be made available. All wheels built under the point. Therefore, we propose the continuation of the existing manylinux -standard, and that a new PEP 425-style [2]_ platform tag called +standard, and that a new :pep:`425`-style platform tag called ``manylinux2014`` be derived from CentOS 7 and that the ``manylinux`` toolchain, PyPI, and ``pip`` be updated to support it. @@ -178,7 +178,7 @@ the ``manylinux2014`` tag: built against Python 2, then, must include either the ``cpy27mu`` tag indicating it was built against an interpreter with the UCS-4 ABI or the ``cpy27m`` tag indicating an interpreter with the UCS-2 - ABI. [6]_ [7]_ + ABI. (:pep:`3149` [7]_) 5. A wheel *must not* require the ``PyFPE_jbuf`` symbol. This is achieved by building it against a Python compiled *without* the ``--with-fpectl`` ``configure`` flag. @@ -281,16 +281,12 @@ References .. [1] CentOS Product Specifications (https://wiki.centos.org/About/Product) -.. [2] PEP 425: Compatibility Tags for Built Distributions - (https://www.python.org/dev/peps/pep-0425/) .. [3] Tracking issue for manylinux2010 rollout (https://github.com/pypa/manylinux/issues/179) .. [4] Red Hat Universal Base Image 7 (https://access.redhat.com/containers/?tab=overview#/registry.access.redhat.com/ubi7) .. [5] The CentOS Alternative Architecture Special Interest Group (https://wiki.centos.org/SpecialInterestGroup/AltArch) -.. [6] PEP 3149: ABI version tagged .so files - (https://www.python.org/dev/peps/pep-3149/) .. [7] SOABI support for Python 2.X and PyPy (https://github.com/pypa/pip/pull/3075) .. [8] auditwheel @@ -299,7 +295,7 @@ References Acceptance ========== -PEP 599 was `accepted by Paul Moore on July 31, 2019 +:pep:`599` was `accepted by Paul Moore on July 31, 2019 `_. Copyright diff --git a/pep-0601.txt b/pep-0601.txt index fa6054d26ec..ffabd2046e0 100644 --- a/pep-0601.txt +++ b/pep-0601.txt @@ -18,7 +18,7 @@ This PEP was rejected by the Steering Council by a vote of 4/4. Guido's arguments for rejecting the PEP are: "it seems to me that most languages implement this kind of construct but have style guides and/or linters that -reject it. I would support a proposal to add this to PEP 8", and "I note that +reject it. I would support a proposal to add this to :pep:`8`", and "I note that the toy examples are somewhat misleading – the functionality that may be useful is a conditional return (or break etc.) inside a finally block.". diff --git a/pep-0602.rst b/pep-0602.rst index ef5f8bf0baf..453e01d20c0 100644 --- a/pep-0602.rst +++ b/pep-0602.rst @@ -120,7 +120,7 @@ Deprecations The current policy around breaking changes assumes at least two releases before a deprecated feature is removed from Python or a ``__future__`` -behavior is enabled by default. This is documented in PEP 387. +behavior is enabled by default. This is documented in :pep:`387`. This PEP proposes to keep this policy of **at least** two releases before making a breaking change. @@ -128,7 +128,7 @@ before making a breaking change. The term of the Steering Council -------------------------------- -The current wording of PEP 13 states that "a new council is elected +The current wording of :pep:`13` states that "a new council is elected after each feature release". This PEP proposes to keep this policy as it will lead to a consistent election schedule. @@ -236,7 +236,7 @@ by one or two: Figure 2. Testing matrix in the 18-month cadence vs. the 12-month The "extended bugfix support at the discretion of the Release Manager" -stage of the current release cycle is not codified. If fact, PEP 101 +stage of the current release cycle is not codified. If fact, :pep:`101` currently states that after the release of Python 3.(X+1).0 only one last bugfix release is made for Python 3.X.0. However, in practice at least the last four versions of Python 3 overlapped with stable releases @@ -291,7 +291,7 @@ More importantly, from the perspective of the user: Double the release cadence to achieve 9 months between major versions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This was originally proposed in PEP 596 and rejected as both too +This was originally proposed in :pep:`596` and rejected as both too irregular and too short. This would not give any of the benefits of a regular release calendar but it would shorten all development phases, especially the beta + RC phases. This was considered dangerous. @@ -311,7 +311,7 @@ better. Slow down releases but don't freeze feature development with Beta 1 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is described in PEP 598. This proposal includes non-standard +This is described in :pep:`598`. This proposal includes non-standard concepts like the "incremental feature release" which makes it hard to understand. The presented advantages are unclear while the unfamiliarity of the scheme poses a real risk of user and integrator diff --git a/pep-0604.rst b/pep-0604.rst index 0796e94da83..0267adae6c9 100644 --- a/pep-0604.rst +++ b/pep-0604.rst @@ -23,10 +23,10 @@ writing ``Union[X, Y]`` as ``X | Y``, and allows it to appear in Motivation ========== -PEP 484 and PEP 526 propose a generic syntax to add typing to variables, -parameters and function returns. PEP 585 proposes to `expose +:pep:`484` and :pep:`526` propose a generic syntax to add typing to variables, +parameters and function returns. :pep:`585` proposes to :pep:`expose parameters to generics at runtime -`_. +<585#parameters-to-generics-are-available-at-runtime>`. Mypy [1]_ accepts a syntax which looks like:: annotation: name_type @@ -144,7 +144,7 @@ In some situations, some exceptions will not be raised as expected. If a metaclass implements the ``__or__`` operator, it will override this:: >>> class M(type): - ... def __or__(self, other): return "Hello" + ... def __or__(self, other): return "Hello" ... >>> class C(metaclass=M): pass ... @@ -185,7 +185,7 @@ CONS: 2. Change only PEP 484 (Type hints) to accept the syntax ``type1 | type2`` ? ---------------------------------------------------------------------------- -PEP 563 (Postponed Evaluation of Annotations) is enough to accept this proposition, +:pep:`563` (Postponed Evaluation of Annotations) is enough to accept this proposition, if we accept to not be compatible with the dynamic evaluation of annotations (``eval()``). :: diff --git a/pep-0605.rst b/pep-0605.rst index bd4eb64a751..95026eb6da4 100644 --- a/pep-0605.rst +++ b/pep-0605.rst @@ -14,7 +14,7 @@ Post-History: 1-Oct-2019, 6-Oct-2019, 20-Oct-2019 Rejection Notice ================ -This PEP was rejected in favour of PEP 602. The potential alpha/beta alternation +This PEP was rejected in favour of :pep:`602`. The potential alpha/beta alternation was deemed too confusing and the two year cadence between releases deemed too long. @@ -24,7 +24,7 @@ Abstract For a long time, CPython's nominal feature release cadence has been "every 18-24 months", and in recent years, has been pretty consistently on the "18 month" -end of that window. PEP 607 provides some common background on the problems +end of that window. :pep:`607` provides some common background on the problems that arise due to that choice of cadence, as well as some of the risks that need to be accounted for when proposing to change it. @@ -155,7 +155,7 @@ and then linked from each of the Python 3.9 alpha and beta announcements. PEP 605: Changes to the pre-release management process ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -As detailed in PEP 605, the pre-release management process has been updated to +As detailed in :pep:`605`, the pre-release management process has been updated to produce a rolling series of beta releases that are considered suitable for production use in environments with sufficiently robust integration testing and operational monitoring capabilities. @@ -174,7 +174,7 @@ ignored by post-freeze interpreter builds. The full CPython ABI will be frozen, and the pre-release flag dropped from the ABI flags, in 3.9.0rc1, which is expected to occur 2 months prior to the final -3.9.0 release (refer to the release schedule in PEP 596 for exact target dates). +3.9.0 release (refer to the release schedule in :pep:`596` for exact target dates). For application developers, migrating to the rolling release stream provides the opportunity to be actively involved in the design and development of @@ -336,7 +336,7 @@ application containers, also make it easier to combine an application with a language runtime in a CI pipeline, and then keep them together until the entire container image is later replaced by an updated one. -In light of those changes in the wider environment, PEP 602 has proposed +In light of those changes in the wider environment, :pep:`602` has proposed reducing the feature delivery latency for the Python standard library and CPython reference interpreter by increasing the frequency of CPython feature releases from every 18-24 months to instead occur every 12 months. @@ -361,7 +361,7 @@ more variants in widespread use can make it more difficult to determine when a fault report is an actual error in the project, or an issue in the reporting user's environment. -PEP 602 proposes that affected organisations and projects simply switch to +:pep:`602` proposes that affected organisations and projects simply switch to adopting every second or third CPython release, rather than attempting to adopt every release, but that creates its own set of new problems to be resolved, both practical (e.g. deprecations would need to cover more than one release if we're @@ -370,7 +370,7 @@ number of versions in active use, there is a much higher chance that open source library maintainers will receive bug reports that only occur on Python versions that they're not using themselves). -PEP 598 was an initial attempt by one of the authors of this PEP to propose +:pep:`598` was an initial attempt by one of the authors of this PEP to propose an alternative scheme to reduce feature delivery latency by adopting a semantic versioning style policy that allowed for the incremental delivery of backwards compatible features within a release series, until that series @@ -378,7 +378,7 @@ reached feature complete status. That variant still had the undesirable consequence of imposing visible changes on end users that are happy enough with the current release management model. -This PEP takes the view that both PEP 598 and PEP 602 share a common flaw: they +This PEP takes the view that both :pep:`598` and :pep:`602` share a common flaw: they are attempting to satisfy the needs of two quite distinct audiences within the constraints of a single release model, which results in conflicting design requirements, and the need for awkward trade-offs between those conflicting @@ -418,7 +418,7 @@ for almost all Python users and contributors: * for users of the new incremental feature release stream, targeting the pre-release phase allows for even lower feature delivery latency than the - annual cadence proposed in PEP 602; + annual cadence proposed in :pep:`602`; * for core developers working on new features, increased frequency and adoption of pre-releases should improve pre-release feedback cycles; * for users of the established release stream, the increased adoption and @@ -438,13 +438,13 @@ for almost all Python users and contributors: That said, it is acknowledged that not all the outcomes of this proposal will be beneficial for all members of the wider Python ecosystem: -* for Python library maintainers, both this PEP and PEP 602 would likely +* for Python library maintainers, both this PEP and :pep:`602` would likely result in user pressure to support the faster release cadence. While this PEP attempts to mitigate that by clearly marking which pre-releases include - potentially breaking changes to the full CPython C ABI, and PEP 602 attempts + potentially breaking changes to the full CPython C ABI, and :pep:`602` attempts to mitigate it by keeping the minimum time between full releases at 12 months, it isn't possible to eliminate this downside completely; -* for third party extension module maintainers, both this PEP and PEP 602 would +* for third party extension module maintainers, both this PEP and :pep:`602` would likely result in user pressure to start supporting the stable ABI in order to provide wheel archives that work on the new version as soon as it is available. Whether that's a net negative or not will depend on how the request @@ -892,11 +892,11 @@ to alternate between traditional stable releases (for 3.8.x, 3.10.x, etc), and release series that used the new rolling release cadence (for 3.9.x, 3.11.x, etc). -This idea suffers from the same core problem as PEP 598 and PEP 602: it imposes +This idea suffers from the same core problem as :pep:`598` and :pep:`602`: it imposes changes on end users that are happy with the status quo without offering them any clear compensating benefit. -It's also affected by one of the main concerns raised against PEP 598: at least +It's also affected by one of the main concerns raised against :pep:`598`: at least some core developers and end users strongly prefer that no particular semantics be assigned to the *value* of any of the numbers in a release version. These community members instead prefer that all the semantic significance be @@ -1209,7 +1209,7 @@ with the specific proposal in this PEP is with Debian, as that has been released in the first half of odd-numbered years since 2005 (roughly 12 months offset from Ubuntu LTS releases). -With the annual release proposal in PEP 602, both Debian and Ubuntu LTS would +With the annual release proposal in :pep:`602`, both Debian and Ubuntu LTS would consistently get a system Python version that is around 6 months old, but would also consistently select different Python versions from each other. @@ -1221,7 +1221,7 @@ releases by the time the Linux distribution ships. If that situation does occur, and is deemed undesirable (but not sufficiently undesirable for *Debian* to choose to adjust their release timing), then that's where the additional complexity of the "incremental feature release" proposal -in PEP 598 may prove worthwhile. +in :pep:`598` may prove worthwhile. (Moving CPython releases to the same half of the year as the Debian and Ubuntu LTS releases would potentially help mitigate the problem, but also creates @@ -1335,7 +1335,7 @@ releases for a longer time without fear of breaking changes. Acknowledgements ================ -Thanks to Łukasz Langa for creating PEP 602 and prompting this discussion of +Thanks to Łukasz Langa for creating :pep:`602` and prompting this discussion of possible improvements to the CPython release cadence, and to Kyle Stanley and h-vetinari for constructive feedback on the initial draft of this PEP. diff --git a/pep-0606.rst b/pep-0606.rst index 87a9cde23fc..964c8d2dcb9 100644 --- a/pep-0606.rst +++ b/pep-0606.rst @@ -76,16 +76,16 @@ The performance overhead of any compatibility code must be low when ``sys.set_python_compat_version()`` is not called. The C API is out of the scope of this PEP: ``Py_LIMITED_API`` macro and -the stable ABI are solving this problem differently, see the `PEP 384: -Defining a Stable ABI `_. +the stable ABI are solving this problem differently, see the :pep:`PEP 384: +Defining a Stable ABI <384>`. Security fixes which break backward compatibility on purpose will not get a compatibility layer; security matters more than compatibility. For example, ``http.client.HTTPSConnection`` was modified in Python 3.4.3 to performs all the necessary certificate and hostname checks by -default. It was a deliberate change motivated by `PEP 476: Enabling +default. It was a deliberate change motivated by :pep:`PEP 476: Enabling certificate verification by default for stdlib http clients -`_ (`bpo-22417 +<476>` (`bpo-22417 `_). The Python language does not provide backward compatibility. @@ -127,8 +127,8 @@ Python 3 is long, and it's getting longer with each Python 3.x release. Cleaning up Python and DeprecationWarning ----------------------------------------- -One of the `Zen of Python (PEP 20) -`_ motto is: +One of the :pep:`Zen of Python (PEP 20) +<20>` motto is: There should be one-- and preferably only one --obvious way to do it. @@ -136,7 +136,7 @@ One of the `Zen of Python (PEP 20) When Python evolves, new ways inevitably emerge. ``DeprecationWarning``\ s are emitted to suggest using the new way, but many developers ignore these warnings, which are silent by default (except in the ``__main__`` -module: see the `PEP 565 `_). +module: see the :pep:`565`). Some developers simply ignore all warnings when there are too many warnings, thus only bother with exceptions when the deprecated code is removed. @@ -393,11 +393,11 @@ means 6 ``.pyc`` files, instead of 3, to support Python 3.8 and Python Temporary moratorium on incompatible changes -------------------------------------------- -In 2009, PEP 3003 "Python Language Moratorium" proposed a +In 2009, :pep:`3003` "Python Language Moratorium" proposed a temporary moratorium (suspension) of all changes to the Python language syntax, semantics, and built-ins for Python 3.1 and Python 3.2. -In May 2018, during the PEP 572 discussions, it was also proposed to slow +In May 2018, during the :pep:`572` discussions, it was also proposed to slow down Python changes: see the python-dev thread `Slow down... `_ @@ -413,8 +413,8 @@ down Python changes: see the python-dev thread `Slow down... PEP 387 ------- -`PEP 387 -- Backwards Compatibility Policy -`_ proposes a process to make +:pep:`PEP 387 -- Backwards Compatibility Policy +<387>` proposes a process to make incompatible changes. The main point is the 4th step of the process: See if there's any feedback. Users not involved in the original @@ -424,11 +424,11 @@ incompatible changes. The main point is the 4th step of the process: PEP 497 ------- -`PEP 497 -- A standard mechanism for backward compatibility -`_ proposes different +:pep:`PEP 497 -- A standard mechanism for backward compatibility +<497>` proposes different solutions to provide backward compatibility. -Except for the ``__past__`` mechanism idea, PEP 497 does not propose +Except for the ``__past__`` mechanism idea, :pep:`497` does not propose concrete solutions: When an incompatible change to core language syntax or semantics is @@ -508,7 +508,7 @@ Examples of Python 3.7 incompatible changes: * ``asyncio`` no longer exports the ``selectors`` and ``_overlapped`` modules as ``asyncio.selectors`` and ``asyncio._overlapped``. Replace ``from asyncio import selectors`` with ``import selectors``. -* PEP 479 is enabled for all code in Python 3.7, meaning that +* :pep:`479` is enabled for all code in Python 3.7, meaning that ``StopIteration`` exceptions raised directly or indirectly in coroutines and generators are transformed into ``RuntimeError`` exceptions. @@ -588,23 +588,23 @@ References Accepted PEPs: -* `PEP 5 -- Guidelines for Language Evolution - `_ -* `PEP 236 -- Back to the __future__ - `_ -* `PEP 411 -- Provisional packages in the Python standard library - `_ -* `PEP 3002 -- Procedure for Backwards-Incompatible Changes - `_ +* :pep:`PEP 5 -- Guidelines for Language Evolution + <5>` +* :pep:`PEP 236 -- Back to the __future__ + <236>` +* :pep:`PEP 411 -- Provisional packages in the Python standard library + <411>` +* :pep:`PEP 3002 -- Procedure for Backwards-Incompatible Changes + <3002>` Draft PEPs: -* `PEP 602 -- Annual Release Cycle for Python - `_ -* `PEP 605 -- A rolling feature release stream for CPython - `_ -* See also withdrawn `PEP 598 -- Introducing incremental feature - releases `_ +* :pep:`PEP 602 -- Annual Release Cycle for Python + <602>` +* :pep:`PEP 605 -- A rolling feature release stream for CPython + <605>` +* See also withdrawn :pep:`PEP 598 -- Introducing incremental feature + releases <598>` Copyright diff --git a/pep-0607.rst b/pep-0607.rst index c8c6bc2a0b4..e1019dddeef 100644 --- a/pep-0607.rst +++ b/pep-0607.rst @@ -16,14 +16,14 @@ Post-History: 20-Oct-2019 Abstract ======== -PEP 602 and PEP 605 describe two alternative approaches to delivering smaller +:pep:`602` and :pep:`605` describe two alternative approaches to delivering smaller collections of features to Python's users more frequently (as compared to the current approach of offering new feature releases every 18-24 months, with the first binary alpha release taking place 6-8 months before the final release). Both PEPs also propose moving to a release cadence that results in full releases -occurring at a consistent time of year (every year for PEP 602, every other -year for PEP 605). +occurring at a consistent time of year (every year for :pep:`602`, every other +year for :pep:`605`). This PEP (from the authors of both competing proposals) provides common background on *why* a change in the release cadence is considered desirable, @@ -44,11 +44,11 @@ given that they include larger pieces of relatively untested code. The easiest way to simplify those investigations and reduce the likelihood of users encountering problems is to reduce the size of the batches being shipped. -PEP 602 proposes to address this problem via the straightforward approach of +:pep:`602` proposes to address this problem via the straightforward approach of reducing CPython's typical batch size by 50%, shipping 12 months of changes each time, rather than accumulating 18+ months of changes. -PEP 605 proposes to address it by regularly delivering 2 months worth of changes +:pep:`605` proposes to address it by regularly delivering 2 months worth of changes to a subset of Python's user base that opts in to running a rolling stream of beta releases (similar to running Windows Insider builds instead of the Windows retail release, or running Debian testing instead of Debian stable). @@ -62,10 +62,10 @@ long period of time between stable releases, it creates an incredibly strong temptation for developers to push changes into stable releases before they're really ready for general use. -PEP 602 proposes to address this problem by reducing the period of time +:pep:`602` proposes to address this problem by reducing the period of time between stable releases to 12 months rather than 18 months. -PEP 605 proposes to address it by actively creating a community of +:pep:`605` proposes to address it by actively creating a community of Python users that regularly install and use CPython beta releases, providing an incentive for core developers to start shipping changes earlier in the pre-release cycle, in order to obtain feedback before the feature gets locked @@ -84,10 +84,10 @@ individual volunteers and for corporate contributors, and also complicates alignment with events like PyCon US (typically April/May) and the now-annual core development sprints (typically in September). -PEP 602 proposes to address this problem by publishing a new release in October +:pep:`602` proposes to address this problem by publishing a new release in October every year, and basing the pre-release calendar for each year off that. -PEP 605 proposes to address this problem by alternating between release years +:pep:`605` proposes to address this problem by alternating between release years (where a new stable release is published in August), and non-release years (where only maintenance releases and new rolling beta releases are published). @@ -106,10 +106,10 @@ literally years to correct any design mistakes identified at that point. Marking APIs as provisional nominally offers a way to avoid that constraint, but actually taking advantage of that freedom causes other problems. -PEP 602 proposes to address this problem by starting the alpha period +:pep:`602` proposes to address this problem by starting the alpha period immediately after the previous stable release. -PEP 605 proposes to address this problem by actively promoting adoption of +:pep:`605` proposes to address this problem by actively promoting adoption of CPython pre-releases for running production workloads (not just for library and application compatibility testing), and adjusting the pre-release management process as necessary to make that a reasonable thing to do. @@ -143,12 +143,12 @@ published CPython release series (for example, Debian stable and Ubuntu LTS sometimes skip releases due to the mismatch between their 24-month release cycles and CPython's typically 18-month cycle). -The faster 12-month full release cadence in PEP 602 means that users in this +The faster 12-month full release cadence in :pep:`602` means that users in this category may end up skipping two releases where they would previously have only skipped one. However, the extended notice period for deprecations means that skipping a single release should no longer result in missed deprecation warnings. -The slower 24-month full release cadence in PEP 605 may move some of the users +The slower 24-month full release cadence in :pep:`605` may move some of the users that have historically been in this category into the "update to every stable release" category. @@ -159,7 +159,7 @@ Impact on users and redistributors that update to every release Many of Python's users never install a pre-release, but do update to every stable release series at some point after it is published. -PEP 602 aims to mitigate the potential negative impact on members of this group +:pep:`602` aims to mitigate the potential negative impact on members of this group by keeping the minimum gap between releases to 12 months, and retaining the 18 month full support period for each release. @@ -167,7 +167,7 @@ Keeping the 18-month full support period for each release branch means that the branches will spend roughly the same amount of time in full support and security-fix-only mode as they do now (~18 months and ~42 months, respectively). -PEP 605 aims to mitigate the potential negative impact on members of this group +:pep:`605` aims to mitigate the potential negative impact on members of this group by increasing use during the pre-release period to achieve more stable final releases with wider ecosystem support at launch. @@ -185,8 +185,8 @@ Despite the difficulties of doing so, there are already some users and redistributors that take on the challenge of using or publishing the CPython master branch directly. -Neither PEP 602 nor PEP 605 should directly affect this group, but the rolling -release stream proposal in PEP 605 aims to lower the barriers to more users +Neither :pep:`602` nor :pep:`605` should directly affect this group, but the rolling +release stream proposal in :pep:`605` aims to lower the barriers to more users adopting this style of usage, by allowing them to adopt the tested rolling beta stream, rather than needing to use the master branch directly. @@ -197,10 +197,10 @@ Impact on maintainers of third party libraries For maintainers of third party libraries, the key source of support complexity is the *number* of different Python versions in widespread use. -PEP 602 aims to mitigate the potential negative impact on members of this group +:pep:`602` aims to mitigate the potential negative impact on members of this group by keeping the minimum gap between full releases to 12 months. -PEP 605 aims to mitigate the potential negative impact on members of this group +:pep:`605` aims to mitigate the potential negative impact on members of this group by increasing the gap between full releases to 24 months, retaining the current policy of moving each release branch to security-fix-only mode not long after its successor is released, and retaining the "beta" naming scheme for the new diff --git a/pep-0608.rst b/pep-0608.rst index e5acb14b56a..43f17afcb7a 100644 --- a/pep-0608.rst +++ b/pep-0608.rst @@ -59,8 +59,7 @@ before a feature can be removed. In practice, DeprecationWarning warnings are ignored for years in major Python projects. Usually, maintainers explain that there are too many warnings and so they simply ignore warnings. Moreover, DeprecationWarning -is silent by default (except in the ``__main__`` module: `PEP 565 -`_). +is silent by default (except in the ``__main__`` module: :pep:`565`). Even if more and more projects are running their test suite with warnings treated as errors (``-Werror``), Python core developers still @@ -86,10 +85,10 @@ all selected projects is available. Shorter Python release schedule ------------------------------- -The `PEP 602: Annual Release Cycle for Python -`_ and the `PEP 605: A +The :pep:`PEP 602: Annual Release Cycle for Python +<602>` and the :pep:`PEP 605: A rolling feature release stream for CPython -`_ would like to release +<605>` would like to release Python more often to ship new features more quickly. The problem is that each Python ``3.x`` release breaks many projects. @@ -203,8 +202,8 @@ Incompatible changes The definition here is large: any Python change which cause an issue when building or testing a project. -See also the `PEP 606: Python Compatibility Version -`_ for more examples of +See also the :pep:`PEP 606: Python Compatibility Version +<606>` for more examples of incompatible changes. Examples @@ -240,8 +239,8 @@ There are different kinds of incompatible changes: Cleaning up Python and DeprecationWarning ----------------------------------------- -One of the `Zen of Python (PEP 20) -`_ motto is: +One of the :pep:`Zen of Python (PEP 20) +<20>` motto is: There should be one-- and preferably only one --obvious way to do it. diff --git a/pep-0610.rst b/pep-0610.rst index d4aacffa44d..810cad81f86 100644 --- a/pep-0610.rst +++ b/pep-0610.rst @@ -14,8 +14,8 @@ Resolution: https://discuss.python.org/t/1535/56 Abstract ======== -Following PEP 440, a distribution can be identified by a name and either a -version, or a direct URL reference (see `PEP440 Direct References`_). +Following :pep:`440`, a distribution can be identified by a name and either a +version, or a direct URL reference (see :pep:`PEP440 Direct References <440#direct-references>`). After installation, the name and version are captured in the project metadata, but currently there is no way to obtain details of the URL used when the distribution was identified by a direct URL reference. @@ -23,7 +23,7 @@ distribution was identified by a direct URL reference. This proposal defines additional metadata, to be added to the installed distribution by the installation front end, which records the Direct URL Origin for use by -consumers which introspect the database of installed packages (see PEP 376). +consumers which introspect the database of installed packages (see :pep:`376`). Provisional acceptance ====================== @@ -55,7 +55,7 @@ Python installers such as pip are capable of downloading and installing distributions from package indexes. They are also capable of downloading and installing source code from requirements specifying arbitrary URLs of source archives and Version Control Systems (VCS) repositories, -as standardized in `PEP440 Direct References`_. +as standardized in :pep:`PEP440 Direct References <440#direct-references>`. In other words, two relevant installation modes exist. @@ -70,7 +70,7 @@ In other words, two relevant installation modes exist. (typically a wheel, a source archive or a VCS repository) and installs it. In this mode, installers typically download the source code in a - temporary directory, invoke the PEP 517 build backend to produce a wheel + temporary directory, invoke the :pep:`517` build backend to produce a wheel if needed, install the wheel, and delete the temporary directory. After installation, no trace of the URL the user requested to download the @@ -132,7 +132,7 @@ revision corresponds to a branch, tag or (in the case of Git) a ref. This information can be used when introspecting the Database of Installed Distributions to communicate to users more information about what version was installed (e.g. whether a branch or tag was installed and, if so, the name of the -branch or tag). This also permits one to know whether a PEP 440 direct +branch or tag). This also permits one to know whether a :pep:`440` direct reference URL can be constructed using the tag form, as only tags have the semantics of immutability. @@ -158,7 +158,7 @@ directory, so the information can be recovered when running "freeze". The use of this workaround, although useful, is fragile, creates confusion about the purpose of the editable mode, and works only when the distribution -can be installed with setuptools (i.e. it is not usable with other PEP 517 +can be installed with setuptools (i.e. it is not usable with other :pep:`517` build backends). When this PEP is implemented, it will not be necessary anymore to use @@ -172,8 +172,9 @@ This PEP specifies a new ``direct_url.json`` metadata file in the ``.dist-info`` directory of an installed distribution. The fields specified are sufficient to reproduce the source archive and `VCS -URLs supported by pip`_. They are also sufficient to reproduce `PEP440 Direct -References`_, as well as `Pipfile and Pipfile.lock`_ entries. Finally, they +URLs supported by pip`_. They are also sufficient to reproduce +:pep:`PEP440 Direct References <440#direct-references>`, +as well as `Pipfile and Pipfile.lock`_ entries. Finally, they are sufficient to record the branch, tag, and/or Git ref origin of the installed version that is already available for editable installs by virtue of a VCS checkout being present. @@ -205,7 +206,7 @@ from a requirement specifying a direct URL reference (including a VCS URL). This file MUST NOT be created when installing a distribution from an other type of requirement (i.e. name plus version specifier). -This JSON file MUST be a dictionary, compliant with `RFC 8259`_ and UTF-8 +This JSON file MUST be a dictionary, compliant with :rfc:`8259` and UTF-8 encoded. If present, it MUST contain at least two fields. The first one is ``url``, with @@ -271,7 +272,7 @@ present as a dictionary with the following key: in editable mode, ``false`` otherwise. If absent, default to ``false``. When ``url`` refers to a local directory, it MUST have the ``file`` scheme -and be compliant with `RFC 8089`_. In particular, the path component must +and be compliant with :rfc:`8089`. In particular, the path component must be absolute. Symbolic links SHOULD be preserved when making relative paths absolute. @@ -515,22 +516,22 @@ there are no backwards compatibility implications. Alternatives ============ -PEP426 source_url ------------------ +PEP 426 source_url +------------------ -The now withdrawn PEP 426 specifies a ``source_url`` metadata entry. +The now withdrawn :pep:`426` specifies a ``source_url`` metadata entry. It is also implemented in `distlib`_. It was intended for a slightly different purpose, for use in sdists. This format lacks support for the ``subdirectory`` option of pip requirement -URLs. The same limitation is present in `PEP440 Direct References`_. +URLs. The same limitation is present in :pep:`PEP440 Direct References <440#direct-references>`. It also lacks explicit support for `environment variables in the user:password part of URLs`_. The introduction of a key/value extensibility mechanism and support -for environment variables for user:password in PEP 440, would be necessary +for environment variables for user:password in :pep:`440`, would be necessary for use in this PEP. revision vs ref @@ -545,14 +546,10 @@ References .. _`pip issue #609`: https://github.com/pypa/pip/issues/609 .. _`thread on discuss.python.org`: https://discuss.python.org/t/pip-freeze-vcs-urls-and-pep-517-feat-editable-installs/1473 -.. _PEP440: http://www.python.org/dev/peps/pep-0440 .. _`VCS URLs supported by pip`: https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support -.. _`PEP440 Direct References`: https://www.python.org/dev/peps/pep-0440/#direct-references .. _`Pipfile and Pipfile.lock`: https://github.com/pypa/pipfile .. _distlib: https://distlib.readthedocs.io .. _`environment variables in the user:password part of URLs`: https://pip.pypa.io/en/stable/reference/pip_install/#id10 -.. _`RFC 8259`: https://tools.ietf.org/html/rfc8259 -.. _`RFC 8089`: https://tools.ietf.org/html/rfc8089 .. _`Recording the Direct URL Origin of installed distributions`: https://packaging.python.org/specifications/direct-url Acknowledgements diff --git a/pep-0612.rst b/pep-0612.rst index 545f314cf8e..e01f2067cea 100644 --- a/pep-0612.rst +++ b/pep-0612.rst @@ -18,9 +18,9 @@ Abstract -------- There currently are two ways to specify the type of a callable, the -``Callable[[int, str], bool]`` syntax defined in `PEP 484 -`_\ , and callback protocols from `PEP -544 `_. Neither of +``Callable[[int, str], bool]`` syntax defined in :pep:`484`, +and callback protocols from :pep:`PEP +544 <544#callback-protocols>`. Neither of these support forwarding the parameter types of one callable over to another callable, making it difficult to annotate function decorators. This PEP proposes ``typing.ParamSpec`` and ``typing.Concatenate`` to @@ -56,12 +56,12 @@ function, is an instance of the Python idiom of one function passing all arguments given to it over to another function. This is done through the combination of the ``*args`` and ``**kwargs`` features in both parameters and in arguments. When one defines a function (like ``inner``\ ) that takes ``(*args, -**kwargs)`` and goes on to call another function with ``(*args, **kwargs)``\ -, the wrapping function can only be safely called in all of the ways that the +**kwargs)`` and goes on to call another function with ``(*args, **kwargs)``, +the wrapping function can only be safely called in all of the ways that the wrapped function could be safely called. To type this decorator, we’d like to be able to place a dependency between the parameters of the callable ``f`` and the -parameters of the returned function. `PEP 484 -`_ supports dependencies between +parameters of the returned function. :pep:`484` +supports dependencies between single types, as in ``def append(l: typing.List[T], e: T) -> typing.List[T]: ...``\ , but there is no existing way to do so with a complicated entity like the parameters of a function. diff --git a/pep-0613.rst b/pep-0613.rst index 540fa2cbee6..92c5bde6f71 100644 --- a/pep-0613.rst +++ b/pep-0613.rst @@ -22,7 +22,7 @@ Motivation ========== Type aliases are declared as top level variable assignments. -In `PEP 484 `_, +In :pep:`PEP 484 <484#type-aliases>`, the distinction between a valid type alias and a global variable was implicitly determined: if a top level assignment is unannotated, and the assigned value is a valid type, then the name being assigned to is a valid type alias. Otherwise, diff --git a/pep-0615.rst b/pep-0615.rst index 18dd4340c29..f5446760610 100644 --- a/pep-0615.rst +++ b/pep-0615.rst @@ -54,8 +54,8 @@ time zone database (also called the "tz" database or the Olson database [#tzdb-wiki]_). The time zone database is in the public domain and is widely distributed — it is present by default on many Unix-like operating systems. Great care goes into the stability of the database: there are IETF RFCs both -for the maintenance procedures (RFC 6557 [#rfc6557]_) and for the compiled -binary (TZif) format (RFC 8636 [#rfc8536]_). As such, it is likely that adding +for the maintenance procedures (:rfc:`6557`) and for the compiled +binary (TZif) format (:rfc:`8636`). As such, it is likely that adding support for the compiled outputs of the IANA database will add great value to end users even with the relatively long cadence of standard library releases. @@ -642,7 +642,7 @@ minimal real world effects were it to occur. Including ``tzdata`` in the standard library by default ------------------------------------------------------- -Although PEP 453 [#pep453-ensurepip]_, which introduced the ``ensurepip`` +Although :pep:`453`, which introduced the ``ensurepip`` mechanism to CPython, provides a convenient template for a standard library module maintained on PyPI, a potentially similar ``ensuretzdata`` mechanism is somewhat less necessary, and would be complicated enough that it is considered @@ -673,9 +673,9 @@ is not used by the ``zoneinfo`` module. Using a ``pytz``-like interface ------------------------------- -A ``pytz``-like ([#pytz]_) interface was proposed in PEP 431 [#pep431]_, but +A ``pytz``-like ([#pytz]_) interface was proposed in :pep:`431`, but was ultimately withdrawn / rejected for lack of ambiguous datetime support. -PEP 495 [#pep495]_ added the ``fold`` attribute to address this problem, but +:pep:`495` added the ``fold`` attribute to address this problem, but ``fold`` obviates the need for ``pytz``'s non-standard ``tzinfo`` classes, and so a ``pytz``-like interface is no longer necessary. [#fastest-footgun]_ @@ -738,7 +738,7 @@ There are several other schemes that were considered and rejected: One advantage to this scheme would be that it would add a natural extension point for specifying non-file-based elements on the search path, such as changing the priority of ``tzdata`` if it exists, or if native support for - TZDIST [#rfc7808]_ were to be added to the library in the future. + :rfc:`TZDIST <7808>` were to be added to the library in the future. This was rejected mainly because these sort of special values are not usually found in ``PATH``-like variables and the only currently proposed use @@ -814,7 +814,7 @@ Arguments against this: imported), and it is a perennial source of confusion for end users. This confusing requirement from end-users can be avoided using a - module-level ``__getattr__`` and ``__dir__`` per PEP 562, but this would + module-level ``__getattr__`` and ``__dir__`` per :pep:`562`, but this would add some complexity to the implementation of the ``datetime`` module. This sort of behavior in modules or classes tends to confuse static analysis tools, which may not be desirable for a library as widely used and critical @@ -864,18 +864,6 @@ Footnotes References ========== -.. [#rfc6557] - RFC 6557: Procedures for Maintaining the Time Zone Database - https://tools.ietf.org/html/rfc6557 - -.. [#rfc7808] - RFC 7808: Time Zone Data Distribution Service - https://tools.ietf.org/html/rfc7808 - -.. [#rfc8536] - RFC 8536: The Time Zone Information Format (TZif) - https://tools.ietf.org/html/rfc8536 - .. [#nontransitive_comp] Paul Ganssle: "A curious case of non-transitive datetime comparison" (Published 15 February 2018) @@ -915,18 +903,6 @@ References Davis) https://pyfound.blogspot.com/2019/05/russell-keith-magee-python-on-other.html -.. [#pep453-ensurepip] - PEP 453: Explicit bootstrapping of pip in Python installations - https://www.python.org/dev/peps/pep-0453/ - -.. [#pep431] - PEP 431: Time zone support improvements - https://www.python.org/dev/peps/pep-0431/ - -.. [#pep495] - PEP 495: Local Time Disambiguation - https://www.python.org/dev/peps/pep-0495/ - .. [#tzinfo] ``datetime.tzinfo`` documentation https://docs.python.org/3/library/datetime.html#datetime.tzinfo diff --git a/pep-0619.rst b/pep-0619.rst index 103b136bba2..631e6bfb66c 100644 --- a/pep-0619.rst +++ b/pep-0619.rst @@ -38,7 +38,7 @@ Release Schedule Note: the dates below use a 17-month development period that results in a 12-month release cadence between major versions, as defined by -PEP 602. +:pep:`602`. Actual: diff --git a/pep-0620.rst b/pep-0620.rst index d1f7ebbafb5..4dd4254f381 100644 --- a/pep-0620.rst +++ b/pep-0620.rst @@ -36,9 +36,9 @@ The C API blocks CPython evolutions Adding or removing members of C structures is causing multiple backward compatibility issues. -Adding a new member breaks the stable ABI (PEP 384), especially for +Adding a new member breaks the stable ABI (:pep:`384`), especially for types declared statically (e.g. ``static PyTypeObject MyType = -{...};``). In Python 3.4, the PEP 442 "Safe object finalization" added +{...};``). In Python 3.4, the :pep:`442` "Safe object finalization" added the ``tp_finalize`` member at the end of the ``PyTypeObject`` structure. For ABI backward compatibility, a new ``Py_TPFLAGS_HAVE_FINALIZE`` type flag was required to announce if the type structure contains the @@ -163,12 +163,12 @@ Hiding implementation details from the C API has multiple advantages: Relationship with the limited C API ----------------------------------- -The PEP 384 "Defining a Stable ABI" is implemented in Python 3.4. It introduces the +The :pep:`384` "Defining a Stable ABI" is implemented in Python 3.4. It introduces the "limited C API": a subset of the C API. When the limited C API is used, it becomes possible to build a C extension only once and use it on multiple Python versions: that's the stable ABI. -The main limitation of the PEP 384 is that C extensions have to opt-in +The main limitation of the :pep:`384` is that C extensions have to opt-in for the limited C API. Only very few projects made this choice, usually to ease distribution of binaries, especially on Windows. @@ -313,7 +313,7 @@ not only ``PyObject*``, to avoid compiler warnings, since most macros cast their parameters to ``PyObject*``. Python 3.6 requires C compilers to support static inline functions: the -PEP 7 requires a subset of C99. +:pep:`7` requires a subset of C99. **STATUS**: Completed (in Python 3.9) @@ -377,7 +377,7 @@ Making ``PyTypeObject`` structure opaque breaks C extensions declaring types statically (e.g. ``static PyTypeObject MyType = {...};``). C extensions must use ``PyType_FromSpec()`` to allocate types on the heap instead. Using heap types has other advantages like being compatible -with subinterpreters. Combined with PEP 489 "Multi-phase extension +with subinterpreters. Combined with :pep:`489` "Multi-phase extension module initialization", it makes a C extension behavior closer to a Python module, like allowing to create more than one module instance. diff --git a/pep-0621.rst b/pep-0621.rst index 6db3c63401e..20867feb856 100644 --- a/pep-0621.rst +++ b/pep-0621.rst @@ -282,7 +282,7 @@ meaning is open to interpretation. These fields accept an array of tables with 2 keys: ``name`` and ``email``. Both values must be strings. The ``name`` value MUST be a valid email name (i.e. whatever can be put as a name, before an email, -in `RFC #822`_) and not contain commas. The ``email`` value MUST be a +in :rfc:`822`) and not contain commas. The ``email`` value MUST be a valid email address. Both keys are optional. Using the data to fill in `core metadata`_ is as follows: @@ -720,7 +720,6 @@ CC0-1.0-Universal license, whichever is more permissive. .. _survey of tools: https://github.com/uranusjr/packaging-metadata-comparisons .. _trove classifiers: https://pypi.org/classifiers/ .. _SPDX: https://spdx.dev/ -.. _RFC #822: https://tools.ietf.org/html/rfc822 .. _entry points specification: https://packaging.python.org/specifications/entry-points/ .. diff --git a/pep-0622.rst b/pep-0622.rst index ed9582b77cd..05c697322b4 100644 --- a/pep-0622.rst +++ b/pep-0622.rst @@ -879,7 +879,7 @@ the match suite, or after the match statement. However, the name will Technically, most such examples can be rewritten using guards and/or nested match statements, but this will be less readable and/or will produce less -efficient code. Essentially, most of the arguments in PEP 572 apply here +efficient code. Essentially, most of the arguments in :pep:`572` apply here equally. The wildcard ``_`` is not a valid name here. @@ -1036,8 +1036,8 @@ thus forcing people to add safety asserts like this:: else: assert False, "should never get here" -PEP 484 specifies that static type checkers should support exhaustiveness in -conditional checks with respect to enum values. PEP 586 later generalized this +:pep:`484` specifies that static type checkers should support exhaustiveness in +conditional checks with respect to enum values. :pep:`586` later generalized this requirement to literal types. This PEP further generalizes this requirement to @@ -1081,7 +1081,7 @@ and enum values are combined:: ... # Type-checking error: basic user unhandled -Obviously, no ``Matchable`` protocol (in terms of PEP 544) is needed, since +Obviously, no ``Matchable`` protocol (in terms of :pep:`544`) is needed, since every class is matchable and therefore is subject to the checks specified above. @@ -1168,7 +1168,7 @@ match:: Note that the above snippet actually fails at runtime with the current implementation of generic classes in the ``typing`` module, as well as -with builtin generic classes in the recently accepted PEP 585, because +with builtin generic classes in the recently accepted :pep:`585`, because they prohibit ``isinstance`` checks. To clarify, generic classes are not prohibited in general from participating @@ -1224,7 +1224,7 @@ Precise type checking of star matches Type checkers should perform precise type checking of star items in pattern matching giving them either a heterogeneous ``list[T]`` type, or -a ``TypedDict`` type as specified by PEP 589. For example:: +a ``TypedDict`` type as specified by :pep:`589`. For example:: stuff: Tuple[int, str, str, float] @@ -1277,7 +1277,7 @@ desire to break or deprecate. The difference between hard and soft keywords is that hard keywords are *always* reserved words, even in positions where they make no sense (e.g. ``x = class + 1``), while soft keywords only get a special -meaning in context. Since PEP 617 the parser backtracks, that means that on +meaning in context. Since :pep:`617` the parser backtracks, that means that on different attempts to parse a code fragment it could interpret a soft keyword differently. @@ -1554,7 +1554,7 @@ ambiguous with capture patterns. Five other alternatives were considered: case side: ... # Assigns side = entree[-1]. This works well with the recommendations for naming constants from - PEP 8. The main objection is that there's no other part of core + :pep:`8`. The main objection is that there's no other part of core Python where the case of a name is semantically significant. In addition, Python allows identifiers to use different scripts, many of which (e.g. CJK) don't have a case distinction. diff --git a/pep-0623.rst b/pep-0623.rst index c1d26354797..3bf1010a5ac 100644 --- a/pep-0623.rst +++ b/pep-0623.rst @@ -12,9 +12,9 @@ Python-Version: 3.10 Abstract ======== -PEP 393 deprecated some unicode APIs, and introduced ``wchar_t *wstr``, +:pep:`393` deprecated some unicode APIs, and introduced ``wchar_t *wstr``, and ``Py_ssize_t wstr_length`` in the Unicode structure to support -these deprecated APIs. [1]_ +these deprecated APIs. This PEP is planning removal of ``wstr``, and ``wstr_length`` with deprecated APIs using these members by Python 3.12. @@ -59,14 +59,14 @@ Rationale Python 4.0 is not scheduled yet ------------------------------- -PEP 393 introduced efficient internal representation of Unicode and +:pep:`393` introduced efficient internal representation of Unicode and removed border between "narrow" and "wide" build of Python. -PEP 393 was implemented in Python 3.3 which is released in 2012. Old +:pep:`393` was implemented in Python 3.3 which is released in 2012. Old APIs were deprecated since then, and the removal was scheduled in Python 4.0. -Python 4.0 was expected as next version of Python 3.9 when PEP 393 +Python 4.0 was expected as next version of Python 3.9 when :pep:`393` was accepted. But the next version of Python 3.9 is Python 3.10, not 4.0. This is why this PEP schedule the removal plan again. @@ -74,7 +74,7 @@ not 4.0. This is why this PEP schedule the removal plan again. Python 2 reached EOL -------------------- -Since Python 2 didn't have PEP 393 Unicode implementation, legacy +Since Python 2 didn't have :pep:`393` Unicode implementation, legacy APIs might help C extension modules supporting both of Python 2 and 3. But Python 2 reached the EOL in 2020. We can remove legacy APIs kept @@ -183,9 +183,6 @@ References They no longer cache the ``wchar_t*`` representation of string objects. -.. [1] PEP 393 -- Flexible String Representation - (https://www.python.org/dev/peps/pep-0393/) - Copyright ========= diff --git a/pep-0624.rst b/pep-0624.rst index 18545fe093b..30b6fb1baf0 100644 --- a/pep-0624.rst +++ b/pep-0624.rst @@ -30,7 +30,7 @@ This PEP proposes to remove deprecated ``Py_UNICODE`` encoder APIs in Python 3.1 .. note:: - `PEP 623 `_ propose to remove + :pep:`623` propose to remove Unicode object APIs relating to ``Py_UNICODE``. On the other hand, this PEP is not relating to Unicode object. These PEPs are split because they have different motivations and need different discussions. diff --git a/pep-0627.rst b/pep-0627.rst index 5a1a3e59528..239ecfc81bd 100644 --- a/pep-0627.rst +++ b/pep-0627.rst @@ -20,7 +20,7 @@ Packaging Authority (PyPA) standards repository, and sets up guidelines for changing it. Two files in installed ``.dist-info`` directories are made optional: -``RECORD`` (which PEP 376 lists as mandatory, but suggests it can be left out +``RECORD`` (which :pep:`376` lists as mandatory, but suggests it can be left out for "system packages"), and ``INSTALLER``. @@ -30,11 +30,11 @@ Motivation Python packaging is moving from relying on specific tools (Setuptools and pip) toward an ecosystem of tools and tool-agnostic interoperability standards. -PEP 376 is not written as an interoperability standard. +:pep:`376` is not written as an interoperability standard. It describes implementation details of specific tools and libraries, and is underspecified, leaving much room for implementation-defined behavior. -This is a proposal to “distill” the standard from PEP 376, clarify it, +This is a proposal to “distill” the standard from :pep:`376`, clarify it, and rewrite it to be tool-agnostic. The aim of this PEP is to have a better standard, not necessarily a perfect one. @@ -44,7 +44,7 @@ Some issues are left to later clarification. Rationale Change ================ -PEP 376's rationale focuses on two problems: +:pep:`376`'s rationale focuses on two problems: * There are too many ways to install projects and this makes interoperation difficult. * There is no API to get information on installed distributions. @@ -86,7 +86,7 @@ to *Recording installed projects*. While putting files in known locations on disk may be thought of as a “database”, it's not what most people think about when they hear the term. -The PyPA links to PEP 376 under the heading *Recording installed distributions*. +The PyPA links to :pep:`376` under the heading *Recording installed distributions*. The PyPA glossary defines “Distribution” (or, “Distribution Package” to prevent confusion with e.g. Linux distributions) as “A versioned archive file […]”. @@ -134,9 +134,9 @@ The “base” of relative paths in ``RECORD`` is specified relative to the Both *hash* and *size* fields are now optional (for any file, not just ``.pyc``, ``.pyo`` and ``RECORD``). Leavng them out is discouraged, except for ``*.pyc`` and ``RECORD`` itself. -(Note that PEP 376 is unclear on what was optional; when taken literally, +(Note that :pep:`376` is unclear on what was optional; when taken literally, its text and examples contradict. Despite that, “both fields are optional“ is a -reasonable interpretation of PEP 376. +reasonable interpretation of :pep:`376`. The alternative would be to mandate—rather than recommend—which files can be recorded without hash and size, and to update that list over time as new use cases come up.) @@ -156,7 +156,7 @@ Tools must not uninstall/remove projects that lack a ``RECORD`` file managers of Linux distros). On Windows, files in ``RECORD`` may be separated by either ``/`` or ``\``. -PEP 376 was unclear on this: it mandates forward slashes in one place, but +:pep:`376` was unclear on this: it mandates forward slashes in one place, but shows backslackes in a Windows-specific example. diff --git a/pep-0629.rst b/pep-0629.rst index 537fdf33d28..a58c0f730c0 100644 --- a/pep-0629.rst +++ b/pep-0629.rst @@ -53,9 +53,9 @@ Overview This PEP proposes the inclusion of a meta tag on the responses of every successful request to a simple API page, which contains a name attribute -of "pypi:repository-version", and a content that is a PEP 440 compatible +of "pypi:repository-version", and a content that is a :pep:`440` compatible version number, which is further constrained to ONLY be Major.Minor, and -none of the additional features supported by PEP 440. +none of the additional features supported by :pep:`440`. This would end up looking like:: diff --git a/pep-0630.rst b/pep-0630.rst index 10416182fa8..5ca9d02e6dc 100644 --- a/pep-0630.rst +++ b/pep-0630.rst @@ -28,7 +28,7 @@ per-module state from code. About this document ------------------- -As an `informational PEP `__, +As an :pep:`informational PEP <1#pep-types>`, this document does not introduce any changes: those should be done in their own PEPs (or issues, if small enough). Rather, it covers the motivation behind an effort that spans multiple releases, and instructs @@ -46,10 +46,10 @@ early. PEPs related to this effort are: -- PEP 384 -- *Defining a Stable ABI*, which added C API for creating +- :pep:`384` -- *Defining a Stable ABI*, which added C API for creating heap types -- PEP 489 -- *Multi-phase extension module initialization* -- PEP 573 -- *Module State Access from C Extension Methods* +- :pep:`489` -- *Multi-phase extension module initialization* +- :pep:`573` -- *Module State Access from C Extension Methods* This document is concerned with Python's public C API, which is not offered by all implementations of Python. However, nothing in this PEP is @@ -110,7 +110,7 @@ Goal: Easy-to-use Module State ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is currently cumbersome or impossible to do everything the C API -offers while keeping modules isolated. Enabled by PEP 384, changes in +offers while keeping modules isolated. Enabled by :pep:`384`, changes in PEPs 489 and 573 (and future planned ones) aim to first make it *possible* to build modules this way, and then to make it *easy* to write new modules this way and to convert old ones, so that it can @@ -228,7 +228,7 @@ Managing Per-Module State To use per-module state, use `multi-phase extension module initialization `__ -introduced in PEP 489. This signals that your module supports multiple +introduced in :pep:`489`. This signals that your module supports multiple interpreters correctly. Set ``PyModuleDef.m_size`` to a positive number to request that many @@ -357,7 +357,7 @@ Module State Access from Regular Methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Accessing the module-level state from methods of a class is somewhat -more complicated, but possible thanks to changes introduced in PEP 573. +more complicated, but possible thanks to changes introduced in :pep:`573`. To get the state, you need to first get the *defining class*, and then get the module state from it. diff --git a/pep-0631.rst b/pep-0631.rst index 4820d6e9493..14a51e4370a 100644 --- a/pep-0631.rst +++ b/pep-0631.rst @@ -15,7 +15,7 @@ Abstract This PEP specifies how to write a project's dependencies in a ``pyproject.toml`` file for packaging-related tools to consume -using the `fields defined in PEP 621`_. +using the :pep:`fields defined in PEP 621 <621#dependencies-optional-dependencies>`. .. note:: This PEP has been accepted and is expected to be merged into @@ -24,7 +24,7 @@ using the `fields defined in PEP 621`_. Entries ======= -All dependency entries MUST be valid `PEP 508 strings`_. +All dependency entries MUST be valid :pep:`PEP 508 strings <508>`. Build backends SHOULD abort at load time for any parsing errors. @@ -222,8 +222,6 @@ This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. -.. _fields defined in PEP 621: https://www.python.org/dev/peps/pep-0621/#dependencies-optional-dependencies -.. _PEP 508 strings: https://www.python.org/dev/peps/pep-0508/ .. _Requires-Dist: https://packaging.python.org/specifications/core-metadata/#requires-dist-multiple-use .. _Provides-Extra: https://packaging.python.org/specifications/core-metadata/#provides-extra-multiple-use .. _docker-compose: https://github.com/docker/compose/blob/789bfb0e8b2e61f15f423d371508b698c64b057f/setup.py#L28-L61 diff --git a/pep-0632.rst b/pep-0632.rst index 3f225d4e79e..efd40ec6eed 100644 --- a/pep-0632.rst +++ b/pep-0632.rst @@ -58,7 +58,7 @@ Deprecation and removal will make it obvious that issues should be fixed in the setuptools project, and will reduce a source of bug reports and unnecessary test maintenance. It will also help promote the development of alternative build backends, which can now be -supported more easily thanks to PEP 517. [4]_ +supported more easily thanks to :pep:`517`. Specification @@ -119,7 +119,7 @@ Code that imports distutils will no longer work from Python 3.12. The suggested migration path is to use the equivalent (though not identical) imports from setuptools (see [5]_), or to migrate to an -alternative build backend (see PEP 517 [4]_). +alternative build backend (see :pep:`517`). Code already exists in setuptools to transparently switch ``setup.py`` files using distutils onto their equivalents, and so most working @@ -247,9 +247,6 @@ References .. [3] setuptools Issue #417 - Adopt distutils (https://github.com/pypa/setuptools/issues/417) -.. [4] PEP 517 - A build-system independent format for source trees - (https://www.python.org/dev/peps/pep-0517/) - .. [5] Porting from Distutils (https://setuptools.readthedocs.io/en/latest/deprecated/distutils-legacy.html) diff --git a/pep-0634.rst b/pep-0634.rst index 8067a05c9b0..f6414365be3 100644 --- a/pep-0634.rst +++ b/pep-0634.rst @@ -20,15 +20,15 @@ Abstract ======== This PEP provides the technical specification for the match -statement. It replaces PEP 622, which is hereby split in three parts: +statement. It replaces :pep:`622`, which is hereby split in three parts: -- PEP 634: Specification -- PEP 635: Motivation and Rationale -- PEP 636: Tutorial +- :pep:`634`: Specification +- :pep:`635`: Motivation and Rationale +- :pep:`636`: Tutorial This PEP is intentionally devoid of commentary; the motivation and all -explanations of our design choices are in PEP 635. First-time readers -are encouraged to start with PEP 636, which provides a gentler +explanations of our design choices are in :pep:`635`. First-time readers +are encouraged to start with :pep:`636`, which provides a gentler introduction to the concepts, syntax and semantics of patterns. @@ -275,7 +275,7 @@ The single underscore (``_``) is not a capture pattern (this is what A capture pattern always succeeds. It binds the subject value to the name using the scoping rules for name binding established for the -walrus operator in PEP 572. (Summary: the name becomes a local +walrus operator in :pep:`572`. (Summary: the name becomes a local variable in the closest containing function scope unless there's an applicable ``nonlocal`` or ``global`` statement.) diff --git a/pep-0635.rst b/pep-0635.rst index edb6d4aa8ba..97a547aa3cf 100644 --- a/pep-0635.rst +++ b/pep-0635.rst @@ -18,9 +18,9 @@ Resolution: https://mail.python.org/archives/list/python-committers@python.org/m Abstract ======== -This PEP provides the motivation and rationale for PEP 634 +This PEP provides the motivation and rationale for :pep:`634` ("Structural Pattern Matching: Specification"). First-time readers -are encouraged to start with PEP 636, which provides a gentler +are encouraged to start with :pep:`636`, which provides a gentler introduction to the concepts, syntax and semantics of patterns. @@ -155,7 +155,7 @@ Rationale This section provides the rationale for individual design decisions. It takes the place of "Rejected ideas" in the standard PEP format. -It is organized in sections corresponding to the specification (PEP 634). +It is organized in sections corresponding to the specification (:pep:`634`). Overview and Terminology @@ -775,7 +775,7 @@ ultimate "wildcard", it does not convey the desired semantics. An alternative that does not suggest an arbitrary number of items would be ``?``. This is even being proposed independently from -pattern matching in PEP 640. We feel however that using ``?`` as a +pattern matching in :pep:`640`. We feel however that using ``?`` as a special "assignment" target is likely more confusing to Python users than using ``_``. It violates Python's (admittedly vague) principle of using punctuation characters only in ways similar to how they are @@ -790,7 +790,7 @@ globbing, "maybe" in regular expressions, "conditional expression" in C and many C-derived languages, "predicate function" in Scheme, "modify error handling" in Rust, "optional argument" and "optional chaining" in TypeScript (the latter meaning has also been proposed for -Python by PEP 505). An as yet unnamed PEP proposes it to mark +Python by :pep:`505`). An as yet unnamed PEP proposes it to mark optional types, e.g. ``int?``. Another common use of ``?`` in programming systems is "help", for @@ -1235,7 +1235,7 @@ an instance of ``Node`` but only extract the value of the ``right`` attribute. Backwards Compatibility ======================= -Through its use of "soft keywords" and the new PEG parser (PEP 617), +Through its use of "soft keywords" and the new PEG parser (:pep:`617`), the proposal remains fully backwards compatible. However, 3rd party tooling that uses a LL(1) parser to parse Python source code may be forced to switch parser technology to be able to support those same diff --git a/pep-0636.rst b/pep-0636.rst index ccec6ed05ac..b476f7c59f4 100644 --- a/pep-0636.rst +++ b/pep-0636.rst @@ -18,16 +18,16 @@ Resolution: https://mail.python.org/archives/list/python-committers@python.org/m Abstract ======== -This PEP is a tutorial for the pattern matching introduced by PEP 634. +This PEP is a tutorial for the pattern matching introduced by :pep:`634`. -PEP 622 proposed syntax for pattern matching, which received detailed discussion +:pep:`622` proposed syntax for pattern matching, which received detailed discussion both from the community and the Steering Council. A frequent concern was about how easy it would be to explain (and learn) this feature. This PEP addresses that concern providing the kind of document which developers could use to learn about pattern matching in Python. -This is considered supporting material for PEP 634 (the technical specification -for pattern matching) and PEP 635 (the motivation and rationale for having pattern +This is considered supporting material for :pep:`634` (the technical specification +for pattern matching) and :pep:`635` (the motivation and rationale for having pattern matching and design considerations). For readers who are looking more for a quick review than for a tutorial, @@ -435,7 +435,7 @@ Any class is a valid match target, and that includes built-in classes like ``boo ``str`` or ``int``. That allows us to combine the code above with a class pattern. So instead of writing ``{"text": message, "color": c}`` we can use ``{"text": str() as message, "color": str() as c}`` to ensure that ``message`` and ``c`` -are both strings. For many builtin classes (see PEP-634 for the whole list), you can +are both strings. For many builtin classes (see :pep:`634` for the whole list), you can use a positional parameter as a shorthand, writing ``str(c)`` rather than ``str() as c``. The fully rewritten version looks like this:: diff --git a/pep-0637.rst b/pep-0637.rst index 50cd30d63c2..100fe9f7821 100644 --- a/pep-0637.rst +++ b/pep-0637.rst @@ -42,7 +42,7 @@ arguments is also provided:: >>> val = x[*(1, 2), **{a=3, b=4}] # Equivalent to above. -This PEP is a successor to PEP 472, which was rejected due to lack of +This PEP is a successor to :pep:`472`, which was rejected due to lack of interest in 2019. Since then there's been renewed interest in the feature. Overview @@ -51,7 +51,7 @@ Overview Background ---------- -PEP 472 was opened in 2014. The PEP detailed various use cases and was created by +:pep:`472` was opened in 2014. The PEP detailed various use cases and was created by extracting implementation strategies from a broad discussion on the python-ideas mailing list, although no clear consensus was reached on which strategy should be used. Many corner cases have been examined more closely and felt @@ -60,7 +60,7 @@ awkward, backward incompatible or both. The PEP was eventually rejected in 2019 [#rejection]_ mostly due to lack of interest for the feature despite its 5 years of existence. -However, with the introduction of type hints in PEP 484 [#pep-0484]_ the +However, with the introduction of type hints in :pep:`484` the square bracket notation has been used consistently to enrich the typing annotations, e.g. to specify a list of integers as Sequence[int]. Additionally, there has been an expanded growth of packages for data analysis such as pandas @@ -160,7 +160,7 @@ specification would improve notation and provide additional value: >>> # The call is now shorter, more mnemonic, and looks+works like typing >>> trio.run[name="func"](func, value1, param2=value2) -7. Availability of star arguments would benefit PEP-646 Variadic Generics [#pep-0646]_, +7. Availability of star arguments would benefit :pep:`646` Variadic Generics, especially in the forms ``a[*x]`` and ``a[*x, *y, p, q, *z]``. The PEP details exactly this notation in its "Unpacking: Star Operator" section. @@ -480,7 +480,7 @@ The successful implementation of this PEP will result in the following behavior: obj[] # Invalid. 12. The same semantics given above must be extended to ``__class__getitem__``: - Since PEP 560, type hints are dispatched so that for ``x[y]``, if no + Since :pep:`560`, type hints are dispatched so that for ``x[y]``, if no ``__getitem__`` method is found, and ``x`` is a type (class) object, and ``x`` has a class method ``__class_getitem__``, that method is called. The same changes should be applied to this method as well, @@ -689,9 +689,9 @@ A reference implementation is currently being developed here [#reference-impl]_. Workarounds =========== -Every PEP that changes the Python language should "clearly explain why +Every PEP that changes the Python language should :pep:`"clearly explain why the existing language specification is inadequate to address the -problem that the PEP solves." [#pep-0001]_ +problem that the PEP solves" <1#what-belongs-in-a-successful-pep>`. Some rough equivalents to the proposed extension, which we call work-arounds, are already possible. The work-arounds provide an alternative to enabling the @@ -755,7 +755,7 @@ Rejected Ideas Previous PEP 472 solutions -------------------------- -PEP 472 presents a good amount of ideas that are now all to be considered +:pep:`472` presents a good amount of ideas that are now all to be considered Rejected. A personal email from D'Aprano to the author specifically said: I have now carefully read through PEP 472 in full, and I am afraid I @@ -765,7 +765,7 @@ We agree that those options are inferior to the currently presented, for one reason or another. To keep this document compact, we will not present here the objections for -all options presented in PEP 472. Suffice to say that they were discussed, +all options presented in :pep:`472`. Suffice to say that they were discussed, and each proposed alternative had one or few dealbreakers. Adding new dunders @@ -842,7 +842,7 @@ Has problems similar to the above. create a new "kwslice" object ----------------------------- -This proposal has already been explored in "New arguments contents" P4 in PEP 472:: +This proposal has already been explored in "New arguments contents" P4 in :pep:`472`:: obj[a, b:c, x=1] # calls type(obj).__getitem__(obj, a, slice(b, c), key(x=1)) @@ -1096,18 +1096,12 @@ References .. [#rejection] "Rejection of PEP 472" (https://mail.python.org/pipermail/python-dev/2019-March/156693.html) -.. [#pep-0484] "PEP 484 -- Type hints" - (https://www.python.org/dev/peps/pep-0484) .. [#request-1] "Allow kwargs in __{get|set|del}item__" (https://mail.python.org/archives/list/python-ideas@python.org/thread/EUGDRTRFIY36K4RM3QRR52CKCI7MIR2M/) .. [#request-2] "PEP 472 -- Support for indexing with keyword arguments" (https://mail.python.org/archives/list/python-ideas@python.org/thread/6OGAFDWCXT5QVV23OZWKBY4TXGZBVYZS/) -.. [#pep-0001] "PEP 1 -- PEP Purpose and Guidelines" - (https://www.python.org/dev/peps/pep-0001/#what-belongs-in-a-successful-pep) .. [#trio-run] "trio.run() should take \*\*kwargs in addition to \*args" (https://github.com/python-trio/trio/issues/470) -.. [#pep-0646] "PEP 646 -- Variadic Generics" - (https://www.python.org/dev/peps/pep-0646) .. [#numpy-ml] "[Numpy-discussion] Request for comments on PEP 637 - Support for indexing with keyword arguments" (http://numpy-discussion.10968.n7.nabble.com/Request-for-comments-on-PEP-637-Support-for-indexing-with-keyword-arguments-td48489.html) .. [#reference-impl] "Reference implementation" diff --git a/pep-0638.rst b/pep-0638.rst index 2e18842480a..710303462cc 100644 --- a/pep-0638.rst +++ b/pep-0638.rst @@ -433,7 +433,7 @@ Which could be converted to: Zero-cost markers and annotations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Annotations, either decorators or PEP 3107 function annotations, have a runtime cost +Annotations, either decorators or :pep:`3107` function annotations, have a runtime cost even if they serve only as markers for checkers or as documentation. :: diff --git a/pep-0639.rst b/pep-0639.rst index 9c7e8b15ca9..7683e2d97bd 100644 --- a/pep-0639.rst +++ b/pep-0639.rst @@ -37,7 +37,7 @@ The PEP also: and ``license ::`` classifiers. - `Adds and deprecates `_ the corresponding keys - in the PEP 621 project source metadata format. + in the :pep:`621` project source metadata format. - `Provides clear guidance `_ for authors and tools converting legacy license metadata, adding license files and @@ -231,8 +231,8 @@ This PEP seeks to clearly define the terms it uses, specifically those that: wheel *format* vs. Wheel *project*). - Are related and often used interchangeably, but have critical - distinctions in meaning (e.g. PEP 621 *key* vs. core metadata *field*, - a point of apparent confusion in PEP 621 with significant effects on this + distinctions in meaning (e.g. :pep:`621` *key* vs. core metadata *field*, + a point of apparent confusion in :pep:`621` with significant effects on this PEP). - Are existing concepts that don't have formal terms/definitions @@ -270,7 +270,7 @@ for the purposes of this PEP (``Syn:``). **Core Metadata Field** *(Short: Metadata Field/Field)* A single key-value pair, or sequence of such with the same key, as defined - by the core metadata specification. Notably, *not* a PEP 621 project + by the core metadata specification. Notably, *not* a :pep:`621` project metadata format key. **Distribution Package** *(Sub: Package, Distribution Archive)* @@ -283,7 +283,7 @@ for the purposes of this PEP (``Syn:``). specifically references the physical **distribution archive**. **License Classifier** - A `PyPI Trove classifier <#classifiers_>`_ (as originally defined in PEP 301) + A `PyPI Trove classifier <#classifiers_>`_ (as originally defined in :pep:`301`) which begins with ``License ::``, currently used to indicate a project's license status by including it as a ``Classifier`` in the core metadata. @@ -314,7 +314,7 @@ for the purposes of this PEP (``Syn:``). **Project Source Metadata** *(Sub: PEP 621 Metadata, Key, Subkey)* Core metadata defined by the package author in the project source tree, - as top-level keys in the ``[project]`` table of a PEP 621 ``pyproject.toml``, + as top-level keys in the ``[project]`` table of a :pep:`621` ``pyproject.toml``, in the ``[metadata]`` table of ``setup.cfg``, or the equivalent for other build tools. @@ -323,7 +323,7 @@ for the purposes of this PEP (``Syn:``). A **PEP 621 metadata key**, or an unqualified *key* refers specifically to a top-level ``[project]`` key (notably, *not* a core metadata *field*), while a **subkey** refers to a second-level key in a table-valued - PEP 621 key. + :pep:`621` key. **Root License Directory** *(Short: License Directory)* The directory under which license files are stored in a project/distribution @@ -348,7 +348,7 @@ for the purposes of this PEP (``Syn:``). A **build tool** is a packaging tool used to generate a source or built distribution from a project source tree or sdist, when directly invoked as such (as opposed to by end-user-facing install tools). - Examples: Wheel project, PEP 517 backends via ``build`` or other + Examples: Wheel project, :pep:`517` backends via ``build`` or other package-developer-facing frontends, calling ``setup.py`` directly. An **install tool** is a packaging tool used to install a source or built @@ -359,7 +359,7 @@ for the purposes of this PEP (``Syn:``). archives to a package index, such as Twine for PyPI. **Wheel Format** *(Short: wheel, Rel: Wheel project)* - Here, **wheel**, the standard built distribution format introduced in PEP 427 + Here, **wheel**, the standard built distribution format introduced in :pep:`427` and `specified by PyPA <#wheelspec_>`_, will be referred to in lowercase, while the `Wheel project <#wheelproject_>`_, its reference implementation, will be referred to as **Wheel** in Title Case. @@ -373,7 +373,7 @@ this PEP include those in both `distribution package metadata `_, as defined in the `core metadata specification <#coremetadataspec_>`_, and `author-provided project source metadata `_, as -originally defined in PEP 621. +originally defined in :pep:`621`. Further, `minor additions `_ to the source distribution (sdist), built distribution (wheel) and installed project @@ -526,7 +526,7 @@ Deprecate license classifiers ''''''''''''''''''''''''''''' Using license `classifiers <#classifiers_>`_ in the ``Classifier`` field -(described in PEP 301) is deprecated and replaced by the more precise +(described in :pep:`301`) is deprecated and replaced by the more precise ``License-Expression`` field. If the ``License-Expression`` field is present, build tools SHOULD and @@ -554,7 +554,7 @@ new version of the specification in a future PEP. Project source metadata ----------------------- -As originally introduced in PEP 621, the +As originally introduced in :pep:`621`, the `PyPA Declaring Project Metadata specification <#pep621spec_>`_ defines how to declare a project's source metadata in a ``[project]`` table in the ``pyproject.toml`` file for @@ -604,7 +604,7 @@ contains verbatim file paths, and the ``globs`` subkey valid glob patterns, which MUST be parsable by the ``glob`` `module <#globmodule_>`_ in the Python standard library. -**Note**: To avoid ambiguity, confusion and (per PEP 20, the Zen of Python) +**Note**: To avoid ambiguity, confusion and (per :pep:`20`, the Zen of Python) "more than one (obvious) way to do it", allowing a flat array of strings as the value for the ``license-files`` key has been `left out for now `_. @@ -745,13 +745,13 @@ each format, per the `specification above `_. Converting legacy metadata -------------------------- -If the contents of the ``license.text`` PEP 621 source metadata key +If the contents of the ``license.text`` :pep:`621` source metadata key (or equivalent for tool-specific config formats) is a valid license expression containing solely known, non-deprecated license identifiers, and, if -PEP 621 metadata are defined, the ``license-expression`` key is listed as +:pep:`621` metadata are defined, the ``license-expression`` key is listed as ``dynamic``, build tools MAY use it to fill the ``License-Expression`` field. -Similarly, if the ``classifiers`` PEP 621 source metadata key (or equivalent +Similarly, if the ``classifiers`` :pep:`621` source metadata key (or equivalent for tool-specific config formats) contains exactly one license classifier that unambiguously maps to exactly one valid, non-deprecated SPDX license identifier, tools MAY fill the ``License-Expression`` field with the latter. @@ -935,7 +935,7 @@ should only need to make a couple of tweaks to take advantage of the new functionality. In your project config file, enter your license expression under -``license-expression`` (PEP 621 ``pyproject.toml``), ``license_expression`` +``license-expression`` (:pep:`621` ``pyproject.toml``), ``license_expression`` (Setuptools ``setup.cfg`` / ``setup.py``), or the equivalent for your packaging tool, and make sure to remove any legacy ``license`` value or ``License ::`` classifiers. Your existing ``license`` value may already @@ -975,7 +975,7 @@ parenthesis (``()``) for grouping to form expressions that cover even the most complex situations. In your project config file, enter your license expression under -``license-expression`` (PEP 621 ``pyproject.toml``), ``license_expression`` +``license-expression`` (:pep:`621` ``pyproject.toml``), ``license_expression`` (Setuptools ``setup.cfg`` / ``setup.py``), or the equivalent for your packaging tool, and make sure to remove any legacy ``license`` value or ``License ::`` classifiers. @@ -1010,13 +1010,13 @@ Backwards Compatibility ======================= Adding a new, dedicated ``License-Expression`` core metadata field and -``license-expression`` PEP 621 source metadata key unambiguously signals +``license-expression`` :pep:`621` source metadata key unambiguously signals support for the specification in this PEP. This avoids the risk of new tooling misinterpreting a license expression as a free-form license description or vice versa, and raises an error if and only if the user affirmatively upgrades to the latest metadata version and adds the new field/key. -The legacy ``License`` core metadata field and ``license`` PEP 621 source +The legacy ``License`` core metadata field and ``license`` :pep:`621` source metadata key will be deprecated along with the license classifiers, retaining backwards compatibility while gently preparing users for their future removal. Such a removal would follow a suitable transition period, and @@ -1027,7 +1027,7 @@ inclusion of the listed files in the distribution merely codifies and refines the existing practices in popular packaging tools, including the Wheel and Setuptools projects, and is designed to be largely backwards-compatible with their existing use of that field. Likewise, the new ``license-files`` -PEP 621 source metadata key standardizes statically specifying the files +:pep:`621` source metadata key standardizes statically specifying the files to include, as well as the default behavior, and allows other tools to make use of them, while only having an effect once users and tools expressly adopt it. @@ -1334,14 +1334,14 @@ Source metadata ``license`` key ------------------------------- Alternate possibilities related to the ``license`` key in the -``pyproject.toml`` project source metadata specified in PEP 621. +``pyproject.toml`` project source metadata specified in :pep:`621`. Add ``expression`` and ``files`` subkeys to table ''''''''''''''''''''''''''''''''''''''''''''''''' A previous working draft of this PEP added ``expression`` and ``files`` subkeys -to the existing ``license`` table in the PEP 621 source metadata, to parallel +to the existing ``license`` table in the :pep:`621` source metadata, to parallel the existing ``file`` and ``text`` subkeys. While this seemed perhaps the most obvious approach at first glance, it had several serious drawbacks relative to that ultimately taken here. @@ -1355,7 +1355,7 @@ This also breaks from the consensus for the core metadata fields, namely to separate the license expression into its own explicit field. Furthermore, this leads to a conflict with marking the key as ``dynamic`` -(assuming that is intended to specify PEP 621 keys, as that PEP seems to rather +(assuming that is intended to specify :pep:`621` keys, as that PEP seems to rather imprecisely imply, rather than core metadata fields), as either both would have to be treated as ``dynamic``. A user may want to specify the ``expression`` key as ``dynamic``, if they intend their tooling to generate it automatically; @@ -1370,8 +1370,8 @@ keep track of which fields are mutually exclusive with which of the others, greatly increasing cognitive and code complexity, and in turn the probability of errors. Conceptually, juxtaposing so many different fields under the same key is rather jarring, and leads to a much more complex mapping between -PEP 621 keys and core metadata fields, not in keeping with PEP 621. -This causes the PEP 621 naming and structure to diverge further from +:pep:`621` keys and core metadata fields, not in keeping with :pep:`621`. +This causes the :pep:`621` naming and structure to diverge further from both the core metadata and native formats of the various popular packaging tools that use it. Finally, this results in the spec being significantly more complex and convoluted to understand and implement than the alternatives. @@ -1382,7 +1382,7 @@ all the issues identified above, and results in a much clearer and cleaner design overall. It allows ``license`` and ``license-files`` to be tagged ``dynamic`` independently, separates two independent types of metadata (syntactically and semantically), restores a closer to 1:1 mapping of -PEP 621 keys to core metadata fields, and reduces nesting by a level for both. +:pep:`621` keys to core metadata fields, and reduces nesting by a level for both. Other than adding two extra keys to the file, there was no significant apparent downside to this latter approach, so it was adopted for this PEP. @@ -1395,7 +1395,7 @@ expressions and files would be adding a separate ``license-files`` key, but re-using the ``license`` key for the license expression, either by defining it as the (previously reserved) string value for the ``license`` key, retaining the ``expression`` subkey in the ``license`` table, or -allowing both. Indeed, this would seem to have been envisioned by PEP 621 +allowing both. Indeed, this would seem to have been envisioned by :pep:`621` itself with this PEP in mind, in particular the first approach: A practical string value for the license key has been purposefully left @@ -1408,12 +1408,12 @@ ultimately rejected, as it shared most of the downsides identified with adding new subkeys under the existing ``license`` table, as well as several of its own, with again minimal advantage over separating both. -Most importantly, it still means that per PEP 621, it is not possible to +Most importantly, it still means that per :pep:`621`, it is not possible to separately mark the ``[project]`` keys corresponding to the ``License`` and ``License-Expression`` metadata fields as dynamic. This, in turn, still renders specifying metadata following that standard incompatible with conversion of legacy metadata, as specified in this PEP's -`Converting legacy metadata`_ section, as PEP 621 strictly prohibits the +`Converting legacy metadata`_ section, as :pep:`621` strictly prohibits the ``license`` key from being both present (to define the existing value of the ``License`` field, or the path to a license file, and thus able to be converted), and specified as ``dynamic`` (which would allow tools to @@ -1435,10 +1435,10 @@ By contrast, the present approach makes clear what the author intended, allows tools to unambiguously determine which field(s) may be dynamically inserted, and ensures backward compatibility such that current project source metadata do not unknowingly specify both the old and the new field -as dynamic, and instead must do so explicitly per PEP 621's intent. +as dynamic, and instead must do so explicitly per :pep:`621`'s intent. Additionally, while differences from existing tool formats (and core metadata -field names) has precedent in PEP 621 (though is best avoided if practical), +field names) has precedent in :pep:`621` (though is best avoided if practical), using a key with an identical name as in all current tools (and of an existing core metadata field) to mean something different (and map to a different core metadata field), with distinct and incompatible syntax and semantics, @@ -1457,7 +1457,7 @@ allowing both), all of which have further significant downsides and none of which are clearly superior or more obvious, leading to needless bikeshedding. If the license expression was made the string value of the ``license`` key, -as reserved by PEP 621, it would be slightly shorter for users to type and +as reserved by :pep:`621`, it would be slightly shorter for users to type and more obviously the preferred approach. However, it is far *less* obvious that it is a license expression at all, to authors and those viewing the files, and this lack of clarity, explicitness, ambiguity and potential for user @@ -1481,19 +1481,19 @@ Add a ``type`` key to treat as expression ''''''''''''''''''''''''''''''''''''''''' Instead of creating a new top-level ``license-expression`` key in the -PEP 621 source metadata, one could add a ``type`` subkey to the existing +:pep:`621` source metadata, one could add a ``type`` subkey to the existing ``license`` table to control whether ``text`` (or a string value) is interpreted as free-text or a license expression. This could make backward compatibility a little more seamless, as older tools could ignore it and always treat ``text`` as ``license``, while newer tools would know to treat it as a license expression, if ``type`` was set appropriately. -Indeed, PEP 621 seems to suggest something of this sort as a possible +Indeed, :pep:`621` seems to suggest something of this sort as a possible alternative way that SPDX license expressions could be implemented. However, all the same downsides as in the previous item apply here, including greater complexity, a more complex mapping between the project source metadata and core metadata and inconsistency between the presentation -in tool config, PEP 621 and core metadata, a much less clean deprecation, +in tool config, :pep:`621` and core metadata, a much less clean deprecation, further bikeshedding over what to name it, and inability to mark one but not the other as dynamic, among others. @@ -1519,7 +1519,7 @@ to be automatically back-filled from the value of the ``license-expression`` key. This would be more explicit that the filling will be done, as strictly speaking the ``license`` key is not (and cannot be) specified in ``pyproject.toml``, and satisfies a stricter interpretation of the letter -of the current PEP 621 specification that this PEP revises. +of the current :pep:`621` specification that this PEP revises. However, this isn't seen to be necessary, because it is simply using the static, verbatim literal value of the ``license-expression`` key, as specified @@ -1544,7 +1544,7 @@ Source metadata ``license-files`` key ------------------------------------- Alternatives considered for the ``license-files`` key in the -PEP 621 project source metadata, primarily related to the +:pep:`621` project source metadata, primarily related to the path/glob type handling. @@ -1552,7 +1552,7 @@ Add a ``type`` subkey to ``license-files`` '''''''''''''''''''''''''''''''''''''''''' Instead of defining mutually exclusive ``paths`` and ``globs`` subkeys -of the ``license-files`` PEP 621 project metadata key, we could +of the ``license-files`` :pep:`621` project metadata key, we could achieve the same effect with a ``files`` subkey for the list and a ``type`` subkey for how to interpret it. However, the latter offers no real advantage over the former, in exchange for requiring more keystrokes, @@ -1608,7 +1608,7 @@ However, for the cost of a few characters, it ensures users are aware whether they are entering globs or verbatim paths. Furthermore, allowing license files to be specified as literal paths avoids edge cases, such as those containing glob characters (or those confusingly or even maliciously similar -to them, as described in PEP 672). +to them, as described in :pep:`672`). Including an explicit ``paths`` value ensures that the resulting ``License-File`` metadata is correct, complete and purely static in the @@ -1680,7 +1680,7 @@ be added in the future, but not removed without breaking backward compatibility. And finally, for the "preferred" option, it means there is more than one obvious way to do it. -Therefore, per PEP 20, the Zen of Python, this approach is hereby rejected. +Therefore, per :pep:`20`, the Zen of Python, this approach is hereby rejected. Allow both ``paths`` and ``globs`` subkeys @@ -1727,7 +1727,7 @@ Must be marked dynamic to use defaults '''''''''''''''''''''''''''''''''''''' It may seem outwardly sensible, at least with a particularly restrictive -interpretation of PEP 621 's description of the ``dynamic`` list, to +interpretation of :pep:`621` 's description of the ``dynamic`` list, to consider requiring the ``license-files`` key to be explicitly marked as ``dynamic`` in order for the default glob patterns to be used, or alternatively for license files to be matched and included at all. @@ -1752,7 +1752,7 @@ Finally, aside from adding an additional line of default-required boilerplate to the file, not defining the default as dynamic allows authors to clearly and unambiguously indicate when their build/packaging tools are going to be handling the inclusion of license files themselves rather than strictly -conforming to the PEP 621 portions of this PEP; to do otherwise would defeat +conforming to the :pep:`621` portions of this PEP; to do otherwise would defeat the primary purpose of the ``dynamic`` list as a marker and escape hatch. @@ -1780,7 +1780,7 @@ their specified license files have not been included. Furthermore, this leads to inconsistent relative file paths for non-root license files between the source, sdist and wheel, and prevents the paths -given in the PEP 621 "static" metadata from being truly static, as they need +given in the :pep:`621` "static" metadata from being truly static, as they need to be flattened, and may potentially overwrite one another. Finally, the source directory structure often implies valuable information about what the licenses apply to, and where to find them in the source, @@ -1826,7 +1826,7 @@ metadata regardless of distribution type. However, this leads to a more cluttered ``.dist-info`` directory, littered with arbitrary license files and subdirectories, as opposed to separating -licenses into their own namespace (which per the Zen of Python, PEP 20, are +licenses into their own namespace (which per the Zen of Python, :pep:`20`, are "one honking great idea"). While currently small, there is still a risk of collision with specific custom license filenames (e.g. ``RECORD``, ``METADATA``) in the ``.dist-info`` directory, which @@ -1908,7 +1908,7 @@ Both ``licenses`` and ``license_files`` have been suggested as potential names for the root license directory inside ``.dist-info`` of wheels and installed projects. The former is slightly shorter, but the latter is more clear and unambiguous regarding its contents, and is consistent with -the name of the core metadata field (``License-File``) and the PEP 621 +the name of the core metadata field (``License-File``) and the :pep:`621` project source metadata key (``license-files``). Therefore, the latter was chosen instead. @@ -2124,7 +2124,7 @@ The simplest migration to this PEP would consist of using this instead:: [metadata] license_expression = MIT -Or, in a PEP 621 ``pyproject.toml``:: +Or, in a :pep:`621` ``pyproject.toml``:: [project] license-expression = "MIT" @@ -2193,7 +2193,7 @@ Putting it all together, our ``setup.cfg`` would be:: setuptools/_vendor/packaging/LICENSE.APACHE setuptools/_vendor/packaging/LICENSE.BSD -In a PEP 621 ``pyproject.toml``, with license files specified explicitly +In a :pep:`621` ``pyproject.toml``, with license files specified explicitly via the ``paths`` subkey, this would look like:: [project] diff --git a/pep-0640.rst b/pep-0640.rst index 734d860346b..2461480fcd2 100644 --- a/pep-0640.rst +++ b/pep-0640.rst @@ -43,8 +43,8 @@ potentially conflicts with the use of ``"_"`` in internationalization, where a call like gettext.gettext() is bound to ``"_"`` and used to mark strings for translation. -In the proposal to add Pattern Matching to Python (originally PEP 622, now -split into PEP 634, PEP 635 and PEP 636), ``"_"`` has an *additional* +In the proposal to add Pattern Matching to Python (originally :pep:`622`, now +split into :pep:`634`, :pep:`635` and :pep:`636`), ``"_"`` has an *additional* special meaning. It is a wildcard pattern, used in places where variables could be assigned to, to indicate anything should be matched but not assigned to anything. The choice of ``"_"`` there matches the use of ``"_"`` @@ -157,7 +157,7 @@ places. Alternatively, it could be introduced as part of an explanation on assignment in ``for`` loops, showing an example where the loop variable is unused. -PEP 636 discusses how to teach ``"_"``, and can simply replace ``"_"`` with +:pep:`636` discusses how to teach ``"_"``, and can simply replace ``"_"`` with ``"?"``, perhaps noting that ``"?"`` is similarly usable in other contexts. Reference Implementation diff --git a/pep-0641.rst b/pep-0641.rst index f2df690f4ae..384157a73ca 100644 --- a/pep-0641.rst +++ b/pep-0641.rst @@ -79,7 +79,7 @@ In non-locale ASCII, ``_`` sorts after any digit, so lexicographic sorting matching a sort by Python version of a wheel file name will be kept. -Since PEP 515 (Python 3.6), underscores in numeric literals are ignored. +Since :pep:`515` (Python 3.6), underscores in numeric literals are ignored. This means that ``int("3_10")`` and ``int("310")`` produce the same result, and ordering based on conversion to an integer will be preserved. **However**, this is still a bad way to sort tags, and the point is raised diff --git a/pep-0642.rst b/pep-0642.rst index 47df5281d34..b06af6dc99f 100644 --- a/pep-0642.rst +++ b/pep-0642.rst @@ -17,13 +17,13 @@ Resolution: Abstract ======== -This PEP covers an alternative syntax proposal for PEP 634's structural pattern +This PEP covers an alternative syntax proposal for :pep:`634`'s structural pattern matching that requires explicit prefixes on all capture patterns and value constraints. It also proposes a new dedicated syntax for instance attribute patterns that aligns more closely with the proposed mapping pattern syntax. While the result is necessarily more verbose than the proposed syntax in -PEP 634, it is still significantly less verbose than the status quo. +:pep:`634`, it is still significantly less verbose than the status quo. As an example, the following match statement would extract "host" and "port" details from a 2 item sequence, a mapping with "host" and "port" keys, any @@ -81,33 +81,33 @@ The intent of this approach is to: adopted in ordinary expressions as a way to more easily retrieve a tuple containing multiple attributes from the same object -Relative to PEP 634, the proposal also deliberately eliminates any syntax that +Relative to :pep:`634`, the proposal also deliberately eliminates any syntax that "binds to the right" without using the ``as`` keyword (using capture patterns -in PEP 634's mapping patterns and class patterns) or binds to both the left and -the right in the same pattern (using PEP 634's capture patterns with AS patterns) +in :pep:`634`'s mapping patterns and class patterns) or binds to both the left and +the right in the same pattern (using :pep:`634`'s capture patterns with AS patterns) Relationship with other PEPs ============================ -This PEP both depends on and competes with PEP 634 - the PEP author agrees that +This PEP both depends on and competes with :pep:`634` - the PEP author agrees that match statements would be a sufficiently valuable addition to the language to be worth the additional complexity that they add to the learning process, but disagrees with the idea that "simple name vs literal or attribute lookup" really offers an adequate syntactic distinction between name binding and value lookup operations in match patterns (at least for Python). -This PEP agrees with the spirit of PEP 640 (that the chosen wildcard pattern to +This PEP agrees with the spirit of :pep:`640` (that the chosen wildcard pattern to skip a name binding should be supported everywhere, not just in match patterns), but is now proposing a different spelling for the wildcard syntax (``__`` rather -than ``?``). As such, it competes with PEP 640 as written, but would complement +than ``?``). As such, it competes with :pep:`640` as written, but would complement a proposal to deprecate the use of ``__`` as an ordinary identifier and instead turn it into a general purpose wildcard marker that always skips making a new local variable binding. While it has not yet been put forward as a PEP, Mark Shannon has a pre-PEP draft [8_] expressing several concerns about the runtime semantics of the pattern -matching proposal in PEP 634. This PEP is somewhat complementary to that one, as +matching proposal in :pep:`634`. This PEP is somewhat complementary to that one, as even though this PEP is mostly about surface syntax changes rather than major semantic changes, it does propose that the Abstract Syntax Tree definition be made more explicit to better separate the details of the surface syntax from the @@ -121,7 +121,7 @@ intentionally be governed by the order of the cases in the match statement. Motivation ========== -The original PEP 622 (which was later split into PEP 634, PEP 635, and PEP 636) +The original :pep:`622` (which was later split into :pep:`634`, :pep:`635`, and :pep:`636`) incorporated an unstated but essential assumption in its syntax design: that neither ordinary expressions *nor* the existing assignment target syntax provide an adequate foundation for the syntax used in match patterns. @@ -155,12 +155,12 @@ The first iteration of this PEP was then born out of an attempt to show that the second assertion was not accurate, and that match patterns could be treated as a variation on assignment targets without leading to inherent contradictions. (An earlier PR submitted to list this option in the "Rejected Ideas" section -of the original PEP 622 had previously been declined [2_]). +of the original :pep:`622` had previously been declined [2_]). However, the review process for this PEP strongly suggested that not only did the contradictions that Tobias mentioned in his email exist, but they were also -concerning enough to cast doubts on the syntax proposal presented in PEP 634. -Accordingly, this PEP was changed to go even further than PEP 634, and largely +concerning enough to cast doubts on the syntax proposal presented in :pep:`634`. +Accordingly, this PEP was changed to go even further than :pep:`634`, and largely abandon alignment between the sequence matching syntax and the existing iterable unpacking syntax (effectively answering "Not really, as least as far as the exact syntax is concerned" to the first question raised in the DLS'20 paper @@ -175,7 +175,7 @@ about the new construct based on experience with existing ones. Finally, before completing the 3rd iteration of the proposal (which dropped inferred patterns entirely), the PEP author spent quite a bit of time reflecting -on the following entries in PEP 20: +on the following entries in :pep:`20`: * Explicit is better than implicit. * Special cases aren't special enough to break the rules. @@ -192,7 +192,7 @@ Specification ============= This PEP retains the overall ``match``/``case`` statement structure and semantics -from PEP 634, but proposes multiple changes that mean that user intent is +from :pep:`634`, but proposes multiple changes that mean that user intent is explicitly specified in the concrete syntax rather than needing to be inferred from the pattern matching context. @@ -242,14 +242,14 @@ Closed patterns are patterns which either consist of a single token (i.e. ``__``), or else have a closing delimiter as a required part of their syntax (e.g. ``[as x, as y]``, ``object{.x as x, .y as y}``). -As in PEP 634, the ``match`` and ``case`` keywords are soft keywords, i.e. they +As in :pep:`634`, the ``match`` and ``case`` keywords are soft keywords, i.e. they are not reserved words in other grammatical contexts (including at the start of a line if there is no colon where expected). This means that they are recognized as keywords when part of a match statement or case block only, and are allowed to be used in all other contexts as variable or argument names. -Unlike PEP 634, patterns are explicitly defined as a new kind of node in the +Unlike :pep:`634`, patterns are explicitly defined as a new kind of node in the abstract syntax tree - even when surface syntax is shared with existing expression nodes, a distinct abstract node is emitted by the parser. @@ -262,13 +262,13 @@ Match Semantics ^^^^^^^^^^^^^^^ This PEP largely retains the overall pattern matching semantics proposed in -PEP 634. +:pep:`634`. The proposed syntax for patterns changes significantly, and is discussed in detail below. There are also some proposed changes to the semantics of class defined -constraints (class patterns in PEP 634) to eliminate the need to special case +constraints (class patterns in :pep:`634`) to eliminate the need to special case any builtin types (instead, the introduction of dedicated syntax for instance attribute constraints allows the behaviour needed by those builtin types to be specified as applying to any type that sets ``__match_args__`` to ``None``) @@ -279,7 +279,7 @@ specified as applying to any type that sets ``__match_args__`` to ``None``) Guards ^^^^^^ -This PEP retains the guard clause semantics proposed in PEP 634. +This PEP retains the guard clause semantics proposed in :pep:`634`. However, the syntax is changed slightly to require that when a guard clause is present, the case pattern must be a *closed* pattern. @@ -296,11 +296,11 @@ Irrefutable case blocks ^^^^^^^^^^^^^^^^^^^^^^^ The definition of irrefutable case blocks changes slightly in this PEP relative -to PEP 634, as capture patterns no longer exist as a separate concept from +to :pep:`634`, as capture patterns no longer exist as a separate concept from AS patterns. Aside from that caveat, the handling of irrefutable cases is the same as in -PEP 634: +:pep:`634`: * wildcard patterns are irrefutable * AS patterns whose left-hand side is irrefutable @@ -383,7 +383,7 @@ is not permitted as a capture target (this is what ``!"__"`` expresses). A capture pattern always succeeds. It binds the subject value to the name using the scoping rules for name binding established for named expressions -in PEP 572. (Summary: the name becomes a local +in :pep:`572`. (Summary: the name becomes a local variable in the closest containing function scope unless there's an applicable ``nonlocal`` or ``global`` statement.) @@ -462,7 +462,7 @@ The rule ``primary`` is defined in the standard Python grammar, and only allows expressions that either consist of a single token, or else are required to end with a closing delimiter. -Value constraints replace PEP 634's literal patterns and value patterns. +Value constraints replace :pep:`634`'s literal patterns and value patterns. Equality constraints are written as ``== EXPR``, while identity constraints are written as ``is EXPR``. @@ -481,14 +481,14 @@ parentheses is desirable. When the same constraint expression occurs multiple times in the same match statement, the interpreter may cache the first value calculated and reuse it, -rather than repeat the expression evaluation. (As for PEP 634 value patterns, +rather than repeat the expression evaluation. (As for :pep:`634` value patterns, this cache is strictly tied to a given execution of a given match statement.) -Unlike literal patterns in PEP 634, this PEP requires that complex +Unlike literal patterns in :pep:`634`, this PEP requires that complex literals be parenthesised to be accepted by the parser. See the Deferred Ideas section for discussion on that point. -If this PEP were to be adopted in preference to PEP 634, then all literal and +If this PEP were to be adopted in preference to :pep:`634`, then all literal and value patterns would instead be written more explicitly as value constraints:: # Literal patterns @@ -568,9 +568,9 @@ Abstract syntax:: MatchAlways -A wildcard pattern always succeeds. As in PEP 634, it binds no name. +A wildcard pattern always succeeds. As in :pep:`634`, it binds no name. -Where PEP 634 chooses the single underscore as its wildcard pattern for +Where :pep:`634` chooses the single underscore as its wildcard pattern for consistency with other languages, this PEP chooses the double underscore as that has a clearer path towards potentially being made consistent across the entire language, whereas that path is blocked for ``"_"`` by i18n related use cases. @@ -601,7 +601,7 @@ abstract syntax tree. It allows users to add parentheses around patterns to emphasize the intended grouping, and to allow nesting of open patterns when the grammar requires a closed pattern. -Unlike PEP 634, there is no potential ambiguity with sequence patterns, as +Unlike :pep:`634`, there is no potential ambiguity with sequence patterns, as this PEP requires that all sequence patterns be written with square brackets. @@ -698,7 +698,7 @@ Subpatterns are mostly required to be closed patterns, but the parentheses may be omitted for value constraints. Sequence elements may also be captured unconditionally without parentheses. -Note: where PEP 634 allows all the same syntactic flexibility as iterable +Note: where :pep:`634` allows all the same syntactic flexibility as iterable unpacking in assignment statements, this PEP restricts sequence patterns specifically to the square bracket form. Given that the open and parenthesised forms are far more popular than square brackets for iterable unpacking, this @@ -752,8 +752,8 @@ and a ``ValueError`` is raised. While it would theoretically be possible to checked for duplicated constant keys at compile time, no such check is currently defined or implemented. -(Note: This semantic description is derived from the PEP 634 reference -implementation, which differs from the PEP 634 specification text at time of +(Note: This semantic description is derived from the :pep:`634` reference +implementation, which differs from the :pep:`634` specification text at time of writing. The implementation seems reasonable, so amending the PEP text seems like the best way to resolve the discrepancy) @@ -900,7 +900,7 @@ converted to an instance attributes constraint as follows: Note: the ``__match_args__ is None`` handling in this PEP replaces the special casing of ``bool``, ``bytearray``, ``bytes``, ``dict``, ``float``, -``frozenset``, ``int``, ``list``, ``set``, ``str``, and ``tuple`` in PEP 634. +``frozenset``, ``int``, ``list``, ``set``, ``str``, and ``tuple`` in :pep:`634`. However, the optimised fast path for those types is retained in the implementation. @@ -911,7 +911,7 @@ Design Discussion Requiring explicit qualification of simple names in match patterns ------------------------------------------------------------------ -The first iteration of this PEP accepted the basic premise of PEP 634 that +The first iteration of this PEP accepted the basic premise of :pep:`634` that iterable unpacking syntax would provide a good foundation for defining a new syntax for pattern matching. @@ -919,13 +919,13 @@ During the review process, however, two major and one minor ambiguity problems were highlighted that arise directly from that core assumption: * most problematically, when binding simple names by default is extended to - PEP 634's proposed class pattern syntax, the ``ATTR=TARGET_NAME`` construct + :pep:`634`'s proposed class pattern syntax, the ``ATTR=TARGET_NAME`` construct binds to the right without using the ``as`` keyword, and uses the normal assignment-to-the-left sigil (``=``) to do it! -* when binding simple names by default is extended to PEP 634's proposed mapping +* when binding simple names by default is extended to :pep:`634`'s proposed mapping pattern syntax, the ``KEY: TARGET_NAME`` construct binds to the right without using the ``as`` keyword -* using a PEP 634 capture pattern together with an AS pattern +* using a :pep:`634` capture pattern together with an AS pattern (``TARGET_NAME_1 as TARGET_NAME_2``) gives an odd "binds to both the left and right" behaviour @@ -957,7 +957,7 @@ no longer read poorly: Resisting the temptation to guess --------------------------------- -PEP 635 looks at the way pattern matching is used in other languages, and +:pep:`635` looks at the way pattern matching is used in other languages, and attempts to use that information to make plausible predictions about the way pattern matching will be used in Python: @@ -1001,7 +1001,7 @@ AST nodes could be reused. Interaction with caching of attribute lookups in local variables ---------------------------------------------------------------- -One of the major changes between this PEP and PEP 634 is to use ``== EXPR`` +One of the major changes between this PEP and :pep:`634` is to use ``== EXPR`` for equality constraint lookups, rather than only offering ``NAME.ATTR``. The original motivation for this was to avoid the semantic conflict with regular assignment targets, where ``NAME.ATTR`` is already used in assignment statements @@ -1014,7 +1014,7 @@ user's intent, and instead requiring them to state it explicitly in the syntax. However, even within match statements themselves, the ``name.attr`` syntax for value patterns has an undesirable interaction with local variable assignment, where routine refactorings that would be semantically neutral for any other -Python statement introduce a major semantic change when applied to a PEP 634 +Python statement introduce a major semantic change when applied to a :pep:`634` style match statement. Consider the following code:: @@ -1047,7 +1047,7 @@ being functionally equivalent:: case __: ... # Handle the non-matching case -By contrast, when using PEP 634's value and capture pattern syntaxes that omit +By contrast, when using :pep:`634`'s value and capture pattern syntaxes that omit the marker prefix, the following two statements wouldn't be equivalent at all:: # PEP 634's value pattern syntax @@ -1069,14 +1069,14 @@ This PEP ensures the original semantics are retained under this style of simplistic refactoring: use ``== name`` to force interpretation of the result as a value constraint, use ``as name`` for a name binding. -PEP 634's proposal to offer only the shorthand syntax, with no explicitly +:pep:`634`'s proposal to offer only the shorthand syntax, with no explicitly prefixed form, means that the primary answer on offer is "Well, don't do that, then, only compare against attributes in namespaces, don't compare against simple names". -PEP 622's walrus pattern syntax had another odd interaction where it might not +:pep:`622`'s walrus pattern syntax had another odd interaction where it might not bind the same object as the exact same walrus expression in the body of the -case clause, but PEP 634 fixed that discrepancy by replacing walrus patterns +case clause, but :pep:`634` fixed that discrepancy by replacing walrus patterns with AS patterns (where the fact that the value bound to the name on the RHS might not be the same value as returned by the LHS is a standard feature common to all uses of the "as" keyword). @@ -1098,7 +1098,7 @@ There were a few concerns with ``==`` as a prefix that kept it from being chosen as the prefix in the initial iteration of the PEP: * for common use cases, it's even more visually noisy than ``?``, as a lot of - folks with PEP 8 trained aesthetic sensibilities are going to want to put + folks with :pep:`8` trained aesthetic sensibilities are going to want to put a space between it and the following expression, effectively making it a 3 character prefix instead of 1 * when used in a mapping pattern, there needs to be a space between the ``:`` @@ -1107,7 +1107,7 @@ chosen as the prefix in the initial iteration of the PEP: * when used in an OR pattern, there needs to be a space between the ``|`` pattern separator and the ``==`` prefix, or the tokeniser will split them up incorrectly (getting ``|=`` and ``=`` instead of ``|`` and ``==``) -* if used in a PEP 634 style class pattern, there needs to be a space between +* if used in a :pep:`634` style class pattern, there needs to be a space between the ``=`` keyword separator and the ``==`` prefix, or the tokeniser will split them up incorrectly (getting ``==`` and ``=`` instead of ``=`` and ``==``) @@ -1129,7 +1129,7 @@ ambiguity concerns. Instead, the following points apply: reducing the need to combine OR patterns with equality constraints (instead, the values to be checked against would be collected as a set, list, or tuple). -Given that perspective, PEP 635's arguments against using ``?`` as part of the +Given that perspective, :pep:`635`'s arguments against using ``?`` as part of the pattern matching syntax held for this proposal as well, and so the PEP was amended accordingly. @@ -1137,12 +1137,12 @@ amended accordingly. Using ``__`` as the wildcard pattern marker ------------------------------------------- -PEP 635 makes a solid case that introducing ``?`` *solely* as a wildcard pattern +:pep:`635` makes a solid case that introducing ``?`` *solely* as a wildcard pattern marker would be a bad idea. With the syntax for value constraints changed to use existing comparison operations rather than ``?`` and ``?is``, that argument holds for this PEP as well. -However, as noted by Thomas Wouters in [6_], PEP 634's choice of ``_`` remains +However, as noted by Thomas Wouters in [6_], :pep:`634`'s choice of ``_`` remains problematic as it would likely mean that match patterns would have a *permanent* difference from all other parts of Python - the use of ``_`` in software internationalisation and at the interactive prompt means that there isn't really @@ -1193,13 +1193,13 @@ be consistent with that existing approach. Representing patterns explicitly in the Abstract Syntax Tree ------------------------------------------------------------ -PEP 634 doesn't explicitly discuss how match statements should be represented +:pep:`634` doesn't explicitly discuss how match statements should be represented in the Abstract Syntax Tree, instead leaving that detail to be defined as part of the implementation. -As a result, while the reference implementation of PEP 634 definitely works (and +As a result, while the reference implementation of :pep:`634` definitely works (and formed the basis of the reference implementation of this PEP), it does contain -a significant design flaw: despite the notes in PEP 635 that patterns should be +a significant design flaw: despite the notes in :pep:`635` that patterns should be considered as distinct from expressions, the reference implementation goes ahead and represents them in the AST as expression nodes. @@ -1225,13 +1225,13 @@ rest of the PEP were to be rejected. Changes to sequence patterns ---------------------------- -This PEP makes one notable change to sequence patterns relative to PEP 634: +This PEP makes one notable change to sequence patterns relative to :pep:`634`: * only the square bracket form of sequence pattern is supported. Neither open (no delimiters) nor tuple style (parentheses as delimiters) sequence patterns are supported. -Relative to PEP 634, sequence patterns are also significantly affected by the +Relative to :pep:`634`, sequence patterns are also significantly affected by the change to require explicit qualification of capture patterns and value constraints, as it means ``case [a, b, c]:`` must instead be written as ``case [as a, as b, as c]:`` and ``case [0, 1]:`` must instead be written as @@ -1245,7 +1245,7 @@ consistency with iterable unpacking. Allowing open and tuple style sequence patterns didn't increase expressivity, only ambiguity of intent (especially relative to group patterns), and encouraged readers down the path of viewing pattern matching syntax as intrinsically linked -to assignment target syntax (which the PEP 634 authors have stated multiple +to assignment target syntax (which the :pep:`634` authors have stated multiple times is not a desirable path to have readers take, and a view the author of this PEP now shares, despite disagreeing with it originally). @@ -1253,7 +1253,7 @@ this PEP now shares, despite disagreeing with it originally). Changes to mapping patterns --------------------------- -This PEP makes two notable changes to mapping patterns relative to PEP 634: +This PEP makes two notable changes to mapping patterns relative to :pep:`634`: * value capturing is written as ``KEY as NAME`` rather than as ``KEY: NAME`` * a wider range of keys are permitted: any "closed expression", rather than @@ -1267,10 +1267,10 @@ The second change is mostly a matter of simplifying the parser and code generator code by reusing the existing expression handling machinery. The restriction to closed expressions is designed to help reduce ambiguity as to where the key expression ends and the match pattern begins. This mostly allows -a superset of what PEP 634 allows, except that complex literals must be written +a superset of what :pep:`634` allows, except that complex literals must be written in parentheses (at least for now). -Adapting PEP 635's mapping pattern examples to the syntax proposed in this PEP:: +Adapting :pep:`635`'s mapping pattern examples to the syntax proposed in this PEP:: match json_pet: case {"type": == "cat", "name" as name, "pattern" as pattern}: @@ -1288,7 +1288,7 @@ Adapting PEP 635's mapping pattern examples to the syntax proposed in this PEP:: for child in children: change_red_to_blue(child) -For reference, the equivalent PEP 634 syntax:: +For reference, the equivalent :pep:`634` syntax:: match json_pet: case {"type": "cat", "name": name, "pattern": pattern}: @@ -1310,7 +1310,7 @@ For reference, the equivalent PEP 634 syntax:: Changes to class patterns ------------------------- -This PEP makes several notable changes to class patterns relative to PEP 634: +This PEP makes several notable changes to class patterns relative to :pep:`634`: * the syntactic alignment with class instantiation is abandoned as being actively misleading and unhelpful. Instead, a new dedicated syntax for @@ -1350,10 +1350,10 @@ matter of considering the leading ``.`` sufficient to render the name usage unambiguous (it's clearly an attribute reference, whereas matching against a variable key in a mapping pattern would be arguably ambiguous) -The final change just supplements a CPython-internal-only check in the PEP 634 +The final change just supplements a CPython-internal-only check in the :pep:`634` reference implementation by making it the default behaviour that classes get if they don't define ``__match_args__`` (the optimised fast path for the builtin -and standard library types named in PEP 634 is retained). +and standard library types named in :pep:`634` is retained). Adapting the class matching example `linked from PEP 635 `_ @@ -1381,7 +1381,7 @@ changes:: case __: raise ValueError(f"Invalid expression value: {repr(expr)}") -For reference, the equivalent PEP 634 syntax:: +For reference, the equivalent :pep:`634` syntax:: match expr: case BinaryOp('+', left, right): @@ -1413,7 +1413,7 @@ checking for named attributes and extracting their values without relying on case object{.host as host}: pass -Compare this to the PEP 634 equivalent, where it really isn't clear which names +Compare this to the :pep:`634` equivalent, where it really isn't clear which names are referring to attributes of the match subject and which names are referring to local variables:: @@ -1470,7 +1470,7 @@ restrictions later can be considered on a case-by-case basis. Accepting complex literals as closed expressions ------------------------------------------------ -PEP 634's reference implementation includes a lot of special casing of binary +:pep:`634`'s reference implementation includes a lot of special casing of binary operations in both the parser and the rest of the compiler in order to accept complex literals without accepting arbitrary binary numeric operations on literal values. @@ -1526,7 +1526,7 @@ Allowing membership checks in match patterns The syntax used for equality and identity constraints would be straightforward to extend to membership checks: ``in container``. -One downside of the proposals in both this PEP and PEP 634 is that checking +One downside of the proposals in both this PEP and :pep:`634` is that checking for multiple values in the same case doesn't look like any existing container membership check in Python:: @@ -1541,7 +1541,7 @@ membership check in Python:: ... Allowing inferred equality constraints under this PEP would only make it look -like the PEP 634 example, it still wouldn't look like the equivalent ``if`` +like the :pep:`634` example, it still wouldn't look like the equivalent ``if`` statement header (``if value in {0, 1, 2, 3}:``). Membership constraints would provide a more explicit, but still concise, way @@ -1583,7 +1583,7 @@ allowing this has been deferred as a topic for possible future consideration. Avoiding special cases in sequence patterns ------------------------------------------- -Sequence patterns in both this PEP and PEP 634 currently special case ``str``, +Sequence patterns in both this PEP and :pep:`634` currently special case ``str``, ``bytes``, and ``bytearray`` as specifically *never* matching a sequence pattern. @@ -1638,14 +1638,14 @@ Restricting permitted expressions in value constraints and mapping pattern keys While it's entirely technically possible to restrict the kinds of expressions permitted in value constraints and mapping pattern keys to just attribute -lookups and constant literals (as PEP 634 does), there isn't any clear runtime +lookups and constant literals (as :pep:`634` does), there isn't any clear runtime value in doing so, so this PEP proposes allowing any kind of primary expression (primary expressions are an existing node type in the grammar that includes things like literals, names, attribute lookups, function calls, container subscripts, parenthesised groups, etc), as well as high precedence unary operations (``+``, ``-``, ``~``) on primary expressions. -While PEP 635 does emphasise several times that literal patterns and value +While :pep:`635` does emphasise several times that literal patterns and value patterns are not full expressions, it doesn't ever articulate a concrete benefit that is obtained from that restriction (just a theoretical appeal to it being useful to separate static checks from dynamic checks, which a code style @@ -1658,7 +1658,7 @@ that just returned their argument) to express the behaviour they wanted before the language definition was finally updated to allow arbitrary expressions and let users make their own decisions about readability. -The situation in PEP 634 that bears a resemblance to the situation with decorator +The situation in :pep:`634` that bears a resemblance to the situation with decorator expressions is that arbitrary expressions are technically supported in value patterns, they just require awkward workarounds where either all the values to match need to be specified in a helper class that is placed before the match @@ -1722,7 +1722,7 @@ Requiring the use of constraint prefix markers for mapping pattern keys ----------------------------------------------------------------------- The initial (unpublished) draft of this proposal suggested requiring mapping -pattern keys be value constraints, just as PEP 634 requires that they be valid +pattern keys be value constraints, just as :pep:`634` requires that they be valid literal or value patterns:: import constants @@ -1765,7 +1765,7 @@ Reference Implementation ======================== A draft reference implementation for this PEP [3_] has been derived from Brandt -Bucher's reference implementation for PEP 634 [4_]. +Bucher's reference implementation for :pep:`634` [4_]. Relative to the text of this PEP, the draft reference implementation has not yet complemented the special casing of several builtin and standard library @@ -1774,7 +1774,7 @@ being set to ``None``. Class defined patterns also currently still accept classes that don't define ``__match_args__``. All other modified patterns have been updated to follow this PEP rather than -PEP 634. +:pep:`634`. Unparsing for match patterns has not yet been migrated to the updated v3 AST. @@ -1787,7 +1787,7 @@ are expected. The examples in this PEP have not yet been converted to test cases, so could plausibly contain typos and other errors. -Several of the old PEP 634 tests are still to be converted to new SyntaxError +Several of the old :pep:`634` tests are still to be converted to new SyntaxError tests. The documentation has not yet been updated. @@ -1796,25 +1796,26 @@ The documentation has not yet been updated. Acknowledgments =============== -The PEP 622 and PEP 634/635/636 authors, as the proposal in this PEP is merely +The :pep:`622` and :pep:`634`/:pep:`635`/:pep:`636` authors, as the proposal in +this PEP is merely an attempt to improve the readability of an already well-constructed idea by proposing that starting with a more explicit syntax and potentially introducing syntactic shortcuts for particularly common operations later is a better option than attempting to *only* define the shortcut version. For areas of the specification where the two PEPs are the same (or at least very similar), the text describing the intended behaviour in this PEP is often derived directly -from the PEP 634 text. +from the :pep:`634` text. Steven D'Aprano, who made a compelling case that the key goals of this PEP could be achieved by using existing comparison tokens to tell the ability to override the compiler when our guesses as to "what most users will want most of the time" are inevitably incorrect for at least some users some of the time, and retaining -some of PEP 634's syntactic sugar (with a slightly different semantic definition) -to obtain the same level of brevity as PEP 634 in most situations. (Paul +some of :pep:`634`'s syntactic sugar (with a slightly different semantic definition) +to obtain the same level of brevity as :pep:`634` in most situations. (Paul Sokolosvsky also independently suggested using ``==`` instead of ``?`` as a more easily understood prefix for equality constraints). -Thomas Wouters, whose publication of PEP 640 and public review of the structured +Thomas Wouters, whose publication of :pep:`640` and public review of the structured pattern matching proposals persuaded the author of this PEP to continue advocating for a wildcard pattern syntax that a future PEP could plausibly turn into a hard keyword that always skips binding a reference in any location a @@ -1865,9 +1866,9 @@ Appendix A -- Full Grammar ========================== Here is the full modified grammar for ``match_stmt``, replacing Appendix A -in PEP 634. +in :pep:`634`. -Notation used beyond standard EBNF is as per PEP 534: +Notation used beyond standard EBNF is as per :pep:`534`: - ``'KWD'`` denotes a hard keyword - ``"KWD"`` denotes a soft keyword @@ -2008,9 +2009,9 @@ Appendix C: Summary of changes relative to PEP 634 ================================================== The overall ``match``/``case`` statement syntax and the guard expression syntax -remain the same as they are in PEP 634. +remain the same as they are in :pep:`634`. -Relative to PEP 634 this PEP makes the following key changes: +Relative to :pep:`634` this PEP makes the following key changes: * a new ``pattern`` type is defined in the AST, rather than reusing the ``expr`` type for patterns @@ -2057,7 +2058,7 @@ Relative to PEP 634 this PEP makes the following key changes: the pattern to be matched starts with ``==``, ``is``, or ``as`` * class patterns treat any class that sets ``__match_args__`` to ``None`` as accepting a single positional pattern that is matched against the entire - object (avoiding the special casing required in PEP 634) + object (avoiding the special casing required in :pep:`634`) * class patterns raise ``TypeError`` when used with an object that does not define ``__match_args__`` * dedicated syntax for ducktyping is added, such that ``case cls{...}:`` is @@ -2069,7 +2070,7 @@ Note that postponing literal patterns also makes it possible to postpone the question of whether we need an "INUMBER" token in the tokeniser for imaginary literals. Without it, the parser can't distinguish complex literals from other binary addition and subtraction operations on constants, so proposals like -PEP 634 have to do work in later compilation steps to check for correct usage. +:pep:`634` have to do work in later compilation steps to check for correct usage. .. _Appendix D: @@ -2077,12 +2078,12 @@ PEP 634 have to do work in later compilation steps to check for correct usage. Appendix D: History of changes to this proposal =============================================== -The first published iteration of this proposal mostly followed PEP 634, but +The first published iteration of this proposal mostly followed :pep:`634`, but suggested using ``?EXPR`` for equality constraints and ``?is EXPR`` for -identity constraints rather than PEP 634's value patterns and literal patterns. +identity constraints rather than :pep:`634`'s value patterns and literal patterns. The second published iteration mostly adopted a counter-proposal from Steven -D'Aprano that kept the PEP 634 style inferred constraints in many situations, +D'Aprano that kept the :pep:`634` style inferred constraints in many situations, but also allowed the use of ``== EXPR`` for explicit equality constraints, and ``is EXPR`` for explicit identity constraints. diff --git a/pep-0645.rst b/pep-0645.rst index 9368caaac9b..4c5fe268070 100644 --- a/pep-0645.rst +++ b/pep-0645.rst @@ -19,7 +19,7 @@ Types have become a valuable and powerful part of the Python language. However, considerable friction to using type annotations. By improving the typing syntax, adding types to Python code becomes simpler and improves the development experience for Python users. -In a similar vein, a PEP to introduce short hand syntax for `Union types `_ [1]_ has +In a similar vein, a PEP to introduce short hand syntax for :pep:`Union types <604>` has been approved and implemented. @@ -27,7 +27,7 @@ Rationale ========= Types in Python can be quite verbose, this can be a hindrance when working towards type adoption. Making types more ergonomic, -as was done with the Union type in PEP 604 (e.g., int | str), would reduce the effort needed to add types to new and existing Python code. +as was done with the Union type in :pep:`604` (e.g., int | str), would reduce the effort needed to add types to new and existing Python code. The Optional annotation is used frequently in both partially and fully typed Python code bases. In a small sampling of `5 well-typed open source projects, on average 7% of annotations `_ [2] included at least one optional type. This indicates @@ -37,8 +37,8 @@ Simplifying the syntax for optionals has been `discussed previously `_ [4], which is currently in a deferred state. -PEP 505 proposes a: +Adding the ? sigil to the Python grammar has been proposed previously in :pep:`505`, which is currently in a deferred state. +:pep:`505` proposes a: - "None coalescing" binary operator ``??`` @@ -47,7 +47,7 @@ PEP 505 proposes a: - "None-aware indexing" operator ``?[]`` ("maybe subscript") -Should PEP 505 be approved in the future, it would not interfere with the typing specific ``?`` proposed in this PEP. As well, +Should :pep:`505` be approved in the future, it would not interfere with the typing specific ``?`` proposed in this PEP. As well, since all uses of the ``?`` would be conceptually related, it would not be confusing in terms of learning Python or a hindrance to quick visual comprehension. The proposed syntax, with the postfix operator, mimics the optional syntax found in other typed languages, like C#, TypeScript and Swift. @@ -100,7 +100,7 @@ It should also be equivalent to a Union with None. # new syntax int? == int | None -Since the new Union syntax specified in PEP 604 is supported in ``isinstance`` and ``issubclass``, the new optional syntax should be supported in both ``isinstance`` and ``issubclass``, +Since the new Union syntax specified in :pep:`604` is supported in ``isinstance`` and ``issubclass``, the new optional syntax should be supported in both ``isinstance`` and ``issubclass``, :: @@ -132,14 +132,10 @@ Discussed alternatives were References ========== -.. [1] PEP 604 - (https://www.python.org/dev/peps/pep-0604/) .. [2] Use of Optional Annotations in Open Source Python projects (https://gist.github.com/MaggieMoss/fd8dfe002b2702fae243dbf81a62624e) .. [3] Github Issue Discussion of Optional syntax (https://github.com/python/typing/issues/429) -.. [4] PEP 505 - (https://www.python.org/dev/peps/pep-0505/) .. [5] Reference Implementation (https://github.com/python/cpython/compare/master...MaggieMoss:new-optional-syntax-postfix) diff --git a/pep-0646.rst b/pep-0646.rst index 9fc4fe1dd15..0e5b1fb332d 100644 --- a/pep-0646.rst +++ b/pep-0646.rst @@ -15,7 +15,7 @@ Post-History: 07-Oct-2020, 23-Dec-2020, 29-Dec-2020 Abstract ======== -PEP 484 introduced ``TypeVar``, enabling creation of generics parameterised +:pep:`484` introduced ``TypeVar``, enabling creation of generics parameterised with a single type. In this PEP, we introduce ``TypeVarTuple``, enabling parameterisation with an *arbitrary* number of types - that is, a *variadic* type variable, enabling *variadic* generics. This enables a wide variety of use cases. @@ -459,7 +459,7 @@ Not Allowed_>`_ unpacking may appear in a tuple: ``*args`` as a Type Variable Tuple ---------------------------------- -PEP 484 states that when a type annotation is provided for ``*args``, every argument +:pep:`484` states that when a type annotation is provided for ``*args``, every argument must be of the type annotated. That is, if we specify ``*args`` to be type ``int``, then *all* arguments must be of type ``int``. This limits our ability to specify the type signatures of functions that take heterogeneous argument types. @@ -496,8 +496,9 @@ Note that this is different to as this would make ``env`` a keyword-only argument. -Using an unpacked unbounded tuple is equivalent to the PEP 484 -behavior [#pep-484-args]_ of ``*args: int``, which accepts zero or +Using an unpacked unbounded tuple is equivalent to the +:pep:`484#arbitrary-argument-lists-and-default-argument-values` +behavior of ``*args: int``, which accepts zero or more values of type ``int``: :: @@ -909,7 +910,7 @@ passed to ``__getitem__``. For example, if we do ``foo[a, *b, c]``, and ``foo.__getitem__`` would receive ``(a, d, e, c)``. To put it another way, note that ``x[..., *a, ...]`` produces the same result -as ``x[(..., *a, ...)]``` (with any slices ``i:j`` in ``...`` replaced with +as ``x[(..., *a, ...)]`` (with any slices ``i:j`` in ``...`` replaced with ``slice(i, j)``, with the one edge case that ``x[*a]`` becomes ``x[(*a,)]``). TypeVarTuple Implementation @@ -1146,7 +1147,7 @@ one in Pyre, as of v0.9.0, and one in Pyright, as of v1.1.108. A preliminary implementation of the ``Unpack`` version of the PEP in CPython is available in `cpython/23527`_. A preliminary version of the version -using the star operator, based on an early implementation of PEP 637, +using the star operator, based on an early implementation of :pep:`637`, is also available at `mrahtz/cpython/pep637+646`_. Appendix A: Shape Typing Use Cases @@ -1343,7 +1344,7 @@ this PEP? We're not sure. One area of overlap is that in some contexts, we could mean(im, axis=Image.axes.index(Channels) Ideally, we might write something like ``im: Array[Height=64, Width=64, Channels=3]`` - -but this won't be possible in the short term, due to the rejection of PEP 637. +but this won't be possible in the short term, due to the rejection of :pep:`637`. In any case, our attitude towards this is mostly "Wait and see what happens before taking any further steps". @@ -1375,7 +1376,7 @@ From **Stephan Hoyer**, member of the NumPy Steering Council: [#stephan-endorsement]_ I just wanted to thank Matthew & Pradeep for writing this PEP and for - clarifications to the broader context of PEP 646 for array typing in + clarifications to the broader context of :pep:`646` for array typing in https://github.com/python/peps/pull/1904. As someone who is heavily involved in the Python numerical computing @@ -1397,14 +1398,14 @@ From **Bas van Beek**, who has worked on preliminary support for shape-generics in NumPy: I very much share Stephan's opinion here and look forward to integrating the - new PEP 646 variadics into numpy. + new :pep:`646` variadics into numpy. In the context of numpy (and tensor typing general): the typing of array shapes is a fairly complicated subject and the introduction of variadics will likely play in big role in laying its foundation, as it allows for the expression of both dimensioability as well as basic shape manipulation. - All in all, I'm very interested in where both PEP 646 and future PEPs will + All in all, I'm very interested in where both :pep:`646` and future PEPs will take us and look forward to further developments. From **Dan Moldovan**, a Senior Software Engineer on the TensorFlow Dev Team @@ -1491,8 +1492,6 @@ References .. [#dan-endorsement] https://mail.python.org/archives/list/python-dev@python.org/message/HTCARTYYCHETAMHB6OVRNR5EW5T2CP4J/ -.. [#pep-484-args] https://www.python.org/dev/peps/pep-0484/#arbitrary-argument-lists-and-default-argument-values - Copyright ========= diff --git a/pep-0647.rst b/pep-0647.rst index b25fd3c6388..4a9c5912e8e 100644 --- a/pep-0647.rst +++ b/pep-0647.rst @@ -336,7 +336,7 @@ decided unnecessary to burden the Python implementation of user-defined type guards with additional complexity to support a contrived use case. If such use cases are identified in the future, there are ways the TypeGuard mechanism could be extended. This could involve the use of keyword indexing, as proposed -in PEP 637. +in :pep:`637`. Narrowing of Implicit "self" and "cls" Parameters diff --git a/pep-0649.rst b/pep-0649.rst index 61ff52f6bff..4ea62075414 100644 --- a/pep-0649.rst +++ b/pep-0649.rst @@ -16,20 +16,20 @@ for annotations: * original or "stock" Python semantics, in which annotations are evaluated at the time they are bound, and -* PEP 563 semantics, currently enabled per-module by +* :pep:`563` semantics, currently enabled per-module by ``from __future__ import annotations``, in which annotations are converted back into strings and must be reparsed and executed by ``eval()`` to be used. Original Python semantics created a circular references problem -for static typing analysis. PEP 563 solved that problem--but +for static typing analysis. :pep:`563` solved that problem--but its novel semantics introduced new problems, including its restriction that annotations can only reference names at module-level scope. This PEP proposes a third way that embodies the best of both previous approaches. It solves the same circular reference -problems solved by PEP 563, while otherwise preserving Python's +problems solved by :pep:`563`, while otherwise preserving Python's original annotation semantics, including allowing annotations to refer to local and class variables. @@ -70,7 +70,7 @@ If accepted, these new semantics for annotations would initially be gated behind ``from __future__ import co_annotations``. However, these semantics would eventually be promoted to be Python's default behavior. Thus this PEP would *supersede* -PEP 563, and PEP 563's behavior would be deprecated and +:pep:`563`, and :pep:`563`'s behavior would be deprecated and eventually removed. Overview @@ -120,7 +120,7 @@ bound, and these values are stored in the annotations dict. But this code doesn't run—it throws a ``NameError`` on the first line, because ``MyType`` hasn't been defined yet. -PEP 563's solution is to decompile the expressions back +:pep:`563`'s solution is to decompile the expressions back into strings, and store those *strings* in the annotations dict. The equivalent runtime code would look something like this: @@ -182,10 +182,10 @@ Motivation Python's original semantics for annotations made its use for static type analysis painful due to forward reference problems. -This was the main justification for PEP 563, and we need not +This was the main justification for :pep:`563`, and we need not revisit those arguments here. -However, PEP 563's solution was to decompile code for Python +However, :pep:`563`'s solution was to decompile code for Python annotations back into strings at compile time, requiring users of annotations to ``eval()`` those strings to restore them to their actual Python values. This has several drawbacks: @@ -197,7 +197,7 @@ them to their actual Python values. This has several drawbacks: need to be reimplemented independently by every other Python implementation. * It requires that all annotations be evaluated at module-level - scope. Annotations under PEP 563 can no longer refer to + scope. Annotations under :pep:`563` can no longer refer to * class variables, * local variables in the current function, or * local variables in enclosing functions. @@ -209,7 +209,7 @@ them to their actual Python values. This has several drawbacks: from Python for space reasons. * In order to evaluate the annotations on a class, it requires obtaining a reference to that class's globals, - which PEP 563 suggests should be done by looking up that class + which :pep:`563` suggests should be done by looking up that class by name in ``sys.modules``—another surprising requirement for a language-level feature. * It adds an ongoing maintenance burden to Python implementations. @@ -218,7 +218,7 @@ them to their actual Python values. This has several drawbacks: tandem in order to support decompiling it. This PEP also solves the forward reference problem outlined in -PEP 563 while avoiding the problems listed above: +:pep:`563` while avoiding the problems listed above: * Python implementations would generate annotations as code objects. This is simpler than stringizing, and is something @@ -240,7 +240,7 @@ PEP 563 while avoiding the problems listed above: Backwards Compatibility ======================= -PEP 563 changed the semantics of annotations. When its semantics +:pep:`563` changed the semantics of annotations. When its semantics are active, annotations must assume they will be evaluated in *module-level* scope. They may no longer refer directly to local variables or class attributes. @@ -253,10 +253,10 @@ at the time the annotation is defined, as long as the not-yet-defined name is created normally (in such a way that it is known to the symbol table for the relevant block, or is a global or class variable found using normal name resolution). Thus, this PEP demonstrates *improved* -backwards compatibility over PEP 563. +backwards compatibility over :pep:`563`. -PEP 563 also requires using ``eval()`` or ``typing.get_type_hints()`` -to examine annotations. Code updated to work with PEP 563 that calls +:pep:`563` also requires using ``eval()`` or ``typing.get_type_hints()`` +to examine annotations. Code updated to work with :pep:`563` that calls ``eval()`` directly would have to be updated simply to remove the ``eval()`` call. Code using ``typing.get_type_hints()`` would continue to work unchanged, though future use of that function @@ -280,7 +280,7 @@ annotations dicts. Specifically: However, there are two uncommon interactions possible with class and module annotations that work today—both with stock semantics, -and with PEP 563 semantics—that would no longer work when this PEP +and with :pep:`563` semantics—that would no longer work when this PEP was active. These two interactions would have to be prohibited. The good news is, neither is common, and neither is considered good practice. In fact, they're rarely seen outside of Python's own @@ -352,7 +352,7 @@ PEP. Mistaken Rejection Of This Approach In November 2017 ==================================================== -During the early days of discussion around PEP 563, +During the early days of discussion around :pep:`563`, using code to delay the evaluation of annotations was briefly discussed, in a November 2017 thread in ``comp.lang.python-dev``. At the time the @@ -373,11 +373,10 @@ annotations for methods to be able to refer to class-level definitions, by maintaining a reference to the class-level scope. This idea, too, was quickly rejected. -PEP 563 summarizes the above discussion here: +:pep:`PEP 563 summarizes the above discussion +<563#keeping-the-ability-to-use-function-local-state-when-defining-annotations>` -https://www.python.org/dev/peps/pep-0563/#keeping-the-ability-to-use-function-local-state-when-defining-annotations - -What's puzzling is PEP 563's own changes to the scoping rules +What's puzzling is :pep:`563`'s own changes to the scoping rules of annotations—it *also* doesn't permit annotations to reference class-level definitions. It's not immediately clear why an inability to reference class-level definitions was enough to @@ -385,9 +384,9 @@ reject using "implicit lambda expressions" for annotations, but was acceptable for stringized annotations. In retrospect there was probably a pivot during the development -of PEP 563. It seems that, early on, there was a prevailing -assumption that PEP 563 would support references to class-level -definitions. But by the time PEP 563 was finalized, this +of :pep:`563`. It seems that, early on, there was a prevailing +assumption that :pep:`563` would support references to class-level +definitions. But by the time :pep:`563` was finalized, this assumption had apparently been abandoned. And it looks like "implicit lambda expressions" were never reconsidered in this new light. @@ -718,7 +717,7 @@ Python supports syntax for local variable annotations inside functions. However, these annotations have no runtime effect--they're discarded at compile-time. Therefore, this PEP doesn't need to do anything to support them, the same -as stock semantics and PEP 563. +as stock semantics and :pep:`563`. @@ -726,7 +725,7 @@ Performance Comparison ---------------------- Performance with this PEP should be favorable, when compared with either -stock behavior or PEP 563. In general, resources are only consumed +stock behavior or :pep:`563`. In general, resources are only consumed on demand—"you only pay for what you use". There are three scenarios to consider: @@ -736,7 +735,7 @@ There are three scenarios to consider: * the runtime cost when annotations are defined *and* referenced. We'll examine each of these scenarios in the context of all three -semantics for annotations: stock, PEP 563, and this PEP. +semantics for annotations: stock, :pep:`563`, and this PEP. When there are no annotations, all three semantics have the same runtime cost: zero. No annotations dict is created and no code is @@ -745,12 +744,12 @@ consumes no memory. When annotations are defined but not referenced, the runtime cost of Python with this PEP should be roughly equal to or slightly better -than PEP 563 semantics, and slightly better than "stock" Python +than :pep:`563` semantics, and slightly better than "stock" Python semantics. The specifics depend on the object being annotated: * With stock semantics, the annotations dict is always built, and set as an attribute of the object being annotated. -* In PEP 563 semantics, for function objects, a single constant +* In :pep:`563` semantics, for function objects, a single constant (a tuple) is set as an attribute of the function. For class and module objects, the annotations dict is always built and set as an attribute of the class or module. @@ -762,9 +761,9 @@ semantics. The specifics depend on the object being annotated: of the object being annotated. When annotations are both defined and referenced, code using -this PEP should be much faster than code using PEP 563 semantics, +this PEP should be much faster than code using :pep:`563` semantics, and equivalent to or slightly improved over original Python -semantics. PEP 563 semantics requires invoking ``eval()`` for +semantics. :pep:`563` semantics requires invoking ``eval()`` for every value inside an annotations dict, which is enormously slow. And, as already mentioned, this PEP generates measurably more efficient bytecode for class and module annotations than stock @@ -789,7 +788,7 @@ to build the dict for all annotatable objects: functions, classes, and modules. Stock semantics also uses ``BUILD_CONST_KEY_MAP`` bytecode -for function annotations. PEP 563 has an even more efficient +for function annotations. :pep:`563` has an even more efficient method for building annotations dicts on functions, leveraging the fact that its annotations dicts only contain strings for both keys and values. At compile-time it constructs a tuple @@ -802,7 +801,7 @@ Of course, this performance win is negated if the annotations are examined, due to the overhead of ``eval()``. For class and module annotations, both stock semantics -and PEP 563 generate a longer and slightly-less-efficient +and :pep:`563` generate a longer and slightly-less-efficient stanza of bytecode, creating the dict and setting the annotations individually. @@ -813,12 +812,12 @@ For Future Discussion Circular Imports ---------------- -There is one unfortunately-common scenario where PEP 563 +There is one unfortunately-common scenario where :pep:`563` currently provides a better experience, and it has to do with large code bases, with circular dependencies and imports, that examine their annotations at run-time. -PEP 563 permitted defining *and examining* invalid +:pep:`563` permitted defining *and examining* invalid expressions as annotations. Its implementation requires annotations to be legal Python expressions, which it then converts into strings at compile-time. But legal Python @@ -834,7 +833,7 @@ Some large organizations have code bases that unfortunately have circular dependency problems with their annotations--class A has methods annotated with class B, but class B has methods annotated with class A--that can be difficult to resolve. -Since PEP 563 stringizes their annotations, it allows them +Since :pep:`563` stringizes their annotations, it allows them to leave these circular dependencies in place, and they can sidestep the circular import problem by never importing the module that defines the types used in the annotations. Their @@ -886,7 +885,7 @@ here: semantics of annotations so that they don't raise a ``NameError`` when an unknown name is evaluated, but instead create some sort of proxy "reference" object. -* Of course, even if we do deprecate PEP 563, it will be +* Of course, even if we do deprecate :pep:`563`, it will be several releases before the functionality is removed, giving us several years in which to research and innovate new solutions for this problem. @@ -903,7 +902,7 @@ cls.__globals__ and fn.__locals__ Is it permissible to add the ``__globals__`` reference to class objects as proposed here? It's not clear why this hasn't already -been done; PEP 563 could have made use of class globals, but instead +been done; :pep:`563` could have made use of class globals, but instead made do with looking up classes inside ``sys.modules``. Python seems strangely allergic to adding a ``__globals__`` reference to class objects. @@ -925,7 +924,7 @@ implementation of this PEP: much more costly for function objects, even as annotations are rarely used at runtime.) * Use the class's ``__module__`` attribute to look up its module - by name in ``sys.modules``. This is what PEP 563 advises. + by name in ``sys.modules``. This is what :pep:`563` advises. While this is passable for userspace or library code, it seems like a little bit of a code smell for this to be defined semantics baked into the language itself. diff --git a/pep-0652.rst b/pep-0652.rst index ede2de38e93..5f509aeaf8c 100644 --- a/pep-0652.rst +++ b/pep-0652.rst @@ -37,9 +37,9 @@ In theory, this brings several advantages: details, this API is becoming a viable target for alternate Python implementations that would be incompatible with the full C API. -However, in hindsight, PEP 384 and its implementation has several issues: +However, in hindsight, :pep:`384` and its implementation has several issues: -* It is ill-defined. According to PEP 384, functions are *opt-out*: +* It is ill-defined. According to :pep:`384`, functions are *opt-out*: all functions not specially marked are part of the Stable ABI. In practice, for Windows there's a list that's *opt-in*. For users there is a ``#define`` that should make only the Stable ABI diff --git a/pep-0653.rst b/pep-0653.rst index 7c97e59103c..527f0bff9ea 100644 --- a/pep-0653.rst +++ b/pep-0653.rst @@ -11,11 +11,11 @@ Post-History: 18-Feb-2021 Abstract ======== -This PEP proposes a semantics for pattern matching that respects the general concept of PEP 634, +This PEP proposes a semantics for pattern matching that respects the general concept of :pep:`634`, but is more precise, easier to reason about, and should be faster. The object model will be extended with two special (dunder) attributes, ``__match_container__`` and -``__match_class__``, in addition to the ``__match_args__`` attribute from PEP 634, to support pattern matching. +``__match_class__``, in addition to the ``__match_args__`` attribute from :pep:`634`, to support pattern matching. Both of these new attributes must be integers and ``__match_args__`` is required to be a tuple of unique strings. With this PEP: @@ -27,14 +27,14 @@ With this PEP: Motivation ========== -Pattern matching in Python, as described in PEP 634, is to be added to Python 3.10. -Unfortunately, PEP 634 is not as precise about the semantics as it could be, +Pattern matching in Python, as described in :pep:`634`, is to be added to Python 3.10. +Unfortunately, :pep:`634` is not as precise about the semantics as it could be, nor does it allow classes sufficient control over how they match patterns. Precise semantics ----------------- -PEP 634 explicitly includes a section on undefined behavior. +:pep:`634` explicitly includes a section on undefined behavior. Large amounts of undefined behavior may be acceptable in a language like C, but in Python it should be kept to a minimum. Pattern matching in Python can be defined more precisely without losing expressiveness or performance. @@ -42,11 +42,11 @@ Pattern matching in Python can be defined more precisely without losing expressi Improved control over class matching ------------------------------------ -PEP 634 delegates the decision over whether a class is a sequence or mapping to ``collections.abc``. +:pep:`634` delegates the decision over whether a class is a sequence or mapping to ``collections.abc``. Not all classes that could be considered sequences are registered as subclasses of ``collections.abc.Sequence``. This PEP allows them to match sequence patterns, without the full ``collections.abc.Sequence`` machinery. -PEP 634 privileges some builtin classes with a special form of matching, the "self" match. +:pep:`634` privileges some builtin classes with a special form of matching, the "self" match. For example the pattern ``list(x)`` matches a list and assigns the list to ``x``. By allowing classes to choose which kinds of pattern they match, other classes can use this form as well. @@ -57,7 +57,7 @@ For example, using ``sympy``, we might want to write:: return Pow(a, 2) Which requires the sympy class ``Symbol`` to "self" match. -For ``sympy`` to support this pattern with PEP 634 is possible, but a bit tricky. +For ``sympy`` to support this pattern with :pep:`634` is possible, but a bit tricky. With this PEP it can be implemented very easily [1]_. Robustness @@ -67,7 +67,7 @@ With this PEP, access to attributes during pattern matching becomes well defined This makes pattern matching less error prone when matching objects with hidden side effects, such as object-relational mappers. Objects will have more control over their own deconstruction, which can help prevent unintended consequences should attribute access have side-effects. -PEP 634 relies on the ``collections.abc`` module when determining which patterns a value can match, implicitly importing it if necessary. +:pep:`634` relies on the ``collections.abc`` module when determining which patterns a value can match, implicitly importing it if necessary. This PEP will eliminate surprising import errors and misleading audit events from those imports. @@ -144,7 +144,7 @@ These special attributes will be inherited as normal. If ``__match_args__`` is overridden, then it is required to hold a tuple of unique strings. It may be empty. .. note:: - ``__match_args__`` will be automatically generated for dataclasses and named tuples, as specified in PEP 634. + ``__match_args__`` will be automatically generated for dataclasses and named tuples, as specified in :pep:`634`. The pattern matching implementation is *not* required to check that any of these attributes behave as specified. If the value of ``__match_container__``, ``__match_class__`` or ``__match_args__`` is not as specified, then @@ -168,7 +168,7 @@ not the values of those variables. The psuedo-function ``QUOTE`` takes a variable and returns the name of that variable. For example, if the meta-variable ``$VAR`` held the variable ``foo`` then ``QUOTE($VAR) == "foo"``. -All additional code listed below that is not present in the original source will not trigger line events, conforming to PEP 626. +All additional code listed below that is not present in the original source will not trigger line events, conforming to :pep:`626`. Preamble @@ -521,7 +521,7 @@ Implementation The naive implementation that follows from the specification will not be very efficient. Fortunately, there are some reasonably straightforward transformations that can be used to improve performance. -Performance should be comparable to the implementation of PEP 634 (at time of writing) by the release of 3.10. +Performance should be comparable to the implementation of :pep:`634` (at time of writing) by the release of 3.10. Further performance improvements may have to wait for the 3.11 release. Possible optimizations @@ -645,7 +645,7 @@ The changes to the semantics can be summarized as: * Allows classes to opt out of deconstruction altogether, if necessary, but setting ``__match_class__ = 0``. * The behavior when matching patterns is more precisely defined, but is otherwise unchanged. -There are no changes to syntax. All examples given in the PEP 636 tutorial should continue to work as they do now. +There are no changes to syntax. All examples given in the :pep:`636` tutorial should continue to work as they do now. Rejected Ideas ============== @@ -668,7 +668,7 @@ For the class:: ... Ideally we would match the attributes "a" and "p", but not "m". -However, there is no general way to do that, so this PEP now follows the semantics of PEP 634. +However, there is no general way to do that, so this PEP now follows the semantics of :pep:`634`. Lookup of ``__match_args__`` on the subject not the pattern ----------------------------------------------------------- @@ -715,11 +715,6 @@ In an earlier version of this PEP, there was a distinct value for ``__match_clas pattern that would have required deconstruction. However, this would become redundant once ``MATCH_POSITIONAL`` is introduced, and complicates the specification for an extremely rare case. -References -========== - -PEP 634 -https://www.python.org/dev/peps/pep-0634 Code examples ============= diff --git a/pep-0654.rst b/pep-0654.rst index 3a16b64d9d1..b5a704c4e89 100644 --- a/pep-0654.rst +++ b/pep-0654.rst @@ -1465,7 +1465,7 @@ Steve Stagg, Victor Stinner, Marco Sulla, Petr Viktorin and Barry Warsaw. Acceptance ========== -PEP 654 was `accepted by Thomas Wouters on Sep 24, 2021 +:pep:`654` was `accepted by Thomas Wouters on Sep 24, 2021 `_. diff --git a/pep-0655.rst b/pep-0655.rst index c4e499eebf4..d39995f9854 100644 --- a/pep-0655.rst +++ b/pep-0655.rst @@ -175,7 +175,7 @@ wishes to preserve *all* annotations in the original source: class Movie(TypedDict): title: str year: NotRequired[int] - + assert get_type_hints(Movie) == \ {'title': str, 'year': int} assert get_type_hints(Movie, include_extras=True) == \ @@ -192,7 +192,7 @@ recognize ``Required[]`` and ``NotRequired[]``: assert get_origin(Required[int]) is Required assert get_args(Required[int]) == (int,) - + assert get_origin(NotRequired[int]) is NotRequired assert get_args(NotRequired[int]) == (int,) diff --git a/pep-0660.rst b/pep-0660.rst index e18b86631c5..7b9ba18ee1d 100644 --- a/pep-0660.rst +++ b/pep-0660.rst @@ -13,7 +13,7 @@ Resolution: https://discuss.python.org/t/pronouncement-on-peps-660-and-662-edita Abstract ======== -This document describes a PEP 517 style method for the installation of packages +This document describes a :pep:`517` style method for the installation of packages in editable mode. Motivation @@ -33,14 +33,14 @@ The installation of projects in such a way that the python code being imported remains in the source directory is known as the *editable* installation mode. -Now that PEP 517 provides a mechanism to create alternatives to setuptools, and +Now that :pep:`517` provides a mechanism to create alternatives to setuptools, and decouple installation front ends from build backends, we need a new mechanism to install packages in editable mode. Rationale ========= -PEP 517 deferred "Editable installs", meaning non-``setup.py`` +:pep:`517` deferred "Editable installs", meaning non-``setup.py`` distributions lacked that feature. The only way to retain ``editable`` installs for these distributions was to provide a compatible ``setup.py develop`` implementation. By defining an editable hook other build frontends gain @@ -79,7 +79,7 @@ encouraged to document such potential differences. The Mechanism ============= -This PEP adds three optional hooks to the PEP 517 backend interface. These hooks +This PEP adds three optional hooks to the :pep:`517` backend interface. These hooks are used to build a wheel that, when installed, allows that distribution to be imported from its source folder. @@ -109,7 +109,7 @@ Build-backends must produce wheels that have the same dependencies with the exception that they can add dependencies necessary for their editable mechanism to function at runtime (such as `editables`_). -The filename for the "editable" wheel needs to be PEP 427 compliant too. It +The filename for the "editable" wheel needs to be :pep:`427` compliant too. It does not need to use the same tags as ``build_wheel`` but it must be tagged as compatible with the system. @@ -135,7 +135,7 @@ get_requires_for_build_editable def get_requires_for_build_editable(config_settings=None): ... -This hook MUST return an additional list of strings containing PEP 508 +This hook MUST return an additional list of strings containing :pep:`508` dependency specifications, above and beyond those specified in the ``pyproject.toml`` file, to be installed when calling the ``build_editable`` hooks. @@ -206,7 +206,7 @@ Frontends must install "editable" wheels in the same way as regular wheels. This also means uninstallation of editables does not require any special treatment. Frontends must create a ``direct_url.json`` file in the ``.dist-info`` -directory of the installed distribution, in compliance with PEP 610. The +directory of the installed distribution, in compliance with :pep:`610`. The ``url`` value must be a ``file://`` url pointing to the project directory (i.e. the directory containing ``pyproject.toml``), and the ``dir_info`` value must be ``{'editable': true}``. @@ -269,14 +269,14 @@ identifier. In other words ``pkg==1.0+local`` is not satisfied by version Virtual wheel ------------- -Another approach was proposed in PEP 662, where +Another approach was proposed in :pep:`662`, where the build backend returns a mapping from source files and directories to the installed layout. It is then up to the installer frontend to realize the editable installation by whatever means it deems adequate for its users. In terms of capabilities, both proposals provide the core "editable" feature. -The key difference is that PEP 662 leaves it to the frontend to decide how the +The key difference is that :pep:`662` leaves it to the frontend to decide how the editable installation will be realized, while with this PEP, the choice must be made by the backend. Both approaches can in principle provide several editable installation methods for a given project, and let the developer choose one at @@ -287,14 +287,14 @@ range of theoretical and practical expectations about editable installs. The reality is that the only one there is wide experience with is path insertion via .pth (i.e. what setup.py develop does). -We believe that PEP 660 better addresses these "unknown unknowns" today in the +We believe that :pep:`660` better addresses these "unknown unknowns" today in the most reliable way, by letting project authors select the backend or implement the method that provides the editable mechanism that best suit their requirements, and test it works correctly. Since the frontend has no latitude in *how* to install the "editable" wheel, in case of issue, there is only one place to investigate: the build backend. -With PEP 662, issues need to be investigated in the frontend, +With :pep:`662`, issues need to be investigated in the frontend, the backend and possiblty the specification. There is also a high probability that different frontends, implementing the specification in different ways, will produce installations that behave differently than project authors @@ -308,7 +308,7 @@ A `prototype `_ was made that created an unpacked wheel in a temporary directory, to be copied to the target environment by the frontend. This approach was not pursued because a wheel archive is easy to create for the backend, and using a wheel as communication -mechanism is a better fit with the PEP 517 philosophy, and therefore keeps +mechanism is a better fit with the :pep:`517` philosophy, and therefore keeps things simpler for the frontend. References diff --git a/pep-0662.rst b/pep-0662.rst index 1567ec77aae..f7494a5fc88 100644 --- a/pep-0662.rst +++ b/pep-0662.rst @@ -138,7 +138,7 @@ For reference, a non-editable installation works as follows: :pep:`518` environment. Once invoked, the backend returns a wheel. #. The frontend takes the wheel and feeds it to an **installer** - (e.g.,`installer`_) to install the wheel into the target Python interpreter. + (e.g., installer_) to install the wheel into the target Python interpreter. The Mechanism ============= @@ -268,7 +268,7 @@ the frontend, and is encouraged for the frontend to communicate with the user exactly the method chosen, and what limitations that solution will have. The frontend must create a ``direct_url.json`` file in the ``.dist-info`` -directory of the installed distribution, in compliance with PEP 610. The ``url`` +directory of the installed distribution, in compliance with :pep:`610`. The ``url`` value must be a ``file://`` URL pointing to the project directory (i.e., the directory containing ``pyproject.toml``), and the ``dir_info`` value must be ``{'editable': true}``. diff --git a/pep-0664.rst b/pep-0664.rst index 6f221dd045c..0f90029b5b8 100644 --- a/pep-0664.rst +++ b/pep-0664.rst @@ -38,7 +38,7 @@ Release Schedule Note: the dates below use a 17-month development period that results in a 12-month release cadence between major versions, as defined by -PEP 602. +:pep:`602`. Actual: diff --git a/pep-0665.rst b/pep-0665.rst index c1d3f100242..aad60648a9f 100644 --- a/pep-0665.rst +++ b/pep-0665.rst @@ -154,7 +154,7 @@ File Format ----------- We wanted the file format to be easy to read as a diff when auditing -a change to the lock file. As such, and thanks to PEP 518 and +a change to the lock file. As such, and thanks to :pep:`518` and ``pyproject.toml``, we decided to go with the TOML_ file format. @@ -267,7 +267,7 @@ Details Lock files MUST use the TOML_ file format. This not only prevents the need to have another file format in the Python packaging ecosystem -thanks to its adoption by PEP 518 for ``pyproject.toml``, but also +thanks to its adoption by :pep:`518` for ``pyproject.toml``, but also assists in making lock files more human-readable. Lock files MUST end their file names with ``.pylock.toml``. The @@ -844,7 +844,7 @@ installers did not have to make any decisions about *what* to install, only validating that the lock file would work for the target platform. This idea was eventually rejected due to the number of combinations -of potential PEP 508 environment markers. The decision was made that +of potential :pep:`508` environment markers. The decision was made that trying to have lockers generate all possible combinations as individual lock files when a project wants to be cross-platform would be too much. @@ -875,18 +875,18 @@ as the term. Accepting PEP 650 ----------------- -PEP 650 was an earlier attempt at trying to tackle this problem by +:pep:`650` was an earlier attempt at trying to tackle this problem by specifying an API for installers instead of standardizing on a lock -file format (ala PEP 517). The +file format (ala :pep:`517`). The `initial response `__ -to PEP 650 could be considered mild/lukewarm. People seemed to be +to :pep:`650` could be considered mild/lukewarm. People seemed to be consistently confused over which tools should provide what functionality to implement the PEP. It also potentially incurred more overhead as it would require executing Python APIs to perform any actions involving packaging. This PEP chooses to standardize around an artifact instead of an API -(ala PEP 621). This would allow for more tool integrations as it +(ala :pep:`621`). This would allow for more tool integrations as it removes the need to specifically use Python to do things such as create a lock file, update it, or even install packages listed in a lock file. It also allows for easier introspection by forcing @@ -897,7 +897,7 @@ tools when it comes to understanding the artifact they produce). It's also simply the approach other language communities have taken and seem to be happy with. -Acceptance of this PEP would mean PEP 650 gets rejected. +Acceptance of this PEP would mean :pep:`650` gets rejected. ------------------------------------------------------- @@ -916,7 +916,7 @@ Specify Where Lockers Gather Input ---------------------------------- This PEP does not specify how a locker gets its input. An initial -suggestion was to partially reuse PEP 621, but due to disagreements +suggestion was to partially reuse :pep:`621`, but due to disagreements on how flexible the potential input should be in terms of specifying things such as indexes, etc., it was decided this would best be left to a separate PEP. @@ -963,7 +963,7 @@ Acknowledgments =============== Thanks to Frost Ming of PDM_ and Sébastien Eustace of Poetry_ for -providing input around dynamic install-time resolution of PEP 508 +providing input around dynamic install-time resolution of :pep:`508` requirements. Thanks to Kushal Das for making sure reproducible builds stayed a diff --git a/pep-0666.txt b/pep-0666.txt index 8c30fb09b59..88057e61dc1 100644 --- a/pep-0666.txt +++ b/pep-0666.txt @@ -75,7 +75,7 @@ than whether it is too hostile for newcomers. Possibly somebody could get around to explaining to me what is the difference between ``__getattr__`` and ``__getattribute__`` in non-Classic classes in 2.2, a question I have foolishly posted in the middle of the current tab -thread. I would like to know the answer to that question [2]_. +thread. I would like to know the answer to that question [1]_. This proposal, if accepted, will probably mean a heck of a lot of work for somebody. But since I don't want it accepted, I don't @@ -85,10 +85,7 @@ care. References ========== -.. [1] PEP 1, PEP Purpose and Guidelines - http://www.python.org/dev/peps/pep-0001/ - -.. [2] Tim Peters already has (private correspondence). My early 2.2 +.. [1] Tim Peters already has (private correspondence). My early 2.2 didn't have a ``__getattribute__``, and ``__getattr__`` was implemented like ``__getattribute__`` now is. This has been fixed. The important conclusion is that my Decorator Pattern diff --git a/pep-0667.rst b/pep-0667.rst index dc681df6767..9aa5aefc7ac 100644 --- a/pep-0667.rst +++ b/pep-0667.rst @@ -371,17 +371,17 @@ ensure that the reference is not used beyond the lifetime of the object. Comparison with PEP 558 ======================= -This PEP and PEP 558 [2]_ share a common goal: +This PEP and :pep:`558` share a common goal: to make the semantics of ``locals()`` and ``frame.f_locals()`` intelligible, and their operation reliable. -The key difference between this PEP and PEP 558 is that -PEP 558 keeps an internal copy of the local variables, +The key difference between this PEP and :pep:`558` is that +:pep:`558` keeps an internal copy of the local variables, whereas this PEP does not. -PEP 558 does not specify exactly when the internal copy is -updated, making the behavior of PEP 558 impossible to reason about. +:pep:`558` does not specify exactly when the internal copy is +updated, making the behavior of :pep:`558` impossible to reason about. Open Issues @@ -401,8 +401,6 @@ References .. [1] https://bugs.python.org/issue30744 -.. [2] https://www.python.org/dev/peps/pep-0558/ - Copyright ========= diff --git a/pep-0668.rst b/pep-0668.rst index 96e1ff16d95..8c432c00b37 100644 --- a/pep-0668.rst +++ b/pep-0668.rst @@ -98,7 +98,7 @@ package Python-specific package manager A tool for installing, upgrading, and/or removing Python packages in a manner that conforms to Python packaging standards (such as - PEP 376 and PEP 427). The most popular Python-specific package + :pep:`376` and :pep:`427`). The most popular Python-specific package manager is pip [#pip]_; other examples include the old Easy Install command [#easy-install]_ as well as direct usage of a ``setup.py`` command. @@ -114,7 +114,7 @@ distro package manager packages in an installed instance of that distro, which is capable of installing Python packages as well as non-Python packages, and therefore generally has its own database of installed software - unrelated to PEP 376. Examples include ``apt``, ``dpkg``, ``dnf``, + unrelated to :pep:`376`. Examples include ``apt``, ``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is that if a package was installed by a distro package manager, removing or upgrading it in a way that would satisfy a Python-specific package @@ -374,8 +374,8 @@ In more detail, the use cases above are: worth calling out explicitly, because anything on the global ``sys.path`` is visible. - Currently, the answer to "Will ``pip` delete externally-installed - packages`` is no, because pip has a special case for running in a + Currently, the answer to "Will ``pip`` delete externally-installed + packages" is no, because pip has a special case for running in a virtual environment and attempting to delete packages outside it. After this PEP, the answer remains no, but the reasoning becomes more general: system site packages will be outside any of the @@ -707,7 +707,7 @@ Filesystem Hierarchy Standard`__. There are two ways you could do this. One is, if you are building and packaging Python libraries directly (e.g., your packaging helpers -unpack a PEP 517-built wheel or call ``setup.py install``), arrange +unpack a :pep:`517`-built wheel or call ``setup.py install``), arrange for those tools to use a directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``. @@ -886,7 +886,7 @@ non-virtual-environment installs in any Python installation, but that is outside the scope of this PEP.) Should the file be TOML? TOML is gaining popularity for packaging (see -e.g. PEP 517) but does not yet have an implementation in the standard +e.g. :pep:`517`) but does not yet have an implementation in the standard library. Strictly speaking, this isn't a blocker - distros need only write the file, not read it, so they don't need a TOML library (the file will probably be written by hand, regardless of format), and @@ -924,16 +924,16 @@ distinction seems difficult. We think it's a good idea for Python-specific package managers to print a warning if they shadow a package, but we think it's not worth disabling it by default. -Why not use the ``INSTALLER`` file from PEP 376 to determine who +Why not use the ``INSTALLER`` file from :pep:`376` to determine who installed a package and whether it can be removed? First, it's specific to a particular package (it's in the package's ``dist-info`` directory), so like some of the alternatives above, it doesn't provide information on an entire environment and whether package installations -are permissible. PEP 627 also updates PEP 376 to prevent programmatic +are permissible. :pep:`627` also updates :pep:`376` to prevent programmatic use of ``INSTALLER``, specifying that the file is "to be used for informational purposes only. [...] Our goal is supporting interoperating tools, and basing any action on which tool happened to -install a package runs counter to that goal." Finally, as PEP 627 +install a package runs counter to that goal." Finally, as :pep:`627` envisions, there are legitimate use cases for one tool knowing how to handle packages installed by another tool; for instance, ``conda`` can safely remove a package installed by ``pip`` into a Conda environment. @@ -1060,7 +1060,7 @@ References For additional background on these problems and previous attempts to solve them, see `Debian bug 771794`_ "pip silently removes/updates -system provided python packages` from 2014, Fedora's 2018 article +system provided python packages" from 2014, Fedora's 2018 article `Making sudo pip safe`_ about pointing ``sudo pip`` at /usr/local (which acknowledges that the changes still do not make ``sudo pip`` completely safe), pip issues 5605_ ("Disable upgrades to existing diff --git a/pep-0669.rst b/pep-0669.rst index ebef129c576..ce5c33f3cb9 100644 --- a/pep-0669.rst +++ b/pep-0669.rst @@ -18,7 +18,8 @@ This PEP proposes an API for monitoring of Python programs running on CPython that will enable monitoring at low cost. Although this PEP does not specify an implementation, it is expected that -it will be implemented using the quickening step of PEP 659 [1]_. +it will be implemented using the quickening step of +:pep:`PEP 659 <659#quickening>`. A ``sys.monitoring`` namespace will be added, which will contain the relevant functions and enum. @@ -37,7 +38,7 @@ Python developers should expect that too. Rationale ========= -The quickening mechanism provided by PEP 659 provides a way to dynamically +The quickening mechanism provided by :pep:`659` provides a way to dynamically modify executing Python bytecode. These modifications have little cost beyond the parts of the code that are modified and a relatively low cost to those parts that are modified. We can leverage this to provide an efficient @@ -205,14 +206,14 @@ This PEP is fully backwards compatible, in the sense that old code will work if the features of this PEP are unused. However, if it is used it will effectively disable ``sys.settrace``, -``sys.setprofile`` and PEP 523 frame evaluation. +``sys.setprofile`` and :pep:`523` frame evaluation. -If PEP 523 is in use, or ``sys.settrace`` or ``sys.setprofile`` has been +If :pep:`523` is in use, or ``sys.settrace`` or ``sys.setprofile`` has been set, then calling ``sys.monitoring.set_events()`` or ``sys.monitoring.set_local_events()`` will raise an exception. Likewise, if ``sys.monitoring.set_events()`` or -``sys.monitoring.set_local_events()`` has been called, then using PEP 523 +``sys.monitoring.set_local_events()`` has been called, then using :pep:`523` or calling ``sys.settrace`` or ``sys.setprofile`` will raise an exception. This PEP is incompatible with ``sys.settrace`` and ``sys.setprofile`` @@ -221,10 +222,10 @@ will use the same underlying mechanism as this PEP. It would be too slow to support both the new and old monitoring mechanisms at the same time, and they would interfere in awkward ways if both were active at the same time. -This PEP is incompatible with PEP 523, because PEP 523 prevents the VM being +This PEP is incompatible with :pep:`523`, because :pep:`523` prevents the VM being able to modify the code objects of executing code, which is a necessary feature. -We may seek to remove ``sys.settrace`` and PEP 523 in the future once the APIs +We may seek to remove ``sys.settrace`` and :pep:`523` in the future once the APIs provided by this PEP have been widely adopted, but that is for another PEP. Performance @@ -235,7 +236,7 @@ performance. If a small set of events are active, e.g. for a debugger, then the overhead of callbacks will be orders of magnitudes less than for ``sys.settrace`` and -much cheaper than using PEP 523. +much cheaper than using :pep:`523`. For heavily instrumented code, e.g. using ``LINE``, performance should be better than ``sys.settrace``, but not by that much as performance will be @@ -264,7 +265,8 @@ implementation for later versions of CPython and other Python implementations may differ considerably. The proposed implementation of this PEP will be built on top of the quickening -step of PEP 659 [1]_. Activating some events will cause all code objects to +step of :pep:`PEP 659 <659#quickening>`. +Activating some events will cause all code objects to be quickened before they are executed. For example, if the ``LINE`` event is turned on, then all instructions that @@ -398,13 +400,6 @@ for inserting the monitoring instructions, rather than have VM do it. However, that puts too much of a burden on the tools, and would make attaching a debugger nearly impossible. -References -========== - -.. [1] Quickening in PEP 659 - https://www.python.org/dev/peps/pep-0659/#quickening - - Copyright ========= diff --git a/pep-0671.rst b/pep-0671.rst index b77e0e4bae6..be568c59415 100644 --- a/pep-0671.rst +++ b/pep-0671.rst @@ -125,15 +125,15 @@ cover the important distinction here (and the fact that they are similar). Interaction with other open PEPs ================================ -PEP 661 attempts to solve one of the same problems as this does. It seeks to +:pep:`661` attempts to solve one of the same problems as this does. It seeks to improve the documentation of sentinel values in default arguments, where this -proposal seeks to remove the need for sentinels in many common cases. PEP 661 +proposal seeks to remove the need for sentinels in many common cases. :pep:`661` is able to improve documentation in arbitrarily complicated functions (it cites ``traceback.print_exception`` as its primary motivation, which has two arguments which must both-or-neither be specified); on the other hand, many of the common cases would no longer need sentinels if the true default could be defined by the function. Additionally, dedicated sentinel objects can be -used as dictionary lookup keys, where PEP 671 does not apply. +used as dictionary lookup keys, where :pep:`671` does not apply. Interaction with annotations diff --git a/pep-0673.rst b/pep-0673.rst index f06bc25a7db..52be7ece8ea 100644 --- a/pep-0673.rst +++ b/pep-0673.rst @@ -18,7 +18,7 @@ Abstract This PEP introduces a simple and intuitive way to annotate methods that return an instance of their class. This behaves the same as the ``TypeVar``-based -approach specified in `PEP 484 `_ +approach specified in :pep:`484` but is more concise and easier to follow. Motivation @@ -501,8 +501,8 @@ is treated equivalently to: return self -See `PEP 544 -`_ for +See :pep:`PEP 544 +<544#self-types-in-protocols>` for details on the behavior of TypeVars bound to protocols. Checking a class for compatibility with a protocol: If a protocol uses diff --git a/pep-0674.rst b/pep-0674.rst index 32f4aee0f60..0e86ec6404d 100644 --- a/pep-0674.rst +++ b/pep-0674.rst @@ -279,7 +279,7 @@ Moreover, `24 projects just have to regenerate their Cython code `_ to use ``Py_SET_TYPE()``. -This change does not follow the PEP 387 deprecation process. There is no +This change does not follow the :pep:`387` deprecation process. There is no known way to emit a deprecation warning only when a macro is used as a l-value, but not when it's used differently (ex: as a r-value). diff --git a/pep-0675.rst b/pep-0675.rst index 5aee54c9bda..3365f147173 100644 --- a/pep-0675.rst +++ b/pep-0675.rst @@ -105,8 +105,8 @@ user work. To meet this goal, we introduce the ``Literal[str]`` type, which only accepts string values that are known to be made of literals. This is a -generalization of the ``Literal["foo"]`` type from `PEP 586 -`_. A string of type +generalization of the ``Literal["foo"]`` type from :pep:`586`. +A string of type ``Literal[str]`` cannot contain user-controlled data. Thus, any API that only accepts ``Literal[str]`` will be immune to injection vulnerabilities (with pragmatic `limitations `_. The only legal +:pep:`586`. The only legal parameter is the literal value ``str``. Other values are rejected even if they evaluate to the same value (``str``), such as ``Literal[(lambda x: x)(str)]``. @@ -526,8 +526,8 @@ match: Backwards Compatibility ----------------------- -As PEP 586 `mentions -`_, +As :pep:`PEP 586 mentions +<586#backwards-compatibility>`, type checkers "should feel free to experiment with more sophisticated inference techniques". So, if the type checker infers a literal string type for an unannotated variable that is initialized with a literal @@ -543,7 +543,7 @@ This enables precise type checking of idiomatic SQL query code without annotating the code at all (as seen in the `Motivation`_ section example). -However, like PEP 586, this PEP does not mandate the above inference +However, like :pep:`586`, this PEP does not mandate the above inference strategy. In case the type checker doesn't infer ``x`` to have type ``Literal["hello"]``, users can aid the type checker by explicitly annotating it as ``x: Literal[str]``: @@ -562,7 +562,7 @@ Backwards compatibility ======================= Backwards compatibility: ``Literal[str]`` is acceptable at runtime, so -this doesn't require any changes to the Python runtime itself. PEP 586 +this doesn't require any changes to the Python runtime itself. :pep:`586` already backports ``Literal``, so this PEP does not need to change it. diff --git a/pep-0677.rst b/pep-0677.rst index 79a2b09b498..2458e69f725 100644 --- a/pep-0677.rst +++ b/pep-0677.rst @@ -30,7 +30,7 @@ Motivation One way to make code safer and easier to analyze is by making sure that functions and classes are well-typed. In Python we have type -annotations, the framework for which is defined in PEP 484, to provide +annotations, the framework for which is defined in :pep:`484`, to provide type hints that can find bugs as well as helping with editor tooling like tab completion, static analysis tooling, and code review. @@ -133,7 +133,7 @@ the fifth most common complex type in typeshed, after ``Optional``, ``Tuple``, ``Union``, and ``List``. The others have had their syntax improved and the need for imports -eliminated by either PEP 604 or PEP 585: +eliminated by either :pep:`604` or :pep:`585`: - ``typing.Optional[int]`` is written ``int | None`` - ``typing.Union[int, str]`` is written ``int | str`` @@ -235,7 +235,7 @@ prevents a type checker from seeing this and alerting a user that ``f(y=10)`` is invalid. -With PEP 612 it is possible to type decorators like this correctly +With :pep:`612` it is possible to type decorators like this correctly as follows:: from typing import Any, Callable, Concatenate, ParamSpec, TypeVar @@ -453,9 +453,9 @@ Here are our proposed changes to the `Python Grammar -If PEP 646 is accepted, we intend to include support for unpacked +If :pep:`646` is accepted, we intend to include support for unpacked types in two ways. To support the "star-for-unpack" syntax proposed in -PEP 646, we will modify the grammar for +:pep:`646`, we will modify the grammar for ``callable_type_positional_argument`` as follows:: callable_type_positional_argument: @@ -514,11 +514,11 @@ to an operator like ``|``:: We discussed each of these behaviors and believe they are desirable: -- Union types (represented by ``A | B`` according to PEP 604) are +- Union types (represented by ``A | B`` according to :pep:`604`) are valid in function signature returns, so we need to allow operators in the return position for consistency. - Given that operators bind more tightly than ``->`` it is correct - that a type like ```bool | () -> bool`` must be a syntax error. We + that a type like ``bool | () -> bool`` must be a syntax error. We should be sure the error message is clear because this may be a common mistake. - Associating ``->`` to the right, rather than requiring explicit @@ -595,7 +595,7 @@ We decided that there were compelling reasons to do this: Incompatibility with other possible uses of ``*`` and ``**`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The use of ``**P`` for supporting PEP 612 ``ParamSpec`` rules out any +The use of ``**P`` for supporting :pep:`612` ``ParamSpec`` rules out any future proposal using a bare ``**`` to type ``kwargs``. This seems acceptable because: @@ -604,7 +604,7 @@ future proposal using a bare ``**`` to type similar to a function signature. In other words, if we ever support typing ``kwargs`` in callable types, we would prefer ``(int, **kwargs: str)`` rather than ``(int, **str)``. -- PEP 646 unpacking syntax would rule out using ``*`` for +- :pep:`646` unpacking syntax would rule out using ``*`` for ``args``. The ``kwargs`` case is similar enough that this rules out a bare ``**`` anyway. @@ -741,7 +741,7 @@ them as if they were written in terms of the following:: Additional Behaviors of ``types.CallableType`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As with the ``A | B`` syntax for unions introduced in PEP 604: +As with the ``A | B`` syntax for unions introduced in :pep:`604`: - The ``__eq__`` method should treat equivalent ``typing.Callable`` values as equal to values constructed using the builtin syntax, and @@ -771,11 +771,11 @@ described by the existing ``typing.Callable`` semantics: is simple callable types with positional parameters, such as ``(int, str) -> bool`` - ParamSpec and Concatenate: The next most important feature is good - support for PEP 612 ``ParamSpec`` and ``Concatenate`` types like + support for :pep:`612` ``ParamSpec`` and ``Concatenate`` types like ``(**P) -> bool`` and ``(int, **P) -> bool``. These are common primarily because of the heavy use of decorator patterns in python code. -- TypeVarTuples: The next most important feature, assuming PEP 646 is +- TypeVarTuples: The next most important feature, assuming :pep:`646` is accepted, is for unpacked types which are common because of cases where a wrapper passes along ``*args`` to some other function. @@ -799,7 +799,7 @@ types would have been equivalent:: Function = (int, y: float, *, z: bool = ..., **kwargs: str) -> bool Advantages of this syntax include: - Most of the advantages of the -proposal in this PEP (conciseness, PEP 612 support, etc) - +proposal in this PEP (conciseness, :pep:`612` support, etc) - Furthermore, the ability to handle named, optional, and variadic arguments @@ -887,7 +887,7 @@ Key downsides that led us to reject the idea include the following: detected by unit tests - where library authors would accidentally use types with named arguments. - Our analysis suggests that support for ``ParamSpec`` is key, but the - scoping rules laid out in PEP 612 would have made this difficult. + scoping rules laid out in :pep:`612` would have made this difficult. Other Proposals Considered @@ -908,7 +908,7 @@ of callback protocols:: named: str, *args: float, keyword_only: int = ..., - **kwargs: str)` + **kwargs: str ) -> bool: ... f: CallableType = ... @@ -1067,7 +1067,7 @@ that it could be used as a type:: callable[[int, str], bool] -This change would be analogous to PEP 585 that made built in collections +This change would be analogous to :pep:`585` that made built in collections like ``list`` and ``dict`` usable as types, and would make imports more convenient, but it wouldn't help readability of the types themselves much. @@ -1198,8 +1198,8 @@ Resources Background and History ---------------------- -`PEP 484 specifies -`_ +:pep:`PEP 484 specifies +<484#suggested-syntax-for-python-2-7-and-straddling-code>` a very similar syntax for function type hint *comments* for use in code that needs to work on Python 2.7. For example:: @@ -1209,7 +1209,7 @@ code that needs to work on Python 2.7. For example:: At that time we used indexing operations to specify generic types like ``typing.Callable`` because we decided not to add syntax for -types. However, we have since begun to do so, e.g. with PEP 604. +types. However, we have since begun to do so, e.g. with :pep:`604`. **Maggie** proposed better callable type syntax as part of a larger `presentation on typing simplifications diff --git a/pep-3000.txt b/pep-3000.txt index 2827689f488..af3ee070a5e 100644 --- a/pep-3000.txt +++ b/pep-3000.txt @@ -35,11 +35,11 @@ files. PEP Numbering ============= -Python 3000 PEPs are numbered starting at PEP 3000. PEPs 3000-3099 +Python 3000 PEPs are numbered starting at :pep:`3000`. PEPs 3000-3099 are meta-PEPs -- these can be either process or informational PEPs. -PEPs 3100-3999 are feature PEPs. PEP 3000 itself (this PEP) is +PEPs 3100-3999 are feature PEPs. :pep:`3000` itself (this PEP) is special; it is the meta-PEP for Python 3000 meta-PEPs (IOW it describe -the process to define processes). PEP 3100 is also special; it's a +the process to define processes). :pep:`3100` is also special; it's a laundry list of features that were selected for (hopeful) inclusion in Python 3000 before we started the Python 3000 process for real. PEP 3099, finally, is a list of features that will *not* change. @@ -48,7 +48,7 @@ Python 3000 before we started the Python 3000 process for real. PEP Timeline ======== -See PEP 361 [#pep361]_, which contains the release schedule for Python +See :pep:`361`, which contains the release schedule for Python 2.6 and 3.0. These versions will be released in lockstep. Note: standard library development is expected to ramp up after 3.0a1 @@ -149,9 +149,6 @@ References .. [2] Joel on Software: Things You Should Never Do, Part I http://www.joelonsoftware.com/articles/fog0000000069.html -.. [#pep361] PEP 361 (Python 2.6 and 3.0 Release Schedule) - http://www.python.org/dev/peps/pep-0361 - Copyright ========= diff --git a/pep-3003.txt b/pep-3003.txt index 2c5c87b4583..d26fcc2fa78 100644 --- a/pep-3003.txt +++ b/pep-3003.txt @@ -122,7 +122,7 @@ Allowed to Change * Backports of 3.x features to 2.x The moratorium only affects features that would be new in 3.x. * Import semantics - For example, PEP 382. After all, import semantics vary between + For example, :pep:`382`. After all, import semantics vary between Python implementations anyway. diff --git a/pep-3099.txt b/pep-3099.txt index d0a3af2e176..f76d4a24a3f 100644 --- a/pep-3099.txt +++ b/pep-3099.txt @@ -149,8 +149,8 @@ Core language * The ``else`` clause in ``while`` and ``for`` loops will not change semantics, or be removed. - Thread: "for/except/else syntax" - https://mail.python.org/pipermail/python-ideas/2009-October/006083.html + Thread: "for/except/else syntax" + https://mail.python.org/pipermail/python-ideas/2009-October/006083.html Builtins diff --git a/pep-3100.txt b/pep-3100.txt index 6cc33f3aeff..feb50a6fc6b 100644 --- a/pep-3100.txt +++ b/pep-3100.txt @@ -13,7 +13,7 @@ Post-History: Abstract ======== -This PEP, previously known as PEP 3000, describes smaller scale changes +This PEP, previously known as :pep:`3000`, describes smaller scale changes and new features for which no separate PEP is written yet, all targeted for Python 3000. @@ -29,7 +29,7 @@ decisions for which changes are listed in this document are made by Guido van Rossum, who has chosen them as goals for Python 3.0. Guido's pronouncements on things that will not change in Python 3.0 -are recorded in PEP 3099. [#pep3099]_ +are recorded in :pep:`3099`. General goals @@ -43,10 +43,10 @@ obvious way of doing something is enough. [1]_ Influencing PEPs ================ -* PEP 238 (Changing the Division Operator) [#pep238]_ -* PEP 328 (Imports: Multi-Line and Absolute/Relative) [#pep328]_ -* PEP 343 (The "with" Statement) [#pep343]_ -* PEP 352 (Required Superclass for Exceptions) [#pep352]_ +* :pep:`238` (Changing the Division Operator) +* :pep:`328` (Imports: Multi-Line and Absolute/Relative) +* :pep:`343` (The "with" Statement) +* :pep:`352` (Required Superclass for Exceptions) Style changes @@ -62,11 +62,11 @@ Style changes Core language ============= -* True division becomes default behavior [#pep238]_ [done] +* True division becomes default behavior :pep:`238` [done] * ``exec`` as a statement is not worth it -- make it a function [done] -* Add optional declarations for static typing [#pep3107]_ [10]_ [done] +* Add optional declarations for static typing :pep:`3107` [10]_ [done] * Support only new-style classes; classic classes will be gone [1]_ [done] -* Replace ``print`` by a function [14]_ [#pep3105]_ [done] +* Replace ``print`` by a function [14]_ :pep:`3105` [done] * The ``softspace`` attribute of files goes away. [done] * Use ``except E1, E2, E3 as err:`` if you want the error variable. [3]_ [done] * ``None`` becomes a keyword [4]_; also ``True`` and ``False`` [done] @@ -74,14 +74,14 @@ Core language * ``as`` becomes a keyword [5]_ (starting in 2.6 already) [done] * Have list comprehensions be syntactic sugar for passing an equivalent generator expression to ``list()``; as a consequence the - loop variable will no longer be exposed [#pep289]_ [done] + loop variable will no longer be exposed :pep:`289` [done] * Comparisons other than ``==`` and ``!=`` between disparate types will raise an exception unless explicitly supported by the type [6]_ [done] * floats will not be acceptable as arguments in place of ints for operations where floats are inadvertently accepted (PyArg_ParseTuple() i & l formats) * Remove from ... import * at function scope. [done] This means that functions can always be optimized and support for unoptimized functions can go away. -* Imports [#pep328]_ +* Imports :pep:`328` + Imports will be absolute by default. [done] + Relative imports must be explicitly specified. [done] + Indirection entries in ``sys.modules`` (i.e., a value of ``None`` for @@ -96,7 +96,7 @@ Core language - List comprehensions will require parentheses around the iterables. This will make list comprehensions more similar to generator comprehensions. [x for x in 1, 2] will need to be: [x for x in (1, 2)] [done] - - Lambdas may have to be parenthesized [#pep308]_ [NO] + - Lambdas may have to be parenthesized :pep:`308` [NO] * In order to get rid of the confusion between __builtin__ and __builtins__, it was decided to rename __builtin__ (the module) to builtins, and to leave @@ -112,7 +112,7 @@ Core language * The ``__nonzero__`` special method will be renamed to ``__bool__`` and have to return a bool. The typeobject slot will be called ``tp_bool`` [23]_ [done] -* Dict comprehensions, as first proposed in [#pep274]_ [done] +* Dict comprehensions, as first proposed in :pep:`274` [done] {K(x): V(x) for x in S if P(x)} means dict((K(x), V(x)) for x in S if P(x)). To be removed: @@ -147,7 +147,7 @@ Atomic Types * Remove distinction between int and long types; 'long' built-in type and literals with 'L' or 'l' suffix disappear [1]_ [done] * Make all strings be Unicode, and have a separate bytes() type [1]_ - The new string type will be called 'str'. See PEP 3137. [done] + The new string type will be called 'str'. See :pep:`3137`. [done] * Return iterable views instead of lists where appropriate for atomic type methods (e.g. ``dict.keys()``, ``dict.values()``, ``dict.items()``, etc.); iter* methods will be removed. [done] @@ -176,7 +176,7 @@ Built-in Namespace * Introduce ``trunc()``, which would call the ``__trunc__()`` method on its argument; suggested use is for objects like float where calling ``__int__()`` has data loss, but an integral representation is still desired? [8]_ [done] -* Exception hierarchy changes [#pep352]_ [done] +* Exception hierarchy changes :pep:`352` [done] * Add a ``bin()`` function for a binary representation of integers [done] To be removed: @@ -202,7 +202,7 @@ Standard library * Move test code to where it belongs, there will be no more test() functions in the standard library * Convert all tests to use either doctest or unittest. -* For the procedures of standard library improvement, see PEP 3001 [#pep3001]_ +* For the procedures of standard library improvement, see :pep:`3001` To be removed: @@ -212,7 +212,7 @@ To be removed: - ``macfs`` [to do] - ``new``, ``reconvert``, ``stringold``, ``xmllib``, ``pcre``, ``pypcre``, ``strop`` [all done] - + see PEP 4 [#pep4]_ + + see :pep:`4` - ``buildtools``, ``mimetools``, ``multifile``, @@ -222,7 +222,7 @@ To be removed: ``sha``, ``statcache``, ``sv``, ``TERMIOS``, ``timing`` [done] - ``cfmfile``, ``gopherlib``, ``md5``, ``MimeWriter``, ``mimify`` [done] - ``cl``, ``sets``, ``xreadlines``, ``rotor``, ``whrandom`` [done] - + Everything in lib-old [#pep4]_ [done] + + Everything in lib-old :pep:`4` [done] - ``Para``, ``addpack``, ``cmp``, ``cmpcache``, ``codehack``, ``dircmp``, ``dump``, ``find``, ``fmt``, ``grep``, ``lockfile``, ``newdir``, ``ni``, ``packmail``, ``poly``, @@ -234,7 +234,7 @@ To be removed: not thread-safe; use ``sys.exc_info()`` or an attribute of the exception [2]_ [11]_ [#sys-module]_ [done] * ``sys.exc_clear``: Python 3's except statements provide the same - functionality [24]_ [#pep3110]_ [#sys-module]_ [done] + functionality [24]_ :pep:`3110` [#sys-module]_ [done] * ``array.read``, ``array.write`` [#array-module]_ * ``operator.isCallable`` : ``callable()`` built-in is being removed [#operator-module]_ [#remove-operator-funcs]_ [done] @@ -364,48 +364,6 @@ References .. [#sequence-types] Python docs (Additional methods for emulation of sequence types) http://docs.python.org/reference/datamodel.html#additional-methods-for-emulation-of-sequence-types -.. [#pep4] PEP 4 ("Deprecation of Standard Modules") - http://www.python.org/dev/peps/pep-0004 - -.. [#pep238] PEP 238 (Changing the Division Operator) - http://www.python.org/dev/peps/pep-0238 - -.. [#pep274] PEP 274 (Dict Comprehensions) - http://www.python.org/dev/peps/pep-0274 - -.. [#pep289] PEP 289 ("Generator Expressions") - http://www.python.org/dev/peps/pep-0289 - -.. [#pep299] PEP 299 ("Special __main__() function in modules") - http://www.python.org/dev/peps/pep-0299 - -.. [#pep308] PEP 308 ("Conditional Expressions") - http://www.python.org/dev/peps/pep-0308 - -.. [#pep328] PEP 328 (Imports: Multi-Line and Absolute/Relative) - http://www.python.org/dev/peps/pep-0328 - -.. [#pep343] PEP 343 (The "with" Statement) - http://www.python.org/dev/peps/pep-0343 - -.. [#pep352] PEP 352 (Required Superclass for Exceptions) - http://www.python.org/dev/peps/pep-0352 - -.. [#pep3001] PEP 3001 (Process for reviewing and improving standard - library modules) http://www.python.org/dev/peps/pep-3001 - -.. [#pep3099] PEP 3099 (Things that will Not Change in Python 3000) - http://www.python.org/dev/peps/pep-3099 - -.. [#pep3105] PEP 3105 (Make print a function) - http://www.python.org/dev/peps/pep-3105 - -.. [#pep3107] PEP 3107 (Function Annotations) - http://www.python.org/dev/peps/pep-3107 - -.. [#pep3110] PEP 3110 (Catching Exceptions in Python 3000) - http://www.python.org/dev/peps/pep-3110/#semantic-changes - .. [#builtin] Approach to resolving __builtin__ vs __builtins__ https://mail.python.org/pipermail/python-3000/2007-March/006161.html diff --git a/pep-3103.txt b/pep-3103.txt index 400cfd66efc..7db213db87f 100644 --- a/pep-3103.txt +++ b/pep-3103.txt @@ -27,7 +27,7 @@ the smorgasbord of proposals, discussing alternatives and explaining my choices where I can. I'll also indicate how strongly I feel about alternatives I discuss. -This PEP should be seen as an alternative to PEP 275. My views are +This PEP should be seen as an alternative to :pep:`275`. My views are somewhat different from that PEP's author, but I'm grateful for the work done in that PEP. @@ -90,7 +90,7 @@ Semantics are discussed in the next top-level section. Alternative 1 ------------- -This is the preferred form in PEP 275:: +This is the preferred form in :pep:`275`:: switch EXPR: case EXPR: @@ -322,7 +322,7 @@ We need to further separate school I into school Ia and school Ib: - School Ib has a more complex position: it agrees with school II that optimization is important, and is willing to concede the compiler - certain liberties to allow this. (For example, PEP 275 Solution 1.) + certain liberties to allow this. (For example, :pep:`275` Solution 1.) In particular, hash() of the switch and case expressions may or may not be called (so it should be side-effect-free); and the case expressions may not be evaluated each time as expected by the diff --git a/pep-3104.txt b/pep-3104.txt index 53cccd2a92a..b88ec8febf5 100644 --- a/pep-3104.txt +++ b/pep-3104.txt @@ -53,7 +53,7 @@ different contexts. Here's an example:: print factorial(5) Python 2.1 moved closer to static nested scoping by making visible -the names bound in all enclosing scopes (see PEP 227). This change +the names bound in all enclosing scopes (see :pep:`227`). This change makes the above code example work as expected. However, because any assignment to a name implicitly declares that name to be local, it is impossible to rebind a name in an outer scope (except when a @@ -119,7 +119,7 @@ much strength, practical flexibility, and pedagogical power from its support and graceful integration of multiple programming paradigms. A proposal for scoping syntax appeared on Python-Dev as far back as -1994 [1]_, long before PEP 227's support for nested scopes was +1994 [1]_, long before :pep:`227`'s support for nested scopes was adopted. At the time, Guido's response was: This is dangerously close to introducing CSNS [classic static @@ -127,7 +127,7 @@ adopted. At the time, Guido's response was: of scoped seem alright. I still think there is not enough need for CSNS to warrant this kind of construct ... -After PEP 227, the "outer name rebinding discussion" has reappeared +After :pep:`227`, the "outer name rebinding discussion" has reappeared on Python-Dev enough times that it has become a familiar event, having recurred in its present form since at least 2003 [2]_. Although none of the language changes proposed in these discussions @@ -265,7 +265,7 @@ statement ``x = 3`` both declares ``x`` a local variable and binds it to 3, the statement ``x := 3`` would change the existing binding of ``x`` without declaring it local. -This is a simple solution, but according to PEP 3099 it has been +This is a simple solution, but according to :pep:`3099` it has been rejected (perhaps because it would be too easy to miss or to confuse with ``=``). diff --git a/pep-3107.txt b/pep-3107.txt index 2e4ffafa681..d29554ab6cf 100644 --- a/pep-3107.txt +++ b/pep-3107.txt @@ -25,7 +25,7 @@ Rationale Because Python's 2.x series lacks a standard way of annotating a function's parameters and return values, a variety of tools and libraries have appeared to fill this gap. Some -utilise the decorators introduced in "PEP 318", while others parse a +utilise the decorators introduced in :pep:`318`, while others parse a function's docstring, looking for annotations there. This PEP aims to provide a single, standard way of specifying this @@ -225,8 +225,8 @@ to support annotations. Relation to Other PEPs ====================== -Function Signature Objects [#pep-362]_ --------------------------------------- +Function Signature Objects (PEP 362) +------------------------------------ Function Signature Objects should expose the function's annotations. The ``Parameter`` object may change or other changes may be warranted. @@ -304,9 +304,6 @@ References and Footnotes .. [#lambda] https://mail.python.org/pipermail/python-3000/2006-May/001613.html -.. [#pep-362] - http://www.python.org/dev/peps/pep-0362/ - .. [#interop0] https://mail.python.org/pipermail/python-3000/2006-August/002895.html diff --git a/pep-3108.txt b/pep-3108.txt index 547b7d6b1e1..02d913067c1 100644 --- a/pep-3108.txt +++ b/pep-3108.txt @@ -26,7 +26,7 @@ inception that not all modules follow. Python 3.0 presents a chance to remove modules that do not have long term usefulness. This chance also allows for the renaming of -modules so that they follow the Python style guide [#pep-0008]_. This +modules so that they follow the :pep:`Python style guide <8>`. This PEP lists modules that should not be included in Python 3.0 or which need to be renamed. @@ -58,9 +58,9 @@ period. Previously deprecated [done] ---------------------------- -PEP 4 lists all modules that have been deprecated in the stdlib -[#pep-0004]_. The specified motivations mirror those listed in -PEP 4. All modules listed +:pep:`4` lists all modules that have been deprecated in the stdlib. +The specified motivations mirror those listed in +:pep:`4`. All modules listed in the PEP at the time of the first alpha release of Python 3.0 will be removed. @@ -544,7 +544,7 @@ for what the module is meant for. * commands [done] - + subprocess module replaces it [#pep-0324]_. + + subprocess module replaces it (:pep:`324`). + Remove getstatus(), move rest to subprocess. * compiler [done] @@ -595,7 +595,7 @@ for what the module is meant for. * popen2 [done] - + subprocess module replaces it [#pep-0324]_. + + subprocess module replaces it (:pep:`324`). * sgmllib [done] @@ -667,7 +667,7 @@ Modules to Rename ================= Many modules existed in -the stdlib before PEP 8 came into existence [#pep-0008]_. This has +the stdlib before :pep:`8` came into existence. This has led to some naming inconsistencies and namespace bloat that should be addressed. @@ -675,10 +675,10 @@ addressed. PEP 8 violations [done] ------------------------ -PEP 8 specifies that modules "should have short, all-lowercase names" -where "underscores can be used ... if it improves readability" -[#pep-0008]_. The use of underscores is discouraged in package names. -The following modules violate PEP 8 and are not somehow being renamed +:pep:`8` specifies that modules "should have short, all-lowercase names" +where "underscores can be used ... if it improves readability". +The use of underscores is discouraged in package names. +The following modules violate :pep:`8` and are not somehow being renamed by being moved to a package. ================== ================================================== @@ -1032,10 +1032,10 @@ Open Issues Renaming of modules maintained outside of the stdlib ---------------------------------------------------- -xml.etree.ElementTree not only does not meet PEP 8 naming standards -but it also has an exposed C implementation [#pep-0008]_. It is an -externally maintained package, though [#pep-0360]_. A request will be -made for the maintainer to change the name so that it matches PEP 8 +xml.etree.ElementTree not only does not meet :pep:`8` naming standards +but it also has an exposed C implementation. It is an +externally maintained package, though :pep:`360`. A request will be +made for the maintainer to change the name so that it matches :pep:`8` and hides the C implementation. @@ -1128,18 +1128,6 @@ been chosen as the guiding force for PEPs to create. References ========== -.. [#pep-0004] PEP 4: Deprecation of Standard Modules - (http://www.python.org/dev/peps/pep-0004/) - -.. [#pep-0008] PEP 8: Style Guide for Python Code - (http://www.python.org/dev/peps/pep-0008/) - -.. [#pep-0324] PEP 324: subprocess -- New process module - (http://www.python.org/dev/peps/pep-0324/) - -.. [#pep-0360] PEP 360: Externally Maintained Packages - (http://www.python.org/dev/peps/pep-0360/) - .. [#module-index] Python Documentation: Global Module Index (http://docs.python.org/modindex.html) diff --git a/pep-3109.txt b/pep-3109.txt index ac8872506b1..53fb911c1dc 100644 --- a/pep-3109.txt +++ b/pep-3109.txt @@ -22,8 +22,8 @@ language. Rationale ========= -One of Python's guiding maxims is "there should be one -- and -preferably only one -- obvious way to do it" [#zen]_. Python 2.x's +One of Python's guiding maxims is :pep:`"there should be one -- and +preferably only one -- obvious way to do it" <20>`. Python 2.x's ``raise`` statement violates this principle, permitting multiple ways of expressing the same thought. For example, these statements are equivalent: :: @@ -37,7 +37,7 @@ tracebacks to be attached to an exception [#grammar]_: :: raise E, V, T -where T is a traceback. As specified in PEP 344 [#pep344]_, +where T is a traceback. As specified in :pep:`344`, exception objects in Python 3.x will possess a ``__traceback__`` attribute, admitting this translation of the three-expression ``raise`` statement: :: @@ -59,7 +59,7 @@ four forms to two: 2. ``raise EXCEPTION`` is used to raise a new exception. This form has two sub-variants: ``EXCEPTION`` may be an exception class or an instance of an exception class; valid exception classes are - BaseException and its subclasses [#pep352]_. If ``EXCEPTION`` + BaseException and its subclasses (:pep:`352`). If ``EXCEPTION`` is a subclass, it will be called with no arguments to obtain an exception instance. @@ -99,8 +99,8 @@ Changes to Builtin Types Because of its relation to exception raising, the signature for the ``throw()`` method on generator objects will change, dropping the -optional second and third parameters. The signature thus changes -from [#throw-sig]_ :: +optional second and third parameters. The signature thus changes (:pep:`342`) +from :: generator.throw(E, [V, [T]]) @@ -232,7 +232,7 @@ The following translations will be performed: raise CompileError from msg Using the ``raise ... from ...`` syntax introduced in - PEP 344. + :pep:`344`. Implementation @@ -244,21 +244,9 @@ This PEP was implemented in revision 57783 [#r57783]_. References ========== -.. [#zen] - http://www.python.org/dev/peps/pep-0020/ - .. [#grammar] http://docs.python.org/reference/simple_stmts.html#raise -.. [#throw-sig] - http://www.python.org/dev/peps/pep-0342/ - -.. [#pep344] - http://www.python.org/dev/peps/pep-0344/ - -.. [#pep352] - http://www.python.org/dev/peps/pep-0352/ - .. [#amk-line-noise] https://mail.python.org/pipermail/python-dev/2005-August/055187.html diff --git a/pep-3110.txt b/pep-3110.txt index c6d7d3ff575..6129e51a682 100644 --- a/pep-3110.txt +++ b/pep-3110.txt @@ -41,7 +41,7 @@ Rationale except (, ): -2. As specified in PEP 352 [#pep352]_, the ability to treat exceptions +2. As specified in :pep:`352`, the ability to treat exceptions as tuples will be removed, meaning this code will no longer work :: except os.error, (errno, errstr): @@ -49,7 +49,7 @@ Rationale Because the automatic unpacking will no longer be possible, it is desirable to remove the ability to use tuples as ``except`` targets. -3. As specified in PEP 344 [#pep344]_, exception instances in Python 3 +3. As specified in :pep:`344`, exception instances in Python 3 will possess a ``__traceback__`` attribute. The Open Issues section of that PEP includes a paragraph on garbage collection difficulties caused by this attribute, namely a "exception -> traceback -> @@ -59,13 +59,13 @@ Rationale Python 3 whereby the target name is deleted at the end of the ``except`` suite. -4. In the spirit of "there should be one -- and preferably only one - -- obvious way to do it" [#zen]_, it is desirable to consolidate +4. In the spirit of :pep:`"there should be one -- and preferably only one + -- obvious way to do it" <20>`, it is desirable to consolidate duplicate functionality. To this end, the ``exc_value``, ``exc_type`` and ``exc_traceback`` attributes of the ``sys`` module [#sys-module]_ will be removed in favor of ``sys.exc_info()``, which provides the same information. These - attributes are already listed in PEP 3100 [#pep3100]_ as targeted + attributes are already listed in :pep:`3100` as targeted for removal. @@ -105,7 +105,7 @@ hard-to-catch bugs -- cannot legally occur in 3.x code. Semantic Changes ================ -In order to resolve the garbage collection issue related to PEP 344, +In order to resolve the garbage collection issue related to :pep:`344`, ``except`` statements in Python 3 will generate additional bytecode to delete the target, thus eliminating the reference cycle. The source-to-source translation, as suggested by Phillip J. Eby @@ -219,7 +219,7 @@ Replacing or Dropping "sys.exc_info()" The idea of dropping ``sys.exc_info()`` or replacing it with a ``sys.exception`` attribute or a ``sys.get_exception()`` function has been raised several times on python-3000 ([#drop-excinfo]_, -[#replace-excinfo]_) and mentioned in PEP 344's "Open Issues" section. +[#replace-excinfo]_) and mentioned in :pep:`344`'s "Open Issues" section. While a ``2to3`` fixer to replace calls to ``sys.exc_info()`` and some attribute accesses would be trivial, it would be far more @@ -240,21 +240,9 @@ implemented in revision 55446 [#r55446]_. References ========== -.. [#pep352] - http://www.python.org/dev/peps/pep-0352/ - -.. [#zen] - http://www.python.org/dev/peps/pep-0020/ - .. [#sys-module] http://docs.python.org/library/sys.html -.. [#pep3100] - http://www.python.org/dev/peps/pep-3100/ - -.. [#pep344] - http://www.python.org/dev/peps/pep-0344/ - .. [#firstproposal] https://mail.python.org/pipermail/python-dev/2006-March/062449.html diff --git a/pep-3111.txt b/pep-3111.txt index 4b9ab7d335d..bb77fedd6e2 100644 --- a/pep-3111.txt +++ b/pep-3111.txt @@ -20,7 +20,8 @@ and two simple means of interactive input through the input() and raw_input() built-in functions. Python 3.0 will introduce various incompatible changes with previous -Python versions\ [1]_. Among the proposed changes, print will become a built-in +Python versions (:pep:`3100`). +Among the proposed changes, print will become a built-in function, print(), while input() and raw_input() would be removed completely from the built-in namespace, requiring importing some module to provide even the most basic input capability. @@ -42,7 +43,8 @@ and to obtain information from the user (interactive input). Any computer language intended to be used in an educational setting should provide straightforward methods for both output and interactive input. -The current proposals for Python 3.0 [1]_ include a simple output pathway +The :pep:`current proposals for Python 3.0 <3100>` +include a simple output pathway via a built-in function named print(), but a more complicated method for input [e.g. via sys.stdin.readline()], one that requires importing an external module. Current versions of Python (pre-3.0) include raw_input() as a @@ -139,9 +141,6 @@ The rationale for accepting the renaming can be found here [4]_. References ========== -.. [1] PEP 3100, Miscellaneous Python 3.0 Plans, Kuchling, Cannon - http://www.python.org/dev/peps/pep-3100/ - .. [2] The fate of raw_input() in Python 3000 https://mail.python.org/pipermail/edu-sig/2006-September/006967.html diff --git a/pep-3112.txt b/pep-3112.txt index 7c51b59497f..584d31a3e1b 100644 --- a/pep-3112.txt +++ b/pep-3112.txt @@ -16,7 +16,7 @@ Abstract ======== This PEP proposes a literal syntax for the ``bytes`` objects -introduced in PEP 358. The purpose is to provide a convenient way to +introduced in :pep:`358`. The purpose is to provide a convenient way to spell ASCII strings and arbitrary binary data. diff --git a/pep-3113.txt b/pep-3113.txt index 689b2202098..45a48d70cbb 100644 --- a/pep-3113.txt +++ b/pep-3113.txt @@ -111,13 +111,13 @@ When looking at the various types of parameters that a Python function can have, one will notice that tuple parameters tend to be an exception rather than the rule. -Consider PEP 3102 (keyword-only arguments) and PEP 3107 (function -annotations) [#pep-3102]_ [#pep-3107]_. Both PEPs have been accepted and +Consider :pep:`3102` (keyword-only arguments) and :pep:`3107` (function +annotations). Both PEPs have been accepted and introduce new functionality within a function's signature. And yet for both PEPs the new feature cannot be applied to tuple parameters as -a whole. PEP 3102 has no support for tuple parameters at all (which +a whole. :pep:`3102` has no support for tuple parameters at all (which makes sense as there is no way to reference a tuple parameter by -name). PEP 3107 allows annotations for each item within the tuple +name). :pep:`3107` allows annotations for each item within the tuple (e.g., ``(x:int, y:int)``), but not the whole tuple (e.g., ``(x, y):int``). @@ -260,12 +260,6 @@ References .. [#MSIL] Microsoft Intermediate Language (http://msdn.microsoft.com/library/en-us/cpguide/html/cpconmicrosoftintermediatelanguagemsil.asp?frame=true) -.. [#pep-3102] PEP 3102 (Keyword-Only Arguments) - (http://www.python.org/dev/peps/pep-3102/) - -.. [#pep-3107] PEP 3107 (Function Annotations) - (http://www.python.org/dev/peps/pep-3107/) - Copyright ========= diff --git a/pep-3114.txt b/pep-3114.txt index d34527b1ae3..9380784fb5c 100644 --- a/pep-3114.txt +++ b/pep-3114.txt @@ -116,7 +116,7 @@ Previous Proposals This proposal is not a new idea. The idea proposed here was supported by the BDFL on python-dev [1]_ and is even mentioned in the original -iterator PEP, PEP 234:: +iterator PEP, :pep:`234`:: (In retrospect, it might have been better to go for __next__() and have a new built-in, next(it), which calls it.__next__(). diff --git a/pep-3115.txt b/pep-3115.txt index 1820ca41af8..85e093fcf9a 100644 --- a/pep-3115.txt +++ b/pep-3115.txt @@ -140,7 +140,7 @@ there may be one or more keyword arguments, one of which can be *metaclass*. Note that the *metaclass* argument is not included in *kwargs*, since it is filtered out by the normal parameter assignment algorithm. (Note also that *metaclass* is a keyword- -only argument as per PEP 3102 [6]_.) +only argument as per :pep:`3102`.) Even though ``__prepare__`` is not required, the default metaclass ('type') implements it, for the convenience of subclasses calling @@ -309,12 +309,6 @@ References .. [4] [Python-3000] Metaclasses in Py3K (Always use an ordered dict) https://mail.python.org/pipermail/python-3000/2006-December/005118.html -.. [5] PEP 359: The 'make' statement - - http://www.python.org/dev/peps/pep-0359/ - -.. [6] PEP 3102: Keyword-only arguments - - http://www.python.org/dev/peps/pep-3102/ - Copyright ========= diff --git a/pep-3117.txt b/pep-3117.txt index 738effa6057..1ce3241c809 100644 --- a/pep-3117.txt +++ b/pep-3117.txt @@ -44,7 +44,7 @@ future-embracing: the introduction of Unicode characters as an integral constituent of source code. Unicode makes it possible to express much more with much less characters, which -is in accordance with the Zen ("Readability counts.") [ZEN]_. Additionally, it +is in accordance with the :pep:`Zen <20>` ("Readability counts."). Additionally, it eliminates the need for a separate type declaration statement, and last but not least, it makes Python measure up to Perl 6, which already uses Unicode for its operators. [#]_ @@ -205,8 +205,6 @@ References .. [#] Though, if you know the language in question, it may not be *that* unrelated. -.. [ZEN] http://www.python.org/dev/peps/pep-0020/ - .. [#] Well, it would, if there was a Perl 6. .. [#] Since the name ``TypeError`` is already in use, this name has been chosen diff --git a/pep-3119.txt b/pep-3119.txt index 8cabce61379..847456c30e8 100644 --- a/pep-3119.txt +++ b/pep-3119.txt @@ -30,7 +30,7 @@ specific mechanism of ABCs, as contrasted with Interfaces or Generic Functions (GFs), but about clarifying philosophical issues like "what makes a set", "what makes a mapping" and "what makes a sequence". -There's also a companion PEP 3141, which defines ABCs for numeric +There's also a companion :pep:`3141`, which defines ABCs for numeric types. @@ -139,7 +139,7 @@ The specification follows the categories listed in the abstract: Overloading ``isinstance()`` and ``issubclass()`` ------------------------------------------------- -During the development of this PEP and of its companion, PEP 3141, we +During the development of this PEP and of its companion, :pep:`3141`, we repeatedly faced the choice between standardizing more, fine-grained ABCs or fewer, coarse-grained ones. For example, at one stage, PEP 3141 introduced the following stack of base classes used for complex @@ -155,14 +155,14 @@ The dilemma here is that we'd rather have fewer ABCs, but then what should a user do who needs a less refined ABC? Consider e.g. the plight of a mathematician who wants to define his own kind of Transcendental numbers, but also wants float and int to be considered -Transcendental. PEP 3141 originally proposed to patch float.__bases__ +Transcendental. :pep:`3141` originally proposed to patch float.__bases__ for that purpose, but there are some good reasons to keep the built-in types immutable (for one, they are shared between all Python interpreters running in the same address space, as is used by mod_python [16]_). Another example would be someone who wants to define a generic -function (PEP 3124) for any sequence that has an ``append()`` method. +function (:pep:`3124`) for any sequence that has an ``append()`` method. The ``Sequence`` ABC (see below) doesn't promise the ``append()`` method, while ``MutableSequence`` requires not only ``append()`` but also various other mutating methods. @@ -431,7 +431,7 @@ partial ordering). But this cannot be the case: If both ``list`` and ``str`` derived from ``Ordering``, this would imply that ``[1, 2] < (1, 2)`` should be defined (and presumably return False), while in fact (in Python 3000!) such "mixed-mode comparisons" operations are -explicitly forbidden and raise ``TypeError``. See PEP 3100 and [14]_ +explicitly forbidden and raise ``TypeError``. See :pep:`3100` and [14]_ for more information. (This is a special case of a more general issue with operations that take another argument of the same type). @@ -749,7 +749,7 @@ character strings (``str``), deriving from ``Sequence`` and **Open issues:** define the base interfaces for these so alternative implementations and subclasses know what they are in for. This may be -the subject of a new PEP or PEPs (PEP 358 should be co-opted for the +the subject of a new PEP or PEPs (:pep:`358` should be co-opted for the ``bytes`` type). diff --git a/pep-3120.txt b/pep-3120.txt index b9cd19e882c..1a9762b32da 100644 --- a/pep-3120.txt +++ b/pep-3120.txt @@ -15,7 +15,7 @@ Specification ============= This PEP proposes to change the default source encoding from ASCII to -UTF-8. Support for alternative source encodings [#pep263]_ continues to +UTF-8. Support for alternative source encodings (:pep:`263`) continues to exist; an explicit encoding declaration takes precedence over the default. @@ -38,7 +38,7 @@ character-by-character basis. As Unicode gives a fixed interpretation to code points, this algorithm effectively fixed a source encoding, at least for files containing non-ASCII characters in Unicode literals. -PEP 263 identified the problem that you can use only those Unicode +:pep:`263` identified the problem that you can use only those Unicode characters in a Unicode literal which are also in Latin-1, and introduced a syntax for declaring the source encoding. If no source encoding was given, the default should be ASCII. For compatibility @@ -50,10 +50,10 @@ encoding is declared. Rationale ========= -With PEP 263, using arbitrary non-ASCII characters in a Python file is +With :pep:`263`, using arbitrary non-ASCII characters in a Python file is possible, but tedious. One has to explicitly add an encoding declaration. Even though some editors (like IDLE and Emacs) support -the declarations of PEP 263, many editors still do not (and never +the declarations of :pep:`263`, many editors still do not (and never will); users have to explicitly adjust the encoding which the editor assumes on a file-by-file basis. @@ -82,14 +82,6 @@ as the parser converts all source code to UTF-8, anyway). IDLE needs to be changed to use UTF-8 as the default encoding. -References -========== - -.. [#pep263] - http://www.python.org/dev/peps/pep-0263/ - - - Copyright ========= diff --git a/pep-3122.txt b/pep-3122.txt index f799165fd25..5591104bd6b 100644 --- a/pep-3122.txt +++ b/pep-3122.txt @@ -17,7 +17,7 @@ Abstract ======== Because of how name resolution works for relative imports in a world -where PEP 328 is implemented, the ability to execute modules within a +where :pep:`328` is implemented, the ability to execute modules within a package ceases being possible. This failing stems from the fact that the module being executed as the "main" module replaces its ``__name__`` attribute with ``"__main__"`` instead of leaving it as @@ -31,17 +31,17 @@ module this will allow at least some instances of executing a module within a package that uses relative imports. This PEP does not address the idea of introducing a module-level -function that is automatically executed like PEP 299 proposes. +function that is automatically executed like :pep:`299` proposes. The Problem =========== -With the introduction of PEP 328, relative imports became dependent on +With the introduction of :pep:`328`, relative imports became dependent on the ``__name__`` attribute of the module performing the import. This is because the use of dots in a relative import are used to strip away parts of the calling module's name to calculate where in the package -hierarchy an import should fall (prior to PEP 328 relative +hierarchy an import should fall (prior to :pep:`328` relative imports could fail and would fall back on absolute imports which had a chance of succeeding). @@ -131,7 +131,7 @@ The stat calls alone can be expensive if the file system the executed script is on is something like NFS. Because of these issues, only when the ``-m`` command-line argument -(introduced by PEP 338) is used will ``__name__`` be set. Otherwise +(introduced by :pep:`338`) is used will ``__name__`` be set. Otherwise the fallback semantics of setting ``__name__`` to ``"__main__"`` will occur. ``sys.main`` will still be set to the proper value, regardless of what ``__name__`` is set to. diff --git a/pep-3124.txt b/pep-3124.txt index d8fad1ac0ec..1d86bfbe6bc 100644 --- a/pep-3124.txt +++ b/pep-3124.txt @@ -74,7 +74,7 @@ created by a third party. Therefore, this PEP proposes a standard library module to address these, and related issues, using decorators and argument annotations -(PEP 3107). The primary features to be provided are: +(:pep:`3107`). The primary features to be provided are: * a dynamic overloading facility, similar to the static overloading found in languages such as Java and C++, but including optional @@ -166,7 +166,7 @@ or this (to avoid copying the implementation):: from overloading import RuleSet RuleSet(flatten).copy_rules((basestring,), (MyString,)) -(Note also that, although PEP 3119 proposes that it should be possible +(Note also that, although :pep:`3119` proposes that it should be possible for abstract base classes like ``Iterable`` to allow classes like ``MyString`` to claim subclass-hood, such a claim is *global*, throughout the application. In contrast, adding a specific overload @@ -563,7 +563,7 @@ decorators could insert a custom metaclass to do processing of this sort. (This is how RuleDispatch, for example, implements the implicit class rule.) -PEP 3115, however, requires that a class' metaclass be determined +:pep:`3115`, however, requires that a class' metaclass be determined *before* the class body has executed, making it impossible to use this technique for class decoration any more. @@ -1014,7 +1014,7 @@ included in PEAK-Rules at the present time. The "implicit class rule" has previously been implemented in the RuleDispatch library. However, it relies on the ``__metaclass__`` -hook that is currently eliminated in PEP 3115. +hook that is currently eliminated in :pep:`3115`. I don't currently know how to make ``@overload`` play nicely with ``classmethod`` and ``staticmethod`` in class bodies. It's not really diff --git a/pep-3125.txt b/pep-3125.txt index 744de708cf3..9362bf81eee 100644 --- a/pep-3125.txt +++ b/pep-3125.txt @@ -219,14 +219,14 @@ References .. [#dedent] (email subject) PEP 30XZ: Simplified Parsing, van Rossum https://mail.python.org/pipermail/python-3000/2007-April/007063.html -.. [#lexical] (email subject) PEP-3125 -- remove backslash +.. [#lexical] (email subject) :pep:`3125` -- remove backslash continuation, Koenig https://mail.python.org/pipermail/python-3000/2007-May/007237.html .. [#snocone] The Snocone Programming Language, Koenig http://www.snobol4.com/report.htm -.. [#guidobughide] (email subject) PEP-3125 -- remove backslash +.. [#guidobughide] (email subject) :pep:`3125` -- remove backslash continuation, van Rossum https://mail.python.org/pipermail/python-3000/2007-May/007244.html diff --git a/pep-3126.txt b/pep-3126.txt index 9149dc86d25..bc993ce17f0 100644 --- a/pep-3126.txt +++ b/pep-3126.txt @@ -171,8 +171,8 @@ Operator Precedence Guido indicated [#rcn-constantfold]_ that this change should be handled by PEP, because there were a few edge cases with other string operators, such as the %. (Assuming that str % stays -- it may be -eliminated in favor of PEP 3101 -- Advanced String Formatting. -[#PEP3101]_ [#elimpercent]_) +eliminated in favor of :pep:`3101` -- Advanced String Formatting. +[#elimpercent]_) The resolution is to use parentheses to enforce precedence -- the same solution that can be used today:: @@ -352,9 +352,6 @@ References van Rossum https://mail.python.org/pipermail/python-3000/2007-April/006563.html -.. [#PEP3101] PEP 3101, Advanced String Formatting, Talin - http://www.python.org/dev/peps/pep-3101/ - .. [#elimpercent] ps to question Re: Need help completing ABC pep, van Rossum https://mail.python.org/pipermail/python-3000/2007-April/006737.html diff --git a/pep-3127.txt b/pep-3127.txt index 6c38e3ed8d1..ed495cc8b83 100644 --- a/pep-3127.txt +++ b/pep-3127.txt @@ -80,7 +80,7 @@ as well as the grammar. The documentation will have to be changed as well: grammar.txt, as well as the integer literal section of the reference manual. -PEP 306 should be checked for other issues, and that PEP should +:pep:`306` should be checked for other issues, and that PEP should be updated if the procedure described therein is insufficient. int() specification @@ -133,7 +133,7 @@ option will need to be updated to add '0o' in front, instead of '0'. In 2.6, alternate octal formatting will continue to add only '0'. In neither 2.6 nor 3.0 will the % operator support binary output. This is because -binary output is already supported by PEP 3101 +binary output is already supported by :pep:`3101` (str.format), which is the preferred string formatting method. @@ -182,7 +182,7 @@ the string representation of integers relate to these features: * Under 2.6, long() is treated the same as int() - Formatting of integers into strings, either via the % string - operator or the new PEP 3101 advanced string formatting method. + operator or the new :pep:`3101` advanced string formatting method. It is presumed that: @@ -227,7 +227,7 @@ are confronted with non-decimal radices. However, in most situations, most people do not write gratuitous zeros in front of their decimal numbers. The primary exception is when an attempt is being made to line up columns of numbers. But -since PEP 8 specifically discourages the use of spaces to try to +since :pep:`8` specifically discourages the use of spaces to try to align Python code, one would suspect the same argument should apply to the use of leading zeros for the same purpose. @@ -439,7 +439,7 @@ with the "x" for "heXadecimal". For the string % operator, "o" was already being used to denote octal. Binary formatting is not being added to the % operator -because PEP 3101 (Advanced String Formatting) already supports +because :pep:`3101` (Advanced String Formatting) already supports binary, % formatting will be deprecated in the future. At the end of the day, since uppercase "O" can look like a zero @@ -466,7 +466,7 @@ ample precedence for case sensitivity in the output format string, and there would need to be a consensus that there is a valid use-case for the "alternate form" of the string % operator to support uppercase 'B' or 'O' characters for binary or -octal output. Currently, PEP 3101 does not even support this +octal output. Currently, :pep:`3101` does not even support this alternate capability, and the hex() function does not allow the programmer to specify the case of the 'x' character. diff --git a/pep-3129.txt b/pep-3129.txt index 6b98709983f..d5a58aece87 100644 --- a/pep-3129.txt +++ b/pep-3129.txt @@ -15,15 +15,16 @@ Abstract ======== This PEP proposes class decorators, an extension to the function -and method decorators introduced in PEP 318. +and method decorators introduced in :pep:`318`. Rationale ========= When function decorators were originally debated for inclusion in -Python 2.4, class decorators were seen as obscure and unnecessary -[#obscure]_ thanks to metaclasses. After several years' experience +Python 2.4, class decorators were seen as +:pep:`obscure and unnecessary <318#motivation>` +thanks to metaclasses. After several years' experience with the Python 2.4.x series of releases and an increasing familiarity with function decorators and their uses, the BDFL and the community re-evaluated class decorators and recommended their @@ -45,7 +46,8 @@ Semantics ========= The semantics and design goals of class decorators are the same as -for function decorators ([#semantics]_, [#goals]_); the only +for function decorators (:pep:`318#current-syntax`, :pep:`318#design-goals`); +the only difference is that you're decorating a class instead of a function. The following two snippets are semantically identical:: @@ -59,7 +61,7 @@ The following two snippets are semantically identical:: class A: pass -For a detailed examination of decorators, please refer to PEP 318. +For a detailed examination of decorators, please refer to :pep:`318`. Implementation @@ -103,21 +105,12 @@ The patch was committed to Subversion as revision 55430. References ========== -.. [#obscure] - http://www.python.org/dev/peps/pep-0318/#motivation - .. [#approval] https://mail.python.org/pipermail/python-dev/2006-March/062942.html .. [#motivation] https://mail.python.org/pipermail/python-dev/2006-March/062888.html -.. [#semantics] - http://www.python.org/dev/peps/pep-0318/#current-syntax - -.. [#goals] - http://www.python.org/dev/peps/pep-0318/#design-goals - .. [#implementation] https://bugs.python.org/issue1671208 diff --git a/pep-3131.txt b/pep-3131.txt index b402c5c12b8..0d8ce9a2584 100644 --- a/pep-3131.txt +++ b/pep-3131.txt @@ -193,7 +193,7 @@ A. Should identifiers be allowed to contain any Unicode letter? solved; tool support is weak. 5. Languages with non-ASCII identifiers use different character sets - and normalization schemes; PEP 3131's choices are non-obvious. + and normalization schemes; :pep:`3131`'s choices are non-obvious. 6. The Unicode bidi algorithm yields an extremely confusing display order for RTL text when digits or operators are nearby. diff --git a/pep-3133.txt b/pep-3133.txt index ae42c5cb1a6..45c41516093 100644 --- a/pep-3133.txt +++ b/pep-3133.txt @@ -15,8 +15,8 @@ Post-History: 13-May-2007 Rejection Notice ================ -This PEP has helped push PEP 3119 towards a saner, more minimalistic -approach. But given the latest version of PEP 3119 I much prefer +This PEP has helped push :pep:`3119` towards a saner, more minimalistic +approach. But given the latest version of :pep:`3119` I much prefer that. GvR. @@ -69,7 +69,7 @@ A Note on Syntax A syntax proposals in this PEP are tentative and should be considered to be strawmen. The necessary bits that this PEP depends -on -- namely PEP 3115's class definition syntax and PEP 3129's class +on -- namely :pep:`3115`'s class definition syntax and :pep:`3129`'s class decorators -- are still being formalized and may change. Function names will, of course, be subject to lengthy bikeshedding debates. @@ -112,7 +112,7 @@ Let's see if roles can help. :: class Rock(Mineral): ... -We use class decorators from PEP 3129 to associate a particular role +We use class decorators from :pep:`3129` to associate a particular role or roles with a class. Client code can now verify that an incoming object performs the ``Doglike`` role, allowing it to handle ``Wolf``, ``LaughingHyena`` and ``Aibo`` [#aibo]_ instances, too. @@ -302,7 +302,7 @@ Relationship to Abstract Base Classes ===================================== Early drafts of this PEP [#proposal]_ envisioned roles as competing -with the abstract base classes proposed in PEP 3119. After further +with the abstract base classes proposed in :pep:`3119`. After further discussion and deliberation, a compromise and a delegation of responsibilities and use-cases has been worked out as follows: @@ -507,7 +507,7 @@ into :: ... Assigning a role could take advantage of the class definition -arguments proposed in PEP 3115: :: +arguments proposed in :pep:`3115`: :: class MyClass(performs=MyRole): ... diff --git a/pep-3134.txt b/pep-3134.txt index d9f8abfdce6..97127dfdfe6 100644 --- a/pep-3134.txt +++ b/pep-3134.txt @@ -14,7 +14,7 @@ Post-History: Numbering Note ============== -This PEP started its life as PEP 344. Since it is now targeted for Python +This PEP started its life as :pep:`344`. Since it is now targeted for Python 3000, it has been moved into the 3xxx space. @@ -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]_. @@ -466,7 +466,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 diff --git a/pep-3135.txt b/pep-3135.txt index 6c93d49f96f..647946150c0 100644 --- a/pep-3135.txt +++ b/pep-3135.txt @@ -15,7 +15,7 @@ Post-History: 28-Apr-2007, 29-Apr-2007 (1), 29-Apr-2007 (2), 14-May-2007, 12-Mar Numbering Note ============== -This PEP started its life as PEP 367. Since it is now targeted +This PEP started its life as :pep:`367`. Since it is now targeted for Python 3000, it has been moved into the 3xxx space. Abstract diff --git a/pep-3137.txt b/pep-3137.txt index 7e94b5fa56a..4db260b5765 100644 --- a/pep-3137.txt +++ b/pep-3137.txt @@ -17,7 +17,7 @@ After releasing Python 3.0a1 with a mutable bytes type, pressure mounted to add a way to represent immutable bytes. Gregory P. Smith proposed a patch that would allow making a bytes object temporarily immutable by requesting that the data be locked using the new buffer -API from PEP 3118. This did not seem the right approach to me. +API from :pep:`3118`. This did not seem the right approach to me. Jeffrey Yasskin, with the help of Adam Hupp, then prepared a patch to make the bytes type immutable (by crudely removing all mutating APIs) @@ -65,7 +65,7 @@ I propose the following type names at the Python level: - ``memoryview`` is a bytes view on another object (PyMemory) The old type named ``buffer`` is so similar to the new type -``memoryview``, introduce by PEP 3118, that it is redundant. The rest +``memoryview``, introduce by :pep:`3118`, that it is redundant. The rest of this PEP doesn't discuss the functionality of ``memoryview``; it is just mentioned here to justify getting rid of the old ``buffer`` type. (An earlier version of this PEP proposed ``buffer`` as the new name @@ -105,7 +105,7 @@ Functionality PEP 3118 Buffer API ------------------- -Both bytes and bytearray implement the PEP 3118 buffer API. The bytes +Both bytes and bytearray implement the :pep:`3118` buffer API. The bytes type only implements read-only requests; the bytearray type allows writable and data-locked requests as well. The element data type is always 'B' (i.e. unsigned byte). @@ -164,7 +164,7 @@ Slicing a bytes object returns a bytes object. Slicing a bytearray object returns a bytearray object. Slice assignment to a bytearray object accepts anything that -implements the PEP 3118 buffer API, or an iterable of integers in +implements the :pep:`3118` buffer API, or an iterable of integers in range(256). Indexing @@ -201,7 +201,7 @@ types, except where mentioned: - ``b *= n``: mutates b if it is a bytearray object. - ``b1 in b2``, ``b1 not in b2``: substring test; b1 can be any - object implementing the PEP 3118 buffer API. + object implementing the :pep:`3118` buffer API. - ``i in b``, ``i not in b``: single-byte membership test; i must be an integer (if it is a length-1 bytes array, it is considered @@ -218,7 +218,7 @@ Methods ------- The following methods are implemented by bytes as well as bytearray, with -similar semantics. They accept anything that implements the PEP 3118 +similar semantics. They accept anything that implements the :pep:`3118` buffer API for bytes arguments, and return the same type as the object whose method is called ("self"):: @@ -246,7 +246,7 @@ which constructs an object from a string containing hexadecimal values (with or without spaces between the bytes). The bytearray type implements these additional methods from the -MutableSequence ABC (see PEP 3119): +MutableSequence ABC (see :pep:`3119`): .extend(), .insert(), .append(), .reverse(), .pop(), .remove(). @@ -275,7 +275,7 @@ is just a special case of conversion to str. There is however no promise that printing a bytes object interprets the individual bytes as characters (unlike in Python 2.x). -The str type currently implements the PEP 3118 buffer API. While this +The str type currently implements the :pep:`3118` buffer API. While this is perhaps occasionally convenient, it is also potentially confusing, because the bytes accessed via the buffer API represent a platform-depending encoding: depending on the platform byte order and @@ -283,7 +283,7 @@ a compile-time configuration option, the encoding could be UTF-16-BE, UTF-16-LE, UTF-32-BE, or UTF-32-LE. Worse, a different implementation of the str type might completely change the bytes representation, e.g. to UTF-8, or even make it impossible to access the data as a -contiguous array of bytes at all. Therefore, the PEP 3118 buffer API +contiguous array of bytes at all. Therefore, the :pep:`3118` buffer API will be removed from the str type. The ``basestring`` Type diff --git a/pep-3140.txt b/pep-3140.txt index ffa947bfd2b..923030967ff 100644 --- a/pep-3140.txt +++ b/pep-3140.txt @@ -79,13 +79,13 @@ string if the input is non-ASCII string):: >>> print(['тест']) ['\xd4\xc5\xd3\xd4'] -One of the motivations for PEP 3138 is that neither ``repr`` nor ``str`` +One of the motivations for :pep:`3138` is that neither ``repr`` nor ``str`` will allow the sensible printing of dicts whose keys are non-ASCII text strings. Now that Unicode identifiers are allowed, it includes Python's own attribute dicts. This also includes JSON serialization (and caused some hoops for the json lib). -PEP 3138 proposes to fix this by breaking the "repr is safe ASCII" +:pep:`3138` proposes to fix this by breaking the "repr is safe ASCII" invariant, and changing the way ``repr`` (which is used for persistence) outputs some objects, with system-dependent failures. diff --git a/pep-3141.txt b/pep-3141.txt index 06ec4540301..e4a7773e1ad 100644 --- a/pep-3141.txt +++ b/pep-3141.txt @@ -34,7 +34,7 @@ Specification This PEP specifies a set of Abstract Base Classes, and suggests a general strategy for implementing some of the methods. It uses -terminology from PEP 3119, but the hierarchy is intended to be +terminology from :pep:`3119`, but the hierarchy is intended to be meaningful for any systematic method of defining sets of classes. The type checks in the standard library should use these classes @@ -518,9 +518,6 @@ tower. References ========== -.. [#pep3119] Introducing Abstract Base Classes - (http://www.python.org/dev/peps/pep-3119/) - .. [#classtree] Possible Python 3K Class Tree?, wiki page by Bill Janssen (http://wiki.python.org/moin/AbstractBaseClasses) diff --git a/pep-3142.txt b/pep-3142.txt index ffa9eec519b..15abbd84197 100644 --- a/pep-3142.txt +++ b/pep-3142.txt @@ -22,8 +22,8 @@ This PEP proposes an enhancement to generator expressions, adding a Rationale ========= -A generator expression (PEP 289 [1]_) is a concise method to serve -dynamically-generated objects to list comprehensions (PEP 202 [2]_). +A generator expression (:pep:`289`) is a concise method to serve +dynamically-generated objects to list comprehensions (:pep:`202`). Current generator expressions allow for an "if" clause to filter the objects that are returned to those meeting some set of criteria. However, since the "if" clause is evaluated for every @@ -33,7 +33,7 @@ objects would be rejected after a certain point. For example:: g = (n for n in range(100) if n*n < 50) which is equivalent to the using a generator function -(PEP 255 [3]_):: +(:pep:`255`):: def __gen(exp): for n in exp: @@ -105,19 +105,6 @@ Raymond Hettinger first proposed the concept of generator expressions in January 2002. -References -========== - -.. [1] PEP 289: Generator Expressions - http://www.python.org/dev/peps/pep-0289/ - -.. [2] PEP 202: List Comprehensions - http://www.python.org/dev/peps/pep-0202/ - -.. [3] PEP 255: Simple Generators - http://www.python.org/dev/peps/pep-0255/ - - Copyright ========= diff --git a/pep-3144.txt b/pep-3144.txt index 9168df17aca..f8be5098474 100644 --- a/pep-3144.txt +++ b/pep-3144.txt @@ -47,7 +47,7 @@ seeks to provide. Background ========== -PEP 3144 and ``ipaddr`` have been up for inclusion before. The +:pep:`3144` and ``ipaddr`` have been up for inclusion before. The version of the library specified here is backwards incompatible with the version on PyPI and the one which was discussed before. In order to avoid confusing users of the current ``ipaddr``, I've diff --git a/pep-3145.txt b/pep-3145.txt index 8a6a8865dfc..e15e9653df8 100644 --- a/pep-3145.txt +++ b/pep-3145.txt @@ -25,7 +25,7 @@ PEP Deferral ============ Further exploration of the concepts covered in this PEP has been deferred -at least until after PEP 3156 has been resolved. +at least until after :pep:`3156` has been resolved. PEP Withdrawal diff --git a/pep-3146.txt b/pep-3146.txt index 03f32b30dde..afa39136af5 100644 --- a/pep-3146.txt +++ b/pep-3146.txt @@ -874,7 +874,7 @@ Lowlights: - Developers must know two related languages, C and C++ to work on the full range of CPython's internals. -- A C++ style guide will need to be developed and enforced. PEP 7 will be +- A C++ style guide will need to be developed and enforced. :pep:`7` will be extended [#pep7-cpp]_ to encompass C++ by taking the relevant parts of the C++ style guides from Unladen Swallow [#us-styleguide]_, LLVM [#llvm-styleguide]_ and Google [#google-styleguide]_. @@ -992,7 +992,7 @@ Proposed Merge Plan We propose focusing our efforts on eventual merger with CPython's 3.x line of development. The BDFL has indicated that 2.7 is to be the final release of CPython's 2.x line of development [#bdfl-27-final]_, and since 2.7 alpha 1 has -already been released [#cpy-27a1]_, we have missed the window. Python 3 is the +:pep:`already been released <373>`, we have missed the window. Python 3 is the future, and that is where we will target our performance efforts. We recommend the following plan for merger of Unladen Swallow into the CPython @@ -1203,12 +1203,6 @@ References .. [#bdfl-27-final] https://mail.python.org/pipermail/python-dev/2010-January/095682.html -.. [#cpy-27a1] - http://www.python.org/dev/peps/pep-0373/ - -.. [#cpy-32]_ - http://www.python.org/dev/peps/pep-0392/ - .. [#us-punchlist] http://code.google.com/p/unladen-swallow/issues/list?q=label:Merger diff --git a/pep-3147.txt b/pep-3147.txt index 07a4e4b0931..5ed2440aa5e 100644 --- a/pep-3147.txt +++ b/pep-3147.txt @@ -22,7 +22,7 @@ allowing more than one byte compilation file (.pyc files) to be co-located with the Python source file (.py file). The extension described here can also be used to support different Python compilation caches, such as JIT output that may be produced by an -Unladen Swallow [1]_ enabled C Python. +Unladen Swallow (:pep:`3146`) enabled C Python. Background @@ -79,7 +79,7 @@ Python release was added or removed from the distribution. Because of the sheer number of packages available, this amount of work is infeasible. -(PEP 384 [7]_ has been proposed to address binary compatibility issues +(:pep:`384` has been proposed to address binary compatibility issues of third party extension modules across different versions of Python.) Because these distributions cannot share pyc files, elaborate @@ -126,7 +126,7 @@ one does not already exist. The pyc file for the imported source will be written to the `__pycache__` directory, using the magic-tag formatted name. If either the creation of the `__pycache__` directory or the pyc file inside that fails, the import will still succeed, just -as it does in a pre-PEP-3147 world. +as it does in a pre-:pep:`3147` world. If the py source file is missing, the pyc file inside `__pycache__` will be ignored. This eliminates the problem of accidental stale pyc @@ -139,7 +139,7 @@ the directory where the py file *would* have been, i.e. not in the be imported if the py source file is missing. Tools such as `py_compile` [15]_ and `compileall` [16]_ will be -extended to create PEP 3147 formatted layouts automatically, but will +extended to create :pep:`3147` formatted layouts automatically, but will have an option to create pyc-only distribution layouts. @@ -432,7 +432,7 @@ package [17]_: Alternative implementations are free to override these functions to return reasonable values based on their own support for this PEP. These methods are allowed to return `None` when the implementation (or -PEP 302 loader [18]_ in effect) for whatever reason cannot calculate +:pep:`302` loader in effect) for whatever reason cannot calculate the appropriate file name. They should not raise exceptions. @@ -443,7 +443,7 @@ For versions of Python earlier than 3.2 (and possibly 2.7), it is possible to backport this PEP. However, in Python 3.2 (and possibly 2.7), this behavior will be turned on by default, and in fact, it will replace the old behavior. Backports will need to support the old -layout by default. We suggest supporting PEP 3147 through the use of +layout by default. We suggest supporting :pep:`3147` through the use of an environment variable called `$PYTHONENABLECACHEDIR` or the command line switch `-Xenablecachedir` to enable the feature. @@ -484,11 +484,11 @@ proposed in this PEP. PEP 304 ------- -There is some overlap between the goals of this PEP and PEP 304 [19]_, -which has been withdrawn. However PEP 304 would allow a user to +There is some overlap between the goals of this PEP and :pep:`304`, +which has been withdrawn. However :pep:`304` would allow a user to create a shadow file system hierarchy in which to store `pyc` files. This concept of a shadow hierarchy for `pyc` files could be used to -satisfy the aims of this PEP. Although the PEP 304 does not indicate +satisfy the aims of this PEP. Although the :pep:`304` does not indicate why it was withdrawn, shadow directories have a number of problems. The location of the shadow `pyc` files would not be easily discovered and would depend on the proper and consistent use of the @@ -565,8 +565,6 @@ this is not an April Fools joke :). References ========== -.. [1] PEP 3146 - .. [2] The marshal module: https://docs.python.org/dev/library/marshal.html @@ -580,8 +578,6 @@ References .. [6] Debian Python Policy: http://www.debian.org/doc/packaging-manuals/python-policy/ -.. [7] PEP 384 - .. [8] python-support: http://wiki.debian.org/DebianPythonFAQ#Whatispython-support.3F @@ -605,10 +601,6 @@ References .. [17] imp: http://www.python.org/doc/current/library/imp.html -.. [18] PEP 302 - -.. [19] PEP 304 - .. [20] http://www.mail-archive.com/python-dev@python.org/msg45203.html .. [21] importlib: http://docs.python.org/3.1/library/importlib.html diff --git a/pep-3149.txt b/pep-3149.txt index 53781005333..0b25a80bde0 100644 --- a/pep-3149.txt +++ b/pep-3149.txt @@ -15,7 +15,7 @@ Resolution: https://mail.python.org/pipermail/python-dev/2010-September/103408.h Abstract ======== -PEP 3147 [1]_ described an extension to Python's import machinery that +:pep:`3147` described an extension to Python's import machinery that improved the sharing of Python source code, by allowing more than one byte compilation file (.pyc) to be co-located with each source file. @@ -28,7 +28,7 @@ more easily provide more than one Python major version at a time. Background ========== -PEP 3147 defined the file system layout for a pure-Python package, +:pep:`3147` defined the file system layout for a pure-Python package, where multiple versions of Python are available on the system. For example, where the `alpha` package containing source modules `one.py` and `two.py` exist on a system with Python 3.2 and 3.3, the post-byte @@ -53,7 +53,7 @@ to changes in the ABI. Different configuration/compilation options for the same Python version can result in different ABIs (e.g. --with-wide-unicode). -While PEP 384 [2]_ defines a stable ABI, it will minimize, but not +While :pep:`384` defines a stable ABI, it will minimize, but not eliminate extension module incompatibilities between Python builds or major versions. Thus a mechanism for discriminating extension module file names is proposed. @@ -71,7 +71,7 @@ In order to share as much as possible between the available Python versions, these distributions install third party package modules (``.pyc`` and ``.so`` files) into `/usr/share/pyshared` and symlink to them from `/usr/lib/pythonX.Y/dist-packages`. The symlinks exist -because in a pre-PEP 3147 world (i.e < Python 3.2), the `.pyc` files +because in a pre-:pep:`3147` world (i.e < Python 3.2), the `.pyc` files resulting from byte compilation by the various installed Pythons will name collide with each other. For Python versions >= 3.2, all pure-Python packages can be shared, because the `.pyc` files will no @@ -187,16 +187,16 @@ useful for Windows. PEP 384 ======= -PEP 384 defines a stable ABI for extension modules. In theory, -universal adoption of PEP 384 would eliminate the need for this PEP +:pep:`384` defines a stable ABI for extension modules. In theory, +universal adoption of :pep:`384` would eliminate the need for this PEP because all extension modules could be compatible with any Python version. In practice of course, it will be impossible to achieve universal adoption, and as described above, different build-time flags still affect the ABI. Thus even with a stable ABI, this PEP may still -be necessary. While a complete specification is reserved for PEP 384, +be necessary. While a complete specification is reserved for :pep:`384`, here is a discussion of the relevant issues. -PEP 384 describes a change to ``PyModule_Create()`` where ``3`` is +:pep:`384` describes a change to ``PyModule_Create()`` where ``3`` is passed as the API version if the extension was compiled with ``Py_LIMITED_API``. This should be formalized into an official macro called ``PYTHON_ABI_VERSION`` to mirror ``PYTHON_API_VERSION``. If @@ -205,7 +205,7 @@ would be bumped. To facilitate sharing, Python would be extended to search for extension modules with the ``PYTHON_ABI_VERSION`` number in its name. The prefix ``abi`` is reserved for Python's use. -Thus, an initial implementation of PEP 384, when Python is configured +Thus, an initial implementation of :pep:`384`, when Python is configured with the default set of flags, would search for the following file names when extension module `foo` is imported (in this order):: @@ -222,7 +222,7 @@ by adding a keyword argument to the ``Extension`` class, such as:: Extension('foo', ['foo.c'], abi=3) Martin v. Löwis describes his thoughts [7]_ about the applicability of this -PEP to PEP 384. In summary: +PEP to :pep:`384`. In summary: * ``--with-pydebug`` would not be supported by the stable ABI because this changes the layout of ``PyObject``, which is an exposed @@ -246,9 +246,9 @@ Independent directories or symlinks Debian and Ubuntu could simply add a version-specific directory to ``sys.path`` that would contain just the extension modules for that -version of Python. Or the symlink trick eliminated in PEP 3147 could +version of Python. Or the symlink trick eliminated in :pep:`3147` could be retained for just shared libraries. This approach is rejected -because it propagates the essential complexity that PEP 3147 tries to +because it propagates the essential complexity that :pep:`3147` tries to avoid, and adds potentially several additional directories to search for all modules, even when the number of extension modules is much fewer than the total number of Python packages. For example, builds @@ -262,7 +262,7 @@ Don't share packages with extension modules It has been suggested that Python packages with extension modules not be shared among all supported Python versions on a distribution. Even -with adoption of PEP 3149, extension modules will have to be compiled +with adoption of :pep:`3149`, extension modules will have to be compiled for every supported Python version, so perhaps sharing of such packages isn't useful anyway. Not sharing packages with extensions though is infeasible for several reasons. @@ -289,10 +289,6 @@ are uploaded. References ========== -.. [1] PEP 3147 - -.. [2] PEP 384 - .. [3] Ubuntu: .. [4] Debian: diff --git a/pep-3150.txt b/pep-3150.txt index dfbf449fba5..b3ba787f621 100644 --- a/pep-3150.txt +++ b/pep-3150.txt @@ -229,13 +229,13 @@ simplify the initial parsing step). New PEP 8 Guidelines -------------------- -As discussed on python-ideas ([7]_, [9]_) new PEP 8 guidelines would also +As discussed on python-ideas ([7]_, [9]_) new :pep:`8` guidelines would also need to be developed to provide appropriate direction on when to use the ``given`` clause over ordinary variable assignments. Based on the similar guidelines already present for ``try`` statements, this PEP proposes the following additions for ``given`` statements to the -"Programming Conventions" section of PEP 8: +"Programming Conventions" section of :pep:`8`: - for code that could reasonably be factored out into a separate function, but is not currently reused anywhere, consider using a ``given`` clause. @@ -336,17 +336,17 @@ That way lies C++ and Perl :) Relation to PEP 403 ------------------- -PEP 403 (General Purpose Decorator Clause) attempts to achieve the main +:pep:`403` (General Purpose Decorator Clause) attempts to achieve the main goals of this PEP using a less radical language change inspired by the existing decorator syntax. Despite having the same author, the two PEPs are in direct competition with -each other. PEP 403 represents a minimalist approach that attempts to achieve +each other. :pep:`403` represents a minimalist approach that attempts to achieve useful functionality with a minimum of change from the status quo. This PEP instead aims for a more flexible standalone statement design, which requires a larger degree of change to the language. -Note that where PEP 403 is better suited to explaining the behaviour of +Note that where :pep:`403` is better suited to explaining the behaviour of generator expressions correctly, this PEP is better able to explain the behaviour of decorator clauses in general. Both PEPs support adequate explanations for the semantics of container comprehensions. @@ -376,7 +376,7 @@ appear to misbehave at class scope: only the outermost iterator is evaluated at class scope, while all predicates, nested iterators and value expressions are evaluated inside a nested scope. -Not that, unlike PEP 403, the current version of this PEP *cannot* +Not that, unlike :pep:`403`, the current version of this PEP *cannot* provide a precisely equivalent expansion for a generator expression. The closest it can get is to define an additional level of scoping:: @@ -448,7 +448,7 @@ though those variables are only going to be used once? When should an inline while loop be replaced with a generator that implements the same logic? Opinions differ, and that's OK. -However, explicit PEP 8 guidance will be needed for CPython and the standard +However, explicit :pep:`8` guidance will be needed for CPython and the standard library, and that is discussed in the proposal above. @@ -718,7 +718,7 @@ Rejected Alternatives expressions to indicate a direct reference to the implied closure, thus preventing it from being called automatically to create the local namespace). All such attempts have appeared unattractive and confusing compared to - the simpler decorator-inspired proposal in PEP 403. + the simpler decorator-inspired proposal in :pep:`403`. Reference Implementation ======================== @@ -730,7 +730,7 @@ semantics and code compilation, feel free to try ;) TO-DO ===== -* Mention PEP 359 and possible uses for locals() in the ``given`` clause +* Mention :pep:`359` and possible uses for locals() in the ``given`` clause * Figure out if this can be used internally to make the implementation of zero-argument super() calls less awful diff --git a/pep-3151.txt b/pep-3151.txt index 644309341ce..749780bcc96 100644 --- a/pep-3151.txt +++ b/pep-3151.txt @@ -499,7 +499,8 @@ of finer-grained exception classes and the coalescing of OSError and IOError. The removal of WindowsError alone has been discussed and rejected -as part of another PEP [2]_, but there seemed to be a consensus that the +as part of :pep:`another PEP <348#removing-windowserror>`, +but there seemed to be a consensus that the distinction with OSError wasn't meaningful. This supports at least its aliasing with OSError. @@ -944,9 +945,6 @@ References .. [1] "IO module precisions and exception hierarchy": https://mail.python.org/pipermail/python-dev/2009-September/092130.html -.. [2] Discussion of "Removing WindowsError" in PEP 348: - http://www.python.org/dev/peps/pep-0348/#removing-windowserror - .. [3] Google Code Search of ``IOError`` in Python code: `around 40000 results `_; ``OSError``: `around 15200 results diff --git a/pep-3152.txt b/pep-3152.txt index 1fe27c316f5..46bcab5e362 100644 --- a/pep-3152.txt +++ b/pep-3152.txt @@ -24,7 +24,7 @@ symptoms. This proposal builds on the 'yield from' mechanism described in PEP 380, and describes some of the semantics of cofunctions in terms of it. However, it would be possible to define and implement cofunctions -independently of PEP 380 if so desired. +independently of :pep:`380` if so desired. Rejection --------- diff --git a/pep-3154.txt b/pep-3154.txt index 9e60e055d77..c3ec5579168 100644 --- a/pep-3154.txt +++ b/pep-3154.txt @@ -219,11 +219,11 @@ Acknowledgments In alphabetic order: -* Alexandre Vassalotti, for starting the second PEP 3154 implementation [6]_ +* Alexandre Vassalotti, for starting the second :pep:`3154` implementation [6]_ * Serhiy Storchaka, for discussing the framing proposal [6]_ -* Stefan Mihaila, for starting the first PEP 3154 implementation as a +* Stefan Mihaila, for starting the first :pep:`3154` implementation as a Google Summer of Code project mentored by Alexandre Vassalotti [7]_. diff --git a/pep-3156.txt b/pep-3156.txt index 19b2b202e7c..d676125222f 100644 --- a/pep-3156.txt +++ b/pep-3156.txt @@ -18,9 +18,9 @@ Abstract This is a proposal for asynchronous I/O in Python 3, starting at Python 3.3. Consider this the concrete proposal that is missing from -PEP 3153. The proposal includes a pluggable event loop, transport and +:pep:`3153`. The proposal includes a pluggable event loop, transport and protocol abstractions similar to those in Twisted, and a higher-level -scheduler based on ``yield from`` (PEP 380). The proposed package +scheduler based on ``yield from`` (:pep:`380`). The proposed package name is ``asyncio``. @@ -120,7 +120,7 @@ there is a system event loop that cannot be started or stopped; see The event loop API does not depend on ``await/yield from``. Rather, it uses a combination of callbacks, additional interfaces (transports and protocols), and Futures. The latter are similar to those defined in -PEP 3148, but have a different implementation and are not tied to +:pep:`3148`, but have a different implementation and are not tied to threads. In particular, the ``result()`` method raises an exception instead of blocking when a result is not yet ready; the user is expected to use callbacks (or ``await/yield from``) to wait for the result. @@ -135,7 +135,7 @@ coroutine or a Future into a Future.) For users (like myself) who don't like using callbacks, a scheduler is provided for writing asynchronous I/O code as coroutines using the PEP -380 ``yield from`` or PEP 492 ``await`` expressions. +380 ``yield from`` or :pep:`492` ``await`` expressions. The scheduler is not pluggable; pluggability occurs at the event loop level, and the standard scheduler implementation should work with any conforming event loop @@ -159,7 +159,7 @@ A less ambitious framework may just call the implementing its own event loop. The event loop API provides limited interoperability with threads: -there is an API to submit a function to an executor (see PEP 3148) +there is an API to submit a function to an executor (see :pep:`3148`) which returns a Future that is compatible with the event loop, and there is a method to schedule a callback with an event loop from another thread in a thread-safe manner. @@ -499,7 +499,7 @@ shared state isn't changed by another callback. clock. This may be ``time.time()`` or ``time.monotonic()`` or some other system-specific clock, but it must return a float expressing the time in units of approximately one second since some epoch. - (No clock is perfect -- see PEP 418.) + (No clock is perfect -- see :pep:`418`.) Note: A previous version of this PEP defined a method named ``call_repeatedly()``, which promised to call a callback at regular @@ -509,7 +509,7 @@ easily be emulated using a callback that reschedules itself using ``call_later()``; it is also easy to write coroutine containing a loop and a ``sleep()`` call (a toplevel function in the module, see below). On the other hand, due to the complexities of accurate timekeeping -there are many traps and pitfalls here for the unaware (see PEP 418), +there are many traps and pitfalls here for the unaware (see :pep:`418`), and different use cases require different behavior in edge cases. It is impossible to offer an API for this purpose that is bullet-proof in all cases, so it is deemed better to let application designers decide @@ -531,7 +531,7 @@ Thread interaction below. - ``run_in_executor(executor, callback, *args)``. Arrange to call - ``callback(*args)`` in an executor (see PEP 3148). Returns an + ``callback(*args)`` in an executor (see :pep:`3148`). Returns an ``asyncio.Future`` instance whose result on success is the return value of that call. This is equivalent to ``wrap_future(executor.submit(callback, *args))``. If ``executor`` @@ -542,7 +542,7 @@ Thread interaction 5 threads in this case.) - ``set_default_executor(executor)``. Set the default executor used - by ``run_in_executor()``. The argument must be a PEP 3148 + by ``run_in_executor()``. The argument must be a :pep:`3148` ``Executor`` instance or ``None``, in order to reset the default executor. @@ -1069,11 +1069,11 @@ Futures ------- The ``asyncio.Future`` class here is intentionally similar to the -``concurrent.futures.Future`` class specified by PEP 3148, but there +``concurrent.futures.Future`` class specified by :pep:`3148`, but there are slight differences. Whenever this PEP talks about Futures or futures this should be understood to refer to ``asyncio.Future`` unless ``concurrent.futures.Future`` is explicitly mentioned. The supported -public API is as follows, indicating the differences with PEP 3148: +public API is as follows, indicating the differences with :pep:`3148`: - ``cancel()``. If the Future is already done (or cancelled), do nothing and return ``False``. Otherwise, this attempts to cancel @@ -1092,23 +1092,23 @@ public API is as follows, indicating the differences with PEP 3148: - ``result()``. Returns the result set with ``set_result()``, or raises the exception set with ``set_exception()``. Raises - ``CancelledError`` if cancelled. Difference with PEP 3148: This has + ``CancelledError`` if cancelled. Difference with :pep:`3148`: This has no timeout argument and does *not* wait; if the future is not yet done, it raises an exception. - ``exception()``. Returns the exception if set with ``set_exception()``, or ``None`` if a result was set with ``set_result()``. Raises ``CancelledError`` if cancelled. - Difference with PEP 3148: This has no timeout argument and does + Difference with :pep:`3148`: This has no timeout argument and does *not* wait; if the future is not yet done, it raises an exception. - ``add_done_callback(fn)``. Add a callback to be run when the Future becomes done (or is cancelled). If the Future is already done (or cancelled), schedules the callback to using ``call_soon()``. - Difference with PEP 3148: The callback is never called immediately, + Difference with :pep:`3148`: The callback is never called immediately, and always in the context of the caller -- typically this is a thread. You can think of this as calling the callback through - ``call_soon()``. Note that in order to match PEP 3148, the callback + ``call_soon()``. Note that in order to match :pep:`3148`, the callback (unlike all other callbacks defined in this PEP, and ignoring the convention from the section "Callback Style" below) is always called with a single argument, the Future object. (The motivation for @@ -1116,18 +1116,18 @@ public API is as follows, indicating the differences with PEP 3148: applies here too.) - ``remove_done_callback(fn)``. Remove the argument from the list of - callbacks. This method is not defined by PEP 3148. The argument + callbacks. This method is not defined by :pep:`3148`. The argument must be equal (using ``==``) to the argument passed to ``add_done_callback()``. Returns the number of times the callback was removed. - ``set_result(result)``. The Future must not be done (nor cancelled) already. This makes the Future done and schedules the callbacks. - Difference with PEP 3148: This is a public API. + Difference with :pep:`3148`: This is a public API. - ``set_exception(exception)``. The Future must not be done (nor cancelled) already. This makes the Future done and schedules the - callbacks. Difference with PEP 3148: This is a public API. + callbacks. Difference with :pep:`3148`: This is a public API. The internal method ``set_running_or_notify_cancel()`` is not supported; there is no way to set the running state. Likewise, @@ -1186,7 +1186,7 @@ There are some public functions related to Futures: it is returned unchanged; if it is a coroutine object, it wraps it in a Task (remember that ``Task`` is a subclass of ``Future``). -- ``asyncio.wrap_future(future)``. This takes a PEP 3148 Future +- ``asyncio.wrap_future(future)``. This takes a :pep:`3148` Future (i.e., an instance of ``concurrent.futures.Future``) and returns a Future compatible with the event loop (i.e., a ``asyncio.Future`` instance). @@ -1583,7 +1583,7 @@ A coroutine is a generator that follows certain conventions. For documentation purposes, all coroutines should be decorated with ``@asyncio.coroutine``, but this cannot be strictly enforced. -Coroutines use the ``yield from`` syntax introduced in PEP 380, +Coroutines use the ``yield from`` syntax introduced in :pep:`380`, instead of the original ``yield`` syntax. The word "coroutine", like the word "generator", is used for two @@ -1647,7 +1647,7 @@ package are provided: ``timeout``, if not ``None``, specifies a timeout for the overall operation; ``return_when``, specifies when to stop. The constants ``FIRST_COMPLETED``, ``FIRST_EXCEPTION``, ``ALL_COMPLETED`` are - defined with the same values and the same meanings as in PEP 3148: + defined with the same values and the same meanings as in :pep:`3148`: - ``ALL_COMPLETED`` (default): Wait until all Futures are done (or until the timeout occurs). @@ -1657,7 +1657,7 @@ package are provided: - ``FIRST_EXCEPTION``: Wait until at least one Future is done but not cancelled with an exception set. (The exclusion of cancelled - Futures from the condition is surprising, but PEP 3148 does it + Futures from the condition is surprising, but :pep:`3148` does it this way.) - ``asyncio.as_completed(fs, timeout=None)``. Returns an iterator whose @@ -2038,19 +2038,19 @@ status allows revising these decisions for Python 3.5.) References ========== -- PEP 492 describes the semantics of ``async/await``. +- :pep:`492` describes the semantics of ``async/await``. -- PEP 380 describes the semantics of ``yield from``. +- :pep:`380` describes the semantics of ``yield from``. - Greg Ewing's ``yield from`` tutorials: http://www.cosc.canterbury.ac.nz/greg.ewing/python/yield-from/yield_from.html -- PEP 3148 describes ``concurrent.futures.Future``. +- :pep:`3148` describes ``concurrent.futures.Future``. -- PEP 3153, while rejected, has a good write-up explaining the need +- :pep:`3153`, while rejected, has a good write-up explaining the need to separate transports and protocols. -- PEP 418 discusses the issues of timekeeping. +- :pep:`418` discusses the issues of timekeeping. - Tulip repo: http://code.google.com/p/tulip/ @@ -2068,7 +2068,7 @@ References Acknowledgments =============== -Apart from PEP 3153, influences include PEP 380 and Greg Ewing's +Apart from :pep:`3153`, influences include :pep:`380` and Greg Ewing's tutorial for ``yield from``, Twisted, Tornado, ZeroMQ, pyftpdlib, and wattle (Steve Dower's counter-proposal). My previous work on asynchronous support in the NDB library for Google App Engine provided diff --git a/pep-3333.txt b/pep-3333.txt index b7b96bbceba..1005890f210 100644 --- a/pep-3333.txt +++ b/pep-3333.txt @@ -12,10 +12,10 @@ Post-History: 26-Sep-2010, 04-Oct-2010 Replaces: 333 -Preface for Readers of PEP \333 -=============================== +Preface for Readers of PEP 333 +============================== -This is an updated version of PEP 333, modified slightly to improve +This is an updated version of :pep:`333`, modified slightly to improve usability under Python 3, and to incorporate several long-standing de facto amendments to the WSGI protocol. (Its code samples have also been ported to Python 3.) @@ -41,8 +41,8 @@ servers and Python web applications or frameworks, to promote web application portability across a variety of web servers. -Original Rationale and Goals (from PEP \333) -============================================ +Original Rationale and Goals (from PEP 333) +=========================================== Python currently boasts a wide variety of web application frameworks, such as Zope, Quixote, Webware, SkunkWeb, PSO, and Twisted Web -- to @@ -555,7 +555,7 @@ current request, whether the request was completed normally, or terminated early due to an application error during iteration or an early disconnect of the browser. (The ``close()`` method requirement is to support resource release by the application. This protocol is intended -to complement PEP 342's generator support, and other common iterables +to complement :pep:`342`'s generator support, and other common iterables with ``close()`` methods.) Applications returning a generator or other custom iterator **should not** @@ -574,7 +574,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. @@ -809,7 +809,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. @@ -817,7 +817,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, @@ -942,12 +942,13 @@ whose ``len()`` is 1, then the server can automatically determine ``Content-Length`` by taking the length of the first bytestring 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 bytestring 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``. @@ -1094,8 +1095,8 @@ all strings passed to or from the server must be of type ``str`` or 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 @@ -1202,8 +1203,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 @@ -1216,13 +1217,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 @@ -1418,7 +1420,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 @@ -1598,7 +1600,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, ...) @@ -1763,13 +1765,7 @@ References (https://wiki.python.org/moin/WebProgramming) .. [2] The Common Gateway Interface Specification, v 1.1, 3rd Draft - (https://tools.ietf.org/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) + (https://datatracker.ietf.org/doc/html/draft-coar-cgi-v11-03) .. [5] mod_ssl Reference, "Environment Variables" (http://www.modssl.org/docs/2.8/ssl_reference.html#ToC25) @@ -1777,7 +1773,7 @@ References .. [6] Procedural issues regarding modifications to PEP \333 (https://mail.python.org/pipermail/python-dev/2010-September/104114.html) -.. [7] SVN revision history for PEP \3333, showing differences from PEP 333 +.. [7] SVN revision history for PEP 3333, showing differences from PEP 333 (http://svn.python.org/view/peps/trunk/pep-3333.txt?r1=84854&r2=HEAD) Copyright diff --git a/pep-8000.rst b/pep-8000.rst index b56c3cade80..a165bbb9e37 100644 --- a/pep-8000.rst +++ b/pep-8000.rst @@ -13,19 +13,19 @@ Abstract This PEP provides an overview of the selection process for a new model of Python language governance in the wake of `Guido's retirement `_. -Once the governance model is selected, it will be codified in PEP 13. +Once the governance model is selected, it will be codified in :pep:`13`. Here is a list of PEPs related to the governance model selection process. PEPs in the lower 8000s describe the general process for selecting a governance model. -* PEP 8001 - Python Governance Voting Process +* :pep:`8001` - Python Governance Voting Process This PEP describes how the vote for the new governance model will be conducted. It outlines the voting method, timeline, criteria for participation, and explicit list of eligible voters. -* PEP 8002 - Open Source Governance Survey +* :pep:`8002` - Open Source Governance Survey Surveys will be conducted of governance models for similar open source and free software projects, and summaries of these models will be outlined in @@ -41,7 +41,7 @@ differences in details (such as the size of a governing council) will be covered in the same PEP, rather than in potentially vote-splitting individual PEPs. -* PEP 8010 - The Technical Leader Governance Model +* :pep:`8010` - The Technical Leader Governance Model This PEP proposes a continuation of the singular technical project leader model. Also within scope is whether an advisory council aids @@ -49,13 +49,13 @@ PEPs. BDFL, nor members of such an advisory council. For that, see PEP 13. -* PEP 8011 - Python Governance Model Lead by Trio of Pythonistas +* :pep:`8011` - Python Governance Model Lead by Trio of Pythonistas This PEP describes a new model of Python governance lead by a Trio of Pythonistas (TOP). It describes the role and responsibilities of the Trio. - This PEP does *not* name members of the Trio. For that, see PEP 13. + This PEP does *not* name members of the Trio. For that, see :pep:`13`. -* PEP 8012 - The Community Governance Model +* :pep:`8012` - The Community Governance Model This is a placeholder PEP for a new model of Python governance based on consensus and voting, without the role of a centralized singular leader or a @@ -63,16 +63,16 @@ PEPs. decisions affecting the Python language. It also describes the criteria for voting eligibility. -* PEP 8013 - The External Governance Model +* :pep:`8013` - The External Governance Model This PEP describes a new model of Python governance based on an external council who are responsible for ensuring good process. Elected by the core development team, this council may reject proposals that are not sufficiently detailed, do not consider all affected users, or are not appropriate for the upcoming release. This PEP does *not* name members of - such a council. For that, see PEP 13. + such a council. For that, see :pep:`13`. -* PEP 8014 - The Commons Governance Model +* :pep:`8014` - The Commons Governance Model This PEP describes a new model of Python governance based on a council of elders who are responsible for ensuring a PEP is supported by a sufficient @@ -81,7 +81,7 @@ PEPs. rights and what a majority vote consists of. In stead this is determined by the council of elders on a case-by-case basis. -* PEP 8015 - Organization of the Python community +* :pep:`8015` - Organization of the Python community This PEP formalizes the current organization of the Python community and proposes 3 main changes: formalize the existing concept of @@ -89,7 +89,7 @@ PEPs. (Guido van Rossum) with a new "Python board" of 3 members which has limited roles, mostly decide how a PEP is approved (or rejected). -* PEP 8016 - The Steering Council Model +* :pep:`8016` - The Steering Council Model This PEP proposes a model of Python governance based around a steering council. The council has broad authority, which they seek diff --git a/pep-8001.rst b/pep-8001.rst index d5e2c930c38..5dd5dc2c04c 100644 --- a/pep-8001.rst +++ b/pep-8001.rst @@ -26,7 +26,7 @@ This PEP outlines the process for how the new model of Python governance is selected, in the wake of `Guido's retirement `_. Once the model is chosen by the procedures outlined here, it will be codified -in PEP 13. +in :pep:`13`. Motivation and Rationale @@ -57,7 +57,7 @@ What are we voting for? ----------------------- We are voting to choose which governance PEP should be implemented by -the Python project. The list of candidate PEPs is listed in PEP 8000 +the Python project. The list of candidate PEPs is listed in :pep:`8000` and consists of all PEPs numbered in the 801X range. To ensure the vote is legitimate, the aforementioned PEPs must not be diff --git a/pep-8010.rst b/pep-8010.rst index 92eae7b7ea8..2983d2e9383 100644 --- a/pep-8010.rst +++ b/pep-8010.rst @@ -35,18 +35,18 @@ This PEP describes: * Any changes to the PEP process to fit the new governance model; This PEP does *not* name a new BDFL. Should this model be adopted, it -will be codified in PEP 13 along with the names of all officeholders +will be codified in :pep:`13` along with the names of all officeholders described in this PEP. PEP Rejection ============= -PEP 8010 was rejected `by a core developer vote +:pep:`8010` was rejected `by a core developer vote `__ -described in PEP 8001 on Monday, December 17, 2018. +described in :pep:`8001` on Monday, December 17, 2018. -PEP 8016 and the governance model it describes were chosen instead. +:pep:`8016` and the governance model it describes were chosen instead. Open discussion points @@ -58,7 +58,7 @@ lengths of service, and voting procedures. These will be codified by the time the PEP is ready to be voted on. The voting procedures and events described in this PEP will default to -the voting method specified in PEP 8001, although as that PEP is still +the voting method specified in :pep:`8001`, although as that PEP is still in discussion at the time of this writing, this is subject to change. It is allowed, and perhaps even expected, that as experience is gained @@ -205,7 +205,7 @@ to the committers discussion forum. Maybe we'll even have debates! This phase of the election runs for two weeks. Core developers then have three weeks to vote, using the process -described in PEP 8001. +described in :pep:`8001`. The Council of Pythonistas (CoP) @@ -233,7 +233,7 @@ popular vote getter shall serve for 2 years, and CoP member with the least number of votes shall serve initially for 1 year. All ties in voting will be broken with a procedure to be determined in -PEP 8001. +:pep:`8001`. The nomination and voting process is similar as with the GUIDO. There is a three-week nomination period, where self-nominations are allowed @@ -250,7 +250,7 @@ No confidence votes As mentioned above, the CoP may, by unanimous decision, initiate a vote of no-confidence in the GUIDO. This process should not be undertaken lightly, but once begun, it triggers up to two votes. In -both cases, voting is done by the same procedure as in PEP 8001, and +both cases, voting is done by the same procedure as in :pep:`8001`, and all core developers may participate in no confidence votes. The first vote is whether to recall the current GUIDO or not. Should @@ -301,7 +301,7 @@ Version 2 - Renamed to "The Technical Leader Governance Model" - "singular leader" -> "singular technical leader" - - The adoption of PEP 8001 voting procedures is tentative until that + - The adoption of :pep:`8001` voting procedures is tentative until that PEP is approved - Describe what happens if the GUIDO steps down - Recall votes require a super majority of core devs to succeed diff --git a/pep-8011.rst b/pep-8011.rst index d6fca8bdab4..b228e86d376 100644 --- a/pep-8011.rst +++ b/pep-8011.rst @@ -13,14 +13,14 @@ Abstract This PEP proposes a governance model for the Core Python development community, led by a trio of equally authoritative leaders. The Trio of Pythonistas (ToP, or simply Trio) is tasked with making final decisions for the language. -It differs from PEP 8010 by specifically not proposing a central singular leader, +It differs from :pep:`8010` by specifically not proposing a central singular leader, but instead a group of three people as the leaders. This PEP also proposes a formation of specialized workgroups to assist the leadership trio in making decisions. This PEP does *not* name the members of the Trio. Should this model be adopted, -it will be codified in PEP 13 along with the names of all officeholders +it will be codified in :pep:`13` along with the names of all officeholders described in this PEP. This PEP describes: @@ -35,11 +35,11 @@ This PEP describes: PEP Rejection ============= -PEP 8011 was rejected `by a core developer vote +:pep:`8011` was rejected `by a core developer vote `__ -described in PEP 8001 on Monday, December 17, 2018. +described in :pep:`8001` on Monday, December 17, 2018. -PEP 8016 and the governance model it describes were chosen instead. +:pep:`8016` and the governance model it describes were chosen instead. Open discussion points ====================== @@ -52,7 +52,7 @@ These will be codified by the time the PEP is ready to be voted on. It is allowed, and perhaps even expected, that as experience is gained with this model, these parameters may be tweaked in order to provide for a smoother governing process. The process for tweaking these parameters will generally -be the same voting process as described in PEP 8001. +be the same voting process as described in :pep:`8001`. Roles and responsibilities of the leadership trio @@ -84,7 +84,7 @@ decide whether a particular decision requires a PEP, and to resolve technical disputes in general. The trio's authority does not include changing the governance itself, or other non-technical disputes that may arise; these should be handled through the process described in -PEP 8001. +:pep:`8001`. What are NOT considered as the role responsibilities of the trio @@ -137,7 +137,7 @@ Only once this PEP is accepted, any active core developers (who are eligible to can submit nomination of groups of three. Once this PEP is accepted and core devs have submitted their nominations, voting -can begin, and the voting mechanism described in PEP 8001 will be used. +can begin, and the voting mechanism described in :pep:`8001` will be used. Qualities desired out of the trio: diff --git a/pep-8012.rst b/pep-8012.rst index 71b46954e68..f22ed48f5f0 100644 --- a/pep-8012.rst +++ b/pep-8012.rst @@ -10,11 +10,11 @@ Created: 03-Oct-2018 PEP Rejection ============= -PEP 8012 was rejected `by a core developer vote +:pep:`8012` was rejected `by a core developer vote `__ -described in PEP 8001 on Monday, December 17, 2018. +described in :pep:`8001` on Monday, December 17, 2018. -PEP 8016 and the governance model it describes were chosen instead. +:pep:`8016` and the governance model it describes were chosen instead. Abstract ======== @@ -27,7 +27,7 @@ the role of a centralized singular leader or a governing council. It describes how, when, and why votes are conducted for decisions affecting the Python language. It also describes the criteria for voting eligibility. -Should this model be adopted, it will be codified in PEP 13. +Should this model be adopted, it will be codified in :pep:`13`. This model can be affectionately called "The Least Worst Governance Model" by its property that while far from ideal, it's still the most @@ -194,7 +194,7 @@ others. Contributors and any workgroups in this model are self-selecting. the interests of a single person or a small group of people. **Proven** This model works. There is a number of large open-source projects -run this way (two of which, Rust and Django, are described in PEP 8002). +run this way (two of which, Rust and Django, are described in :pep:`8002`). ECMAScript and C++ are similarly developed. @@ -302,7 +302,7 @@ PEP, Enhanced ~~~~~~~~~~~~~ The PEP process is augmented with the following changes and clarifications -over information already present in PEP 1: +over information already present in :pep:`1`: * PEPs are not merged until the final decision is made on them; they are open pull requests on GitHub until that moment; @@ -463,7 +463,7 @@ conduct-wg@python.org. Acknowledgements ================ -Thank you to the authors of PEP 8002 which was a helpful resource in +Thank you to the authors of :pep:`8002` which was a helpful resource in shaping this document. Thank you to Alex Crichton and the Rust team for a governance model diff --git a/pep-8013.rst b/pep-8013.rst index c5500770361..ddf9f9ac4a9 100644 --- a/pep-8013.rst +++ b/pep-8013.rst @@ -11,8 +11,8 @@ Abstract This PEP proposes a new model of Python governance based on a Council of Auditors (CoA) tasked with making final decisions for the language. -It differs from PEP 8010 by specifically not proposing a central -singular leader, and from PEP 8011 by disallowing core committers from +It differs from :pep:`8010` by specifically not proposing a central +singular leader, and from :pep:`8011` by disallowing core committers from being council members. It describes the size and role of the council, how the initial group of council members will be chosen, any term limits of the council members, and how successors will be elected. @@ -27,17 +27,17 @@ circumstances. This only works when process is unspecified, but all participants have similar expectations. This PEP does *not* name the members of the CoA. Should this model be -adopted, it will be codified in PEP 13 along with the names of all +adopted, it will be codified in :pep:`13` along with the names of all officeholders described in this PEP. PEP Rejection ============= -PEP 8013 was rejected `by a core developer vote +:pep:`8013` was rejected `by a core developer vote `__ -described in PEP 8001 on Monday, December 17, 2018. +described in :pep:`8001` on Monday, December 17, 2018. -PEP 8016 and the governance model it describes were chosen instead. +:pep:`8016` and the governance model it describes were chosen instead. The Importance of the Grey Area =============================== diff --git a/pep-8014.rst b/pep-8014.rst index 31ca81eb919..62b9c9100c0 100644 --- a/pep-8014.rst +++ b/pep-8014.rst @@ -29,11 +29,11 @@ carried by a sufficient majority. PEP Rejection ============= -PEP 8014 was rejected `by a core developer vote +:pep:`8014` was rejected `by a core developer vote `__ -described in PEP 8001 on Monday, December 17, 2018. +described in :pep:`8001` on Monday, December 17, 2018. -PEP 8016 and the governance model it describes were chosen instead. +:pep:`8016` and the governance model it describes were chosen instead. Introduction ============ @@ -310,7 +310,7 @@ other person or body. Note that this proposal most likely favors conservatism over progression. Or, at least, the danger of it leading to stagnation is bigger than the danger of it leading to reckless blazing ahead into unknown territories. So: we should realise -that it is unlikely that a PEP like PEP 572 will pass if this model is in +that it is unlikely that a PEP like :pep:`572` will pass if this model is in place. Copyright diff --git a/pep-8015.rst b/pep-8015.rst index 036ddef7512..c61acc95d89 100644 --- a/pep-8015.rst +++ b/pep-8015.rst @@ -25,11 +25,11 @@ developers, need ``>= 2/3`` majority). PEP Rejection ============= -PEP 8015 was rejected `by a core developer vote +:pep:`8015` was rejected `by a core developer vote `__ -described in PEP 8001 on Monday, December 17, 2018. +described in :pep:`8001` on Monday, December 17, 2018. -PEP 8016 and the governance model it describes were chosen instead. +:pep:`8016` and the governance model it describes were chosen instead. Rationale diff --git a/pep-8016.rst b/pep-8016.rst index b071636cd14..3ddb87bbd6b 100644 --- a/pep-8016.rst +++ b/pep-8016.rst @@ -10,7 +10,7 @@ Note ==== This PEP is retained for historical purposes, but the official -governance document is now PEP 13. +governance document is now :pep:`13`. Abstract @@ -30,9 +30,9 @@ decisions. PEP Acceptance ============== -PEP 8016 was accepted `by a core developer vote +:pep:`8016` was accepted `by a core developer vote `__ -described in PEP 8001 on Monday, December 17, 2018. +described in :pep:`8001` on Monday, December 17, 2018. Rationale diff --git a/pep-8100.rst b/pep-8100.rst index 3a50907381f..e24a9417b39 100644 --- a/pep-8100.rst +++ b/pep-8100.rst @@ -14,7 +14,7 @@ Abstract This document describes the schedule and other details of the January 2019 election for the Python steering council, as specified in -PEP 13. This is the first steering council election. +:pep:`13`. This is the first steering council election. Returns officer @@ -22,7 +22,7 @@ Returns officer In future elections, the returns officer will be appointed by the outgoing steering council. Since this is the first election, we have -no outgoing steering council, and PEP 13 says that the returns officer +no outgoing steering council, and :pep:`13` says that the returns officer is instead appointed by the PSF Executive Director, Ewa Jodlowska. `She appointed Ee W. Durbin III `__. @@ -144,7 +144,7 @@ The top five vote-getters are: * Guido van Rossum * Nick Coghlan -No conflict of interest as defined in PEP 13 were observed. +No conflict of interest as defined in :pep:`13` were observed. The full vote counts are as follows: diff --git a/pep-8101.rst b/pep-8101.rst index 8fd781b56f1..070b2e5f448 100644 --- a/pep-8101.rst +++ b/pep-8101.rst @@ -15,7 +15,7 @@ Abstract This document describes the schedule and other details of the December 2019 election for the Python steering council, as specified in -PEP 13. This is steering council election for the 2020 term. +:pep:`13`. This is steering council election for the 2020 term. Election Administration @@ -145,7 +145,7 @@ The top five vote-getters are: * Thomas Wouters * Victor Stinner -No conflict of interest as defined in PEP 13 were observed. +No conflict of interest as defined in :pep:`13` were observed. The full vote counts are as follows: diff --git a/pep-8102.rst b/pep-8102.rst index d8471203e54..b083fc717eb 100644 --- a/pep-8102.rst +++ b/pep-8102.rst @@ -15,7 +15,7 @@ Abstract This document describes the schedule and other details of the December 2020 election for the Python steering council, as specified in -PEP 13. This is the steering council election for the 2021 term. +:pep:`13`. This is the steering council election for the 2021 term. Election Administration @@ -75,7 +75,7 @@ Voter Roll ========== All active Python core team members are eligible to vote. Active status -is determined as described in `PEP 13 `_ +is determined as described in :pep:`PEP 13 <13#membership>` and implemented via the software at `python/voters `_ [1]_. Ballots will be distributed based on the `The Python Voter Roll for this @@ -151,7 +151,7 @@ The top five vote-getters are: * Pablo Galindo Salgado * Thomas Wouters -No conflict of interest as defined in PEP 13 were observed. +No conflict of interest as defined in :pep:`13` were observed. The full vote counts are as follows: diff --git a/pep-8103.rst b/pep-8103.rst index 3e0b739ec81..bdb58a38943 100644 --- a/pep-8103.rst +++ b/pep-8103.rst @@ -15,7 +15,7 @@ Abstract This document describes the schedule and other details of the December 2021 election for the Python steering council, as specified in -PEP 13. This is the steering council election for the 2022 term +:pep:`13`. This is the steering council election for the 2022 term (i.e. Python 3.11). @@ -72,7 +72,7 @@ Voter Roll ========== All active Python core team members are eligible to vote. Active status -is determined as described in `PEP 13 `_ +is determined as described in :pep:`PEP 13 <13#membership>` and implemented via the software at `python/voters `_ [1]_. Ballots will be distributed based on the `The Python Voter Roll for this @@ -148,7 +148,7 @@ The top five vote-getters are: * Gregory P. Smith * Brett Cannon -No conflict of interest as defined in PEP 13 were observed. +No conflict of interest as defined in :pep:`13` were observed. The full vote counts are as follows: diff --git a/pep_sphinx_extensions/__init__.py b/pep_sphinx_extensions/__init__.py index 5479a1dc132..d2e201c3df2 100644 --- a/pep_sphinx_extensions/__init__.py +++ b/pep_sphinx_extensions/__init__.py @@ -19,18 +19,8 @@ from sphinx.application import Sphinx # Monkeypatch sphinx.environment.default_settings as Sphinx doesn't allow custom settings or Readers -# These settings should go in docutils.conf, but are overridden here for now so as not to affect -# pep2html.py -environment.default_settings |= { - "pep_references": True, - "rfc_references": True, - "pep_base_url": "", - "pep_file_url_template": "", - "_disable_config": True, # disable using docutils.conf whilst running both PEP generators -} - -# TODO replace all inlined PEP and RFC strings with marked-up roles, disable pep_references and rfc_references and remove this monkey-patch -states.Inliner.pep_reference = lambda s, m, _l: [nodes.reference("", m.group(0), refuri=s.document.settings.pep_url.format(int(m.group("pepnum2"))))] +# This disables reading configuration from docutils.conf so as not to affect pep2html.py +environment.default_settings["_disable_config"] = True def _depart_maths():