Merge branch 'main' into bugifx

Author: lpyu001

.github/CODEOWNERS

@@ -630,7 +630,7 @@ Lib/test/test_unittest/testmock/ @cjw296
 Doc/library/zlib.rst          @StanFromIreland
 Lib/compression/zlib.py       @StanFromIreland
 Lib/test/test_zlib.py         @StanFromIreland
-Modules/_zlibmodule.c         @StanFromIreland
+Modules/zlibmodule.c          @StanFromIreland
 
 # Zipfile.Path
 Lib/test/test_zipfile/_path/  @jaraco

.github/workflows/reusable-docs.yml

@@ -86,6 +86,9 @@ jobs:
           --fail-if-regression \
           --fail-if-improved \
           --fail-if-new-news-nit
+    - name: 'Build list of changes'
+      run: |
+        make -C Doc/ PYTHON=../python changes
     - name: 'Collect HTML IDs'
       if: github.event_name == 'pull_request'
       run: python Doc/tools/check-html-ids.py collect Doc/build/html -o Doc/build/html-ids-head.json.gz

Doc/library/constants.rst Doc/builtins/constants.rstDoc/library/constants.rst renamed to Doc/builtins/constants.rst

@@ -129,7 +129,7 @@ are always available.  They are listed here in alphabetical order.
                        anext(async_iterator, default, /)
 
    When awaited, return the next item from the given :term:`asynchronous
-   iterator`, or *default* if given and the iterator is exhausted.
+   iterator`, or *default* if given and the iterator is :term:`exhausted`.
 
    This is the async variant of the :func:`next` builtin, and behaves
    similarly.
@@ -1223,7 +1223,7 @@ are always available.  They are listed here in alphabetical order.
               process_block(block)
 
    *stop_exception* is useful for callables
-   which report exhaustion by raising an exception
+   which report :term:`exhaustion <exhausted>` by raising an exception
    instead of returning a special value.
    For example, draining a queue::
 
@@ -1315,7 +1315,7 @@ are always available.  They are listed here in alphabetical order.
    yielding the results.  If additional *iterables* arguments are passed,
    *function* must take that many arguments and is applied to the items from all
    iterables in parallel.  With multiple iterables, the iterator stops when the
-   shortest iterable is exhausted.  If *strict* is ``True`` and one of the
+   shortest iterable is :term:`exhausted`.  If *strict* is ``True`` and one of the
    iterables is exhausted before the others, a :exc:`ValueError` is raised. For
    cases where the function inputs are already arranged into argument tuples,
    see :func:`itertools.starmap`.
@@ -1397,7 +1397,7 @@ are always available.  They are listed here in alphabetical order.
 
    Retrieve the next item from the :term:`iterator` by calling its
    :meth:`~iterator.__next__` method.  If *default* is given, it is returned
-   if the iterator is exhausted, otherwise :exc:`StopIteration` is raised.
+   if the iterator is :term:`exhausted`, otherwise :exc:`StopIteration` is raised.
 
 
 .. class:: object()
@@ -2312,7 +2312,7 @@ are always available.  They are listed here in alphabetical order.
    the code that prepared these iterables.  Python offers three different
    approaches to dealing with this issue:
 
-   * By default, :func:`zip` stops when the shortest iterable is exhausted.
+   * By default, :func:`zip` stops when the shortest iterable is :term:`exhausted`.
      It will ignore the remaining items in the longer iterables, cutting off
      the result to the length of the shortest iterable::
 
@@ -2327,7 +2327,7 @@ are always available.  They are listed here in alphabetical order.
         [('a', 1), ('b', 2), ('c', 3)]
 
      Unlike the default behavior, it raises a :exc:`ValueError` if one iterable
-     is exhausted before the others:
+     is :term:`exhausted` before the others:
 
         >>> for item in zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True):  # doctest: +SKIP
         ...     print(item)

Doc/library/exceptions.rst Doc/builtins/exceptions.rstDoc/library/exceptions.rst renamed to Doc/builtins/exceptions.rst

@@ -0,0 +1,35 @@
+.. _builtins-index:
+
+##############################
+  Python built-ins reference
+##############################
+
+Python comes with a number of built-in functions and classes.
+
+The built-in classes include data types that would normally be considered part
+of the "core" of a language, such as numbers and lists.  For these types, the
+Python language core defines the form of literals and places some constraints
+on their semantics, but does not fully define the semantics.
+
+The built-ins also include functions and exceptions --- objects that can
+be used by all Python code without the need of an :keyword:`import` statement.
+Some of these are defined by the core language, but many are not essential for
+the core semantics and are only described here.
+
+.. seealso::
+
+   In addition to the built-ins, Python provides an extensive importable
+   standard library, see :ref:`library-index`.
+
+.. We don't use :numbered: option for the TOC below as it enforces
+   numbered sections for the entire builtin docs.  If desired,
+   :numbered: can be enabled on a per-page basis.
+.. toctree::
+   :maxdepth: 2
+
+   stdtypes.rst
+   constants.rst
+   functions.rst
+   exceptions.rst
+   threadsafety.rst
+   time-complexity.rst

Doc/library/functions.rst Doc/builtins/functions.rstDoc/library/functions.rst renamed to Doc/builtins/functions.rst

@@ -231,6 +231,7 @@ called with a non-bytes parameter.
    Resize a bytes object. *newsize* will be the new length of the bytes object.
    You can think of it as creating a new bytes object and destroying the old
    one, only more efficiently.
+
    Pass the address of an
    existing bytes object as an lvalue (it may be written into), and the new size
    desired.  On success, *\*bytes* holds the resized bytes object and ``0`` is
@@ -239,6 +240,11 @@ called with a non-bytes parameter.
    *\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is
    returned.
 
+   While bytes objects are usually immutable in Python, this special C API
+   allows mutating a bytes object in-place. The returned bytes object can still
+   be mutated using :c:func:`PyBytesWriter_GetData`; except if *newsize* is
+   zero in which case it returns the immutable empty bytes string.
+
    .. soft-deprecated:: 3.15
       Use the :c:type:`PyBytesWriter` API instead.
 
@@ -290,10 +296,10 @@ object.
 
 .. c:type:: PyBytesWriter
 
-   A bytes writer instance.
+   A bytes writer object.
 
-   The API is **not thread safe**: a writer should only be used by a single
-   thread at the same time.
+   The API is **not thread safe**. A :c:type:`PyBytesWriter` object must only
+   be used by a single thread, it must not be shared between threads.
 
    The instance must be destroyed by :c:func:`PyBytesWriter_Finish` on
    success, or :c:func:`PyBytesWriter_Discard` on error.
@@ -429,7 +435,7 @@ Low-level API
    On success, return ``0``.
    On error, set an exception and return ``-1``.
 
-   *size* can be negative to shrink the writer.
+   *grow* can be negative to shrink the writer.
 
 .. c:function:: void* PyBytesWriter_GrowAndUpdatePointer(PyBytesWriter *writer, Py_ssize_t size, void *buf)