Merge branch 'main' into pep750-october-updates

davepeck · davepeck · commit e78d42566853 · 2025-01-13T12:34:15.000-08:00
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -574,7 +574,7 @@ peps/pep-0690.rst  @warsaw
 peps/pep-0691.rst  @dstufft
 peps/pep-0692.rst  @jellezijlstra
 peps/pep-0693.rst  @Yhg1s
-peps/pep-0694.rst  @dstufft
+peps/pep-0694.rst  @dstufft @warsaw
 peps/pep-0695.rst  @gvanrossum
 peps/pep-0696.rst  @jellezijlstra
 peps/pep-0697.rst  @encukou
@@ -646,6 +646,8 @@ peps/pep-0765.rst  @iritkatriel @ncoghlan
 peps/pep-0766.rst  @warsaw
 peps/pep-0767.rst  @carljm
 peps/pep-0768.rst  @pablogsal
+peps/pep-0769.rst  @facundobatista
+peps/pep-0770.rst  @sethmlarson @brettcannon
 # ...
 peps/pep-0777.rst  @warsaw
 # ...
diff --git a/.github/workflows/render.yml b/.github/workflows/render.yml
@@ -23,7 +23,7 @@ jobs:
       matrix:
         python-version:
         - "3.x"
-        - "3.13-dev"
+        - "3.14-dev"
 
     steps:
       - name: Checkout
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -62,7 +62,8 @@ jobs:
           uvx --with tox-uv tox -e py -- -v --cov-report term
 
       - name: Upload coverage
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v5
         with:
           flags: ${{ matrix.os }}
           name: ${{ matrix.os }} Python ${{ matrix.python-version }}
+          token: ${{ secrets.CODECOV_ORG_TOKEN }}
diff --git a/Makefile b/Makefile
@@ -40,6 +40,7 @@ htmllive: _ensure-sphinx-autobuild html
 .PHONY: dirhtml
 dirhtml: BUILDER = dirhtml
 dirhtml: html
+	mv $(BUILDDIR)/404/index.html $(BUILDDIR)/404.html
 
 ## linkcheck      to check validity of links within PEP sources
 .PHONY: linkcheck
diff --git a/pep_sphinx_extensions/pep_theme/templates/page.html b/pep_sphinx_extensions/pep_theme/templates/page.html
@@ -49,12 +49,12 @@ <h1>Python Enhancement Proposals</h1>
         <article>
             {{ body }}
         </article>
-        {%- if not pagename == "numerical" %}
+        {%- if not pagename.startswith(("404", "numerical")) %}
         <nav id="pep-sidebar">
             <h2>Contents</h2>
             {{ toc }}
             <br>
-            {%- if not pagename.startswith(("numerical", "pep-0000", "topic")) %}
+            {%- if not pagename.startswith(("pep-0000", "topic")) %}
             <a id="source" href="https://github.com/python/peps/blob/main/peps/{{pagename}}.rst">Page Source (GitHub)</a>
             {%- endif %}
         </nav>
diff --git a/peps/conf.py b/peps/conf.py
@@ -19,6 +19,7 @@
 
 # Add any Sphinx extension module names here, as strings.
 extensions = [
+    "notfound.extension",
     "pep_sphinx_extensions",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
@@ -85,6 +86,10 @@
     "pypi": ("https://pypi.org/project/%s/", "%s"),
 }
 
+# sphinx-notfound-page
+# https://sphinx-notfound-page.readthedocs.io/en/latest/faq.html#does-this-extension-work-with-github-pages
+notfound_urls_prefix = None
+
 # -- Options for HTML output -------------------------------------------------
 
 _PSE_PATH = _ROOT / "pep_sphinx_extensions"
