Merge branch 'main' into use-stackrefs

Author: markshannon

.github/workflows/build.yml

@@ -120,7 +120,7 @@ jobs:
       - name: Build CPython
         run: |
           make -j4 regen-all
-          make regen-stdlib-module-names regen-sbom
+          make regen-stdlib-module-names regen-sbom regen-unicodedata
       - name: Check for changes
         run: |
           git add -u

Doc/c-api/stable.rst

@@ -66,7 +66,7 @@ Limited C API
 
 Python 3.2 introduced the *Limited API*, a subset of Python's C API.
 Extensions that only use the Limited API can be
-compiled once and work with multiple versions of Python.
+compiled once and be loaded on multiple versions of Python.
 Contents of the Limited API are :ref:`listed below <limited-api-list>`.
 
 .. c:macro:: Py_LIMITED_API
@@ -76,7 +76,7 @@ Contents of the Limited API are :ref:`listed below <limited-api-list>`.
 
    Define ``Py_LIMITED_API`` to the value of :c:macro:`PY_VERSION_HEX`
    corresponding to the lowest Python version your extension supports.
-   The extension will work without recompilation with all Python 3 releases
+   The extension will be ABI-compatible with all Python 3 releases
    from the specified one onward, and can use Limited API introduced up to that
    version.
 
@@ -94,7 +94,15 @@ Stable ABI
 ----------
 
 To enable this, Python provides a *Stable ABI*: a set of symbols that will
-remain compatible across Python 3.x versions.
+remain ABI-compatible across Python 3.x versions.
+
+.. note::
+
+   The Stable ABI prevents ABI issues, like linker errors due to missing
+   symbols or data corruption due to changes in structure layouts or function
+   signatures.
+   However, other changes in Python can change the *behavior* of extensions.
+   See Python's Backwards Compatibility Policy (:pep:`387`) for details.
 
 The Stable ABI contains symbols exposed in the :ref:`Limited API
 <limited-c-api>`, but also other ones – for example, functions necessary to

Doc/howto/free-threading-extensions.rst

@@ -167,6 +167,8 @@ that return :term:`strong references <strong reference>`.
 +-----------------------------------+-----------------------------------+
 | :c:func:`PyImport_AddModule`      | :c:func:`PyImport_AddModuleRef`   |
 +-----------------------------------+-----------------------------------+
+| :c:func:`PyCell_GET`              | :c:func:`PyCell_Get`              |
++-----------------------------------+-----------------------------------+
 
 Not all APIs that return borrowed references are problematic.  For
 example, :c:func:`PyTuple_GetItem` is safe because tuples are immutable.

Doc/howto/logging.rst

@@ -127,7 +127,7 @@ that; formatting options will also be explained later.
 
 Notice that in this example, we use functions directly on the ``logging``
 module, like ``logging.debug``, rather than creating a logger and calling
-functions on it. These functions operation on the root logger, but can be useful
+functions on it. These functions operate on the root logger, but can be useful
 as they will call :func:`~logging.basicConfig` for you if it has not been called yet, like in
 this example.  In larger programs you'll usually want to control the logging
 configuration explicitly however - so for that reason as well as others, it's

Doc/library/collections.rst

@@ -783,10 +783,10 @@ sequence of key-value pairs into a dictionary of lists:
 
 When each key is encountered for the first time, it is not already in the
 mapping; so an entry is automatically created using the :attr:`~defaultdict.default_factory`
-function which returns an empty :class:`list`.  The :meth:`list.append`
+function which returns an empty :class:`list`.  The :meth:`!list.append`
 operation then attaches the value to the new list.  When keys are encountered
 again, the look-up proceeds normally (returning the list for that key) and the
-:meth:`list.append` operation adds another value to the list. This technique is
+:meth:`!list.append` operation adds another value to the list. This technique is
 simpler and faster than an equivalent technique using :meth:`dict.setdefault`:
 
     >>> d = {}

Doc/library/ctypes.rst

@@ -1949,6 +1949,24 @@ Utility functions
    It behaves similar to ``pointer(obj)``, but the construction is a lot faster.
 
 
+.. function:: CopyComPointer(src, dst)
+
+   Copies a COM pointer from *src* to *dst* and returns the Windows specific
+   :c:type:`!HRESULT` value.
+
+   If *src* is not ``NULL``, its ``AddRef`` method is called, incrementing the
+   reference count.
+
+   In contrast, the reference count of *dst* will not be decremented before
+   assigning the new value. Unless *dst* is ``NULL``, the caller is responsible
+   for decrementing the reference count by calling its ``Release`` method when
+   necessary.
+
+   .. availability:: Windows
+
+   .. versionadded:: next
+
+
 .. function:: cast(obj, type)
 
    This function is similar to the cast operator in C. It returns a new instance

Doc/library/errno.rst

@@ -613,6 +613,13 @@ defined by the module.  The specific list of defined symbols is available as
    No route to host
 
 
