Merge branch 'main' into gh-builtit-bug

Author: johng

.github/workflows/reusable-wasi.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-26.04-arm
     timeout-minutes: 60
     env:
-      WASMTIME_VERSION: 38.0.3
+      WASMTIME_VERSION: 48.0.2
       CROSS_BUILD_WASI: cross-build/wasm32-wasip1
     steps:
     - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

.pre-commit-config.yaml

@@ -143,6 +143,15 @@ repos:
         entry: Space found in path, move to Misc/NEWS.d/next/Core_and_Builtins/
         files: Misc/NEWS.d/next/Core and Builtins/20.*.rst
 
+  - repo: local
+    hooks:
+      - id: check-capi-macros
+        name: Check C API macros start with Py
+        language: python
+        entry: python Tools/build/check_capi_macros.py
+        pass_filenames: false
+        files: ^(Include/(cpython/)?[^/]+\.h|pyconfig\.h\.in|Tools/build/check_capi_macros)
+
   - repo: meta
     hooks:
       - id: check-hooks-apply

Doc/Makefile

@@ -191,8 +191,8 @@ lock:
 # Dependencies have a 14 day cooldown period to mitigate supply chain attacks,
 # except for sphinx_linklint and python-docs-theme, which are maintained by
 # core team members.
-	uv pip compile requirements.txt \
-		--exclude-newer P14D \
+	$(UV) pip compile requirements.txt \
+		--upgrade --exclude-newer P14D \
 		--exclude-newer-package sphinx_linklint=PT0S \
 		--exclude-newer-package python-docs-theme=PT0S \
 		--no-cache --output-file $(REQUIREMENTS) \

Doc/c-api/unicode.rst

@@ -16,6 +16,13 @@ points must be below 1114112 (which is the full Unicode range).
 
 UTF-8 representation is created on demand and cached in the Unicode object.
 
+.. impl-detail::
+
+   The internal buffer always includes an extra trailing null character for
+   compatibility with null terminated C strings. This extra character is not
+   counted in :c:func:`PyUnicode_GetLength` nor in the various *size* arguments
+   of the functions below.
+
 .. note::
    The :c:type:`Py_UNICODE` representation has been removed since Python 3.12
    with deprecated APIs.
@@ -164,11 +171,15 @@ access to internal read-only data of Unicode objects:
    .. versionadded:: 3.3
 
 
-.. c:function:: Py_UCS4 PyUnicode_READ(int kind, void *data, \
-                                       Py_ssize_t index)
+.. c:function:: Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)
 
    Read a code point from a canonical representation *data* (as obtained with
-   :c:func:`PyUnicode_DATA`).  No checks or ready calls are performed.
+   :c:func:`PyUnicode_DATA`).  No checks are performed.
+
+   .. impl-detail::
+
+      Accept reading the trailing null character at index
+      :c:func:`PyUnicode_GetLength`.
 
    .. versionadded:: 3.3
 
@@ -179,6 +190,11 @@ access to internal read-only data of Unicode objects:
    representation.  This is less efficient than :c:func:`PyUnicode_READ` if you
    do multiple consecutive reads.
 
+   .. impl-detail::
+
+      Accept reading the trailing null character at index
+      :c:func:`PyUnicode_GetLength`.
+
    .. versionadded:: 3.3
 
 
@@ -716,6 +732,10 @@ APIs:
 
    On error, set an exception and return ``-1``.
 
+   .. impl-detail::
+
+      The length does not count the trailing null character.
+
    .. versionadded:: 3.3
 
 
@@ -794,6 +814,11 @@ APIs:
 
    Return character on success, ``-1`` on error with an exception set.
 
+   .. impl-detail::
+
+      Do not accept reading the trailing null character at index
+      :c:func:`PyUnicode_GetLength`.
+
    .. versionadded:: 3.3
 
 

Doc/conf.py

@@ -636,3 +636,40 @@
     "library/threadsafety.rst": "builtins/threadsafety.rst",
     "library/time-complexity.rst": "builtins/time-complexity.rst",
 }