diff --git a/peps/pep-0694.rst b/peps/pep-0694.rst
diff --git a/peps/pep-0728.rst b/peps/pep-0728.rst
@@ -258,7 +258,7 @@ If ``closed`` is not provided, the behavior is inherited from the superclass.
 If the superclass is TypedDict itself or the superclass does not have ``closed=True``
 or the ``extra_items`` parameter, the previous TypedDict behavior is preserved:
 arbitrary extra items are allowed. If the superclass has ``closed=True``, the
-child class is also closed.
+child class is also closed::
 
     class BaseMovie(TypedDict, closed=True):
         name: str
diff --git a/peps/pep-0747.rst b/peps/pep-0747.rst
@@ -410,8 +410,9 @@ extract components of some type form objects.
 ::
 
    import typing
+   from typing import TypeForm, cast
 
-   def strip_annotated_metadata(typx: TypeForm[T]) -> TypeForm[T]:
+   def strip_annotated_metadata[T](typx: TypeForm[T]) -> TypeForm[T]:
        if typing.get_origin(typx) is typing.Annotated:
            typx = cast(TypeForm[T], typing.get_args(typx)[0])
        return typx
@@ -423,15 +424,16 @@ kinds of type form objects:
 
    import types
    import typing
+   from typing import TypeForm, cast
 
    def split_union(typx: TypeForm) -> tuple[TypeForm, ...]:
-       if isinstance(typ, types.UnionType):  # X | Y
-           return cast(tuple[TypeForm, ...], typing.get_args(typ))
-       if typing.get_origin(typ) is typing.Union:  # Union[X, Y]
-           return cast(tuple[TypeForm, ...], typing.get_args(typ))
-       if typ in (typing.Never, typing.NoReturn,):
+       if isinstance(typx, types.UnionType):  # X | Y
+           return cast(tuple[TypeForm, ...], typing.get_args(typx))
+       if typing.get_origin(typx) is typing.Union:  # Union[X, Y]
+           return cast(tuple[TypeForm, ...], typing.get_args(typx))
+       if typx in (typing.Never, typing.NoReturn,):
            return ()
-       return (typ,)
+       return (typx,)
 
 
 Combining with a type variable
@@ -443,7 +445,7 @@ within the same function definition:
 ::
 
    def as_instance[T](typx: TypeForm[T]) -> T | None:
-       return typ() if isinstance(typ, type) else None
+       return typx() if isinstance(typx, type) else None
 
 
 Combining with ``type``
@@ -455,7 +457,7 @@ variable within the same function definition:
 ::
 
    def as_type[T](typx: TypeForm[T]) -> type[T] | None:
-       return typ if isinstance(typ, type) else None
+       return typx if isinstance(typx, type) else None
 
 
 Combining with ``TypeIs`` and ``TypeGuard``
diff --git a/peps/pep-0767.rst b/peps/pep-0767.rst
@@ -98,8 +98,7 @@ Today, there are three major ways of achieving read-only attributes, honored by
 Protocols
 ---------
 
-A read-only attribute ``name: T`` on a :class:`~typing.Protocol` in principle
-defines two requirements:
+Suppose a :class:`~typing.Protocol` member ``name: T`` defining two requirements:
 
 1. ``hasattr(obj, "name")``
 2. ``isinstance(obj.name, T)``
@@ -251,7 +250,12 @@ Initialization
 
 Assignment to a read-only attribute can only occur in the class declaring the attribute.
 There is no restriction to how many times the attribute can be assigned to.
-The assignment must be allowed in the following contexts:
+Depending on the kind of the attribute, they can be assigned to at different sites:
+
+Instance Attributes
+'''''''''''''''''''
+
+Assignment to an instance attribute must be allowed in the following contexts:
 
 * In ``__init__``, on the instance received as the first parameter (likely, ``self``).
 * In ``__new__``, on instances of the declaring class created via a call
@@ -267,9 +271,6 @@ Additionally, a type checker may choose to allow the assignment:
 * In ``@classmethod``\ s, on instances of the declaring class created via
   a call to the class' or super-class' ``__new__`` method.
 
