Merge branch 'main' into atan2

Author: hpkfft

.claude/CLAUDE.md

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

.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/c-api/marshal.rst

@@ -16,6 +16,20 @@ Numeric values are stored with the least significant byte first.
 The module supports several versions of the data format; see
 the :py:mod:`Python module documentation <marshal>` for details.
 
+The following exceptions can be raised by these functions:
+:exc:`ValueError` if the value cannot be marshalled,
+:exc:`ValueError` or :exc:`TypeError` if the data is malformed,
+:exc:`EOFError` if the end of the data is reached before the value is complete,
+:exc:`OSError` if reading from or writing to a :c:expr:`FILE*` fails,
+:exc:`KeyboardInterrupt` if reading or writing is interrupted by a signal,
+and :exc:`MemoryError` if memory allocation fails.
+
+.. versionchanged:: next
+   Previously, in functions taking a :c:expr:`FILE*`,
+   the reading functions raised :exc:`EOFError`
+   instead of :exc:`OSError` and :exc:`KeyboardInterrupt`,
+   and the writing functions ignored I/O errors and interruptions.
+
 .. c:macro:: Py_MARSHAL_VERSION
 
    The current format version. See :py:data:`marshal.version`.
@@ -42,6 +56,8 @@ the :py:mod:`Python module documentation <marshal>` for details.
    Return a bytes object containing the marshalled representation of *value*.
    *version* indicates the file format.
 
+   On error, raises an exception and returns ``NULL``.
+
 
 The following functions allow marshalled values to be read back in.
 
@@ -52,8 +68,7 @@ The following functions allow marshalled values to be read back in.
    for reading.  Only a 32-bit value can be read in using this function,
    regardless of the native size of :c:expr:`long`.
 
-   On error, sets the appropriate exception (:exc:`EOFError`) and returns
-   ``-1``.
+   On error, raises an exception and returns ``-1``.
 
 
 .. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
@@ -62,17 +77,15 @@ The following functions allow marshalled values to be read back in.
    for reading.  Only a 16-bit value can be read in using this function,
    regardless of the native size of :c:expr:`short`.
 
-   On error, sets the appropriate exception (:exc:`EOFError`) and returns
-   ``-1``.
+   On error, raises an exception and returns ``-1``.
 
 
 .. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
 
    Return a Python object from the data stream in a :c:expr:`FILE*` opened for
    reading.
 
-   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
-   or :exc:`TypeError`) and returns ``NULL``.
+   On error, raises an exception and returns ``NULL``.
 
 
 .. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
@@ -85,15 +98,13 @@ The following functions allow marshalled values to be read back in.
    file.  Only use this variant if you are certain that you won't be reading
    anything else from the file.
 
-   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
-   or :exc:`TypeError`) and returns ``NULL``.
+   On error, raises an exception and returns ``NULL``.
 
 
 .. c:function:: PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
 
    Return a Python object from the data stream in a byte buffer
    containing *len* bytes pointed to by *data*.
 
-   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
-   or :exc:`TypeError`) and returns ``NULL``.
+   On error, raises an exception and returns ``NULL``.
 

Doc/c-api/module.rst

@@ -853,7 +853,7 @@ struct:
 
    .. versionadded:: 3.5
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyModule_FromSlotsAndSpec` in new code.
 
@@ -877,7 +877,7 @@ struct:
 
    .. versionadded:: 3.5
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyModule_FromSlotsAndSpec` in new code.
 
@@ -887,7 +887,7 @@ struct:
 
    .. versionadded:: 3.5
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       To run a module's own execution slots, prefer :c:func:`PyModule_Exec`,
       which works on modules that were not created from a

Doc/c-api/type.rst

@@ -828,7 +828,7 @@ They will continue to work, but new features will be added as slots for
 
    .. versionadded:: 3.12
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.
 
@@ -859,7 +859,7 @@ They will continue to work, but new features will be added as slots for
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.
 
@@ -885,7 +885,7 @@ They will continue to work, but new features will be added as slots for
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.
 
@@ -910,7 +910,7 @@ They will continue to work, but new features will be added as slots for
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.
 

Doc/howto/curses.rst

@@ -295,17 +295,21 @@ underline, reverse code, or in color.  They'll be explained in more detail in
 the next subsection.
 
 