+
+# Refuse to run the doctest builder under a mismatched Python
+# -----------------------------------------------------------
+
+
+def _check_doctest_interpreter(app):
+    # The doctests are executed by the interpreter running Sphinx,
+    # so refuse to run them if its version doesn't match the source tree.
+    if app.builder.name != "doctest":
+        return
+
+    running_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    if running_version != version:
+        from sphinx.util import logging as sphinx_logging
+
+        logger = sphinx_logging.getLogger(__name__)
+        logger.error(
+            "The doctests are executed by the Python running Sphinx, "
+            "which is Python %s, however this source tree is Python %s, "
+            "so they would test Python %s rather than the code "
+            "documented here.\n"
+            "Recreate the venv with a matching interpreter, for example: "
+            "'make clean-venv && make venv PYTHON=../python'.",
+            running_version,
+            version,
+            running_version,
+        )
+        raise SystemExit(1)
+
+
+def setup(app):
+    app.connect("builder-inited", _check_doctest_interpreter)
+    return {
+        "version": "1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

Doc/library/asyncio-task.rst

@@ -175,6 +175,9 @@ other coroutines::
    * a *coroutine object*: an object returned by calling a
      *coroutine function*.
 
+   Generator-based coroutines, created with :func:`types.coroutine`, are
+   covered by neither term and are not supported by asyncio.
+
 
 .. rubric:: Tasks
 
@@ -1220,6 +1223,10 @@ Introspection
 
    .. versionadded:: 3.4
 
+   .. versionchanged:: 3.12
+      Generator-based coroutines are no longer supported, and ``False``
+      is returned for them.
+
 .. _asyncio-task-obj:
 
 Task object

Doc/library/ctypes.rst

@@ -997,6 +997,15 @@ Generally you only use this feature if you receive a pointer from a C function,
 and you *know* that the pointer actually points to an array instead of a single
 item.
 
+.. warning::
+
+   Because pointer objects support subscription, they implicitly support
+   :term:`iteration <iterator>`. Unless doing this in a controlled manner,
+   such as by manually calling :func:`next` on a :func:`pointer` iterator, this
+   will typically lead to infinite loops or crashes, because ctypes has no way
+   of knowing when to stop iteration. In other words, a ``pointer`` iterator
+   will infinitely yield arbitrary memory.
+
 Behind the scenes, the :func:`pointer` function does more than simply create
 pointer instances, it has to create pointer *types* first. This is done with the
 :func:`POINTER` function, which accepts any :mod:`!ctypes` type, and returns a
@@ -3383,3 +3392,47 @@ Exceptions
    .. availability:: Windows
 
    .. versionadded:: 3.14
+
+
+Library version
+^^^^^^^^^^^^^^^
+
+The following constants are only available if :mod:`!ctypes` was built with
+libffi 3.5 or later, which is the first version providing this information.
+
+.. data:: LIBFFI_VERSION
+
+   The version string of the libffi library that was used for building
+   the module, like ``'3.5.2'``.
+   This may be different from the libffi library actually used at runtime,
+   which is available as :const:`libffi_version`.
+
+   .. versionadded:: next
+
+.. data:: libffi_version
+
+   The version string of the libffi library actually loaded by the interpreter.
+
+   .. versionadded:: next
+
+.. data:: LIBFFI_VERSION_INFO
+
+   A named tuple containing the three components of the libffi library
+   version that was used for building the module:
+   *major*, *minor*, and *patch*.
+   All values are integers.
+   The components can also be accessed by name,
+   so ``ctypes.LIBFFI_VERSION_INFO[0]`` is equivalent to
+   ``ctypes.LIBFFI_VERSION_INFO.major`` and so on.
+   This may be different from the libffi library actually used at runtime,
+   which is available as :const:`libffi_version_info`.
+
+   .. versionadded:: next
+
+.. data:: libffi_version_info
+
+   A named tuple containing the version of the libffi library
+   actually loaded by the interpreter,
+   with the same fields as :const:`LIBFFI_VERSION_INFO`.
+
+   .. versionadded:: next

Doc/library/ipaddress.rst

@@ -261,7 +261,7 @@ write code that handles both IP versions correctly.  Address objects are
 
    .. attribute:: ipv6_mapped
 
-      :class:`IPv4Address` object representing the IPv4-mapped IPv6 address. See :RFC:`4291`.
+      :class:`IPv6Address` object representing the IPv4-mapped IPv6 address. See :RFC:`4291`.
 
       .. versionadded:: 3.13
 

Doc/library/json.rst

@@ -234,6 +234,16 @@ Basic Usage
       If ``True``, dictionaries will be outputted sorted by key.
       Default ``False``.
 
+   .. note::
+
+      Keys in key/value pairs of JSON are always of the type :class:`str`. When
+      a dictionary is converted into JSON, all the keys of the dictionary are
+      converted to strings. As a result of this, if a dictionary is converted
+      into JSON and then back into a dictionary, the dictionary may not equal
+      the original one. That is, ``loads(dumps(x)) != x`` if x has non-string
+      keys. *sort_keys* sorts the keys before they are converted to strings,
+      so numeric keys are sorted by value, not by their string representation.
+
    .. versionchanged:: 3.2
       Allow strings for *indent* in addition to integers.
 
@@ -253,17 +263,6 @@ Basic Usage
    table <py-to-json-table>`.  The arguments have the same meaning as in
    :func:`dump`.
 
-   .. note::
-
-      Keys in key/value pairs of JSON are always of the type :class:`str`. When
-      a dictionary is converted into JSON, all the keys of the dictionary are
-      coerced to strings. As a result of this, if a dictionary is converted
-      into JSON and then back into a dictionary, the dictionary may not equal
-      the original one. That is, ``loads(dumps(x)) != x`` if x has non-string
-      keys.
-      *sort_keys* sorts the keys before they are coerced to strings,
-      so numeric keys are sorted by value, not by their string representation.
-
 .. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, \
                    parse_int=None, parse_constant=None, \
                    object_pairs_hook=None, array_hook=None, **kw)

Doc/library/statistics.rst

@@ -306,6 +306,11 @@ However, for reading convenience, most of the examples show sorted sequences.
    .. image:: kde_example.png
       :alt: Scatter plot of the estimated probability density function.
 
+   Because the returned ``f_hat`` function is typically called many times,
+   it caches the *data* for performance. To support dynamic datasets, this
+   cache automatically refreshes whenever the length of the *data* changes.
+   This allows new samples to be added as they become available.
+
    .. versionadded:: 3.13