-Note that a child class cannot assign to any read-only attributes of a parent class
-in any of the aforementioned contexts, unless the attribute is redeclared.
-
 .. code-block:: python
 
     from collections import abc
@@ -332,6 +333,25 @@ in any of the aforementioned contexts, unless the attribute is redeclared.
             self.numerator, self.denominator = f.as_integer_ratio()
             return self
 
+Class Attributes
+''''''''''''''''
+
+Read-only class attributes are attributes annotated as both ``ReadOnly`` and ``ClassVar``.
+Assignment to such attributes must be allowed in the following contexts:
+
+* At declaration in the body of the class.
+* In ``__init_subclass__``, on the class object received as the first parameter (likely, ``cls``).
+
+.. code-block:: python
+
+    class URI:
+        protocol: ReadOnly[ClassVar[str]] = ""
+
+        def __init_subclass__(cls, protocol: str = "") -> None:
+            cls.protocol = protocol
+
+    class File(URI, protocol="file"): ...
+
 When a class-level declaration has an initializing value, it can serve as a `flyweight <https://en.wikipedia.org/wiki/Flyweight_pattern>`_
 default for instances:
 
@@ -367,8 +387,8 @@ protocols or ABCs)::
 Subtyping
 ---------
 
-Read-only attributes are covariant. This has a few subtyping implications.
-Borrowing from :pep:`705#inheritance`:
+The inability to reassign read-only attributes makes them covariant.
+This has a few subtyping implications. Borrowing from :pep:`705#inheritance`:
 
 * Read-only attributes can be redeclared as writable attributes, descriptors
   or class variables::
@@ -493,9 +513,6 @@ Interaction with Other Type Qualifiers
 This is consistent with the interaction of ``ReadOnly`` and :class:`typing.TypedDict`
 defined in :pep:`705`.
 
-An attribute annotated as both ``ReadOnly`` and ``ClassVar`` can only be assigned to
-at declaration in the class body.
-
 An attribute cannot be annotated as both ``ReadOnly`` and ``Final``, as the two
 qualifiers differ in semantics, and ``Final`` is generally more restrictive.
 ``Final`` remains allowed as an annotation of attributes that are only implied
@@ -604,23 +621,6 @@ to allow initialization in. This however could easily result in users mistakenly
 or purposefully breaking the aforementioned invariants. It is also a fairly
 big ask for a relatively niche feature.
 
-``ReadOnly[ClassVar[...]]`` and ``__init_subclass__``
------------------------------------------------------
-
-Should read-only class variables be assignable to within the declaring class'
-``__init_subclass__``?
-
-.. code-block:: python
-
-    class URI:
-        protocol: ReadOnly[ClassVar[str]] = ""
-
-        def __init_subclass__(cls, protocol: str = "") -> None:
-            cls.foo = protocol
-
-    class File(URI, protocol="file"): ...
-
-
 Footnotes
 =========
 
diff --git a/peps/pep-0768.rst b/peps/pep-0768.rst
@@ -136,20 +136,19 @@ A new structure is added to PyThreadState to support remote debugging:
 
     typedef struct _remote_debugger_support {
         int debugger_pending_call;
-        char debugger_script[MAX_SCRIPT_SIZE];
+        char debugger_script_path[MAX_SCRIPT_PATH_SIZE];
     } _PyRemoteDebuggerSupport;
 
-
 This structure is appended to ``PyThreadState``, adding only a few fields that
 are **never accessed during normal execution**. The ``debugger_pending_call`` field
 indicates when a debugger has requested execution, while ``debugger_script``
 provides Python code to be executed when the interpreter reaches a safe point.
 
-The value for ``MAX_SCRIPT_SIZE`` will be a trade-off between binary size and
-how big debugging scripts can be. As most of the logic should be in libraries
-and arbitrary code can be executed with very short amount of Python we are
-proposing to start with 4kb initially. This value can be extended in the future
-if we ever need to.
+The value for ``MAX_SCRIPT_PATH_SIZE`` will be a trade-off between binary size
+and how big debugging scripts' paths can be. To limit the memory overhead per
+thread we will be limiting this to 512 bytes. This size will also be provided as
+part of the debugger support structure so debuggers know how much they can
+write. This value can be extended in the future if we ever need to.
 
 
 Debug Offsets Table
@@ -168,18 +167,20 @@ debugger support:
 .. code-block:: C
 
     struct _debugger_support {
-        uint64_t eval_breaker;            // Location of the eval breaker flag
-        uint64_t remote_debugger_support; // Offset to our support structure
-        uint64_t debugger_pending_call;   // Where to write the pending flag
-        uint64_t debugger_script;         // Where to write the script path
+        uint64_t eval_breaker;              // Location of the eval breaker flag
+        uint64_t remote_debugger_support;   // Offset to our support structure
+        uint64_t debugger_pending_call;     // Where to write the pending flag
+        uint64_t debugger_script_path;      // Where to write the script path
+        uint64_t debugger_script_path_size; // Size of the script path buffer
     } debugger_support;
 
 These offsets allow debuggers to locate critical debugging control structures in
 the target process's memory space. The ``eval_breaker`` and ``remote_debugger_support``
 offsets are relative to each ``PyThreadState``, while the ``debugger_pending_call``
 and ``debugger_script`` offsets are relative to each ``_PyRemoteDebuggerSupport``
 structure, allowing the new structure and its fields to be found regardless of
-where they are in memory.
+where they are in memory. ``debugger_script_path_size`` informs the attaching
+tool of the size of the buffer.
 
 Attachment Protocol
 -------------------
@@ -201,7 +202,7 @@ When a debugger wants to attach to a Python process, it follows these steps:
 
    - Write a filename containing Python code to be executed into the
      ``debugger_script`` field in ``_PyRemoteDebuggerSupport``.
-   - Set ``debugger_pending_call`` flag in ``_PyRemoteDebuggerSupport``
+   - Set ``debugger_pending_call`` flag in ``_PyRemoteDebuggerSupport`` to 1
    - Set ``_PY_EVAL_PLEASE_STOP_BIT`` in the ``eval_breaker`` field
 
 Once the interpreter reaches the next safe point, it will execute the script
@@ -224,6 +225,9 @@ the interpreter will execute the provided debugging code at the next safe point.
 This all happens in a completely safe context, since the interpreter is
 guaranteed to be in a consistent state whenever the eval breaker is checked.
 
+The only valid values for ``debugger_pending_call`` will initially be 0 and 1
+and other values are reserved for future use.
+
 An audit event will be raised before the code is executed, allowing this mechanism
 to be audited or disabled if desired by a system's administrator.
 
@@ -464,6 +468,21 @@ in the file path to point to somewhere attacker controlled, this would allow
 them to force their malicious code to be executed rather than the code the
 debugger intends to run.
 
+Using a Single Runtime Buffer
+-----------------------------
+
+During the review of this PEP it has been suggested using a single
+shared buffer at the runtime level for all debugger communications. While this
+appeared simpler and required less memory, we discovered it would actually prevent scenarios
+where multiple debuggers need to coordinate operations across different threads,
+or where a single debugger needs to orchestrate complex debugging operations. A
+single shared buffer would force serialization of all debugging operations,
+making it impossible for debuggers to work independently on different threads.
+
+The per-thread buffer approach, despite its memory overhead in highly threaded
+applications, enables these important debugging scenarios by allowing each
+debugger to communicate independently with its target thread. 
+
 Thanks
 ======
 
diff --git a/peps/pep-0769.rst b/peps/pep-0769.rst
diff --git a/peps/pep-0770.rst b/peps/pep-0770.rst
diff --git a/requirements.txt b/requirements.txt