+.. data:: EHWPOISON
+
+   Memory page has hardware error.
+
+   .. versionadded:: next
+
+
 .. data:: EALREADY
 
    Operation already in progress. This error is mapped to the

Doc/library/io.rst

@@ -64,6 +64,12 @@ In-memory text streams are also available as :class:`StringIO` objects::
 
    f = io.StringIO("some initial text data")
 
+.. note::
+
+   When working with a non-blocking stream, be aware that read operations on text I/O objects
+   might raise a :exc:`BlockingIOError` if the stream cannot perform the operation
+   immediately.
+
 The text stream API is described in detail in the documentation of
 :class:`TextIOBase`.
 
@@ -770,6 +776,11 @@ than raw I/O does.
       Read and return *size* bytes, or if *size* is not given or negative, until
       EOF or if the read call would block in non-blocking mode.
 
+      .. note::
+
+         When the underlying raw stream is non-blocking, a :exc:`BlockingIOError`
+         may be raised if a read operation cannot be completed immediately.
+
    .. method:: read1(size=-1, /)
 
       Read and return up to *size* bytes with only one call on the raw stream.
@@ -779,6 +790,10 @@ than raw I/O does.
       .. versionchanged:: 3.7
          The *size* argument is now optional.
 
+      .. note::
+
+         When the underlying raw stream is non-blocking, a :exc:`BlockingIOError`
+         may be raised if a read operation cannot be completed immediately.
 
 .. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)
 
@@ -1007,6 +1022,11 @@ Text I/O
    .. versionchanged:: 3.10
       The *encoding* argument now supports the ``"locale"`` dummy encoding name.
 
+   .. note::
+
+      When the underlying raw stream is non-blocking, a :exc:`BlockingIOError`
+      may be raised if a read operation cannot be completed immediately.
+
    :class:`TextIOWrapper` provides these data attributes and methods in
    addition to those from :class:`TextIOBase` and :class:`IOBase`:
 

Doc/library/itertools.rst

@@ -877,6 +877,11 @@ and :term:`generators <generator>` which incur interpreter overhead.
        "Returns the sequence elements n times."
        return chain.from_iterable(repeat(tuple(iterable), n))
 
+   def loops(n):
+       "Loop n times. Like range(n) but without creating integers."
+       # for _ in loops(100): ...
+       return repeat(None, n)
+
    def tail(n, iterable):
        "Return an iterator over the last n items."
        # tail(3, 'ABCDEFG') → E F G
@@ -1099,6 +1104,11 @@ The following recipes have a more mathematical flavor:
            data[p*p : n : p+p] = bytes(len(range(p*p, n, p+p)))
        yield from iter_index(data, 1, start=3)
 
+   def is_prime(n):
+       "Return True if n is prime."
+       # is_prime(1_000_000_000_000_403) → True
+       return n > 1 and all(n % p for p in sieve(math.isqrt(n) + 1))
+
    def factor(n):
        "Prime factors of n."
        # factor(99) → 3 3 11
@@ -1202,6 +1212,16 @@ The following recipes have a more mathematical flavor:
     [0, 2, 4, 6]
 
 
+    >>> for _ in loops(5):
+    ...     print('hi')
+    ...
+    hi
+    hi
+    hi
+    hi
+    hi
+
+
     >>> list(tail(3, 'ABCDEFG'))
     ['E', 'F', 'G']
     >>> # Verify the input is consumed greedily
@@ -1475,6 +1495,23 @@ The following recipes have a more mathematical flavor:
     True
 
 
+    >>> small_primes = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97]
+    >>> list(filter(is_prime, range(-100, 100))) == small_primes
+    True
+    >>> carmichael = {561, 1105, 1729, 2465, 2821, 6601, 8911}  # https://oeis.org/A002997
+    >>> any(map(is_prime, carmichael))
+    False
+    >>> # https://www.wolframalpha.com/input?i=is+128884753939+prime
+    >>> is_prime(128_884_753_939)           # large prime
+    True
+    >>> is_prime(999953 * 999983)           # large semiprime
+    False
+    >>> is_prime(1_000_000_000_000_007)     # factor() example
+    False
+    >>> is_prime(1_000_000_000_000_403)     # factor() example
+    True
+
+
     >>> list(factor(99))                    # Code example 1
     [3, 3, 11]
     >>> list(factor(1_000_000_000_000_007)) # Code example 2

Doc/library/traceback.rst

@@ -157,6 +157,13 @@ Module-Level Functions
    arguments have the same meaning as for :func:`print_stack`.
 
 
+.. function:: print_list(extracted_list, file=None)
+
+   Print the list of tuples as returned by :func:`extract_tb` or
+   :func:`extract_stack` as a formatted stack trace to the given file.
+   If *file* is ``None``, the output is written to :data:`sys.stderr`.
+
+
 .. function:: format_list(extracted_list)
 
    Given a list of tuples or :class:`FrameSummary` objects as returned by