[pull] main from python:main

Doc/c-api/unicode.rst

@@ -321,12 +321,22 @@ These APIs can be used to work with surrogates:
 
    Check if *ch* is a low surrogate (``0xDC00 <= ch <= 0xDFFF``).
 
+.. c:function:: Py_UCS4 Py_UNICODE_HIGH_SURROGATE(Py_UCS4 ch)
+
+    Return the high UTF-16 surrogate (``0xD800`` to ``0xDBFF``) for a Unicode
+    code point in the range ``[0x10000; 0x10FFFF]``.
+
+.. c:function:: Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch)
+
+    Return the low UTF-16 surrogate (``0xDC00`` to ``0xDFFF``) for a Unicode
+    code point in the range ``[0x10000; 0x10FFFF]``.
+
 .. c:function:: Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)
 
    Join two surrogate code points and return a single :c:type:`Py_UCS4` value.
    *high* and *low* are respectively the leading and trailing surrogates in a
-   surrogate pair. *high* must be in the range [0xD800; 0xDBFF] and *low* must
-   be in the range [0xDC00; 0xDFFF].
+   surrogate pair. *high* must be in the range ``[0xD800; 0xDBFF]`` and *low* must
+   be in the range ``[0xDC00; 0xDFFF]``.
 
 
 Creating and accessing Unicode strings

Doc/library/email.headerregistry.rst

@@ -294,7 +294,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
        ``inline`` and ``attachment`` are the only valid values in common use.
 
 
-.. class:: ContentTransferEncoding
+.. class:: ContentTransferEncodingHeader
 
    Handles the :mailheader:`Content-Transfer-Encoding` header.
 

Doc/library/http.client.rst

@@ -133,7 +133,7 @@ This module provides the following function:
 
    Parse the headers from a file pointer *fp* representing a HTTP
    request/response. The file has to be a :class:`~io.BufferedIOBase` reader
-   (i.e. not text) and must provide a valid :rfc:`2822` style header.
+   (i.e. not text) and must provide a valid :rfc:`5322` style header.
 
    This function returns an instance of :class:`http.client.HTTPMessage`
    that holds the header fields, but no payload

Doc/library/http.server.rst

@@ -154,7 +154,7 @@ instantiation, of which this module provides three different variants:
       variable. This instance parses and manages the headers in the HTTP
       request. The :func:`~http.client.parse_headers` function from
       :mod:`http.client` is used to parse the headers and it requires that the
-      HTTP request provide a valid :rfc:`2822` style header.
+      HTTP request provide a valid :rfc:`5322` style header.
 
    .. attribute:: rfile
 

Doc/library/mailbox.rst

@@ -917,7 +917,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
    copied; furthermore, any format-specific information is converted insofar as
    possible if *message* is a :class:`!Message` instance. If *message* is a string,
    a byte string,
-   or a file, it should contain an :rfc:`2822`\ -compliant message, which is read
+   or a file, it should contain an :rfc:`5322`\ -compliant message, which is read
    and parsed.  Files should be open in binary mode, but text mode files
    are accepted for backward compatibility.
 

Doc/library/time.rst

@@ -584,7 +584,7 @@ Functions
       calculations when the day of the week and the year are specified.
 
    Here is an example, a format for dates compatible with that specified  in the
-   :rfc:`2822` Internet email standard.  [1]_ ::
+   :rfc:`5322` Internet email standard.  [1]_ ::
 
       >>> from time import gmtime, strftime
       >>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
@@ -1066,4 +1066,5 @@ Timezone Constants
    strict reading of the original 1982 :rfc:`822` standard calls for a two-digit
    year (``%y`` rather than ``%Y``), but practice moved to 4-digit years long before the
    year 2000.  After that, :rfc:`822` became obsolete and the 4-digit year has
-   been first recommended by :rfc:`1123` and then mandated by :rfc:`2822`.
+   been first recommended by :rfc:`1123` and then mandated by :rfc:`2822`,
+   with :rfc:`5322` continuing this requirement.

Doc/tools/.nitignore

@@ -8,7 +8,6 @@ Doc/c-api/init_config.rst
 Doc/c-api/intro.rst
 Doc/c-api/module.rst
 Doc/c-api/stable.rst
-Doc/c-api/type.rst
 Doc/c-api/typeobj.rst
 Doc/library/ast.rst
 Doc/library/asyncio-extending.rst

Doc/tools/extensions/c_annotations.py

@@ -154,7 +154,10 @@ def add_annotations(app: Sphinx, doctree: nodes.document) -> None:
         node.insert(0, annotation)
 
 
-def _stable_abi_annotation(record: StableABIEntry) -> nodes.emphasis:
+def _stable_abi_annotation(
+    record: StableABIEntry,
+    is_corresponding_slot: bool = False,
+) -> nodes.emphasis:
     """Create the Stable ABI annotation.
 
     These have two forms:
@@ -168,9 +171,28 @@ def _stable_abi_annotation(record: StableABIEntry) -> nodes.emphasis:
     ... all of which can have "since version X.Y" appended.
     """
     stable_added = record.added
-    message = sphinx_gettext("Part of the")
-    message = message.center(len(message) + 2)
-    emph_node = nodes.emphasis(message, message, classes=["stableabi"])
+    emph_node = nodes.emphasis('', '', classes=["stableabi"])
+    if is_corresponding_slot:
+        # See "Type slot annotations" in add_annotations
+        ref_node = addnodes.pending_xref(
+            "slot ID",
+            refdomain="c",
+            reftarget="PyType_Slot",
+            reftype="type",
+            refexplicit="True",
+        )
+        ref_node += nodes.Text(sphinx_gettext("slot ID"))
+
+        message = sphinx_gettext("The corresponding")
+        emph_node += nodes.Text(" " + message + " ")
+        emph_node += ref_node
+        emph_node += nodes.Text(" ")
+        emph_node += nodes.literal(record.name, record.name)
+        message = sphinx_gettext("is part of the")
+        emph_node += nodes.Text(" " + message + " ")
+    else:
+        message = sphinx_gettext("Part of the")
+        emph_node += nodes.Text(" " + message + " ")
     ref_node = addnodes.pending_xref(
         "Stable ABI",
         refdomain="std",
@@ -265,6 +287,51 @@ def run(self) -> list[nodes.Node]:
         return [node]
 
 
+class CorrespondingTypeSlot(SphinxDirective):
+    """Type slot annotations
+
+    Docs for these are with the corresponding field, for example,
+    "Py_tp_repr" is documented under "PyTypeObject.tp_repr", with
+    only a stable ABI note mentioning "Py_tp_repr" (and linking to
+    docs on how this works).
+
+    If there is no corresponding field, these should be documented as normal
+    macros.
+    """
+
+    has_content = False
+
+    required_arguments = 1
+    optional_arguments = 0
+
+    def run(self) -> list[nodes.Node]:
+        name = self.arguments[0]
+        state = self.env.domaindata["c_annotations"]
+        stable_abi_data = state["stable_abi_data"]
+
+        try:
+            record = stable_abi_data[name]
+        except LookupError as err:
+            raise LookupError(
+                f"{name} is not part of stable ABI. "
+                + "Document it as `c:macro::` rather than "
+                + "`corresponding-type-slot::`."
+            ) from err
+
+        annotation = _stable_abi_annotation(record, is_corresponding_slot=True)
+
+        node = nodes.paragraph()
+        content = [
+            ".. c:namespace:: NULL",
+            "",
+            ".. c:macro:: " + name,
+            "   :no-typesetting:",
+        ]
+        self.state.nested_parse(StringList(content), 0, node)
+        node.insert(0, annotation)
+        return [node]
+
+
 def init_annotations(app: Sphinx) -> None:
     # Using domaindata is a bit hack-ish,
     # but allows storing state without a global variable or closure.
@@ -281,6 +348,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_config_value("refcount_file", "", "env", types={str})
     app.add_config_value("stable_abi_file", "", "env", types={str})
     app.add_directive("limited-api-list", LimitedAPIList)
+    app.add_directive("corresponding-type-slot", CorrespondingTypeSlot)
     app.connect("builder-inited", init_annotations)
     app.connect("doctree-read", add_annotations)
 

Doc/tutorial/stdlib.rst

@@ -335,7 +335,7 @@ sophisticated and robust capabilities of its larger packages. For example:
   names, no direct knowledge or handling of XML is needed.
 
 * The :mod:`email` package is a library for managing email messages, including
-  MIME and other :rfc:`2822`-based message documents. Unlike :mod:`smtplib` and
+  MIME and other :rfc:`5322`-based message documents. Unlike :mod:`smtplib` and
   :mod:`poplib` which actually send and receive messages, the email package has
   a complete toolset for building or decoding complex message structures
   (including attachments) and for implementing internet encoding and header