From b199a29c8af3ca8b73cbb6648610300d670869f4 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Mon, 31 Jul 2023 17:50:14 +0100 Subject: [PATCH] Many PEPs: Resolve reference warnings (#3214) This commit resolves all outstanding duplicate label and duplicate citation warnings. I have not yet addressed unreferenced footnote warnings. I took the general strategy of replacing a target above a section heading with references directly to that section heading, or where impractical, disambiguting the target with ``PEP NNN``. I also converted all the citations in PEP 482 to links, as they were causing duplicate citation warnings. --- pep-0394.txt | 2 - pep-0400.txt | 4 +- pep-0482.txt | 103 ++++++++++++++++----------------------------------- pep-0526.txt | 8 ++-- pep-0544.txt | 51 +++++++++++-------------- pep-0557.rst | 16 +------- pep-0573.rst | 12 ------ pep-0583.rst | 23 +++--------- pep-0612.rst | 2 - pep-0615.rst | 6 +-- pep-0622.rst | 72 +++++++++-------------------------- pep-0633.rst | 4 +- pep-0634.rst | 2 +- pep-0636.rst | 14 +------ pep-0642.rst | 8 ---- pep-0649.rst | 5 +-- pep-0669.rst | 15 +------- pep-0675.rst | 16 ++------ pep-0680.rst | 20 +++------- pep-0689.rst | 4 +- pep-0692.rst | 16 +++----- pep-0695.rst | 8 ++-- pep-0696.rst | 12 +++--- pep-0697.rst | 21 ++++------- pep-0701.rst | 12 ++---- pep-0704.rst | 4 +- pep-0710.rst | 12 +++--- pep-0720.rst | 32 +++++----------- pep-3151.txt | 37 +++++++----------- 29 files changed, 155 insertions(+), 386 deletions(-) diff --git a/pep-0394.txt b/pep-0394.txt index 10ad8a911..7e6110112 100644 --- a/pep-0394.txt +++ b/pep-0394.txt @@ -183,8 +183,6 @@ administrators with the freedom to configure their systems based on the needs of their particular environment. -.. _rationale: - Current Rationale ================= diff --git a/pep-0400.txt b/pep-0400.txt index acb35694c..5067e5a4e 100644 --- a/pep-0400.txt +++ b/pep-0400.txt @@ -84,7 +84,7 @@ StreamReader and StreamWriter issues supports UNIX newlines ('\\n'). * StreamReader and StreamWriter are stateful codecs but don't expose functions to control their state (getstate() or setstate()). Each - codec has to handle corner cases, see `Appendix A`_. + codec has to handle corner cases, see `Appendix A `_. * StreamReader and StreamWriter are very similar to IncrementalReader and IncrementalEncoder, some code is duplicated for stateful codecs (e.g. UTF-16). @@ -207,7 +207,7 @@ Python 3.3. Defining a subclass doesn't emit a DeprecationWarning. codecs.open() will be changed to reuse the builtin open() function (TextIOWrapper) to read-write text files. -.. _Appendix A: +.. _PEP 400 Appendix A: Alternative Approach ==================== diff --git a/pep-0482.txt b/pep-0482.txt index f30511e8b..6c0dc550a 100644 --- a/pep-0482.txt +++ b/pep-0482.txt @@ -26,36 +26,47 @@ Existing Approaches for Python mypy ---- -(This section is a stub, since mypy [mypy]_ is essentially what we're +(This section is a stub, since `mypy`__ is essentially what we're proposing.) +__ https://mypy-lang.org + Reticulated Python ------------------ -Reticulated Python [reticulated]_ by Michael Vitousek is an example of +`Reticulated Python`__ by Michael Vitousek is an example of a slightly different approach to gradual typing for Python. It is -described in an actual academic paper [reticulated-paper]_ written by +described in an actual `academic paper`__ written by Vitousek with Jeremy Siek and Jim Baker (the latter of Jython fame). +__ https://github.com/mvitousek/reticulated +__ http://wphomes.soic.indiana.edu/jsiek/files/2014/03/retic-python.pdf PyCharm ------- PyCharm by JetBrains has been providing a way to specify and check -types for about four years. The type system suggested by PyCharm -[pycharm]_ grew from simple class types to tuple types, generic types, +types for about four years. The type system suggested by PyCharm__ +grew from simple class types to tuple types, generic types, function types, etc. based on feedback of many users who shared their experience of using type hints in their code. +__ https://github.com/JetBrains/python-skeletons#types Others ------ -TBD: Add sections on pyflakes [pyflakes]_, pylint [pylint]_, numpy -[numpy]_, Argument Clinic [argumentclinic]_, pytypedecl [pytypedecl]_, -numba [numba]_, obiwan [obiwan]_. +TBD: Add sections on pyflakes__, pylint__, numpy__, +`Argument Clinic`__, pytypedecl__, numba__, obiwan__. +__ https://github.com/pyflakes/pyflakes/ +__ https://www.pylint.org +__ https://www.numpy.org +__ https://docs.python.org/3/howto/clinic.html +__ https://github.com/google/pytypedecl +__ https://numba.pydata.org +__ https://pypi.org/project/obiwan Existing Approaches in Other Languages ====================================== @@ -63,11 +74,13 @@ Existing Approaches in Other Languages ActionScript ------------ -ActionScript [actionscript]_ is a class-based, single inheritance, +ActionScript__ is a class-based, single inheritance, object-oriented superset of ECMAScript. It supports inferfaces and strong runtime-checked static typing. Compilation supports a “strict dialect” where type mismatches are reported at compile-time. +__ https://livedocs.adobe.com/specs/actionscript/3/ + Example code with types:: package { @@ -95,10 +108,12 @@ Example code with types:: Dart ---- -Dart [dart]_ is a class-based, single inheritance, object-oriented +Dart__ is a class-based, single inheritance, object-oriented language with C-style syntax. It supports interfaces, abstract classes, reified generics, and optional typing. +__ https://www.dartlang.org + Types are inferred when possible. The runtime differentiates between two modes of execution: *checked mode* aimed for development (catching type errors at runtime) and *production mode* recommended for speed execution @@ -121,10 +136,12 @@ Example code with types:: Hack ---- -Hack [hack]_ is a programming language that interoperates seamlessly +Hack__ is a programming language that interoperates seamlessly with PHP. It provides opt-in static type checking, type aliasing, generics, nullable types, and lambdas. +__ https://hacklang.org + Example code with types:: `_ listed at the end of this PEP. Abstract @@ -395,8 +395,8 @@ Changes to Standard Library and Documentation instances. This restriction is ensured by static checkers, but not at runtime. See the `classvar`_ section for examples and explanations for the usage of - ``ClassVar``, and see the `rejected`_ section for more information on - the reasoning behind ``ClassVar``. + ``ClassVar``, and see the `rejected `_ section + for more information on the reasoning behind ``ClassVar``. - Function ``get_type_hints`` in the ``typing`` module will be extended, so that one can retrieve type annotations at runtime from modules @@ -511,7 +511,7 @@ These stored annotations might be used for other purposes, but with this PEP we explicitly recommend type hinting as the preferred use of annotations. -.. _rejected: +.. _PEP 526 rejected: Rejected/Postponed Proposals ============================ diff --git a/pep-0544.txt b/pep-0544.txt index d8c86ce8d..04df7bd7f 100644 --- a/pep-0544.txt +++ b/pep-0544.txt @@ -24,7 +24,7 @@ static and runtime semantics of protocol classes that will provide a support for *structural* subtyping (static duck typing). -.. _rationale: +.. _PEP 544 rationale: Rationale and Goals =================== @@ -86,8 +86,8 @@ subtyping have their strengths and weaknesses. Therefore, in this PEP we *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 -end of this PEP for additional motivation. +where to apply a particular solution. See section on `rejected +`_ ideas at the end of this PEP for additional motivation. Non-goals @@ -181,8 +181,9 @@ approaches related to structural subtyping in Python and other languages: assert issubclass(tuple, MyTuple) assert isinstance((), MyTuple) - As mentioned in the `rationale`_, we want to avoid such necessity, especially - in static context. However, in a runtime context, ABCs are good candidates for + As mentioned in the `rationale `_, + we want to avoid such necessity, especially in static context. + However, in a runtime context, ABCs are good candidates for protocol classes and they are already used extensively in the ``typing`` module. @@ -200,8 +201,9 @@ approaches related to structural subtyping in Python and other languages: assert isinstance(MyIterable(), Iterable) Such behavior seems to be a perfect fit for both runtime and static behavior - of protocols. As discussed in `rationale`_, we propose to add static support - for such behavior. In addition, to allow users to achieve such runtime + of protocols. As discussed in `rationale `_, + we propose to add static support for such behavior. + In addition, to allow users to achieve such runtime behavior for *user-defined* protocols a special ``@runtime_checkable`` decorator will be provided, see detailed `discussion`_ below. @@ -225,9 +227,9 @@ approaches related to structural subtyping in Python and other languages: prohibits redundant members in implementations. While the idea of optional members looks interesting, it would complicate this proposal and it is not clear how useful it will be. Therefore, it is proposed to postpone - this; see `rejected`_ ideas. In general, the idea of static protocol - checking without runtime implications looks reasonable, and basically - this proposal follows the same line. + this; see `rejected `_ ideas. In general, the idea of + static protocol checking without runtime implications looks reasonable, + and basically this proposal follows the same line. * Go [golang]_ uses a more radical approach and makes interfaces the primary way to provide type information. Also, assignments are used to explicitly @@ -242,11 +244,9 @@ approaches related to structural subtyping in Python and other languages: } Both these ideas are questionable in the context of this proposal. See - the section on `rejected`_ ideas. + the section on `rejected `_ ideas. -.. _specification: - Specification ============= @@ -496,8 +496,9 @@ considering subtyping, since structural compatibility is the criterion, not the MRO. If ``Protocol`` is included in the base class list, all the other base classes -must be protocols. A protocol can't extend a regular class, see `rejected`_ -ideas for rationale. Note that rules around explicit subclassing are different +must be protocols. A protocol can't extend a regular class, see `rejected +`_ ideas for rationale. +Note that rules around explicit subclassing are different from regular ABCs, where abstractness is simply defined by having at least one abstract method being unimplemented. Protocol classes must be marked *explicitly*. @@ -551,7 +552,7 @@ the declared variance. Examples:: Note that unlike nominal classes, de facto covariant protocols cannot be declared as invariant, since this can break transitivity of subtyping -(see `rejected`_ ideas for details). For example:: +(see `rejected `_ ideas for details). For example:: T = TypeVar('T') @@ -732,7 +733,7 @@ Example:: 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`, -see `rejected`_ ideas for more details. +see `rejected `_ ideas for more details. ``Type[]`` and class objects vs protocols @@ -888,7 +889,8 @@ that provides the same semantics for class and instance checks as for assert isinstance(open('some/file'), SupportsClose) Note that instance checks are not 100% reliable statically, this is why -this behavior is opt-in, see section on `rejected`_ ideas for examples. +this behavior is opt-in, see section on `rejected `_ +ideas for examples. The most type checkers can do is to treat ``isinstance(obj, Iterator)`` roughly as a simpler way to write ``hasattr(x, '__iter__') and hasattr(x, '__next__')``. To minimize @@ -1027,7 +1029,7 @@ at runtime in this case). But together with other introspection tools this give a reasonable perspective for runtime type checking tools. -.. _rejected: +.. _PEP 544 rejected: Rejected/Postponed Ideas ======================== @@ -1498,14 +1500,3 @@ Copyright ========= This document has been placed in the public domain. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - coding: utf-8 - End: diff --git a/pep-0557.rst b/pep-0557.rst index d30d302ef..44d17286e 100644 --- a/pep-0557.rst +++ b/pep-0557.rst @@ -14,7 +14,7 @@ Notice for Reviewers This PEP and the initial implementation were drafted in a separate repo: https://github.com/ericvsmith/dataclasses. Before commenting in -a public forum please at least read the `discussion`_ listed at the +a public forum please at least read the discussion_ listed at the end of this PEP. Abstract @@ -139,8 +139,6 @@ Where is it not appropriate to use Data Classes? - Type validation beyond that provided by PEPs 484 and 526 is required, or value validation or conversion is required. -.. _Specification: - Specification ============= @@ -666,8 +664,6 @@ Module level helper functions def is_dataclass_instance(obj): return is_dataclass(obj) and not isinstance(obj, type) -.. _discussion: - Discussion ========== @@ -974,13 +970,3 @@ Copyright ========= This document has been placed in the public domain. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - coding: utf-8 - End: diff --git a/pep-0573.rst b/pep-0573.rst index 740965de0..6007d0015 100644 --- a/pep-0573.rst +++ b/pep-0573.rst @@ -46,8 +46,6 @@ Process-Global State C-level static variables. Since this is very low-level memory storage, it must be managed carefully. -.. _per-module state: - Per-module State ---------------- @@ -476,13 +474,3 @@ Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - coding: utf-8 - End: diff --git a/pep-0583.rst b/pep-0583.rst index 99dc2b8af..3a5574ffb 100644 --- a/pep-0583.rst +++ b/pep-0583.rst @@ -223,7 +223,7 @@ interface would specify that puts happen before gets, and we'd reason directly from that. -.. _hazards: +.. _PEP 583 hazards: Surprising behaviors with races =============================== @@ -657,10 +657,11 @@ than ordinary python code. If we want to get those tiers back, we could: Sequential Consistency ---------------------- -We could just adopt sequential consistency for Python. This avoids -all of the hazards_ mentioned above, but it prohibits lots of -optimizations too. As far as I know, this is the current model of -CPython, but if CPython learned to optimize out some variable reads, +We could just adopt sequential consistency for Python. +This avoids all of the `hazards `_ mentioned above, +but it prohibits lots of optimizations too. +As far as I know, this is the current model of CPython, +but if CPython learned to optimize out some variable reads, it would lose this property. If we adopt this, Jython's ``dict`` implementation may no longer be @@ -827,15 +828,3 @@ Copyright ========= This document has been placed in the public domain. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - coding: utf-8 - End: - diff --git a/pep-0612.rst b/pep-0612.rst index c9e7b5aba..a5c51d3a0 100644 --- a/pep-0612.rst +++ b/pep-0612.rst @@ -702,8 +702,6 @@ We decided to go with ``ParamSpec``\ s over this approach for several reasons: In summary, between these two equivalently powerful syntaxes, ``ParamSpec`` fits much more naturally into the status quo. -.. _Concatenating Keyword Parameters: - Concatenating Keyword Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/pep-0615.rst b/pep-0615.rst index f415c4a9a..dbac9575f 100644 --- a/pep-0615.rst +++ b/pep-0615.rst @@ -78,8 +78,6 @@ are grouped together by subject. The ``zoneinfo.ZoneInfo`` class ------------------------------- -.. _Constructors: - Constructors ############ @@ -162,7 +160,7 @@ should always be true: This is an alternate constructor that allows the construction of a ``ZoneInfo`` object from any TZif byte stream. This constructor takes an optional parameter, ``key``, which sets the name of the zone, for the purposes of -``__str__`` and ``__repr__`` (see Representations_). +``__str__`` and ``__repr__`` (see `Representations `_). Unlike the primary constructor, this always constructs a new object. There are two reasons that this deviates from the primary constructor's caching behavior: @@ -247,8 +245,6 @@ Manipulation of the cache behavior is expected to be a niche use case; this function is primarily provided to facilitate testing, and to allow users with unusual requirements to tune the cache invalidation behavior to their needs. -.. _Representations: - String representation ##################### diff --git a/pep-0622.rst b/pep-0622.rst index bf061cf62..41832b77c 100644 --- a/pep-0622.rst +++ b/pep-0622.rst @@ -77,8 +77,6 @@ Finally, we discuss some possible extensions that might be considered in the future, once the community has ample experience with the currently proposed syntax and semantics. -.. _overview: - Overview ======== @@ -313,13 +311,14 @@ Although this will work, it's not necessarily what the proposal is focused on, and the new syntax has been designed to best support the destructuring scenarios. -See the `syntax`_ sections below for a more detailed specification. +See the `syntax `_ sections below +for a more detailed specification. We propose that destructuring objects can be customized by a new special ``__match_args__`` attribute. As part of this PEP we specify the general API and its implementation for some standard library -classes (including named tuples and dataclasses). See the `runtime`_ -section below. +classes (including named tuples and dataclasses). See the `runtime +`_ section below. Finally, we aim to provide comprehensive support for static type checkers and similar tools. For this purpose, we propose to introduce @@ -327,12 +326,10 @@ a ``@typing.sealed`` class decorator that will be a no-op at runtime but will indicate to static tools that all sub-classes of this class must be defined in the same module. This will allow effective static exhaustiveness checks, and together with dataclasses, will provide -basic support for algebraic data types [2]_. See the `static checkers`_ -section for more details. +basic support for algebraic data types [2]_. See the `static checkers +`_ section for more details. -.. _syntax: - Syntax and Semantics ==================== @@ -420,15 +417,16 @@ A simplified, approximate grammar for the proposed syntax is:: | mapping_pattern | class_pattern -See `Appendix A`_ for the full, unabridged grammar. The simplified grammars in -this section are there for helping the reader, not as a full specification. +See `Appendix A `_ for the full, unabridged grammar. +The simplified grammars in this section are there for helping the reader, +not as a full specification. We propose that the match operation should be a statement, not an expression. Although in many languages it is an expression, being a statement better suits the general logic of Python syntax. See `rejected ideas`_ for more discussion. -The allowed patterns are described in detail below in the `patterns`_ -subsection. +The allowed patterns are described in detail below in the `patterns +`_ subsection. The ``match`` and ``case`` keywords are proposed to be soft keywords, so that they are recognized as keywords at the beginning of a match @@ -460,8 +458,8 @@ statements. Note that unlike for the previously proposed ``switch`` statement, the pre-computed dispatch dictionary semantics does not apply here. There is no ``default`` or ``else`` case - instead the special wildcard -``_`` can be used (see the section on `capture_pattern`_) as a final -'catch-all' pattern. +``_`` can be used (see the section on `capture_pattern `_) +as a final 'catch-all' pattern. Name bindings made during a successful pattern match outlive the executed suite and can be used after the match statement. This follows the logic of other @@ -498,8 +496,6 @@ We introduce the proposed syntax gradually. Here we start from the main building blocks. The following patterns are supported: -.. _literal_pattern: - Literal Patterns ~~~~~~~~~~~~~~~~ @@ -551,8 +547,6 @@ are supported. F-strings are not allowed (since in general they are not really literals). -.. _capture_pattern: - Capture Patterns ~~~~~~~~~~~~~~~~ @@ -599,8 +593,6 @@ as a `wildcard pattern`_. Reminder: ``None``, ``False`` and ``True`` are keywords denoting literals, not names. -.. _wildcard_pattern: - Wildcard Pattern ~~~~~~~~~~~~~~~~ @@ -619,8 +611,6 @@ matches but *never* binds:: Given that no binding is made, it can be used as many times as desired, unlike capture patterns. -.. _constant_value_pattern: - Constant Value Patterns ~~~~~~~~~~~~~~~~~~~~~~~ @@ -652,8 +642,6 @@ patterns (they always denote variables to be captured). See considered for constant value patterns. -.. _sequence_pattern: - Sequence Patterns ~~~~~~~~~~~~~~~~~ @@ -691,8 +679,6 @@ example: ``"a"`` and ends with ``"z"``. -.. _mapping_pattern: - Mapping Patterns ~~~~~~~~~~~~~~~~ @@ -735,8 +721,6 @@ on-the-fly by ``__missing__`` or ``__getitem__``. For example, were already present when the ``match`` block was entered. -.. _class_pattern: - Class Patterns ~~~~~~~~~~~~~~ @@ -766,8 +750,8 @@ example:: Whether a match succeeds or not is determined by the equivalent of an ``isinstance`` call. If the subject (``shape``, in the example) is not an instance of the named class (``Point`` or ``Rectangle``), the match -fails. Otherwise, it continues (see details in the `runtime`_ -section). +fails. Otherwise, it continues (see details in the `runtime +`_ section). The named class must inherit from ``type``. It may be a single name or a dotted name (e.g. ``some_mod.SomeClass`` or ``mod.pkg.Class``). @@ -817,8 +801,6 @@ the same set of variables (excluding ``_``). For example:: ... -.. _guards: - Guards ------ @@ -885,8 +867,6 @@ equally. The wildcard ``_`` is not a valid name here. -.. _runtime: - Runtime specification ===================== @@ -1016,8 +996,6 @@ existing standard library classes and adding ``__match_args__`` where it looks beneficial. -.. _static checkers: - Static checkers specification ============================= @@ -1354,8 +1332,6 @@ A small `collection of example code available on GitHub. -.. _rejected ideas: - Rejected Ideas ============== @@ -1932,8 +1908,6 @@ We decided not to add an ``else`` clause for several reasons. new functionality. -.. _deferred ideas: - Deferred Ideas ============== @@ -2210,7 +2184,8 @@ Version History - Drop the ``__match__`` protocol (moved to `deferred ideas`_) - Drop ``ImpossibleMatchError`` exception - Drop leading dot for loads (moved to `deferred ideas`_) - - Reworked the initial sections (everything before `syntax`_) + - Reworked the initial sections (everything before `syntax + `_) - Added an overview of all the types of patterns before the detailed description - Added simplified syntax next to the description of each pattern @@ -2260,8 +2235,6 @@ References https://jupyter.org -.. _Appendix A: - Appendix A -- Full Grammar ========================== @@ -2332,14 +2305,3 @@ Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - coding: utf-8 - End: diff --git a/pep-0633.rst b/pep-0633.rst index 1b17037e0..5e673b3c8 100644 --- a/pep-0633.rst +++ b/pep-0633.rst @@ -109,8 +109,6 @@ values can have one of the following types: - array: an array of requirement tables. It is an error to specify an empty array ``[]`` as a value. -.. _requirement-spec: - Requirement table ^^^^^^^^^^^^^^^^^ @@ -166,7 +164,7 @@ The values can have one of the following types: - array: an array of requirement tables. These requirement tables have -`the same specification as above <#requirement-spec>`_, with the addition of +`the same specification as above `_, with the addition of the following required key: - ``for-extra`` (string): the name of the :pep:`508` extra that this diff --git a/pep-0634.rst b/pep-0634.rst index 82b1ebd3c..20ff9ff50 100644 --- a/pep-0634.rst +++ b/pep-0634.rst @@ -35,7 +35,7 @@ introduction to the concepts, syntax and semantics of patterns. Syntax and Semantics ==================== -See :ref:`Appendix A <634-appendix-a>` for the complete grammar. +See `Appendix A <634-appendix-a_>`_ for the complete grammar. Overview and Terminology ------------------------ diff --git a/pep-0636.rst b/pep-0636.rst index a28f6fdb7..3f9353aac 100644 --- a/pep-0636.rst +++ b/pep-0636.rst @@ -31,7 +31,7 @@ for pattern matching) and :pep:`635` (the motivation and rationale for having pa matching and design considerations). For readers who are looking more for a quick review than for a tutorial, -see `Appendix A`_. +see `Appendix A `_. Tutorial ======== @@ -453,7 +453,7 @@ The fully rewritten version looks like this:: -.. _Appendix A: +.. _PEP 636 Appendix A: Appendix A -- Quick Intro ========================= @@ -614,13 +614,3 @@ Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - coding: utf-8 - End: diff --git a/pep-0642.rst b/pep-0642.rst index 601e7c4df..6418dfa23 100644 --- a/pep-0642.rst +++ b/pep-0642.rst @@ -274,8 +274,6 @@ attribute constraints allows the behaviour needed by those builtin types to be specified as applying to any type that sets ``__match_args__`` to ``None``) -.. _guards: - Guards ^^^^^^ @@ -312,8 +310,6 @@ Aside from that caveat, the handling of irrefutable cases is the same as in must be last. -.. _patterns: - Patterns -------- @@ -429,8 +425,6 @@ Subpatterns are mostly required to be closed patterns, but the parentheses may be omitted for value constraints. -.. _value_constraints: - Value constraints ^^^^^^^^^^^^^^^^^ @@ -555,8 +549,6 @@ The ``== (1-1j)`` example illustrates the use of parentheses to turn any subexpression into a closed one. -.. _wildcard_pattern: - Wildcard Pattern ^^^^^^^^^^^^^^^^ diff --git a/pep-0649.rst b/pep-0649.rst index 3e6840c96..ad6c64afb 100644 --- a/pep-0649.rst +++ b/pep-0649.rst @@ -416,7 +416,8 @@ Wrappers Wrappers are functions or classes that wrap user functions or classes and add functionality. Examples of this would be -:func:`dataclass`, :func:`functools.partial`, ``attrs``, and ``wrapt``. +:func:`~dataclasses.dataclass`, :func:`functools.partial`, +``attrs``, and ``wrapt``. Wrappers are a distinct subcategory of runtime annotation users. Although they do use annotations at runtime, they may or may not @@ -535,8 +536,6 @@ approach to solve the problems facing annotations users, resulting in this PEP. -.. _Implementation: - ************** Implementation ************** diff --git a/pep-0669.rst b/pep-0669.rst index e2851a871..a12c30161 100644 --- a/pep-0669.rst +++ b/pep-0669.rst @@ -90,7 +90,8 @@ For 3.12, CPython will support the following events: * INSTRUCTION -- A VM instruction is about to be executed. * JUMP -- An unconditional jump in the control flow graph is made. * BRANCH -- A conditional branch is taken (or not). -* STOP_ITERATION -- An artificial ``StopIteration`` is raised; see :ref:`669-stopiteration`. +* STOP_ITERATION -- An artificial ``StopIteration`` is raised; + see `the STOP_ITERATION event`_. More events may be added in the future. @@ -145,8 +146,6 @@ The other events that can be monitored are: * EXCEPTION_HANDLED -.. _669-stopiteration: - The STOP_ITERATION event '''''''''''''''''''''''' @@ -596,13 +595,3 @@ Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - coding: utf-8 - End: diff --git a/pep-0675.rst b/pep-0675.rst index b42808891..505b89f33 100644 --- a/pep-0675.rst +++ b/pep-0675.rst @@ -343,8 +343,8 @@ following cases: has type ``LiteralString`` if and only if ``s`` and the arguments have types compatible with ``LiteralString``. -+ Literal-preserving methods: In `Appendix C `_, we have - provided an exhaustive list of ``str`` methods that preserve the ++ Literal-preserving methods: In `Appendix C `_, + we have provided an exhaustive list of ``str`` methods that preserve the ``LiteralString`` type. In all other cases, if one or more of the composed values has a @@ -1008,7 +1008,7 @@ is documentation, which is easily ignored and often not seen. With ``LiteralString``, API misuse requires conscious thought and artifacts in the code that reviewers and future developers can notice. -.. _appendix_C: +.. _PEP 675 Appendix C: Appendix C: ``str`` methods that preserve ``LiteralString`` =========================================================== @@ -1309,13 +1309,3 @@ Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - coding: utf-8 - End: diff --git a/pep-0680.rst b/pep-0680.rst index 235c94bdb..97e250d15 100644 --- a/pep-0680.rst +++ b/pep-0680.rst @@ -224,7 +224,8 @@ Several potential alternative implementations exist: API is more complex than that of ``tomli``. It allows customising output style through a complicated encoder API, and some very limited and mostly unused functionality to preserve input style through an undocumented decoder API. - For more details on its API differences from this PEP, refer to `Appendix A`_. + For more details on its API differences from this PEP, refer to `Appendix A + `_. * ``pytomlpp`` is a Python wrapper for the C++ project ``toml++``. Pure Python libraries are easier to maintain than extension modules. @@ -360,8 +361,8 @@ However, the ``toml`` package on PyPI is widely used, so there are backward compatibility concerns. Since the standard library takes precedence over third party packages, libraries and applications who current depend on the ``toml`` package would likely break when upgrading Python versions due to the many -API incompatibilities listed in `Appendix A`_, even if they pin their -dependency versions. +API incompatibilities listed in `Appendix A `_, +even if they pin their dependency versions. To further clarify, applications with pinned dependencies are of greatest concern here. Even if we were able to obtain control of the ``toml`` PyPI @@ -406,7 +407,7 @@ Previous Discussion `_ -.. _Appendix A: +.. _PEP 680 Appendix A: Appendix A: Differences between proposed API and ``toml`` ========================================================= @@ -528,14 +529,3 @@ Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - coding: utf-8 - End: diff --git a/pep-0689.rst b/pep-0689.rst index 89d5bb01e..01cf6f269 100644 --- a/pep-0689.rst +++ b/pep-0689.rst @@ -142,7 +142,7 @@ Several rules for dealing with the unstable tier will be introduced: - Any API introduced before Python 3.12 that was named with a leading underscore. - For examples, see the :ref:`initial unstable API ` + For examples, see the `initial unstable API`_ specified in this PEP. - To move an *internal* API to the unstable tier, it should be @@ -199,8 +199,6 @@ a CPython issue to request exposing public API for their use case, and eventually switching to that. -.. _pep689-initial-list: - Initial unstable API -------------------- diff --git a/pep-0692.rst b/pep-0692.rst index ef4da7bae..bb12250eb 100644 --- a/pep-0692.rst +++ b/pep-0692.rst @@ -25,8 +25,6 @@ precise ``**kwargs`` typing. The new approach revolves around using ``TypedDict`` to type ``**kwargs`` that comprise keyword arguments of different types. -.. _pep-692-motivation: - Motivation ========== @@ -55,7 +53,7 @@ are of different types. In addition, even if the keyword arguments are of the same type, there is no way to check whether the function is being called with keyword names that it actually expects. -As described in the :ref:`Intended Usage ` section, +As described in the `Intended Usage`_ section, using ``**kwargs`` is not always the best tool for the job. Despite that, it is still a widely used pattern. As a consequence, there has been a lot of discussion around supporting more precise ``**kwargs`` typing and it became a @@ -70,8 +68,6 @@ that are usually used as defaults to indicate no user input, such as ``None``, can be passed in by a user and should result in a valid, non-default behavior. For example, this issue `came up `__ in the popular ``httpx`` library. -.. _pep-692-rationale: - Rationale ========= @@ -224,7 +220,7 @@ compatible:: accept_animal = accept_dog # WRONG! Expression of type Animal # cannot be assigned to a variable of type Dog. -.. _pep-692-assignment-dest-no-kwargs: +.. _PEP 692 assignment dest no kwargs: Source contains ``**kwargs`` and destination doesn't ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -329,7 +325,7 @@ return types should behave covariantly. Passing kwargs inside a function to another function ---------------------------------------------------- -:ref:`A previous point ` +`A previous point `_ mentions the problem of possibly passing additional keyword arguments by assigning a subclass instance to a variable that has a base class type. Let's consider the following example:: @@ -390,7 +386,7 @@ to perform the function call:: Using ``Unpack`` with types other than ``TypedDict`` ---------------------------------------------------- -As described in the :ref:`Rationale ` section, +As described in the Rationale_ section, ``TypedDict`` is the most natural candidate for typing ``**kwargs``. Therefore, in the context of typing ``**kwargs``, using ``Unpack`` with types other than ``TypedDict`` should not be allowed and type checkers should @@ -408,12 +404,10 @@ typing is interchangeable with using the asterisk syntax:: Therefore, in order to be compatible with the new use case, ``Unpack``'s ``repr`` should be changed to simply ``Unpack[T]``. -.. _pep-692-intended-usage: - Intended Usage ============== The intended use cases for this proposal are described in the -:ref:`pep-692-motivation` section. In summary, more precise ``**kwargs`` typing +Motivation_ section. In summary, more precise ``**kwargs`` typing can bring benefits to already existing codebases that decided to use ``**kwargs`` initially, but now are mature enough to use a stricter contract via type hints. Using ``**kwargs`` can also help in reducing code duplication diff --git a/pep-0695.rst b/pep-0695.rst index b9b415bcf..4ecada5a0 100644 --- a/pep-0695.rst +++ b/pep-0695.rst @@ -308,7 +308,7 @@ Runtime Representation of Bounds and Constraints The upper bounds and constraints of ``TypeVar`` objects are accessible at runtime through the ``__bound__`` and ``__constraints__`` attributes. For ``TypeVar`` objects defined through the new syntax, these attributes -become lazily evaluated, as discussed under :ref:`695-lazy-evaluation` below. +become lazily evaluated, as discussed under `Lazy Evaluation`_ below. Generic Type Alias @@ -379,7 +379,7 @@ include: All of these attributes are read-only. -The value of the type alias is evaluated lazily (see :ref:`695-lazy-evaluation` below). +The value of the type alias is evaluated lazily (see `Lazy Evaluation`_ below). Type Parameter Scopes @@ -390,7 +390,7 @@ includes the type parameters. Type parameters can be accessed by name within inner scopes. As with other symbols in Python, an inner scope can define its own symbol that overrides an outer-scope symbol of the same name. This section provides a verbal description of the new scoping rules. -The :ref:`695-scoping-behavior` section below specifies the behavior in terms +The `Scoping Behavior`_ section below specifies the behavior in terms of a translation to near-equivalent existing Python code. Type parameters are visible to other @@ -825,8 +825,6 @@ and ``ClassDef`` to include an additional optional attribute called ``typeparams`` that includes a list of type parameters associated with the function or class. -.. _695-lazy-evaluation: - Lazy Evaluation --------------- diff --git a/pep-0696.rst b/pep-0696.rst index b3644b08f..ce1678adc 100644 --- a/pep-0696.rst +++ b/pep-0696.rst @@ -146,7 +146,7 @@ future, this might be possible (see `Interaction with PEP ``ParamSpec`` defaults are defined using the same syntax as ``TypeVar`` \ s but use a ``list`` of types or an ellipsis -literal "``...``" or another in-scope ``ParamSpec`` (see :ref:`696-scoping-rules`). +literal "``...``" or another in-scope ``ParamSpec`` (see `Scoping Rules`_). .. code-block:: py @@ -163,7 +163,7 @@ literal "``...``" or another in-scope ``ParamSpec`` (see :ref:`696-scoping-rules ``TypeVarTuple`` defaults are defined using the same syntax as ``TypeVar`` \ s but use an unpacked tuple of types instead of a single type -or another in-scope ``TypeVarTuple`` (see :ref:`696-scoping-rules`). +or another in-scope ``TypeVarTuple`` (see `Scoping Rules`_). .. code-block:: py @@ -217,7 +217,7 @@ Where ``T1`` is the default for ``T2`` the following rules apply. ``TypeVarTuple``\s are not supported because: -- :ref:`696-scoping-rules` does not allow usage of ``TypeVarLikes`` +- `Scoping Rules`_ does not allow usage of ``TypeVarLikes`` from outer scopes. - Multiple ``TypeVarTuple``\s cannot appear in the type parameter list for a single class, as specified in @@ -227,8 +227,6 @@ Where ``T1`` is the default for ``T2`` the following rules apply. These reasons leave no current valid location where a ``TypeVarTuple`` could have a default. -.. _696-scoping-rules: - Scoping Rules ~~~~~~~~~~~~~ @@ -281,7 +279,7 @@ The constraints of ``T2`` must be a superset of the constraints of ``T1``. ``TypeVarLike``\ s are valid as parameters to generics inside of a ``default`` when the first parameter is in scope as determined by the -:ref:`previous section <696-scoping-rules>`. +`previous section `_. .. code-block:: py @@ -549,7 +547,7 @@ Allowing ``TypeVarLike``\s with defaults to be used in function signatures A previous version of this PEP allowed ``TypeVarLike``\s with defaults to be used in function signatures. This was removed for the reasons described in -:ref:`696-function-defaults`. Hopefully, this can be added in the future if +`Function Defaults`_. Hopefully, this can be added in the future if a way to get the runtime value of a type parameter is added. Allowing ``TypeVarLikes`` from outer scopes in ``default`` diff --git a/pep-0697.rst b/pep-0697.rst index 342745294..b44300cca 100644 --- a/pep-0697.rst +++ b/pep-0697.rst @@ -15,7 +15,7 @@ Resolution: https://discuss.python.org/t/19743/30 .. canonical-doc:: :external+py3.12:c:member:`PyType_Spec.basicsize`, :external+py3.12:c:func:`PyObject_GetTypeData`, - :external+py3.12:data:`Py_TPFLAGS_ITEMS_AT_END`, + :external+py3.12:c:macro:`Py_TPFLAGS_ITEMS_AT_END`, :external+py3.12:c:macro:`Py_RELATIVE_OFFSET`, :external+py3.12:c:func:`PyObject_GetItemData` @@ -116,7 +116,8 @@ However, this has disadvantages: use ``PyObject_GetAttrString(obj, "__basicsize__")``. This is cumbersome, and unsafe in edge cases (the Python attribute can be overridden). -* Variable-size objects are not handled (see :ref:`697-var-sized` below). +* Variable-size objects are not handled + (see `Extending variable-size objects`_ below). To make this easy (and even *best practice* for projects that choose loose coupling over maximum performance), this PEP proposes an API to: @@ -147,8 +148,6 @@ The ``tp_basicsize`` of the new class will be set to the computed total size, so code that inspects classes will continue working as before. -.. _697-var-sized: - Extending variable-size objects ------------------------------- @@ -250,7 +249,7 @@ big-picture decision tree. .. note:: The individual cases are easier to explain in isolation (see the - :ref:`reference implementation <697-ref-impl>` for draft docs). + `reference implementation `_ for draft docs). * ``spec->basicsize > 0``: No change to the status quo. (The base class layout is known.) @@ -399,7 +398,7 @@ This function will initially *not* be added to the Limited API. Extending a class with positive ``base->itemsize`` using negative ``spec->basicsize`` will fail unless ``Py_TPFLAGS_ITEMS_AT_END`` is set, either on the base or in ``spec->flags``. -(See :ref:`697-var-sized` for a full explanation.) +(See `Extending variable-size objects`_ for a full explanation.) Extending a class with positive ``spec->itemsize`` using negative ``spec->basicsize`` will fail. @@ -478,7 +477,7 @@ and `has been verifying the implementation `__ that the API looks good in general. -(See :ref:`below <697-alignment-performance>` for a possible solution to +(See `below `_ for a possible solution to performance concerns.) @@ -490,8 +489,6 @@ and a What's New entry, which should be enough for the target audience -- authors of C extension libraries. -.. _697-ref-impl: - Reference Implementation ======================== @@ -502,8 +499,6 @@ in the ``encukou/cpython`` GitHub repo. Possible Future Enhancements ============================ -.. _697-alignment-performance: - Alignment & Performance ----------------------- @@ -529,8 +524,8 @@ Other layouts for variable-size types ------------------------------------- A flag like ``Py_TPFLAGS_ITEMS_AT_END`` could be added to signal the -“tuple-like” layout described in :ref:`697-var-sized`, and all mechanisms -this PEP proposes could be adapted to support it. +“tuple-like” layout described in `Extending variable-size objects`_, +and all mechanisms this PEP proposes could be adapted to support it. Other layouts could be added as well. However, it seems there'd be very little practical benefit, so it's just a theoretical possibility. diff --git a/pep-0701.rst b/pep-0701.rst index c7bd90c69..f4b393d0b 100644 --- a/pep-0701.rst +++ b/pep-0701.rst @@ -100,7 +100,7 @@ these tokens. This has the following problems: #. Other Python implementations have no way to know if they have implemented f-strings correctly because contrary to other language features, they are not - part of the :ref:`official Python grammar `. + part of the :ref:`official Python grammar `. This is important because several prominent alternative implementations are using CPython's PEG parser, `such as PyPy`_, and/or are basing their grammars on the official PEG grammar. The @@ -147,7 +147,7 @@ f-string literals (as well as the Python language in general). >>> f"{f"{f"infinite"}"}" + " " + f"{f"nesting!!!"}" This "feature" is not universally agreed to be desirable, and some users find this unreadable. - For a discussion on the different views on this, see the :ref:`701-considerations-of-quote-reuse` section. + For a discussion on the different views on this, see the `considerations regarding quote reuse`_ section. #. Another issue that has felt unintuitive to most is the lack of support for backslashes within the expression component of an f-string. One example that keeps coming up is including @@ -226,7 +226,7 @@ for details on the syntax): | fstring_replacement_field The new tokens (``FSTRING_START``, ``FSTRING_MIDDLE``, ``FSTRING_END``) are defined -:ref:`later in this document <701-new-tokens>`. +`later in this document `_. This PEP leaves up to the implementation the level of f-string nesting allowed (f-strings within the expression parts of other f-strings) but **specifies a @@ -286,8 +286,6 @@ and not just the associated tokens. How parser/lexer implementations deal with this problem is of course up to the implementation. -.. _701-new-tokens: - New tokens ---------- @@ -344,8 +342,6 @@ while ``f"""some words"""`` will be tokenized simply as:: FSTRING_MIDDLE - 'some words' FSTRING_END - '"""' -.. _701-tokenize-changes: - Changes to the tokenize module ------------------------------ @@ -517,7 +513,7 @@ Backwards Compatibility This PEP does not introduce any backwards incompatible syntactic or semantic changes to the Python language. However, the :mod:`tokenize` module (a quasi-public part of the standard library) will need to be updated to support the new f-string tokens (to allow tool authors -to correctly tokenize f-strings). See :ref:`701-tokenize-changes` for more details regarding +to correctly tokenize f-strings). See `changes to the tokenize module`_ for more details regarding how the public API of ``tokenize`` will be affected. How to Teach This diff --git a/pep-0704.rst b/pep-0704.rst index a1607e307..18cb4f342 100644 --- a/pep-0704.rst +++ b/pep-0704.rst @@ -61,7 +61,7 @@ When a user runs an installer without an active virtual environment, the install The error message SHOULD inform the user that a virtual environment is required, SHOULD provide shell-specific instructions on how to create and activate a virtual environment named ``.venv``, and SHOULD provide a link to a documentation page that explains how to create and activate a virtual environment. -See :ref:`704-implementation` for more details. +See `Implementation Notes`_ for more details. Opting out of virtual environments ---------------------------------- @@ -105,8 +105,6 @@ Reference Implementation There is no reference implementation for this PEP. However, the proposed behaviour is largely already implemented in ``pip`` and can be activated by setting the ``PIP_REQUIRE_VENV`` environment variable to ``1``. (Leaving it unset results in the proposed opt-in behaviour of not requiring a virtual environment for installation.) -.. _704-implementation: - Implementation Notes ==================== diff --git a/pep-0710.rst b/pep-0710.rst index 100f46b3a..512ef56e6 100644 --- a/pep-0710.rst +++ b/pep-0710.rst @@ -175,7 +175,7 @@ Backwards Compatibility Following the :ref:`packaging:recording-installed-packages` specification, installers may keep additional installer-specific files in the ``.dist-info`` directory. To make sure this PEP does not cause any backwards compatibility -issues, a :ref:`comprehensive survey of installers and libraries <710-tool-survey>` +issues, a `comprehensive survey of installers and libraries <710-tool-survey_>`_ found no current tools that are using a similarly-named file, or other major feasibility concerns. @@ -191,14 +191,14 @@ managers in the Python ecosystem analyzed the implications of adding support for ``provenance_url.json`` to each tool. In summary, no major backwards compatibility issues, conflicts or feasibility blockers were found as of the time of writing of this PEP. More details about the survey -can be found in the :ref:`710-tool-survey` section. +can be found in the `Appendix: Survey of installers and libraries`_ section. Compatibility with direct_url.json ---------------------------------- This proposal does not make any changes to the ``direct_url.json`` file described in :pep:`610` and :ref:`its corresponding canonical PyPA spec -`. +`. The content of ``provenance_url.json`` file was designed in a way to eventually allow installers reuse some of the logic supporting ``direct_url.json`` when a @@ -402,8 +402,8 @@ issues for already existing ``direct_url.json`` consumers. Keeping the hash key in the archive_info dictionary --------------------------------------------------- -:pep:`610` and :ref:`its corresponding canonical PyPA spec ` discuss -the possibility to include the ``hash`` key alongside the ``hashes`` key in the +:pep:`610` and :ref:`its corresponding canonical PyPA spec ` +discuss the possibility to include the ``hash`` key alongside the ``hashes`` key in the ``archive_info`` dictionary. This PEP explicitly does not include the ``hash`` key in the ``provenance_url.json`` file and allows only the ``hashes`` key to be present. By doing so we eliminate possible redundancy in the file, possible confusion, @@ -413,7 +413,7 @@ sync. Making the hashes key optional ------------------------------ -:pep:`610` and :ref:`its corresponding canonical PyPA spec ` +:pep:`610` and :ref:`its corresponding canonical PyPA spec ` recommend including the ``hashes`` key of the ``archive_info`` in the ``direct_url.json`` file but it is not required (per the :rfc:`2119` language): diff --git a/pep-0720.rst b/pep-0720.rst index 2ce440eab..87c00ae7c 100644 --- a/pep-0720.rst +++ b/pep-0720.rst @@ -50,8 +50,8 @@ with cross-compilation, but it's unofficial and at a best-effort basis. For example, the ``sysconfig`` module allows overwriting the data module name via the ``_PYTHON_SYSCONFIGDATA_NAME`` environment variable, something that is required for cross-builds, and setuptools `accepts patches`__ [1]_ to tweak/fix -its logic to be compatible with popular -:ref:`"environment faking" ` workflows [2]_. +its logic to be compatible with popular `"environment faking" +`_ workflows [2]_. The lack of first-party support in upstream projects leads to cross-compilation being fragile and requiring a significant effort from users, but at the same @@ -92,9 +92,8 @@ Downstream approaches Cross-compilation approaches fall in a spectrum that goes from, by design, requiring extensive user interaction to (ideally) almost none. Usually, they'll -be based on one of two main strategies, using a -:ref:`cross-build environment `, or -:ref:`faking the target environment `. +be based on one of two main strategies, using a `cross-build environment`_, +or `faking the target environment`_. .. _approach-cross-environment: @@ -113,7 +112,7 @@ of user interaction. .. admonition:: Examples :class: note - :ref:`python-for-android`, :ref:`kivy-ios`, etc. + `python-for-android`_, `kivy-ios`_, etc. .. [3] The scope of the build-system patching varies between users and usually depends on the their goal — some (eg. Linux distributions) may patch the @@ -121,8 +120,6 @@ of user interaction. compiler paths and system information in the build-system, to simply make the build work. -.. _approach-target-environment: - Faking the target environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -150,7 +147,7 @@ though it doesn't succeed in being generic. .. admonition:: Examples :class: note - :ref:`crossenv`, :ref:`conda-forge`, etc. + `crossenv`_, `conda-forge`_, etc. Environment introspection @@ -481,7 +478,7 @@ build systems. - This is implementation-defined, but it **usually** differs between non-identical builds. Please refer to the - :ref:`env-sysconfig-config-vars` table for a overview of the different + `sysconfig configuration variables`_ table for a overview of the different configuration variable that are usually present. .. [4] Ideally, you want to perform cross-builds with the same Python version @@ -511,9 +508,8 @@ CPython (and similar) ~~~~~~~~~~~~~~~~~~~~~ -.. _env-sysconfig-config-vars: - .. list-table:: ``sysconfig`` configuration variables + :name: sysconfig configuration variables :header-rows: 1 :widths: 20 20 30 30 @@ -753,8 +749,6 @@ Case studies ============ -.. _crossenv: - crossenv -------- @@ -764,11 +758,9 @@ crossenv ``crossenv`` is a tool to create a virtual environment with a monkeypatched Python installation that tries to emulate the target machine in certain scenarios. More about this approach can be found in the -:ref:`approach-target-environment` section. +`Faking the target environment`_ section. -.. _conda-forge: - conda-forge ----------- @@ -833,8 +825,6 @@ Beeware TODO -.. _python-for-android: - python-for-android ------------------ @@ -855,8 +845,6 @@ recipes for any other native dependencies. .. __: https://github.com/kivy/python-for-android/tree/develop/pythonforandroid/recipes -.. _kivy-ios: - kivy-ios -------- @@ -867,7 +855,7 @@ kivy-ios build a Python distribution with your app and its dependencies, as well as a CLI to create and manage Xcode projects that integrate with the toolchain. -It uses the same approach as :ref:`python-for-android` (also maintained by the +It uses the same approach as `python-for-android`_ (also maintained by the `Kivy project`__) for app dependencies — pure-Python dependencies are handled automatically, but native dependencies need recipes__, and the project provides recipes for `popular dependencies`__. diff --git a/pep-3151.txt b/pep-3151.txt index 749780bcc..21af2cd5f 100644 --- a/pep-3151.txt +++ b/pep-3151.txt @@ -99,8 +99,8 @@ exception specifics has to examine the ``errno`` or ``winerror`` attribute anyway. .. note:: - `Appendix B`_ surveys the use of the various exception types across - the interpreter and the standard library. + `Appendix B `_ surveys the use of the + various exception types across the interpreter and the standard library. Lack of fine-grained exceptions @@ -180,9 +180,9 @@ unconnected socket (ditto), a socket timeout, a file type mismatch, an invalid argument, a transmission failure, insufficient permissions, a non-existent directory, a full filesystem, etc. -(moreover, the use of certain of these exceptions is irregular; `Appendix B`_ -exposes the case of the `select`_ module, which raises different exceptions -depending on the implementation) +(moreover, the use of certain of these exceptions is irregular; `Appendix B +`_ exposes the case of the `select`_ module, +which raises different exceptions depending on the implementation) *Careful* code is defined as code which, when catching any of the above exceptions, examines the ``errno`` attribute to determine the actual error @@ -264,8 +264,8 @@ The rationale for keeping ``OSError`` as the official name for generic OS-related exceptions is that it, precisely, is more generic than ``IOError``. ``EnvironmentError`` is more tedious to type and also much lesser-known. -The survey in `Appendix B`_ shows that IOError is the dominant -error today in the standard library. As for third-party Python code, +The survey in `Appendix B `_ shows that IOError is the +dominant error today in the standard library. As for third-party Python code, Google Code Search shows IOError being ten times more popular than EnvironmentError in user code, and three times more popular than OSError [3]_. However, with no intention to deprecate IOError in the middle @@ -323,10 +323,10 @@ Step 2: define additional subclasses The second step of the resolution is to extend the hierarchy by defining subclasses which will be raised, rather than their parent, for specific errno values. Which errno values is subject to discussion, but a survey -of existing exception matching practices (see `Appendix A`_) helps us -propose a reasonable subset of all values. Trying to map all errno -mnemonics, indeed, seems foolish, pointless, and would pollute the root -namespace. +of existing exception matching practices (see `Appendix A +`_) helps us propose a reasonable subset of all values. +Trying to map all errno mnemonics, indeed, seems foolish, pointless, +and would pollute the root namespace. Furthermore, in a couple of cases, different errno values could raise the same exception subclass. For example, EAGAIN, EALREADY, EWOULDBLOCK @@ -586,7 +586,7 @@ While they would deserve less cryptic names, this can be handled separately from the exception hierarchy reorganization effort. -.. _Appendix A: +.. _PEP 3151 Appendix A: Appendix A: Survey of common errnos =================================== @@ -669,7 +669,7 @@ Common errnos with select.error * ``EINTR``: interrupted function call -.. _Appendix B: +.. _PEP 3151 Appendix B: Appendix B: Survey of raised OS and IO errors ============================================= @@ -958,14 +958,3 @@ Copyright ========= This document has been placed in the public domain. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - coding: utf-8 - End: