6 files changed, 78 insertions, 25 deletions
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 3bbc990b632..49dbc8d71cc 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -685,6 +685,7 @@ Building values
 
    ``p`` (:class:`bool`) [int]
       Convert a C :c:expr:`int` to a Python :class:`bool` object.
+
       .. versionadded:: 3.14
 
    ``c`` (:class:`bytes` of length 1) [char]
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index c8e1b5c2461..885dbeb7530 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -982,6 +982,7 @@ the variables:
 
 .. index::
    single: PyExc_BaseException (C var)
+   single: PyExc_BaseExceptionGroup (C var)
    single: PyExc_Exception (C var)
    single: PyExc_ArithmeticError (C var)
    single: PyExc_AssertionError (C var)
@@ -1041,6 +1042,8 @@ the variables:
 +=========================================+=================================+==========+
 | :c:data:`PyExc_BaseException`           | :exc:`BaseException`            | [1]_     |
 +-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_BaseExceptionGroup`      | :exc:`BaseExceptionGroup`       | [1]_     |
++-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_Exception`               | :exc:`Exception`                | [1]_     |
 +-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ArithmeticError`         | :exc:`ArithmeticError`          | [1]_     |
@@ -1164,6 +1167,9 @@ the variables:
 .. versionadded:: 3.6
    :c:data:`PyExc_ModuleNotFoundError`.
 
+.. versionadded:: 3.11
+   :c:data:`PyExc_BaseExceptionGroup`.
+
 These are compatibility aliases to :c:data:`PyExc_OSError`:
 
 .. index::
@@ -1207,6 +1213,7 @@ the variables:
    single: PyExc_Warning (C var)
    single: PyExc_BytesWarning (C var)
    single: PyExc_DeprecationWarning (C var)
+   single: PyExc_EncodingWarning (C var)
    single: PyExc_FutureWarning (C var)
    single: PyExc_ImportWarning (C var)
    single: PyExc_PendingDeprecationWarning (C var)
@@ -1225,6 +1232,8 @@ the variables:
 +------------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_DeprecationWarning`       | :exc:`DeprecationWarning`       |          |
 +------------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_EncodingWarning`          | :exc:`EncodingWarning`          |          |
++------------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_FutureWarning`            | :exc:`FutureWarning`            |          |
 +------------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ImportWarning`            | :exc:`ImportWarning`            |          |
@@ -1245,6 +1254,9 @@ the variables:
 .. versionadded:: 3.2
    :c:data:`PyExc_ResourceWarning`.
 
+.. versionadded:: 3.10
+   :c:data:`PyExc_EncodingWarning`.
+
 Notes:
 
 .. [3]
diff --git a/Doc/c-api/lifecycle.rst b/Doc/c-api/lifecycle.rst
index 0e2ffc096ca..5a170862a26 100644
--- a/Doc/c-api/lifecycle.rst
+++ b/Doc/c-api/lifecycle.rst
@@ -55,16 +55,14 @@ that must be true for *B* to occur after *A*.
    .. image:: lifecycle.dot.svg
       :align: center
       :class: invert-in-dark-mode
-      :alt: Diagram showing events in an object's life.  Explained in detail
-            below.
+      :alt: Diagram showing events in an object's life.  Explained in detail below.
 
 .. only:: latex
 
    .. image:: lifecycle.dot.pdf
       :align: center
       :class: invert-in-dark-mode
-      :alt: Diagram showing events in an object's life.  Explained in detail
-            below.
+      :alt: Diagram showing events in an object's life.  Explained in detail below.
 
 .. container::
    :name: life-events-graph-description
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index f7f4d37d4c7..710135dca89 100644
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -288,22 +288,40 @@ An alternate way to specify extensions is to request "multi-phase initialization
 Extension modules created this way behave more like Python modules: the
 initialization is split between the *creation phase*, when the module object
 is created, and the *execution phase*, when it is populated.
-The distinction is similar to the :py:meth:`!__new__` and :py:meth:`!__init__` methods
-of classes.
+The distinction is similar to the :py:meth:`~object.__new__` and
+:py:meth:`~object.__init__` methods of classes.
 
 Unlike modules created using single-phase initialization, these modules are not
-singletons: if the *sys.modules* entry is removed and the module is re-imported,
-a new module object is created, and the old module is subject to normal garbage
-collection -- as with Python modules.
-By default, multiple modules created from the same definition should be
-independent: changes to one should not affect the others.
-This means that all state should be specific to the module object (using e.g.
-using :c:func:`PyModule_GetState`), or its contents (such as the module's
-:attr:`~object.__dict__` or individual classes created with :c:func:`PyType_FromSpec`).
+singletons.
+For example, if the :py:attr:`sys.modules` entry is removed and the module
+is re-imported, a new module object is created, and typically populated with
+fresh method and type objects.
+The old module is subject to normal garbage collection.
+This mirrors the behavior of pure-Python modules.
+
+Additional module instances may be created in
+:ref:`sub-interpreters <sub-interpreter-support>`
+or after after Python runtime reinitialization
+(:c:func:`Py_Finalize` and :c:func:`Py_Initialize`).
+In these cases, sharing Python objects between module instances would likely
+cause crashes or undefined behavior.
+
+To avoid such issues, each instance of an extension module should
+be *isolated*: changes to one instance should not implicitly affect the others,
+and all state, including references to Python objects, should be specific to
+a particular module instance.
+See :ref:`isolating-extensions-howto` for more details and a practical guide.
+
+A simpler way to avoid these issues is
+:ref:`raising an error on repeated initialization <isolating-extensions-optout>`.
 
 All modules created using multi-phase initialization are expected to support
-:ref:`sub-interpreters <sub-interpreter-support>`. Making sure multiple modules
-are independent is typically enough to achieve this.
+:ref:`sub-interpreters <sub-interpreter-support>`, or otherwise explicitly
+signal a lack of support.
+This is usually achieved by isolation or blocking repeated initialization,
+as above.
+A module may also be limited to the main interpreter using
+the :c:data:`Py_mod_multiple_interpreters` slot.
 
 To request multi-phase initialization, the initialization function
 (PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty
diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst
index 124e58cf950..9b65e0b8d23 100644
--- a/Doc/c-api/stable.rst
+++ b/Doc/c-api/stable.rst
@@ -51,6 +51,7 @@ It is generally intended for specialized, low-level tools like debuggers.
 Projects that use this API are expected to follow
 CPython development and spend extra effort adjusting to changes.
 
+.. _stable-application-binary-interface:
 
 Stable Application Binary Interface
 ===================================
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index cdd90d05b70..07fdcfd9729 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -191,6 +191,22 @@ access to internal read-only data of Unicode objects:
    .. versionadded:: 3.2
 
 
+.. c:function:: Py_hash_t PyUnstable_Unicode_GET_CACHED_HASH(PyObject *str)
+
+   If the hash of *str*, as returned by :c:func:`PyObject_Hash`, has been
+   cached and is immediately available, return it.
+   Otherwise, return ``-1`` *without* setting an exception.
+
+   If *str* is not a string (that is, if ``PyUnicode_Check(obj)``
+   is false), the behavior is undefined.
+
+   This function never fails with an exception.
+
+   Note that there are no guarantees on when an object's hash is cached,
+   and the (non-)existence of a cached hash does not imply that the string has
+   any other properties.
+
+
 Unicode Character Properties
 """"""""""""""""""""""""""""
 
@@ -1461,10 +1477,6 @@ the user settings on the machine running the codec.
    .. versionadded:: 3.3
 
 
-Methods & Slots
-"""""""""""""""
-
-
 .. _unicodemethodsandslots:
 
 Methods and Slot Functions
@@ -1726,10 +1738,6 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
    from user input, prefer calling :c:func:`PyUnicode_FromString` and
    :c:func:`PyUnicode_InternInPlace` directly.
 
-   .. impl-detail::
-
-      Strings interned this way are made :term:`immortal`.
-
 
 .. c:function:: unsigned int PyUnicode_CHECK_INTERNED(PyObject *str)
 
@@ -1806,9 +1814,24 @@ object.
 
    See also :c:func:`PyUnicodeWriter_DecodeUTF8Stateful`.
 
+.. c:function:: int PyUnicodeWriter_WriteASCII(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)
+
+   Write the ASCII string *str* into *writer*.
+
+   *size* is the string length in bytes. If *size* is equal to ``-1``, call
+   ``strlen(str)`` to get the string length.
+
+   *str* must only contain ASCII characters. The behavior is undefined if
+   *str* contains non-ASCII characters.
+
+   On success, return ``0``.
+   On error, set an exception, leave the writer unchanged, and return ``-1``.
+
+   .. versionadded:: next
+
 .. c:function:: int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)
 
-   Writer the wide string *str* into *writer*.
+   Write the wide string *str* into *writer*.
 
    *size* is a number of wide characters. If *size* is equal to ``-1``, call
    ``wcslen(str)`` to get the string length.