Merge branch 'main' into pagefind-search

Author: miketheman

.github/CODEOWNERS

@@ -692,6 +692,8 @@ peps/pep-0811.rst  @sethmlarson @gpshead
 peps/pep-0814.rst  @vstinner @corona10
 peps/pep-0815.rst  @emmatyping
 peps/pep-0816.rst  @brettcannon
+peps/pep-0817.rst  @warsaw @dstufft
+peps/pep-0817/     @warsaw @dstufft
 # ...
 peps/pep-0819.rst  @emmatyping
 peps/pep-0820.rst  @encukou

README.rst

@@ -20,6 +20,12 @@ Shortcut redirects are also available.
 For example, ``https://peps.python.org/8`` redirects to the canonical link.
 
 
+API
+===
+
+Several data files are available at https://peps.python.org/api/
+
+
 Contributing to PEPs
 ====================
 

pep_sphinx_extensions/pep_processor/html/pep_html_builder.py

@@ -33,7 +33,8 @@ def get_doc_context(self, docname: str, body: str, _metatags: str) -> dict:
         toc_tree = self.env.tocs[docname].deepcopy()
         if len(toc_tree) and len(toc_tree[0]) > 1:
             toc_tree = toc_tree[0][1]  # don't include document title
-            del toc_tree[0]  # remove contents node
+            if docname.startswith("pep-"):
+                del toc_tree[0]  # remove contents node from PEPs
             for node in toc_tree.findall(nodes.reference):
                 node["refuri"] = node["anchorname"] or '#'  # fix targets
             toc = self.render_partial(toc_tree)["fragment"]

peps/api/index.rst

@@ -207,3 +207,9 @@ for example:
        ]
      }
    }
+
+release-schedule.ics
+--------------------
+
+An iCalendar file of Python release dates is available at
+https://peps.python.org/api/release-schedule.ics.

peps/pep-0011.rst

@@ -9,6 +9,7 @@ Post-History: `18-Aug-2007 <https://mail.python.org/archives/list/python-dev@pyt
               `14-May-2014 <https://mail.python.org/archives/list/python-dev@python.org/thread/T7WTUJ6TD3IGYGWV3M4PHJWNLM2WPZAW/>`__,
               `20-Feb-2015 <https://mail.python.org/archives/list/python-dev@python.org/thread/OEQHRR2COYZDL6LZ42RBZOMIUB32WI34/>`__,
               `10-Mar-2022 <https://mail.python.org/archives/list/python-committers@python.org/thread/K757345KX6W5ZLTWYBUXOXQTJJTL7GW5/>`__,
+              `21-Nov-2025 <https://discuss.python.org/t/104986>`__,
 
 
 Abstract
@@ -35,15 +36,20 @@ unmaintainability: without having experts for a large number of
 platforms, it is not possible to determine whether a certain
 change to the CPython source code will work on all supported
 platforms.
-
 To reduce this risk, this PEP specifies what is required for a
-platform to be considered supported by CPython as well as providing a
-procedure to remove code for platforms with few or no CPython
-users.
+platform to be considered supported by the CPython core team,
+as well as providing a procedure to remove code for platforms
+with few or no CPython users.
+
+On the other hand, allowing these fragments in the main repository
+can promote collaboration, can help identify non-portable parts of
+the code base, and is necessary for bootstrapping support for
+a "new" platform.
+This PEP specifies what it means for a platform to be "unsupported",
+and how the core team handles code for such platforms.
 
-This PEP also lists what platforms *are* supported by the CPython
-interpreter. This lets people know what platforms are directly
-supported by the CPython development team.
+This PEP also explicitly lists what platforms are directly
+*supported* by the CPython development team.
 
 
 Support tiers
@@ -135,17 +141,43 @@ x86_64-unknown-freebsd           BSD libc, clang             Victor Stinner
 ================================ =========================== ========
 
 
