diff --git a/.github/PULL_REQUEST_TEMPLATE/Mark a PEP Final.md b/.github/PULL_REQUEST_TEMPLATE/Mark a PEP Final.md index cc667804f70..bd37727c7ac 100644 --- a/.github/PULL_REQUEST_TEMPLATE/Mark a PEP Final.md +++ b/.github/PULL_REQUEST_TEMPLATE/Mark a PEP Final.md @@ -9,6 +9,6 @@ If you're unsure about something, just leave it blank and we'll take a look. * [ ] Any substantial changes since the accepted version approved by the SC/PEP delegate * [ ] Pull request title in appropriate format (``PEP 123: Mark Final``) * [ ] ``Status`` changed to ``Final`` (and ``Python-Version`` is correct) -* [ ] Canonical docs/spec linked with a ``canonical-doc`` directive +* [ ] Canonical docs/spec linked with a ``canonical-doc`` directive (or ``canonical-pypa-spec`` for packaging PEPs, or ``canonical-typing-spec`` for typing PEPs) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 6e4826f5801..89ff7ad05a9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -17,6 +17,13 @@ repos: - id: mixed-line-ending name: "Normalize mixed line endings" args: [--fix=lf] + - id: end-of-file-fixer + name: "Ensure files end with a single newline" + exclude: '^peps/pep-(0[2-6]|3111|3118|3133|3146).*$' + - id: trailing-whitespace + name: "Remove trailing whitespace" + exclude: '^peps/pep-(0[2-6]|3000|3002|31).*$' + - id: file-contents-sorter name: "Sort codespell ignore list" files: '.codespell/ignore-words.txt' diff --git a/pep_sphinx_extensions/tests/peps/pep-9000.rst b/pep_sphinx_extensions/tests/peps/pep-9000.rst index 84a117c17e5..d1a959125aa 100644 --- a/pep_sphinx_extensions/tests/peps/pep-9000.rst +++ b/pep_sphinx_extensions/tests/peps/pep-9000.rst @@ -1,6 +1,6 @@ PEP: 9000 Title: Test with authors with email addresses -Author: Francis Fussyreverend , +Author: Francis Fussyreverend , Javier Soulfulcommodore Created: 20-Apr-2022 Status: Draft diff --git a/peps/pep-0008.rst b/peps/pep-0008.rst index 087370feddf..733b73e4c93 100644 --- a/peps/pep-0008.rst +++ b/peps/pep-0008.rst @@ -820,7 +820,7 @@ complete sentences, with each sentence ending in a period. You should use one or two spaces after a sentence-ending period in multi-sentence comments, except after the final sentence. -Ensure that your comments are clear and easily understandable to other +Ensure that your comments are clear and easily understandable to other speakers of the language you are writing in. Python coders from non-English speaking countries: please write your diff --git a/peps/pep-0703.rst b/peps/pep-0703.rst index 587819766e0..3277ab688ac 100644 --- a/peps/pep-0703.rst +++ b/peps/pep-0703.rst @@ -713,7 +713,7 @@ that wrap those calls. Python objects should not be allocated through other APIs, such as raw calls to C's malloc or the C++ new operator. Additionally, ``PyObject_Malloc`` should be used only for allocating Python objects; it should not be used for allocating buffers, -storages, or other data structures that are not PyObjects. +storages, or other data structures that are not PyObjects. This PEP also imposes restrictions on the pluggable allocator API (``PyMem_SetAllocator``). When compiling without the GIL, allocators @@ -967,7 +967,7 @@ per-object locking -- another thread might modify the list leading to The problematic borrowed reference APIs are supplemented with functions that return "new references" but are otherwise -equivalent: +equivalent: * ``PyList_FetchItem(list, idx)`` for ``PyList_GetItem`` * ``PyDict_FetchItem(dict, key)`` for ``PyDict_GetItem`` @@ -1087,7 +1087,7 @@ and improve single-threaded performance. Although lock acquisition has low overhead compared to most operations, accessing individual elements of lists and dictionaries are fast operations (so the locking overhead is comparatively larger) and frequent (so the -overhead has more impact). +overhead has more impact). This section describes the challenges with implementing dictionary and list accesses without locking followed by a description of this PEP's diff --git a/peps/pep-0705.rst b/peps/pep-0705.rst index 5ba78e3f938..cae156d4127 100644 --- a/peps/pep-0705.rst +++ b/peps/pep-0705.rst @@ -581,4 +581,3 @@ Copyright ========= This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. - diff --git a/peps/pep-0706.rst b/peps/pep-0706.rst index 5585a809b03..984b7555017 100644 --- a/peps/pep-0706.rst +++ b/peps/pep-0706.rst @@ -110,7 +110,7 @@ However, there are some issues with this approach: affect all subsequent operations on the same ``TarFile`` object. This behavior is fine for most uses, but despite that, it would be very surprising if ``TarFile.extractall`` did this by default. -- Calling ``getmembers`` can be expensive and it +- Calling ``getmembers`` can be expensive and it `requires a seekable archive `__. - When verifying members in advance, it may be necessary to track how each member would have changed the filesystem, e.g. how symlinks are being set up. diff --git a/peps/pep-0713.rst b/peps/pep-0713.rst index 65d117b1d2c..9547b497b31 100644 --- a/peps/pep-0713.rst +++ b/peps/pep-0713.rst @@ -204,4 +204,3 @@ Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. - diff --git a/peps/pep-0719.rst b/peps/pep-0719.rst index 420c04422fe..27f7301b6a2 100644 --- a/peps/pep-0719.rst +++ b/peps/pep-0719.rst @@ -72,5 +72,3 @@ Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. - - diff --git a/peps/pep-0722.rst b/peps/pep-0722.rst index 9d421302711..ab252400dcc 100644 --- a/peps/pep-0722.rst +++ b/peps/pep-0722.rst @@ -231,7 +231,7 @@ reference implementation can be included here. from packaging.requirements import Requirement DEPENDENCY_BLOCK_MARKER = r"(?i)^#\s+script\s+dependencies:\s*$" - + def read_dependency_block(filename): # Use the tokenize module to handle any encoding declaration. with tokenize.open(filename) as f: diff --git a/peps/pep-0724.rst b/peps/pep-0724.rst index 89c6695df2b..7ef23850b8b 100644 --- a/peps/pep-0724.rst +++ b/peps/pep-0724.rst @@ -348,4 +348,3 @@ Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. - diff --git a/peps/pep-0725.rst b/peps/pep-0725.rst index 13fc866d6f7..52aa8d1c2fb 100644 --- a/peps/pep-0725.rst +++ b/peps/pep-0725.rst @@ -104,7 +104,7 @@ Multiple types of external dependencies can be distinguished: Concrete packages are straightforward to understand, and are a concept present in virtually every package management system. Virtual packages are a concept also present in a number of packaging systems -- but not always, and the -details of their implementation varies. +details of their implementation varies. Cross compilation ----------------- @@ -186,7 +186,7 @@ The two types of concrete packages are supported by PURL_ (Package URL), which implements a scheme for identifying packages that is meant to be portable across packaging ecosystems. Its design is:: - scheme:type/namespace/name@version?qualifiers#subpath + scheme:type/namespace/name@version?qualifiers#subpath The ``scheme`` component is a fixed string, ``pkg``, and of the other components only ``type`` and ``name`` are required. As an example, a package diff --git a/peps/pep-0727.rst b/peps/pep-0727.rst index a6663a87bda..8bc9a638e2d 100644 --- a/peps/pep-0727.rst +++ b/peps/pep-0727.rst @@ -346,14 +346,14 @@ For example: .. code:: java /** - * Returns an Image object that can then be painted on the screen. + * Returns an Image object that can then be painted on the screen. * The url argument must specify an absolute {@link URL}. The name - * argument is a specifier that is relative to the url argument. + * argument is a specifier that is relative to the url argument. *

