Merge branch 'main' into deprecate-__getformat__/145633

Author: skirpichev

.claude/CLAUDE.md

@@ -0,0 +1 @@
+../AGENTS.md

.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

.gitignore

@@ -178,8 +178,12 @@ Python/frozen_modules/MANIFEST
 /python
 !/Python/
 
-# People's custom https://docs.anthropic.com/en/docs/claude-code/memory configs.
-/.claude/
+# Local AI agent scratch state (per-PR and per-branch notebooks, sandbox
+# experiments) and personal agent overrides, none of which are committed.
+/.claude/pr-*
+/.claude/branch-*
+/.claude/sandbox/
+AGENTS.local.md
 CLAUDE.local.md
 
 #### main branch only stuff below this line, things to backport go above. ####

AGENTS.md

@@ -0,0 +1,16 @@
+# AI agent guidance
+
+CPython has a [policy on the use of AI tools](https://devguide.python.org/getting-started/ai-tools/).
+All use of AI tools and agents when working on or interacting with CPython
+must follow it.
+
+> [!important]
+> **Primary directive**: Read the policy before making or proposing any changes.
+
+When acting on this repository, apply the policy's core principles:
+
+- Consider whether the change is necessary.
+- Make minimal, focused changes.
+- Follow existing coding style and patterns.
+- Write tests that exercise the change.
+- Keep backwards compatibility with prior releases in mind.

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

@@ -1,7 +1,7 @@
 .. XXX document all delegations to __special__ methods
 .. _built-in-funcs:
 
-Built-in Functions
+Built-in functions
 ==================
 
 The Python interpreter has a number of functions and types built into it that
@@ -65,14 +65,54 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. function:: aiter(async_iterable, /)
+              aiter(callable, /, stop_value, *, stop_exception=StopAsyncIteration)
+              aiter(callable, /, *, stop_exception)
+
+   Return an :term:`asynchronous iterator` object.
+   The first argument is interpreted very differently
+   depending on the presence of the other arguments.
+   Without other arguments,
+   the single argument must be an :term:`asynchronous iterable`,
+   and the result is equivalent to calling ``x.__aiter__()``.
+
+   If *stop_value* or *stop_exception* is given,
+   then the first argument must be a callable object.
+   The asynchronous iterator created in this case
+   calls *callable* with no arguments and awaits the result
+   for each call to its :meth:`~object.__anext__` method;
+   if the awaited value is equal to *stop_value*,
+   or if the call raises an exception matching *stop_exception*,
+   :exc:`StopAsyncIteration` will be raised,
+   otherwise the value will be returned.
+   The callable is only called when the result of :meth:`~object.__anext__`
+   is awaited.
+
+   *stop_exception* is an exception class or a tuple of exception classes.
+   If *stop_value* is not specified,
+   the iteration stops only when the callable raises an exception.
+   If the callable raises :exc:`StopAsyncIteration`
+   which does not match *stop_exception*,
+   it is replaced with a :exc:`RuntimeError`,
+   as for asynchronous generators (see :pep:`525`).
+
+   For example, reading fixed-size chunks from an asynchronous stream
+   until the end of file is reached::
 
-   Return an :term:`asynchronous iterator` for an :term:`asynchronous iterable`.
-   Equivalent to calling ``x.__aiter__()``.
+      from functools import partial
+      async for chunk in aiter(partial(reader.read, 1024), b''):
+          process_chunk(chunk)
+
+   Or consuming an :class:`asyncio.Queue` until it is shut down::
 
-   Note: Unlike :func:`iter`, :func:`aiter` has no 2-argument variant.
+      from asyncio import QueueShutDown
+      async for item in aiter(queue.get, stop_exception=QueueShutDown):
+          process_item(item)
 
    .. versionadded:: 3.10
 
+   .. versionchanged:: next
+      Added the *stop_value* and *stop_exception* parameters.
+
 .. function:: all(iterable, /)
 
    Return ``True`` if all elements of the *iterable* are true (or if the iterable
@@ -89,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.
@@ -1143,22 +1183,34 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. function:: iter(iterable, /)
-              iter(callable, sentinel, /)
+              iter(callable, /, stop_value, *, stop_exception=StopIteration)
+              iter(callable, /, *, stop_exception)
 
    Return an :term:`iterator` object.  The first argument is interpreted very
-   differently depending on the presence of the second argument. Without a
-   second argument, the single argument must be a collection object which supports the
+   differently depending on the presence of the other arguments. Without other
+   arguments, the single argument must be a collection object which supports the
    :term:`iterable` protocol (the :meth:`~object.__iter__` method),
    or it must support
    the sequence protocol (the :meth:`~object.__getitem__` method with integer arguments
    starting at ``0``).  If it does not support either of those protocols,
-   :exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
+   :exc:`TypeError` is raised.
+
+   If *stop_value* or *stop_exception* is given,
    then the first argument must be a callable object.  The iterator created in this case
    will call *callable* with no arguments for each call to its
    :meth:`~iterator.__next__` method; if the value returned is equal to
-   *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will
+   *stop_value*, or if the call raises an exception matching *stop_exception*,
+   :exc:`StopIteration` will be raised, otherwise the value will
    be returned.
 
+   *stop_exception* is an exception class or a tuple of exception classes.
+   If *stop_value* is not specified,
+   the iteration stops only when the callable raises an exception.
+   If the callable raises :exc:`StopIteration`
+   which does not match *stop_exception*,
+   it is replaced with a :exc:`RuntimeError`,
+   as for generators (see :pep:`479`).
+
    See also :ref:`typeiter`.
 
    One useful application of the second form of :func:`iter` is to build a
@@ -1170,6 +1222,19 @@ are always available.  They are listed here in alphabetical order.
           for block in iter(partial(f.read, 64), b''):
               process_block(block)
 
+   *stop_exception* is useful for callables
+   which report :term:`exhaustion <exhausted>` by raising an exception
+   instead of returning a special value.
+   For example, draining a queue::
+
+      import queue
+      for item in iter(input_queue.get_nowait, stop_exception=queue.Empty):
+          process_item(item)
+
+   .. versionchanged:: next
+      Added the *stop_exception* parameter
+      and allowed passing *stop_value* by keyword.
+
 
 .. function:: len(object, /)
 
@@ -1250,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`.
@@ -1332,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()
@@ -1394,7 +1459,8 @@ are always available.  They are listed here in alphabetical order.
    already exists), ``'x'`` for exclusive creation, and ``'a'`` for appending
    (which on *some* Unix systems, means that *all* writes append to the end of
    the file regardless of the current seek position).  In text mode, if
-   *encoding* is not specified the encoding used is platform-dependent:
+   *encoding* is not specified, UTF-8 is used by default; if
+   :ref:`Python UTF-8 Mode <utf8-mode>` is disabled,
    :func:`locale.getencoding` is called to get the current locale encoding.
    (For reading and writing raw bytes use binary mode and leave
    *encoding* unspecified.)  The available modes are:
@@ -1425,7 +1491,7 @@ are always available.  They are listed here in alphabetical order.
    argument) return contents as :class:`bytes` objects without any decoding.  In
    text mode (the default, or when ``'t'`` is included in the *mode* argument),
    the contents of the file are returned as :class:`str`, the bytes having been
-   first decoded using a platform-dependent encoding or using the specified
+   first decoded using the default encoding or using the specified
    *encoding* if given.
 
    .. note::
@@ -1454,9 +1520,11 @@ are always available.  They are listed here in alphabetical order.
      described above for binary files.
 
    *encoding* is the name of the encoding used to decode or encode the file.
-   This should only be used in text mode.  The default encoding is platform
-   dependent (whatever :func:`locale.getencoding` returns), but any
-   :term:`text encoding` supported by Python can be used.
+   This should only be used in text mode.  The default encoding is UTF-8;
+   if :ref:`Python UTF-8 Mode <utf8-mode>` is disabled, the default is
+   platform-dependent (whatever :func:`locale.getencoding` returns).
+   Any :term:`text encoding` supported by Python can be used, and
+   ``encoding="locale"`` specifies the current locale encoding explicitly.
    See the :mod:`codecs` module for the list of supported encodings.
 
    *errors* is an optional string that specifies how encoding and decoding
@@ -1573,6 +1641,10 @@ are always available.  They are listed here in alphabetical order.
    .. versionchanged:: 3.11
       The ``'U'`` mode has been removed.
 
+   .. versionchanged:: 3.15
+      UTF-8 is now the default encoding, instead of the
+      platform-dependent locale encoding (:pep:`686`).
+
 .. function:: ord(character, /)
 
    Return the ordinal value of a character.
@@ -2247,7 +2319,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::
 
@@ -2262,7 +2334,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