-All other platforms
--------------------
+Unsupported platforms
+---------------------
+
+All platforms not listed in the above tiers are *unsupported* by the core team.
+The core team does not develop and test on such platforms, and so they
+cannot provide any promises that Python will work on them.
+
+However, the code base does include unsupported code -- that is, code
+specific to unsupported platforms.
+Contributions in this area are welcome as long as they:
+
+- pose a minimal maintenance burden to the core team, and
+- benefit substantially more people than the contributor.
+
+We assume contributors are able to maintain modifications/patches,
+test patched builds, redistribute modified code, make promises to their users,
+and otherwise support "their" platform.
+With that in mind, it is generally unnecessary to backport unsupported
+fixes to CPython's maintenance branches.
+
+Unsupported code that *does* cause a maintenance burden, or obstructs
+general improvements, may be rejected or removed from the code base
+without a deprecation process.
+Core team members that do this intentionally are encouraged to notify people
+listed in the `Platforms experts list`_ in the CPython contributor's guide,
+to review any submitted fixes (if unobtrusive), and to consider adding
+configuration or extension capabilities necessary for workarounds.
+
+People interested in unsupported platforms may add themselves to the
+`Platforms experts list`_ to request that they be notified on issues
+related to "their" platform.
+There is, however, no formal guarantee that they *will* be notified.
 
-Support for a platform may be partial within the code base, such as
-from active development around platform support or accidentally.
-Code changes to platforms not listed in the above tiers may be rejected
-or removed from the code base without a deprecation process if they
-cause a maintenance burden or obstruct general improvements.
+.. _Platforms experts list: https://devguide.python.org/core-team/experts/#platforms
 
-Platforms not listed here may be supported by the wider Python
-community in some way. If your desired platform is not listed above,
+Platforms not listed in this PEP may also be supported by the wider Python
+community in other ways. If your desired platform is not listed above,
 please perform a search online to see if someone is already providing
 support in some form.
 
@@ -207,6 +239,27 @@ source tree 3 years after the extended support for the compiler has
 ended (but continue to remain available in revision control).
 
 
+POSIX
+'''''
+
+Features specified in POSIX are expected to work according to the standard.
+This cuts two ways:
+
+- If a POSIX feature is available, it is expected to conform to POSIX.
+
+  Workarounds for out-of-spec platforms are acceptable.
+  For unsupported platforms, disabling functionality is
+  preferred over a non-trivial workaround.
+
+- CPython should make no assumptions about POSIX features beyond what's
+  specified in POSIX.
+
+  For example, while POSIX specifies ``errno`` as an ``int`` with no
+  restrictions, error codes on all supported platforms happen to be positive.
+  Relying on this would be considered a bug, even if it only manifests on
+  unsupported platforms.
+
+
 Legacy C Locale
 '''''''''''''''
 
@@ -373,6 +426,9 @@ No-longer-supported platforms
 Discussions
 ===========
 
+* November 2025: `Policy for unsupported platforms
+  <https://discuss.python.org/t/104986>`_
+  (Petr Viktorin)
 * April 2022: `Consider adding a Tier 3 to tiered platform support
   <https://mail.python.org/archives/list/python-committers@python.org/thread/V3OZPJGA5VJFYM6XYGPZIVPOIYKX6KTD/>`_
   (Victor Stinner)

peps/pep-0807.rst

@@ -114,7 +114,7 @@ apply to all parts of this PEP's specification:
   clients **MUST** reject any URLs that do not meet this constraint.
 
   In practice, this means that a discovery request to
-  ``https://upload.example.com/.well-known/pytp/{key}`` can only
+  ``https://upload.example.com/.well-known/pytp?discover={key}`` can only
   return URLs with the ``upload.example.com`` host.
 
 * All client requests **SHOULD** have an
@@ -157,39 +157,57 @@ The discovery mechanism is as follows:
    For the above example, the path component is
    ``/legacy/``.
 
-3. The uploading client takes the SHA2-256 hash of the path component,
-   producing the *discovery key*.
+3. The uploading client performs a query-safe URL encoding of the path component
+   (i.e. percent-encoding as defined in :rfc:`3986`, including encoding
+   of forward slashes and spaces), producing the *discovery key*.
 
    For the above example, the discovery key is
