diff --git a/pep-0012.rst b/pep-0012.rst index d2dd1257b..36758bb80 100644 --- a/pep-0012.rst +++ b/pep-0012.rst @@ -155,7 +155,7 @@ directions below. For reference, here are all of the possible header fields (everything in brackets should either be replaced or have the field removed if -it has a leading `*` marking it as optional and it does not apply to +it has a leading ``*`` marking it as optional and it does not apply to your PEP):: PEP: [NNN] diff --git a/pep-0548.rst b/pep-0548.rst index 673a63804..ef76cb4dc 100644 --- a/pep-0548.rst +++ b/pep-0548.rst @@ -79,8 +79,8 @@ Semantics A ``break if`` or ``continue if`` is executed if and only if ``expression`` evaluates to true. -A `while` statement with no expression loops until a break or return -is executed (or an error is raised), as if it were a `'while True`` +A ``while`` statement with no expression loops until a break or return +is executed (or an error is raised), as if it were a ``while True`` statement. Given that the loop can never terminate except in a way that would not cause an ``else`` suite to execute, no ``else`` suite is allowed in the expressionless form. If practical, it diff --git a/pep-0554.rst b/pep-0554.rst index a7377f0ef..f50f0032d 100644 --- a/pep-0554.rst +++ b/pep-0554.rst @@ -1014,7 +1014,7 @@ the following: A separate page will be added to the docs for resources to help extension maintainers ensure their modules can be used safely in -subinterpreters, under `Extending Python `. The page +subinterpreters, under `Extending Python `_. The page will include the following information: * a summary about subinterpreters (similar to the same in the new @@ -1262,7 +1262,7 @@ With the proposed object passing machanism of "channels", other similar basic types aren't required to achieve the minimal useful functionality of subinterpreters. Such types include pipes (like unbuffered channels, but one-to-one) and queues (like channels, but more generic). See below -in `Rejected Ideas` for more information. +in `Rejected Ideas`_ for more information. Even though these types aren't part of this proposal, they may still be useful in the context of concurrency. Adding them later is entirely diff --git a/pep-0565.rst b/pep-0565.rst index cd243c4b5..11aaf70e4 100644 --- a/pep-0565.rst +++ b/pep-0565.rst @@ -242,7 +242,7 @@ The intent was to avoid cases of tooling output like the following:: async = True ... actual tool output ... -Even when `devtool` is a tool specifically for Python programmers, this is not +Even when ``devtool`` is a tool specifically for Python programmers, this is not a particularly useful warning, as it will be shown on every invocation, even though the main helpful step an end user can take is to report a bug to the developers of ``devtool``. diff --git a/pep-0572.rst b/pep-0572.rst index 2c59851e9..c5cad1bdf 100644 --- a/pep-0572.rst +++ b/pep-0572.rst @@ -790,7 +790,7 @@ statements to add a means of capturing the compared value:: This works beautifully if and ONLY if the desired condition is based on the truthiness of the captured value. It is thus effective for specific -use-cases (regex matches, socket reads that return `''` when done), and +use-cases (regex matches, socket reads that return ``''`` when done), and completely useless in more complicated cases (e.g. where the condition is ``f(x) < 0`` and you want to capture the value of ``f(x)``). It also has no benefit to list comprehensions. diff --git a/pep-0573.rst b/pep-0573.rst index 37a86fe16..20d5fb6e1 100644 --- a/pep-0573.rst +++ b/pep-0573.rst @@ -88,7 +88,7 @@ For example, ``int`` is the defining class of ``True.to_bytes``, In C, the defining class is the one defined with the corresponding ``tp_methods`` or "tp slots" [#tp-slots]_ entry. For methods defined in Python, the defining class is saved in the -`__class__` closure cell. +``__class__`` closure cell. C-API diff --git a/pep-0575.rst b/pep-0575.rst index 92d6e061f..474d3e9f3 100644 --- a/pep-0575.rst +++ b/pep-0575.rst @@ -187,7 +187,7 @@ cfunction This is the new version of the old ``builtin_function_or_method`` class. The name ``cfunction`` was chosen to avoid confusion with "built-in" in the sense of "something in the ``builtins`` module". -It also fits better with the C API which use the `PyCFunction`` prefix. +It also fits better with the C API which use the ``PyCFunction`` prefix. The class ``cfunction`` is a copy of ``base_function``, with the following differences: diff --git a/pep-0588.rst b/pep-0588.rst index 54a7f2249..04872719a 100644 --- a/pep-0588.rst +++ b/pep-0588.rst @@ -221,7 +221,7 @@ for issues related to their area of interest and expertise. To help with this situation, we can develop a bot that can notify people whenever an issue has been categorized using labels. For example, when an issue -was labeled with `area-windows`, the windows experts can be notified. +was labeled with ``area-windows``, the windows experts can be notified. The notification can be in the form of email notification, or @-mention on GitHub. Open issues diff --git a/pep-0591.rst b/pep-0591.rst index f0f5fc17a..8c1997ed2 100644 --- a/pep-0591.rst +++ b/pep-0591.rst @@ -243,7 +243,7 @@ following should be allowed:: Reference Implementation ======================== -The mypy [#mypy]_ type checker supports `Final` and `final`. A +The mypy [#mypy]_ type checker supports ``Final`` and ``final``. A reference implementation of the runtime component is provided in the ``typing_extensions`` [#typing_extensions]_ module. diff --git a/pep-0595.rst b/pep-0595.rst index 30f639938..bfb964944 100644 --- a/pep-0595.rst +++ b/pep-0595.rst @@ -346,11 +346,11 @@ need to be addressed regardless of the approach used: Setting up a redirect for each migrated issue on bpo might mitigate the issue, however -- if references in migrated messages are not updated -- it will cause confusion (e.g. if bpo issue - `#1234` becomes GitHub issue `#4321`, a reference to `#1234` - in a migrated message could link to bpo `#1234` and bpo can - redirect to GitHub issue `#4321`, but new references to `#1234` - will link to GitHub PR `#1234` rather than GitHub issue `#4321`). - Manually having to specify a `bpo-` or `gh-` prefix is error prone. + ``#1234`` becomes GitHub issue ``#4321``, a reference to ``#1234`` + in a migrated message could link to bpo ``#1234`` and bpo can + redirect to GitHub issue ``#4321``, but new references to ``#1234`` + will link to GitHub PR ``#1234`` rather than GitHub issue ``#4321``). + Manually having to specify a ``bpo-`` or ``gh-`` prefix is error prone. * **External issue links preservation.** A number of websites, mails, etc. link to bpo issues. If bpo is shut down, these links @@ -371,9 +371,9 @@ need to be addressed regardless of the approach used: Since Roundup converts references to links when messages are requested, it is possible to update the target and generate the correct link. This need already arose several times, for - example: files and HG changesets moved from `hg.python.org` to - GitHub and the devguide moved from `docs.python.org/devguide` to - `devguide.python.org`. + example: files and HG changesets moved from ``hg.python.org`` to + GitHub and the devguide moved from ``docs.python.org/devguide`` to + ``devguide.python.org``. Since messages on GitHub are static, the links will need to be generated and hardcoded during the migration or they will be lost. @@ -423,7 +423,7 @@ need to be addressed regardless of the approach used: * **bpo-related MLs.** There are currently two mailing lists where bpo posts new tracker issues and all messages respectively: - `new-bugs-announce` [#]_ and `python-bugs-list` [#]_. A new system + ``new-bugs-announce`` [#]_ and ``python-bugs-list`` [#]_. A new system will need to be developed to preserve this functionality. These MLs offer additional ways to keep track of the tracker activity. diff --git a/pep-0605.rst b/pep-0605.rst index fa221b83b..f0cb78f83 100644 --- a/pep-0605.rst +++ b/pep-0605.rst @@ -550,7 +550,7 @@ This PEP proposes that the policy for beta releases be set as follows: * as with current beta releases, the release manager is expected to review open release blocker issues prior to preparation and publication of the beta release -* as with current beta releases, any additions to the `abi3` stable C ABI would +* as with current beta releases, any additions to the ``abi3`` stable C ABI would be expected to become a permanent part of that ABI unless and until that stable ABI version is retired completely (Note: there are no current plans to increment the stable ABI version) diff --git a/pep-0610.rst b/pep-0610.rst index 935e8c394..6e484542c 100644 --- a/pep-0610.rst +++ b/pep-0610.rst @@ -267,8 +267,8 @@ MUST be present as a dictionary with the following key: When ``url`` refers to a local directory, the ``dir_info`` key MUST be present as a dictionary with the following key: -- ``editable`` (type: ``boolean``): `true` if the distribution was installed - in editable mode, `false` otherwise. If absent, default to `false`. +- ``editable`` (type: ``boolean``): ``true`` if the distribution was installed + in editable mode, ``false`` otherwise. If absent, default to ``false``. When ``url`` refers to a local directory, it MUST have the ``file`` sheme and be compliant with `RFC 8089`_. In particular, the path component must diff --git a/pep-0613.rst b/pep-0613.rst index 45430ff8f..f11c56259 100644 --- a/pep-0613.rst +++ b/pep-0613.rst @@ -38,7 +38,7 @@ diagnosis of malformed type aliases downstream. The following examples each include an illustration of some of the suboptimal or confusing behaviors resulting from existing implicit alias declarations. -We also introduce explicit aliases of the format :code:`TypeName: TypeAlias = Expression` +We also introduce explicit aliases of the format ``TypeName: TypeAlias = Expression`` here for the sake of comparison, but the syntax is discussed in further detail in later sections. @@ -50,10 +50,10 @@ Forward References: MyType = "ClassName" def foo() -> MyType: ... -This code snippet should not error so long as :code:`ClassName` is defined +This code snippet should not error so long as ``ClassName`` is defined later on. However, a type checker is forced to assume that MyType is a value assignment rather than a type alias, and therefore may throw spurious errors -that (1) :code:`MyType` is an unannotated global string, and (2) :code:`MyType` +that (1) ``MyType`` is an unannotated global string, and (2) ``MyType`` cannot be used as a return annotation because it is not a valid type. :: @@ -62,7 +62,7 @@ cannot be used as a return annotation because it is not a valid type. def foo() -> MyType: ... Explicit aliases remove ambiguity so neither of the above errors will be -thrown. Additionally, if something is wrong with :code:`ClassName` +thrown. Additionally, if something is wrong with ``ClassName`` (i.e., it’s not actually defined later), the type checker can throw an error. @@ -74,11 +74,11 @@ Error Messaging: MyType1 = InvalidType MyType2 = MyGeneric(int) # i.e., intention was MyGeneric[int] -A type checker should warn on this code snippet that :code:`InvalidType` is not +A type checker should warn on this code snippet that ``InvalidType`` is not a valid type, and therefore cannot be used to annotate an expression or to construct a type alias. Instead, type checkers are forced to throw spurious -errors that (1) :code:`MyType` is a global expression missing an annotation, -and (2) :code:`MyType` is not a valid type in all usages of :code:`MyType` +errors that (1) ``MyType`` is a global expression missing an annotation, +and (2) ``MyType`` is not a valid type in all usages of ``MyType`` across the codebase. :: @@ -87,9 +87,9 @@ across the codebase. MyType2: TypeAlias = MyGeneric(int) With explicit aliases, the type checker has enough information to error on the -actual definition of the bad type alias, and explain why: that :code:`MyGeneric(int)` -and `InvalidType` are not valid types. When the value expression is no longer -evaluated as a global value, unactionable type errors on all usages of :code:`MyType` +actual definition of the bad type alias, and explain why: that ``MyGeneric(int)`` +and ``InvalidType`` are not valid types. When the value expression is no longer +evaluated as a global value, unactionable type errors on all usages of ``MyType`` across the codebase can be suppressed. Scope Restrictions: @@ -101,8 +101,8 @@ Scope Restrictions: def foo() -> None: x = ClassName -The outer :code:`x` is a valid type alias, but type checkers must error if the -inner :code:`x` is ever used as a type because type aliases cannot be defined +The outer ``x`` is a valid type alias, but type checkers must error if the +inner ``x`` is ever used as a type because type aliases cannot be defined inside a nested scope. This is confusing because the alias declaration rule is not explicit, and because a type error will not be thrown on the location of the inner type alias declaration @@ -158,7 +158,7 @@ Explicit syntax: Note: The examples above illustrate implicit and explicit alias declarations in isolation. For the sake of backwards compatibility, type checkers should support -both simultaneously, meaning an untyped global expression :code:`x = int` will +both simultaneously, meaning an untyped global expression ``x = int`` will still be considered a valid type alias. @@ -192,11 +192,11 @@ This looks a lot like an uninitialized variable. MyType = TypeAlias[int] Along with the option above, this format potentially adds confusion around -what the runtime value of :code:`MyType` is. +what the runtime value of ``MyType`` is. -In comparison, the chosen syntax option :code:`MyType: TypeAlias = int` is -appealing because it still sticks with the :code:`MyType = int` assignment +In comparison, the chosen syntax option ``MyType: TypeAlias = int`` is +appealing because it still sticks with the ``MyType = int`` assignment syntax, and adds some information for the type checker purely as an annotation. diff --git a/pep-0621.rst b/pep-0621.rst index 0c18d94cf..ac8728e81 100644 --- a/pep-0621.rst +++ b/pep-0621.rst @@ -550,7 +550,7 @@ distribution or wheel file is out of scope for this PEP. Name the ``[project.urls]`` table ``[project.project-urls]`` ------------------------------------------------------------ This suggestion came thanks to the corresponding `core metadata`_ -being `Project-Url`. But once the overall table name of `[project]` +being ``Project-Url``. But once the overall table name of ``[project]`` was chosen, the redundant use of the word "project" suggested the current, shorter name was a better fit. diff --git a/pep-0622.rst b/pep-0622.rst index 4c4139bb3..0d81853ee 100644 --- a/pep-0622.rst +++ b/pep-0622.rst @@ -390,7 +390,7 @@ The proposed indentation structure is as following:: case pattern_2: ... -Here, `some_expression` represents the value that is being matched against, +Here, ``some_expression`` represents the value that is being matched against, which will be referred to hereafter as the *subject* of the match. @@ -424,9 +424,9 @@ statement. For example:: During failed pattern matches, some sub-patterns may succeed. For example, while matching the value ``[0, 1, 2]`` with the pattern ``(0, x, 1)``, the -sub-pattern `x` may succeed if the list elements are matched from left to right. +sub-pattern ``x`` may succeed if the list elements are matched from left to right. The implementation may choose to either make persistent bindings for those -partial matches or not. User code including a `match` statement should not rely +partial matches or not. User code including a ``match`` statement should not rely on the bindings being made for a failed match, but also shouldn't assume that variables are unchanged by a failed match. This part of the behavior is left intentionally unspecified so different implementations can add @@ -1449,7 +1449,7 @@ simple-minded code editors. Finally, the horizontal space issue can be alleviated by allowing "half-indent" (i.e. two spaces instead of four) for match statements. -In sample programs using `match`, written as part of the development of this +In sample programs using ``match``, written as part of the development of this PEP, a noticeable improvement in code brevity is observed, more than making up for the additional indentation level. @@ -1584,10 +1584,10 @@ surprising to users. Range matching patterns ----------------------- -This would allow patterns such as `1...6`. However, there are a host of +This would allow patterns such as ``1...6``. However, there are a host of ambiguities: -* Is the range open, half-open, or closed? (I.e. is `6` included in the +* Is the range open, half-open, or closed? (I.e. is ``6`` included in the above example or not?) * Does the range match a single number, or a range object? * Range matching is often used for character ranges ('a'...'z') but that @@ -1597,7 +1597,7 @@ ambiguities: to the fact that names can be dynamically rebound. Rather than creating a special-case syntax for ranges, it was decided -that allowing custom pattern objects (`InRange(0, 6)`) would be more flexible +that allowing custom pattern objects (``InRange(0, 6)``) would be more flexible and less ambiguous; however those ideas have been postponed for the time being (See `deferred ideas`_).