Merge branch 'main' into argparse-abbrev-subparser

.devcontainer/devcontainer.json

@@ -1,7 +1,5 @@
 {
-    "build": {
-        "dockerfile": "Dockerfile"
-    },
+    "image": "ghcr.io/python/devcontainer:2024.09.25.11038928730",
     "onCreateCommand": [
         // Install common tooling.
         "dnf",

.github/CODEOWNERS

@@ -207,7 +207,6 @@ Doc/c-api/stable.rst          @encukou
 **/*bisect*                   @rhettinger
 **/*heapq*                    @rhettinger
 **/*functools*                @rhettinger
-**/*decimal*                  @rhettinger
 
 **/*dataclasses*              @ericvsmith
 

Doc/c-api/init_config.rst

@@ -1248,19 +1248,24 @@ PyConfig
 
    .. c:member:: int perf_profiling
 
-      Enable compatibility mode with the perf profiler?
+      Enable the Linux ``perf`` profiler support?
 
-      If non-zero, initialize the perf trampoline. See :ref:`perf_profiling`
-      for more information.
+      If equals to ``1``, enable support for the Linux ``perf`` profiler.
 
-      Set by :option:`-X perf <-X>` command-line option and by the
-      :envvar:`PYTHON_PERF_JIT_SUPPORT` environment variable for perf support
-      with stack pointers and :option:`-X perf_jit <-X>` command-line option
-      and by the :envvar:`PYTHON_PERF_JIT_SUPPORT` environment variable for perf
-      support with DWARF JIT information.
+      If equals to ``2``, enable support for the Linux ``perf`` profiler with
+      DWARF JIT support.
+
+      Set to ``1`` by :option:`-X perf <-X>` command-line option and the
+      :envvar:`PYTHONPERFSUPPORT` environment variable.
+
+      Set to ``2`` by the :option:`-X perf_jit <-X>` command-line option and
+      the :envvar:`PYTHON_PERF_JIT_SUPPORT` environment variable.
 
       Default: ``-1``.
 
+      .. seealso::
+         See :ref:`perf_profiling` for more information.
+
       .. versionadded:: 3.12
 
    .. c:member:: int use_environment

Doc/c-api/long.rst

@@ -159,7 +159,6 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.13
 
 
-.. XXX alias PyLong_AS_LONG (for now)
 .. c:function:: long PyLong_AsLong(PyObject *obj)
 
    .. index::
@@ -181,6 +180,16 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionchanged:: 3.10
       This function will no longer use :meth:`~object.__int__`.
 
+   .. c:namespace:: NULL
+
+   .. c:function:: long PyLong_AS_LONG(PyObject *obj)
+
+      A :term:`soft deprecated` alias.
+      Exactly equivalent to the preferred ``PyLong_AsLong``. In particular,
+      it can fail with :exc:`OverflowError` or another exception.
+
+      .. deprecated:: 3.14
+         The function is soft deprecated.
 
 .. c:function:: int PyLong_AsInt(PyObject *obj)
 

Doc/c-api/unicode.rst

@@ -317,7 +317,7 @@ These APIs can be used to work with surrogates:
 
 .. c:function:: Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)
 
-   Join two surrogate characters and return a single :c:type:`Py_UCS4` value.
+   Join two surrogate code points and return a single :c:type:`Py_UCS4` value.
    *high* and *low* are respectively the leading and trailing surrogates in a
    surrogate pair. *high* must be in the range [0xD800; 0xDBFF] and *low* must
    be in the range [0xDC00; 0xDFFF].
@@ -338,6 +338,8 @@ APIs:
    This is the recommended way to allocate a new Unicode object.  Objects
    created using this function are not resizable.
 
+   On error, set an exception and return ``NULL``.
+
    .. versionadded:: 3.3
 
 
@@ -614,6 +616,8 @@ APIs:
 
    Return the length of the Unicode object, in code points.
 
+   On error, set an exception and return ``-1``.
+
    .. versionadded:: 3.3
 
 
@@ -657,6 +661,8 @@ APIs:
    not out of bounds, and that the object can be modified safely (i.e. that it
    its reference count is one).
 
+   Return ``0`` on success, ``-1`` on error with an exception set.
+
    .. versionadded:: 3.3
 
 
@@ -666,6 +672,8 @@ APIs:
    Unicode object and the index is not out of bounds, in contrast to
    :c:func:`PyUnicode_READ_CHAR`, which performs no error checking.
 
+   Return character on success, ``-1`` on error with an exception set.
+
    .. versionadded:: 3.3
 
 
@@ -674,6 +682,7 @@ APIs:
 
    Return a substring of *unicode*, from character index *start* (included) to
    character index *end* (excluded).  Negative indices are not supported.
+   On error, set an exception and return ``NULL``.
 
    .. versionadded:: 3.3
 
@@ -990,6 +999,9 @@ These are the UTF-8 codec APIs:
    object.  Error handling is "strict".  Return ``NULL`` if an exception was
    raised by the codec.
 
+   The function fails if the string contains surrogate code points
+   (``U+D800`` - ``U+DFFF``).
+
 
 .. c:function:: const char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
 
@@ -1002,6 +1014,9 @@ These are the UTF-8 codec APIs:
    On error, set an exception, set *size* to ``-1`` (if it's not NULL) and
    return ``NULL``.
 
+   The function fails if the string contains surrogate code points
+   (``U+D800`` - ``U+DFFF``).
+
    This caches the UTF-8 representation of the string in the Unicode object, and
    subsequent calls will return a pointer to the same buffer.  The caller is not
    responsible for deallocating the buffer. The buffer is deallocated and
@@ -1429,8 +1444,9 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
    Compare a Unicode object with a char buffer which is interpreted as
    being UTF-8 or ASCII encoded and return true (``1``) if they are equal,
    or false (``0``) otherwise.
-   If the Unicode object contains surrogate characters or
-   the C string is not valid UTF-8, false (``0``) is returned.
+   If the Unicode object contains surrogate code points
+   (``U+D800`` - ``U+DFFF``) or the C string is not valid UTF-8,
+   false (``0``) is returned.
 
    This function does not raise exceptions.
 

Doc/conf.py

@@ -413,8 +413,8 @@
 \let\endVerbatim=\endOriginalVerbatim
 \setcounter{tocdepth}{2}
 ''',
-    # The paper size ('letter' or 'a4').
-    'papersize': 'a4',
+    # The paper size ('letterpaper' or 'a4paper').
+    'papersize': 'a4paper',
     # The font size ('10pt', '11pt' or '12pt').
     'pointsize': '10pt',
 }

Doc/deprecations/pending-removal-in-3.16.rst

@@ -18,6 +18,14 @@ Pending Removal in Python 3.16
     Use the ``'w'`` format code (:c:type:`Py_UCS4`)
     for Unicode characters instead.
 
+* :mod:`asyncio`:
+
+   * :mod:`asyncio`:
+     :func:`!asyncio.iscoroutinefunction` is deprecated
+     and will be removed in Python 3.16,
+     use :func:`inspect.iscoroutinefunction` instead.
+     (Contributed by Jiahao Li and Kumar Aditya in :gh:`122875`.)
+
 * :mod:`shutil`:
 
   * The :class:`!ExecError` exception

Doc/faq/programming.rst

@@ -1613,9 +1613,16 @@ method too, and it must do so carefully.  The basic implementation of
            self.__dict__[name] = value
        ...
 
-Most :meth:`!__setattr__` implementations must modify
-:attr:`self.__dict__ <object.__dict__>` to store
-local state for self without causing an infinite recursion.
+Many :meth:`~object.__setattr__` implementations call :meth:`!object.__setattr__` to set
+an attribute on self without causing infinite recursion::
+
+   class X:
+       def __setattr__(self, name, value):
+           # Custom logic here...
+           object.__setattr__(self, name, value)
+
+Alternatively, it is possible to set attributes by inserting
+entries into :attr:`self.__dict__ <object.__dict__>` directly.
 
 
 How do I call a method defined in a base class from a derived class that extends it?

Doc/howto/sorting.rst

@@ -47,11 +47,14 @@ lists. In contrast, the :func:`sorted` function accepts any iterable.
 Key Functions
 =============
 
-Both :meth:`list.sort` and :func:`sorted` have a *key* parameter to specify a
-function (or other callable) to be called on each list element prior to making
+The :meth:`list.sort` method and the functions :func:`sorted`,
+:func:`min`, :func:`max`, :func:`heapq.nsmallest`, and
+:func:`heapq.nlargest` have a *key* parameter to specify a function (or
+other callable) to be called on each list element prior to making
 comparisons.
 
-For example, here's a case-insensitive string comparison:
+For example, here's a case-insensitive string comparison using
+:meth:`str.casefold`:
 
 .. doctest::
 
@@ -272,6 +275,70 @@ to make it usable as a key function::
 
     sorted(words, key=cmp_to_key(strcoll))  # locale-aware sort order
 
+Strategies For Unorderable Types and Values
+===========================================
+
+A number of type and value issues can arise when sorting.
+Here are some strategies that can help:
+
+* Convert non-comparable input types to strings prior to sorting:
+
+.. doctest::
+
+   >>> data = ['twelve', '11', 10]
+   >>> sorted(map(str, data))
+   ['10', '11', 'twelve']
+
+This is needed because most cross-type comparisons raise a
+:exc:`TypeError`.
+
+* Remove special values prior to sorting:
+
+.. doctest::
+
+   >>> from math import isnan
+   >>> from itertools import filterfalse
+   >>> data = [3.3, float('nan'), 1.1, 2.2]
+   >>> sorted(filterfalse(isnan, data))
+   [1.1, 2.2, 3.3]
+
+This is needed because the `IEEE-754 standard
+<https://en.wikipedia.org/wiki/IEEE_754>`_ specifies that, "Every NaN
+shall compare unordered with everything, including itself."
+
+Likewise, ``None`` can be stripped from datasets as well:
+
+.. doctest::
+
+   >>> data = [3.3, None, 1.1, 2.2]
+   >>> sorted(x for x in data if x is not None)
+   [1.1, 2.2, 3.3]
+
+This is needed because ``None`` is not comparable to other types.
+
+* Convert mapping types into sorted item lists before sorting:
+
+.. doctest::
+
+   >>> data = [{'a': 1}, {'b': 2}]
+   >>> sorted(data, key=lambda d: sorted(d.items()))
+   [{'a': 1}, {'b': 2}]
+
+This is needed because dict-to-dict comparisons raise a
+:exc:`TypeError`.
+
+* Convert set types into sorted lists before sorting:
+
+.. doctest::
+
+    >>> data = [{'a', 'b', 'c'}, {'b', 'c', 'd'}]
+    >>> sorted(map(sorted, data))
+    [['a', 'b', 'c'], ['b', 'c', 'd']]
+
+This is needed because the elements contained in set types do not have a
+deterministic order.  For example, ``list({'a', 'b'})`` may produce
+either ``['a', 'b']`` or ``['b', 'a']``.
+
 Odds and Ends
 =============
 

Doc/library/annotationlib.rst

@@ -32,7 +32,7 @@ This module supports retrieving annotations in three main formats
   for annotations that cannot be resolved, allowing you to inspect the
   annotations without evaluating them. This is useful when you need to
   work with annotations that may contain unresolved forward references.
-* :attr:`~Format.SOURCE` returns the annotations as a string, similar
+* :attr:`~Format.STRING` returns the annotations as a string, similar
   to how it would appear in the source file. This is useful for documentation
   generators that want to display annotations in a readable way.
 
@@ -135,7 +135,7 @@ Classes
       values. Real objects may contain references to, :class:`ForwardRef`
       proxy objects.
 
-   .. attribute:: SOURCE
+   .. attribute:: STRING
       :value: 3
 
       Values are the text string of the annotation as it appears in the
@@ -197,23 +197,23 @@ Classes
 Functions
 ---------
 
-.. function:: annotations_to_source(annotations)
+.. function:: annotations_to_string(annotations)
 
    Convert an annotations dict containing runtime values to a
    dict containing only strings. If the values are not already strings,
-   they are converted using :func:`value_to_source`.
+   they are converted using :func:`value_to_string`.
    This is meant as a helper for user-provided
-   annotate functions that support the :attr:`~Format.SOURCE` format but
+   annotate functions that support the :attr:`~Format.STRING` format but
    do not have access to the code creating the annotations.
 
-   For example, this is used to implement the :attr:`~Format.SOURCE` for
+   For example, this is used to implement the :attr:`~Format.STRING` for
    :class:`typing.TypedDict` classes created through the functional syntax:
 
    .. doctest::
 
        >>> from typing import TypedDict
        >>> Movie = TypedDict("movie", {"name": str, "year": int})
-       >>> get_annotations(Movie, format=Format.SOURCE)
+       >>> get_annotations(Movie, format=Format.STRING)
        {'name': 'str', 'year': 'int'}
 
    .. versionadded:: 3.14
@@ -282,7 +282,7 @@ Functions
       NameError: name 'undefined' is not defined
       >>> call_evaluate_function(Alias.evaluate_value, Format.FORWARDREF)
       ForwardRef('undefined')
-      >>> call_evaluate_function(Alias.evaluate_value, Format.SOURCE)
+      >>> call_evaluate_function(Alias.evaluate_value, Format.STRING)
       'undefined'
 
    .. versionadded:: 3.14
@@ -369,14 +369,14 @@ Functions
 
    .. versionadded:: 3.14
 
-.. function:: value_to_source(value)
+.. function:: value_to_string(value)
 
    Convert an arbitrary Python value to a format suitable for use by the
-   :attr:`~Format.SOURCE` format. This calls :func:`repr` for most
+   :attr:`~Format.STRING` format. This calls :func:`repr` for most
    objects, but has special handling for some objects, such as type objects.
 
    This is meant as a helper for user-provided
-   annotate functions that support the :attr:`~Format.SOURCE` format but
+   annotate functions that support the :attr:`~Format.STRING` format but
    do not have access to the code creating the annotations. It can also
    be used to provide a user-friendly string representation for other
    objects that contain values that are commonly encountered in annotations.