-   ``0cace9579789849db6e16d48df183951c8f17582200d84bc93c7678d6c8f78a7``. [#fn-hash]_
+   ``%2Flegacy%2F``. [#fn-discovery-key]_
 
 4. The uploading client constructs a *discovery URL* by taking the
    scheme and authority components (as defined in :rfc:`3986`)
-   of the upload URL and appending ``/.well-known/pytp/``
-   and the discovery key.
+   of the upload URL and appending ``/.well-known/pytp`` as the path.
+   Then, the uploading client appends the discovery key as the value
+   of the ``discover`` query parameter.
 
    For the above example, the discovery URL is
-   ``https://upload.example.com/.well-known/pytp/af030c06750716b1b35852298fe852b90def13dcbd012a5fe5148470f1206bfc``.
+   ``https://upload.example.com/.well-known/pytp?discover=%2Flegacy%2F``.
 
 5. The uploading client performs an HTTP GET request to the discovery URL.
 
 6. The server responds with a ``200 OK`` status code and a body
    containing a JSON object if the index supports Trusted Publishing
-   for the given upload URL. The JSON object **MUST** contain the following
+   for the given upload URL.
+
+   The JSON object **MUST** contain the following
    fields:
 
    - ``audience-endpoint``: a string containing the URL of the OIDC
      audience endpoint to be used during token exchange.
    - ``token-mint-endpoint``: a string containing the URL of the
      token minting endpoint to be used during token exchange.
 
+   Additionally, the JSON object **MAY** contain the following fields:
+
+   - ``features``: an array of strings indicating optional features
+     supported by the index's Trusted Publishing implementation.
+     The set of possible features is defined under `<Feature Negotiation_>`__.
+
+   - ``default-features``: an array of strings indicating the default
+     features used by the index's Trusted Publishing implementation
+     if a request does not explicitly specify any features.
+     If the ``default-features`` field is not present, the uploading client
+     **MUST** assume a default of ``["multi-use-token"]``.
+
    For the above example, a valid response body would be:
 
    .. code-block:: json
 
       {
          "audience-endpoint": "https://upload.example.com/_/oidc/audience",
-         "token-mint-endpoint": "https://upload.example.com/_/oidc/mint-token"
+         "token-mint-endpoint": "https://upload.example.com/_/oidc/mint-token",
+         "features": ["single-use-token", "multi-use-token"],
+         "default-features": ["multi-use-token"]
       }
 
 If the server does not support Trusted Publishing for the given
@@ -250,6 +268,20 @@ POST request **MUST** be a JSON object containing the following:
 
 - ``token``: a string containing the identity credential
   obtained from the Trusted Publishing provider.
+- ``features``: an **optional** array of strings
+  indicating the desired features for the minted upload credential.
+  If this field is not provided by the client, the server **MUST** use
+  its own default features as specified in the
+  ``default-features`` field during discovery.
+
+For example, a valid request body would be:
+
+.. code-block:: json
+
+   {
+      "token": "ey...",
+      "features": ["single-use-token"]
+   }
 
 On success, the server responds with a ``200 OK`` status code and a body
 containing a JSON object with the following fields:
@@ -275,6 +307,32 @@ containing a JSON object with the following fields:
 On failure, the server **MUST** respond with any standard HTTP
 error code in the 400 or 500 range to indicate the appropriate error condition.
 
+Feature Negotiation
+~~~~~~~~~~~~~~~~~~~
+
+The protocol defined in this PEP supports an *optional* mechanism for
+negotiating non-default features between the uploading client and the
+receiving index server. These features are advertised as an array of
+strings in the ``features`` field of the discovery response; the client
+can then request one or more features by including them in the ``features``
+field of the token minting request.
+
+The following features are defined:
+
+- ``single-use-token``: the tokens minted by the index server
+  **MUST** be single-use tokens. In other words, the token returned
+  by the token minting endpoint **MUST** only be usable for a single
+  upload operation. Any subsequent upload attempts using the same
+  token **MUST** be rejected by the index server. Clients that request
+  the ``single-use-token`` feature **MUST** be prepared to perform
+  multiple token minting operations if multiple upload operations
+  are needed.
+
+- ``multi-use-token``: the tokens minted by the index server
+  **MUST** be multi-use tokens. In other words, the token returned
+  by the token minting endpoint **MAY** be usable for multiple
+  upload operations until it expires.
+
 Security Implications
 =====================
 
@@ -389,17 +447,17 @@ This approach too has downsides:
 Footnotes
 =========
 
-.. [#fn-hash]
+.. [#fn-discovery-key]
 
    The discovery key may be computed thusly:
 
    .. code-block:: pycon
 
-      >>> import hashlib
+      >>> import urllib.parse
       >>> path = "/legacy/"
-      >>> key = hashlib.sha256(path.encode("utf-8")).hexdigest()
+      >>> key = urllib.parse.quote_plus(path)
       >>> print(key)
-      0cace9579789849db6e16d48df183951c8f17582200d84bc93c7678d6c8f78a7
+      '%2Flegacy%2F'
 
 .. [#fn-oidc] Widely used CI/CD and cloud providers variously implement "ambient"
               OIDC token retrieval mechanisms that aren't standardized.