- * This method always returns immediately, whether or not the + * This method always returns immediately, whether or not the * image exists. When this applet attempts to draw the image on - * the screen, the data will be loaded. The graphics primitives - * that draw the image will incrementally paint on the screen. + * the screen, the data will be loaded. The graphics primitives + * that draw the image will incrementally paint on the screen. * * @param url an absolute URL giving the base location of the image * @param name the location of the image, relative to the url argument diff --git a/peps/pep-0728.rst b/peps/pep-0728.rst index e9556ce2c5a..f68542604d5 100644 --- a/peps/pep-0728.rst +++ b/peps/pep-0728.rst @@ -48,7 +48,7 @@ Another possible use case for this is a sound way to class Movie(TypedDict): name: str director: str - + class Book(TypedDict): name: str author: str @@ -194,12 +194,12 @@ to the ``extra_items`` argument. For example:: class Movie(TypedDict, extra_items=bool): name: str - + a: Movie = {"name": "Blade Runner", "novel_adaptation": True} # OK b: Movie = { "name": "Blade Runner", "year": 1982, # Not OK. 'int' is not assignable to 'bool' - } + } Here, ``extra_items=bool`` specifies that items other than ``'name'`` have a value type of ``bool`` and are non-required. @@ -214,12 +214,12 @@ the ``extra_items`` argument:: def f(movie: Movie) -> None: reveal_type(movie["name"]) # Revealed type is 'str' reveal_type(movie["novel_adaptation"]) # Revealed type is 'bool' - + ``extra_items`` is inherited through subclassing:: class MovieBase(TypedDict, extra_items=int | None): name: str - + class Movie(MovieBase): year: int @@ -315,7 +315,7 @@ function parameters still apply:: class Movie(TypedDict, extra_items=int): name: str - + def f(**kwargs: Unpack[Movie]) -> None: ... # Should be equivalent to: @@ -356,7 +356,7 @@ unless it is declared to be ``ReadOnly`` in the superclass:: class Parent(TypedDict, extra_items=int | None): pass - + class Child(Parent, extra_items=int): # Not OK. Like any other TypedDict item, extra_items's type cannot be changed Second, ``extra_items=T`` effectively defines the value type of any unnamed @@ -384,10 +384,10 @@ For example:: class MovieBase(TypedDict, extra_items=int | None): name: str - + class AdaptedMovie(MovieBase): # Not OK. 'bool' is not assignable to 'int | None' adapted_from_novel: bool - + class MovieRequiredYear(MovieBase): # Not OK. Required key 'year' is not known to 'Parent' year: int | None @@ -478,7 +478,7 @@ checks:: class MovieDetails(TypedDict, extra_items=int | None): name: str year: NotRequired[int] - + details: MovieDetails = {"name": "Kill Bill Vol. 1", "year": 2003} movie: Movie = details # Not OK. While 'int' is assignable to 'int | None', # 'int | None' is not assignable to 'int' @@ -502,7 +502,7 @@ possible for an item to have a :term:`narrower ` type than the class Movie(TypedDict, extra_items=ReadOnly[str | int]): name: str - + class MovieDetails(TypedDict, extra_items=int): name: str year: NotRequired[int] @@ -522,19 +522,19 @@ enforced:: class MovieExtraStr(TypedDict, extra_items=str): name: str - + extra_int: MovieExtraInt = {"name": "No Country for Old Men", "year": 2007} extra_str: MovieExtraStr = {"name": "No Country for Old Men", "description": ""} extra_int = extra_str # Not OK. 'str' is not assignable to extra items type 'int' extra_str = extra_int # Not OK. 'int' is not assignable to extra items type 'str' - + A non-closed TypedDict type implicitly allows non-required extra keys of value type ``ReadOnly[object]``. Applying the assignability rules between this type and a closed TypedDict type is allowed:: class MovieNotClosed(TypedDict): name: str - + extra_int: MovieExtraInt = {"name": "No Country for Old Men", "year": 2007} not_closed: MovieNotClosed = {"name": "No Country for Old Men"} extra_int = not_closed # Not OK. @@ -636,8 +636,8 @@ For example:: def f(x: IntDict) -> None: v: dict[str, int] = x # OK v.clear() # OK - - not_required_num_dict: IntDictWithNum = {"num": 1, "bar": 2} + + not_required_num_dict: IntDictWithNum = {"num": 1, "bar": 2} regular_dict: dict[str, int] = not_required_num_dict # OK f(not_required_num_dict) # OK @@ -652,7 +652,7 @@ because such dict can be a subtype of dict:: class CustomDict(dict[str, int]): pass - + not_a_regular_dict: CustomDict = {"num": 1} int_dict: IntDict = not_a_regular_dict # Not OK diff --git a/peps/pep-0732-concentric.drawio.svg b/peps/pep-0732-concentric.drawio.svg index 02677c5ee5c..cab0340519f 100644 --- a/peps/pep-0732-concentric.drawio.svg +++ b/peps/pep-0732-concentric.drawio.svg @@ -1,4 +1,4 @@ -
3   
3   
2   
2   
1
1
1
1
2
2
3
3
World
includes readers of the documentation
World...
Documentation Working Group
volunteers who contribute to the docs
Documentation Working Group...
Documentation Editoral Board
trusted group
Documentation Editoral Board...Text is not SVG - cannot display \ No newline at end of file +
3   
3   
2   
2   
1
1
1
1
2
2
3
3
World
includes readers of the documentation
World...
Documentation Working Group
volunteers who contribute to the docs
Documentation Working Group...
Documentation Editoral Board
trusted group
Documentation Editoral Board...Text is not SVG - cannot display diff --git a/peps/pep-0732.rst b/peps/pep-0732.rst index dc79b41e98f..b64ae519721 100644 --- a/peps/pep-0732.rst +++ b/peps/pep-0732.rst @@ -22,16 +22,16 @@ This PEP: Motivation ========== -The Steering Council approved the creation of a +The Steering Council approved the creation of a `Documentation Working Group `_ in March 2021 to set direction for the docs. This group is now called the Editorial Board to differentiate it from the Documentation Working Group that was created -since then to focus on more tactical work. +since then to focus on more tactical work. -The purpose of the Python documentation is to serve the -present and future end users of Python. As such, the core -development community and the greater Python documentation +The purpose of the Python documentation is to serve the +present and future end users of Python. As such, the core +development community and the greater Python documentation contributors work together to achieve this: .. image:: pep-0732-concentric.drawio.svg @@ -66,7 +66,7 @@ The editorial board will: Responsibilities ---------------- -The board has authority to make decisions about Python’s +The board has authority to make decisions about Python’s documentation, as scoped below. For example, it can: * Set big-picture strategy for Python’s documentation @@ -94,9 +94,9 @@ The Editorial board oversees the content and strategy for the following: - PEPs (peps.python.org) * - - PyPA documentation - * - + * - - www.python.org - * - + * - - The Python Wiki (wiki.python.org) @@ -127,52 +127,52 @@ Editorial board members should have: * A history of making significant contributions to Python * A willingness to dedicate time to improving Python's docs -Members of the Editorial Board should have experience in education, -communication, technical writing, Python’s documentation, accessibility, +Members of the Editorial Board should have experience in education, +communication, technical writing, Python’s documentation, accessibility, translation, or community management. Term ~~~~ -Editorial Board members serve for an indefinite term, though it is -generally expected that there will be changes in Editorial Board -composition each year. Editorial Board members will confirm annually -whether they wish to continue as a board member. Members may resign +Editorial Board members serve for an indefinite term, though it is +generally expected that there will be changes in Editorial Board +composition each year. Editorial Board members will confirm annually +whether they wish to continue as a board member. Members may resign at any time. -If a board member drops out of touch and cannot be contacted for a +If a board member drops out of touch and cannot be contacted for a month or longer, then the rest of the board may vote to replace them. Changes to the Editorial Board's Size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Annually after each major Python release, the Editorial Board will -review whether the board's size should change. This provides -flexibility if the needs of the documentation community change -over time. A simple majority is needed to make a decision to +Annually after each major Python release, the Editorial Board will +review whether the board's size should change. This provides +flexibility if the needs of the documentation community change +over time. A simple majority is needed to make a decision to increase the board's size where quorum is 80% of the current board. -As the sponsoring organization of the Documentation Editorial -Board, the Steering Council may change the number of members of -the Board at any time, including appointing new members or -dismissing existing members. +As the sponsoring organization of the Documentation Editorial +Board, the Steering Council may change the number of members of +the Board at any time, including appointing new members or +dismissing existing members. Vacancies ~~~~~~~~~ -If a vacancy exists on the board for any reason, the Documentation -Editorial Board will publicly announce a call for prospective -board members. Prospective board members would submit a brief -document stating qualifications and their motivation to serve. -The sitting members of the Editorial Board will select new board +If a vacancy exists on the board for any reason, the Documentation +Editorial Board will publicly announce a call for prospective +board members. Prospective board members would submit a brief +document stating qualifications and their motivation to serve. +The sitting members of the Editorial Board will select new board members by a simple majority where quorum is 80% of the current board. Amendments ========== -This PEP serves as a charter for the Docs Editorial Board. Changes -to its operation can be made either through a new PEP or through -a change to this PEP. In either case, the change would be decided +This PEP serves as a charter for the Docs Editorial Board. Changes +to its operation can be made either through a new PEP or through +a change to this PEP. In either case, the change would be decided upon by the Steering Council after discussion in the community. diff --git a/peps/pep-0736.rst b/peps/pep-0736.rst index 64b7acc04f2..67656390443 100644 --- a/peps/pep-0736.rst +++ b/peps/pep-0736.rst @@ -424,7 +424,7 @@ Recommendations for using this syntax As with any other language feature, the programmer should exercise their own judgement about whether it is prudent to use it in any given context. We do not -recommend enforcing a rule to use the feature in all cases where it may be +recommend enforcing a rule to use the feature in all cases where it may be applicable. As described `above `__, we propose that a diff --git a/peps/pep-0744.rst b/peps/pep-0744.rst index 9a0ff3de2e8..1f9ef1ef84d 100644 --- a/peps/pep-0744.rst +++ b/peps/pep-0744.rst @@ -99,10 +99,10 @@ physical hardware registers). Since much of this data varies even between identical runs of a program and the existing optimization pipeline makes heavy use of runtime profiling information, -it doesn't make much sense to compile these traces ahead of time and would be a -substantial redesign of the existing specification and micro-op tracing infrastructure -that has already been implemented. As has been demonstrated for many other dynamic -languages (`and even Python itself `__), the most promising +it doesn't make much sense to compile these traces ahead of time and would be a +substantial redesign of the existing specification and micro-op tracing infrastructure +that has already been implemented. As has been demonstrated for many other dynamic +languages (`and even Python itself `__), the most promising approach is to compile the optimized micro-ops "just in time" for execution. Rationale @@ -120,7 +120,7 @@ high-quality Python-specific optimizations for the code being run, *but also* quick generation of efficient machine code for the optimized program. The Python core development team has the necessary skills and experience for the former (a middle-end tightly coupled to the interpreter), and copy-and-patch compilation -provides an attractive solution for the latter. +provides an attractive solution for the latter. In a nutshell, copy-and-patch allows a high-quality template JIT compiler to be generated from the same DSL used to generate the rest of the interpreter. For a @@ -139,9 +139,9 @@ code and 500 lines of runtime C code. Specification ============= -The JIT is currently not part of the default build configuration, and it is -likely to remain that way for the foreseeable future (though official binaries -may include it). That said, the JIT will become non-experimental once all of +The JIT is currently not part of the default build configuration, and it is +likely to remain that way for the foreseeable future (though official binaries +may include it). That said, the JIT will become non-experimental once all of the following conditions are met: #. It provides a meaningful performance improvement for at least one popular @@ -245,7 +245,7 @@ Since the code templates emitted by the JIT are compiled by Clang, it *may* be possible to allow JIT frames to be traced through by simply modifying the compiler flags to use frame pointers more carefully. It may also be possible to harvest and emit the debugging information produced by Clang. Neither of these -ideas have been explored very deeply. +ideas have been explored very deeply. While this is an issue that *should* be fixed, fixing it is not a particularly high priority at this time. This is probably a problem best explored by somebody @@ -299,7 +299,7 @@ How to Teach This Choose the sections that best describe you: - **If you are a Python programmer or end user...** - + - ...nothing changes for you. Nobody should be distributing JIT-enabled CPython interpreters to you while it is still an experimental feature. Once it is non-experimental, you will probably notice slightly better performance @@ -317,7 +317,7 @@ Choose the sections that best describe you: - ...nothing changes for you. All Python profiling and tracing functionality remains. - + - **If you profile or debug C code...** - ...currently, the ability to trace *through* JIT frames is limited. This may @@ -376,13 +376,13 @@ Reference Implementation Key parts of the implementation include: - |readme|_: Instructions for how to build the JIT. - + - |jit|_: The entire runtime portion of the JIT compiler. - + - |jit_stencils|_: An example of the JIT's generated templates. - + - |template|_: The code which is compiled to produce the JIT's templates. - + - |targets|_: The code to compile and parse the templates at build time. .. |readme| replace:: ``Tools/jit/README.md`` @@ -500,7 +500,7 @@ Open Issues Speed ----- -Currently, the JIT is `about as fast as the existing specializing interpreter +Currently, the JIT is `about as fast as the existing specializing interpreter `__ on most platforms. Improving this is obviously a top priority at this point, since providing a significant performance gain is the entire motivation for @@ -528,9 +528,9 @@ likely to be a real concern. Not much effort has been put into optimizing the JIT's memory usage yet, so these numbers likely represent a maximum that will be reduced over time. Improving this is a medium priority, and is being tracked in `GH-116017 -`__. We may consider +`__. We may consider exposing configurable parameters for limiting memory consumption in the -future, but no official APIs will be exposed until the JIT meets the +future, but no official APIs will be exposed until the JIT meets the requirements to be considered non-experimental. Earlier versions of the JIT had a more complicated memory allocation scheme @@ -543,8 +543,8 @@ Dependencies At the time of writing, the JIT has a build-time dependency on LLVM. LLVM is used to compile individual micro-op instructions into blobs of machine code, -which are then linked together to form the JIT's templates. These templates are -used to build CPython itself. The JIT has no runtime dependency on LLVM and is +which are then linked together to form the JIT's templates. These templates are +used to build CPython itself. The JIT has no runtime dependency on LLVM and is therefore not at all exposed as a dependency to end users. Building the JIT adds between 3 and 60 seconds to the build process, depending diff --git a/peps/pep-0746.rst b/peps/pep-0746.rst index 342b730aa69..f4665f83ea1 100644 --- a/peps/pep-0746.rst +++ b/peps/pep-0746.rst @@ -54,7 +54,7 @@ that specifies whether the metadata is valid for a given type:: __supports_annotated_base__: int The attribute may also be marked as a ``ClassVar`` to avoid interaction with dataclasses:: - + from dataclasses import dataclass from typing import ClassVar @@ -77,7 +77,7 @@ To support generic ``Gt`` metadata, one might write:: class SupportsGt[T](Protocol): def __gt__(self, __other: T) -> bool: ... - + class Gt[T]: __supports_annotated_base__: ClassVar[SupportsGt[T]] diff --git a/peps/pep-0747.rst b/peps/pep-0747.rst index 1d5483ad77d..b91078673f3 100644 --- a/peps/pep-0747.rst +++ b/peps/pep-0747.rst @@ -284,7 +284,7 @@ intent to use the value as a type form object. Second, static type checkers validate that all rules for type expressions are followed:: x4 = type(int) # No error, evaluates to "type[int]" - + x5 = TypeForm(type(int)) # Error: call not allowed in type expression @@ -341,7 +341,7 @@ by a function parameter, returned by a function, or stored in a variable: ^ | variable type - + return sum Type expressions evaluate to valid *type form* objects at runtime and can be @@ -353,8 +353,8 @@ assigned to variables and manipulated like any other data in a program: | | v v int_type_form: TypeForm = int | None - ^ - | + ^ + | the type of a type form object ``TypeForm[]`` is how you spell the type of a *type form* object, which is @@ -381,7 +381,7 @@ type form object as input. :: from trycast import isassignable - + if isassignable(some_object, MyTypedDict): # OK: MyTypedDict is a TypeForm[] ... diff --git a/peps/pep-0749.rst b/peps/pep-0749.rst index 5afd763a2d2..303ee18dd1d 100644 --- a/peps/pep-0749.rst +++ b/peps/pep-0749.rst @@ -64,7 +64,7 @@ The future of ``from __future__ import annotations`` which changes all annotations to strings. :pep:`649` proposes an alternative approach that does not require this future import, and states: - If this PEP is accepted, PEP 563 will be deprecated and eventually removed. + If this PEP is accepted, PEP 563 will be deprecated and eventually removed. However, the PEP does not provide a detailed plan for this deprecation. @@ -922,7 +922,7 @@ code execution even with no access to any globals or builtins. For example: .. code-block:: pycon >>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__.__builtins__["print"]("Hello world")): pass - ... + ... >>> annotationlib.get_annotations(f, format=annotationlib.Format.SOURCE) Hello world {'x': 'None'} diff --git a/peps/pep-0750.rst b/peps/pep-0750.rst index 3291da787ea..5009d97a47a 100644 --- a/peps/pep-0750.rst +++ b/peps/pep-0750.rst @@ -57,7 +57,7 @@ Motivation ========== Python f-strings are easy to use and very popular. Over time, however, developers -have encountered limitations that make them +have encountered limitations that make them `unsuitable for certain use cases `__. In particular, f-strings provide no way to intercept and transform interpolated values before they are combined into a final string. @@ -108,7 +108,7 @@ Template String Literals ------------------------ This PEP introduces a new string prefix, ``t``, to define template string literals. -These literals resolve to a new type, ``Template``, found in a new top-level +These literals resolve to a new type, ``Template``, found in a new top-level standard library module, ``templatelib``. The following code creates a ``Template`` instance: @@ -139,7 +139,7 @@ Template strings evaluate to an instance of a new type, ``templatelib.Template`` class Template: args: Sequence[str | Interpolation] - + def __init__(self, *args: str | Interpolation): ... @@ -187,7 +187,7 @@ Like ``Template``, it is a new concrete type found in the ``templatelib`` module ): ... -Like ``Template``, ``Interpolation`` is shallow immutable. Its attributes +Like ``Template``, ``Interpolation`` is shallow immutable. Its attributes cannot be reassigned. The ``value`` attribute is the evaluated result of the interpolation: @@ -292,8 +292,8 @@ for detailed working examples. Template String Concatenation ----------------------------- -Template strings support explicit concatenation using ``+``. Concatenation is -supported for two ``Template`` instances as well as for a ``Template`` instance +Template strings support explicit concatenation using ``+``. Concatenation is +supported for two ``Template`` instances as well as for a ``Template`` instance and a ``str``: .. code-block:: python @@ -305,10 +305,10 @@ and a ``str``: assert template1 + "!" == t"Hello !" assert "Hello " + template2 == t"Hello {name}" -Concatenation of templates is "viral": the concatenation of a ``Template`` and +Concatenation of templates is "viral": the concatenation of a ``Template`` and a ``str`` always results in a ``Template`` instance. -Python's implicit concatenation syntax is also supported. The following code +Python's implicit concatenation syntax is also supported. The following code will work as expected: .. code-block:: python @@ -320,7 +320,7 @@ will work as expected: assert template2 == t"Hello World" -The ``Template`` type implements the ``__add__()`` and ``__radd__()`` methods +The ``Template`` type implements the ``__add__()`` and ``__radd__()`` methods roughly as follows: .. code-block:: python @@ -339,7 +339,7 @@ roughly as follows: return Template(other + self.args[0], *self.args[1:]) Special care is taken to ensure that the interleaving of ``str`` and ``Interpolation`` -instances is maintained when concatenating. (See the +instances is maintained when concatenating. (See the `Interleaving of Template.args`_ section for more information.) @@ -386,7 +386,7 @@ No Support for Ordering ----------------------- The ``Template`` and ``Interpolation`` types do not support ordering. This is -unlike all other string literal types in Python, which support lexicographic +unlike all other string literal types in Python, which support lexicographic ordering. Because interpolations can contain arbitrary values, there is no natural ordering for them. As a result, neither the ``Template`` nor the ``Interpolation`` type implements the standard comparison methods. @@ -501,8 +501,8 @@ evaluated with different values. Access to the static parts can be done with Interleaving is an invariant maintained by the ``Template`` class. Developers can take advantage of it but they are not required to themselves maintain it. -Specifically, ``Template.__init__()`` can be called with ``str`` and -``Interpolation`` instances in *any* order; the constructor will "interleave" them +Specifically, ``Template.__init__()`` can be called with ``str`` and +``Interpolation`` instances in *any* order; the constructor will "interleave" them as necessary before assigning them to ``args``. @@ -736,7 +736,7 @@ logging: .. note:: Example code See `logging.py`__ and `test_logging.py`__. - + __ https://github.com/davepeck/pep750-examples/blob/main/pep/logging.py __ https://github.com/davepeck/pep750-examples/blob/main/pep/test_logging.py @@ -748,7 +748,7 @@ This PEP contains several short HTML templating examples. It turns out that the "hypothetical" ``html()`` function mentioned in the `Motivation`_ section (and a few other places in this PEP) exists and is available in the `pep750-examples repository `_. -If you're thinking about parsing a complex grammar with template strings, we +If you're thinking about parsing a complex grammar with template strings, we hope you'll find it useful. @@ -786,26 +786,26 @@ We hope that teaching developers will be straightforward. At a glance, template strings look just like f-strings. Their syntax is familiar and the scoping rules remain the same. -The first thing developers must learn is that template string literals don't -evaluate to strings; instead, they evaluate to a new type, ``Template``. This +The first thing developers must learn is that template string literals don't +evaluate to strings; instead, they evaluate to a new type, ``Template``. This is a simple type intended to be used by template processing code. It's not until -developers call a processing function that they get the result they want: -typically, a string, although processing code can of course return any arbitrary +developers call a processing function that they get the result they want: +typically, a string, although processing code can of course return any arbitrary type. -Because developers will learn that t-strings are nearly always used in tandem -with processing functions, they don't necessarily need to understand the details +Because developers will learn that t-strings are nearly always used in tandem +with processing functions, they don't necessarily need to understand the details of the ``Template`` type. As with descriptors and decorators, we expect many more developers will use t-strings than write t-string processing functions. -Over time, a small number of more advanced developers *will* wish to author their -own template processing code. Writing processing code often requires thinking -in terms of formal grammars. Developers will need to learn how to parse the -``args`` attribute of a ``Template`` instance and how to process interpolations -in a context-sensitive fashion. More sophisticated grammars will likely require -parsing to intermediate representations like an AST. Great template processing -code will handle format specifiers and conversions when appropriate. Writing -production-grade template processing code -- for instance, to support HTML +Over time, a small number of more advanced developers *will* wish to author their +own template processing code. Writing processing code often requires thinking +in terms of formal grammars. Developers will need to learn how to parse the +``args`` attribute of a ``Template`` instance and how to process interpolations +in a context-sensitive fashion. More sophisticated grammars will likely require +parsing to intermediate representations like an AST. Great template processing +code will handle format specifiers and conversions when appropriate. Writing +production-grade template processing code -- for instance, to support HTML templates -- can be a large undertaking. We expect that template strings will provide framework authors with a powerful @@ -1016,7 +1016,7 @@ and is able to ``await`` an interpolation's value. .. note:: Example code See `aformat.py`__ and `test_aformat.py`__. - + __ https://github.com/davepeck/pep750-examples/blob/main/pep/aformat.py __ https://github.com/davepeck/pep750-examples/blob/main/pep/test_aformat.py @@ -1186,14 +1186,14 @@ Disallowing String Concatenation Earlier versions of this PEP proposed that template strings should not support concatenation. This was rejected in favor of allowing concatenation. -There are reasonable arguments in favor of rejecting one or all forms of -concatenation: namely, that it cuts off a class of potential bugs, particularly -when one takes the view that template strings will often contain complex grammars -for which concatenation doesn't always have the same meaning (or any meaning). +There are reasonable arguments in favor of rejecting one or all forms of +concatenation: namely, that it cuts off a class of potential bugs, particularly +when one takes the view that template strings will often contain complex grammars +for which concatenation doesn't always have the same meaning (or any meaning). -Moreover, the earliest versions of this PEP proposed a syntax closer to -JavaScript's tagged template literals, where an arbitrary callable could be used -as a prefix to a string literal. There was no guarantee that the callable would +Moreover, the earliest versions of this PEP proposed a syntax closer to +JavaScript's tagged template literals, where an arbitrary callable could be used +as a prefix to a string literal. There was no guarantee that the callable would return a type that supported concatenation. In the end, we decided that the surprise to developers of a new string type @@ -1203,7 +1203,7 @@ after all, and while we are sure there are cases where this introduces bugs, it's not clear that those bugs outweigh the benefits of supporting concatenation.) While concatenation is supported, we expect that code that uses template strings -will more commonly build up larger templates through nesting and composition +will more commonly build up larger templates through nesting and composition rather than concatenation. @@ -1221,16 +1221,16 @@ separate PEP. Removing ``conv`` From ``Interpolation`` ---------------------------------------- -During the authoring of this PEP, we considered removing the ``conv`` attribute +During the authoring of this PEP, we considered removing the ``conv`` attribute from ``Interpolation`` and specifying that the conversion should be performed eagerly, before ``Interpolation.value`` is set. This was done to simplify the work of writing template processing code. The ``conv`` attribute is of limited extensibility (it is typed as -``Literal["r", "s", "a"] | None``). It is not clear that it adds significant +``Literal["r", "s", "a"] | None``). It is not clear that it adds significant value or flexibility to template strings that couldn't better be achieved with custom format specifiers. Unlike with format specifiers, there is no -equivalent to Python's :func:`python:format` built-in. (Instead, we include an +equivalent to Python's :func:`python:format` built-in. (Instead, we include an sample implementation of ``convert()`` in the `Examples`_ section.) Ultimately we decided to keep the ``conv`` attribute in the ``Interpolation`` type @@ -1267,11 +1267,11 @@ Alternate Layouts for ``Template.args`` During the development of this PEP, we considered several alternate layouts for the ``args`` attribute of the ``Template`` type. This included: -- Instead of ``args``, ``Template`` contains a ``strings`` attribute of type - ``Sequence[str]`` and an ``interpolations`` attribute of type - ``Sequence[Interpolation]``. There are zero or more interpolations and - there is always one more string than there are interpolations. Utility code - could build an interleaved sequence of strings and interpolations from these +- Instead of ``args``, ``Template`` contains a ``strings`` attribute of type + ``Sequence[str]`` and an ``interpolations`` attribute of type + ``Sequence[Interpolation]``. There are zero or more interpolations and + there is always one more string than there are interpolations. Utility code + could build an interleaved sequence of strings and interpolations from these separate attributes. This was rejected as being overly complex. - ``args`` is typed as a ``Sequence[tuple[str, Interpolation | None]]``. Each diff --git a/peps/pep-0754.rst b/peps/pep-0754.rst index d10565fc52d..94bab4fc0fd 100644 --- a/peps/pep-0754.rst +++ b/peps/pep-0754.rst @@ -209,7 +209,7 @@ Copyright This document has been placed in the public domain. - + .. Local Variables: mode: indented-text diff --git a/peps/pep-0756.rst b/peps/pep-0756.rst index fd5447e860e..c52c9283d37 100644 --- a/peps/pep-0756.rst +++ b/peps/pep-0756.rst @@ -403,4 +403,3 @@ Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. - diff --git a/peps/pep-0758.rst b/peps/pep-0758.rst index 9a9369117b7..9f7dc270005 100644 --- a/peps/pep-0758.rst +++ b/peps/pep-0758.rst @@ -102,8 +102,8 @@ list of exception types. The grammar will be updated as follows: | 'except' ':' block except_star_block - | 'except' '*' expressions ':' block - | 'except' '*' expression 'as' NAME ':' block + | 'except' '*' expressions ':' block + | 'except' '*' expression 'as' NAME ':' block This allows both the current parenthesized syntax and the new unparenthesized syntax while requiring parentheses when the ``as`` keyword is used: diff --git a/peps/pep-0760.rst b/peps/pep-0760.rst index 888f2b373b4..721944c3d03 100644 --- a/peps/pep-0760.rst +++ b/peps/pep-0760.rst @@ -180,7 +180,7 @@ Rejected ideas This code guarantees that no matter what exception occurs, any open transaction will be aborted, while in the successful condition, the - transaction will be committed. + transaction will be committed. We do believe that although there are cases such like this one where bare ``except:`` handlers are correct, it would be better to actually @@ -202,4 +202,3 @@ CC0-1.0-Universal license, whichever is more permissive. .. [6] https://4.docs.plone.org/develop/plone-coredev/style.html#concrete-rules .. [7] https://docs.openedx.org/en/latest/developers/references/developer_guide/style_guides/python-guidelines.html .. [8] https://gitlab.com/mailman/mailman/-/blob/master/src/mailman/database/transaction.py#L27 - diff --git a/peps/pep-0762.rst b/peps/pep-0762.rst index c3dc8295ffd..a4d1aa77d2b 100644 --- a/peps/pep-0762.rst +++ b/peps/pep-0762.rst @@ -1,7 +1,7 @@ PEP: 762 Title: REPL-acing the default REPL Author: Pablo Galindo Salgado , Łukasz Langa , Lysandros Nikolaou , Emily Morehouse-Valcarcel -Sponsor: Pablo Galindo Salgado +Sponsor: Pablo Galindo Salgado Status: Final Type: Informational Created: 11-Oct-2024 @@ -126,19 +126,19 @@ introduces the following key features: 2. Copying and Pasting: in supported terminal emulators, bracketed pasting capability is discovered and used by PyREPL. This allows for transparent pasting of blocks of code without immediate execution or invalid automatic indentation. - + For terminal emulators that don’t support this mode, a dedicated paste mode is implemented to allow for easy insertion of multi-line code snippets without triggering immediate execution or indentation issues. - + Users enter manual paste mode by hitting the :kbd:`F3` key. The prompt changes from ``>>>`` to ``(paste)`` where users can paste contents from their clipboard or manually type as desired. Once the content is ready, hitting :kbd:`F3` exits paste mode. Then, pressing Enter executes the block. - + Users can enter multiple commands on a single input when using paste mode, which will help paste code from other sources. - + To copy blocks of code without the leading command prompts and without the output of the commands, users can enter the history view via the :kbd:`F2` key. This mode uses a pager to display history of executed commands without the prompts @@ -149,13 +149,13 @@ introduces the following key features: Access to the standard Help module is accessible via a Custom Command ``help`` (see below) or via the :kbd:`F1` key. Hit :kbd:`F1` to enter help mode. When you're done, hit :kbd:`F1` or a standard command (``q``, ``quit`` or ``exit``) to exit. - + Browsing interactive help does not retain command history. 4. Custom Commands: The REPL supports the implementation of custom commands, such as ``exit``, in a more natural and user-friendly manner, avoiding the current function call workaround. - + The initial list of custom commands includes: * ``exit`` @@ -163,7 +163,7 @@ introduces the following key features: * ``copyright`` * ``help`` * ``clear`` - + Commands are available as long as there is no name conflict with a variable in a reachable scope. For example, after assigning ``exit = 1``, the variable will take precedence over PyREPL commands. ``del exit`` in this case will remove the @@ -268,7 +268,7 @@ Several alternative approaches were considered and ultimately rejected: and lack of additional dependencies. Another key factor was the alignment with PyPy's implementation. - + Acknowledgments =============== diff --git a/peps/pep-0777.rst b/peps/pep-0777.rst index fb5a9576219..04d99a020f7 100644 --- a/peps/pep-0777.rst +++ b/peps/pep-0777.rst @@ -15,7 +15,7 @@ Abstract The current :pep:`wheel 1.0 specification <427>` was written over a decade ago, and has been extremely robust to changes in the Python packaging ecosystem. -Previous efforts to improve the wheel specification +Previous efforts to improve the wheel specification :pep:`were deferred <491#pep-deferral>` to focus on other packaging specifications. Meanwhile, the use of wheels has changed dramatically in the last decade. There have been many requests for new wheel features over the