-The :meth:`~curses.window.addstr` method takes a Python string or
-bytestring as the value to be displayed.  The contents of bytestrings
-are sent to the terminal as-is.  Strings are encoded to bytes using
-the value of the window's :attr:`~window.encoding` attribute; this defaults to
-the default system encoding as returned by :func:`locale.getencoding`.
+The :meth:`~curses.window.addstr` method takes a Python string, bytestring
+or :class:`~curses.complexstr` as the value to be displayed.  The contents
+of bytestrings are sent to the terminal as-is.
+On a build without wide-character support strings are encoded
+using the value of the window's :attr:`~window.encoding` attribute;
+this defaults to the default system encoding
+as returned by :func:`locale.getencoding`.
 
 The :meth:`~curses.window.addch` methods take a character, which can be
-either a string of length 1, a bytestring of length 1, or an integer.
+either a string of length 1, a bytestring of length 1, an integer, or a
+:class:`~curses.complexchar`.
 
-Constants are provided for extension characters; these constants are
-integers greater than 255.  For example, :const:`ACS_PLMINUS` is a +/-
+Constants are provided for the characters of the terminal's alternate
+character set.
+For example, :const:`ACS_PLMINUS` is a +/-
 symbol, and :const:`ACS_ULCORNER` is the upper left corner of a box
 (handy for drawing borders).  You can also use the appropriate Unicode
 character.
@@ -319,11 +323,11 @@ won't be distracting; it can be confusing to have the cursor blinking at some
 apparently random location.
 
 If your application doesn't need a blinking cursor at all, you can
-call ``curs_set(False)`` to make it invisible.  For compatibility
-with older curses versions, there's a ``leaveok(bool)`` function
-that's a synonym for :func:`~curses.curs_set`.  When *bool* is true, the
-curses library will attempt to suppress the flashing cursor, and you
-won't need to worry about leaving it in odd locations.
+call ``curs_set(False)`` to make it invisible.
+The window method :meth:`~curses.window.leaveok` does something different:
+when its argument is true,
+curses leaves the cursor wherever the last update put it,
+instead of moving it back to the window's cursor position.
 
 
 Attributes and Color
@@ -364,6 +368,14 @@ could code::
                  curses.A_REVERSE)
    stdscr.refresh()
 
+A :class:`~curses.complexchar` carries its attributes and color pair
+together with the text of one character cell,
+and a :class:`~curses.complexstr` is a run of such cells.
+They are what :meth:`~curses.window.in_wch` and
+:meth:`~curses.window.in_wchstr` return,
+so a part of the screen can be read and written back
+with its appearance intact.
+
 The curses library also supports color on those terminals that provide it. The
 most common such terminal is probably the Linux console, followed by color
 xterms.
@@ -429,40 +441,48 @@ The C curses library offers only very simple input mechanisms. Python's
 :mod:`curses` module adds a basic text-input widget.  (Other libraries
 such as :pypi:`Urwid` have more extensive collections of widgets.)
 
-There are two methods for getting input from a window:
+There are three methods for getting input from a window:
 
-* :meth:`~curses.window.getch` refreshes the screen and then waits for
+* :meth:`~curses.window.get_wch` refreshes the screen and then waits for
   the user to hit a key, displaying the key if :func:`~curses.echo` has been
   called earlier.  You can optionally specify a coordinate to which
   the cursor should be moved before pausing.
 
-* :meth:`~curses.window.getkey` does the same thing but converts the
-  integer to a string.  Individual characters are returned as
-  1-character strings, and special keys such as function keys return
-  longer strings containing a key name such as ``KEY_UP`` or ``^G``.
+* :meth:`~curses.window.getch` does the same thing but returns the code of
+  the key instead of a character.
+  With ncurses this is a single byte of the key's encoding in the current
+  locale, so a character encoded with several bytes takes several calls,
+  one byte per call.
+
+* :meth:`~curses.window.getkey` does the same as :meth:`!getch` but returns
+  a string:
+  an ordinary key as a 1-character string,
+  and a special key as its name, such as ``KEY_UP``.
 
 It's possible to not wait for the user using the
 :meth:`~curses.window.nodelay` window method. After ``nodelay(True)``,
-:meth:`!getch` and :meth:`!getkey` for the window become
-non-blocking. To signal that no input is ready, :meth:`!getch` returns
-``curses.ERR`` (a value of -1) and :meth:`!getkey` raises an exception.
+the reads for the window become non-blocking.
+To signal that no input is ready,
+:meth:`!get_wch` and :meth:`!getkey` raise an exception,
+and :meth:`!getch` returns ``-1``.
 There's also a :func:`~curses.halfdelay` function, which can be used to (in
-effect) set a timer on each :meth:`!getch`; if no input becomes
+effect) set a timer on each read; if no input becomes
 available within a specified delay (measured in tenths of a second),
-curses raises an exception.
+the read fails the same way.
 
-The :meth:`!getch` method returns an integer; if it's between 0 and 255, it
-represents the ASCII code of the key pressed.  Values greater than 255 are
-special keys such as Page Up, Home, or the cursor keys. You can compare the
-value returned to constants such as :const:`curses.KEY_PPAGE`,
+Special keys such as Page Up, Home, or the cursor keys are returned by all
+three as one of the :ref:`KEY_* constants <curses-key-constants>`,
+all larger than 255.
+You can compare the value returned to constants such as
+:const:`curses.KEY_PPAGE`,
 :const:`curses.KEY_HOME`, or :const:`curses.KEY_LEFT`.  The main loop of
 your program may look something like this::
 
    while True:
-       c = stdscr.getch()
-       if c == ord('p'):
+       c = stdscr.get_wch()
+       if c == 'p':
            PrintDocument()
-       elif c == ord('q'):
+       elif c == 'q':
            break  # Exit the while loop
        elif c == curses.KEY_HOME:
            x = y = 0
@@ -474,16 +494,17 @@ conversion functions  that take either integer or 1-character-string arguments
 and return the same type.  For example, :func:`curses.ascii.ctrl` returns the
 control character corresponding to its argument.
 
-There's also a method to retrieve an entire string,
-:meth:`~curses.window.getstr`.  It isn't used very often, because its
+There's also a method to retrieve an entire line,
+:meth:`~curses.window.get_wstr`.  It isn't used very often, because its
 functionality is quite limited; the only editing keys available are
-the backspace key and the Enter key, which terminates the string.  It
-can optionally be limited to a fixed number of characters. ::
+the erase and kill characters, and the Enter key, which terminates the line.
+It can optionally be limited to a fixed number of characters;
+:meth:`~curses.window.getstr` returns a bytes object instead. ::
 
    curses.echo()            # Enable echoing of characters
 
-   # Get a 15-character string, with the cursor on the top line
-   s = stdscr.getstr(0,0, 15)
+   # Get a line of at most 15 characters, with the cursor on the top line
+   s = stdscr.get_wstr(0,0, 15)
 
 The :mod:`curses.textpad` module supplies a text box that supports an
 Emacs-like set of keybindings.  Various methods of the

Doc/library/argparse.rst

@@ -835,7 +835,9 @@ how the command-line arguments should be handled. The supplied actions are:
     >>> parser.parse_args(['-vvv'])
     Namespace(verbose=3)
 
-  Note, the *default* will be ``None`` unless explicitly set to *0*.
+  Unless explicitly set, the *default* will be ``None``. If the default
+  value is a non-zero number, the count starts from that number rather
+  than from zero.
 
 * ``'help'`` - This prints a complete help message for all the options in the
   current parser and then exits. By default a help action is automatically

Doc/library/ast.rst

@@ -2254,7 +2254,7 @@ and classes for traversing abstract syntax trees:
 
    In addition, if ``mode`` is ``'func_type'``, the input syntax is
    modified to correspond to :pep:`484` "signature type comments",
-   e.g. ``(str, int) -> List[str]``.
+   for example ``(str, int) -> List[str]``.
 
    Setting ``feature_version`` to a tuple ``(major, minor)`` will result in
    a "best-effort" attempt to parse using that Python version's grammar.

Doc/library/asyncio-task.rst

@@ -356,7 +356,7 @@ and reliable way to wait for all tasks in the group to finish.
       The signature matches that of :func:`asyncio.create_task`.
       If the task group is inactive (e.g. not yet entered,
       already finished, or in the process of shutting down),
-      we will close the given ``coro``.
+      we will close the given ``coro`` and raise :exc:`RuntimeError`.
 
       .. versionchanged:: 3.13