Merge remote-tracking branch 'upstream/main' into test/c-api-codec-111495

Author: picnixz

.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].
@@ -999,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)
 
@@ -1011,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
@@ -1438,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/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/dataclasses.rst

@@ -231,7 +231,7 @@ Module contents
    follows a field with a default value.  This is true whether this
    occurs in a single class, or as a result of class inheritance.
 
-.. function:: field(*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING)
+.. function:: field(*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING, doc=None)
 
    For common and simple use cases, no other functionality is
    required.  There are, however, some dataclass features that
@@ -300,6 +300,10 @@ Module contents
 
     .. versionadded:: 3.10
 
+   - ``doc``: optional docstring for this field.
+
+    .. versionadded:: 3.13
+
    If the default value of a field is specified by a call to
    :func:`!field`, then the class attribute for this field will be
    replaced by the specified *default* value.  If *default* is not

Doc/library/functools.rst

@@ -543,6 +543,25 @@ The :mod:`functools` module defines the following functions:
      ...     print(arg.real, arg.imag)
      ...
 
+   For code that dispatches on a collections type (e.g., ``list``), but wants
+   to typehint the items of the collection (e.g., ``list[int]``), the
+   dispatch type should be passed explicitly to the decorator itself with the
+   typehint going into the function definition::
+
+     >>> @fun.register(list)
+     ... def _(arg: list[int], verbose=False):
+     ...     if verbose:
+     ...         print("Enumerate this:")
+     ...     for i, elem in enumerate(arg):
+     ...         print(i, elem)
+
+   .. note::
+
+      At runtime the function will dispatch on an instance of a list regardless
+      of the type contained within the list i.e. ``[1,2,3]`` will be
+      dispatched the same as ``["foo", "bar", "baz"]``. The annotation
+      provided in this example is for static type checkers only and has no
+      runtime impact.
 
    To enable registering :term:`lambdas<lambda>` and pre-existing functions,
    the :func:`register` attribute can also be used in a functional form::

Doc/library/importlib.rst

@@ -1166,10 +1166,9 @@ find and load modules.
 .. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)
 
    A specification for a module's import-system-related state.  This is
-   typically exposed as the module's :attr:`__spec__` attribute.  In the
-   descriptions below, the names in parentheses give the corresponding
-   attribute available directly on the module object,
-   e.g. ``module.__spec__.origin == module.__file__``.  Note, however, that
+   typically exposed as the module's :attr:`__spec__` attribute.  Many
+   of these attributes are also available directly on a module: for example,
+   ``module.__spec__.origin == module.__file__``.  Note, however, that
    while the *values* are usually equivalent, they can differ since there is
    no synchronization between the two objects.  For example, it is possible to update
    the module's :attr:`__file__` at runtime and this will not be automatically
@@ -1179,66 +1178,60 @@ find and load modules.
 
    .. attribute:: name
 
-   (:attr:`__name__`)
-
-   The module's fully qualified name.
-   The :term:`finder` should always set this attribute to a non-empty string.
+      The module's fully qualified name
+      (see :attr:`__name__` attributes on modules).
+      The :term:`finder` should always set this attribute to a non-empty string.
 
    .. attribute:: loader
 
-   (:attr:`__loader__`)
-
-   The :term:`loader` used to load the module.
-   The :term:`finder` should always set this attribute.
+      The :term:`loader` used to load the module
+      (see :attr:`__loader__` attributes on modules).
+      The :term:`finder` should always set this attribute.
 
    .. attribute:: origin
 
-   (:attr:`__file__`)
-
-   The location the :term:`loader` should use to load the module.
-   For example, for modules loaded from a .py file this is the filename.
-   The :term:`finder` should always set this attribute to a meaningful value
-   for the :term:`loader` to use.  In the uncommon case that there is not one
-   (like for namespace packages), it should be set to ``None``.
+      The location the :term:`loader` should use to load the module
+      (see :attr:`__file__` attributes on modules).
+      For example, for modules loaded from a .py file this is the filename.
+      The :term:`finder` should always set this attribute to a meaningful value
+      for the :term:`loader` to use.  In the uncommon case that there is not one
+      (like for namespace packages), it should be set to ``None``.
 
    .. attribute:: submodule_search_locations
 
-   (:attr:`__path__`)
-
-   The list of locations where the package's submodules will be found.
-   Most of the time this is a single directory.
-   The :term:`finder` should set this attribute to a list, even an empty one, to indicate
-   to the import system that the module is a package.  It should be set to ``None`` for
-   non-package modules.  It is set automatically later to a special object for
-   namespace packages.
+      The list of locations where the package's submodules will be found
+      (see :attr:`__path__` attributes on modules).
+      Most of the time this is a single directory.
+      The :term:`finder` should set this attribute to a list, even an empty one, to indicate
+      to the import system that the module is a package.  It should be set to ``None`` for
+      non-package modules.  It is set automatically later to a special object for
+      namespace packages.
 
    .. attribute:: loader_state
 
-   The :term:`finder` may set this attribute to an object containing additional,
-   module-specific data to use when loading the module.  Otherwise it should be
-   set to ``None``.
+      The :term:`finder` may set this attribute to an object containing additional,
+      module-specific data to use when loading the module.  Otherwise it should be
+      set to ``None``.
 
    .. attribute:: cached
 
-   (:attr:`__cached__`)
-
-   The filename of a compiled version of the module's code.
-   The :term:`finder` should always set this attribute but it may be ``None``
-   for modules that do not need compiled code stored.
+      The filename of a compiled version of the module's code
+      (see :attr:`__cached__` attributes on modules).
+      The :term:`finder` should always set this attribute but it may be ``None``
+      for modules that do not need compiled code stored.
 
    .. attribute:: parent
 
-   (:attr:`__package__`)
-
-   (Read-only) The fully qualified name of the package the module is in (or the
-   empty string for a top-level module).
-   If the module is a package then this is the same as :attr:`name`.
+      (Read-only) The fully qualified name of the package the module is in (or the
+      empty string for a top-level module).
+      See :attr:`__package__` attributes on modules.
+      If the module is a package then this is the same as :attr:`name`.
 
    .. attribute:: has_location
 
-   ``True`` if the spec's :attr:`origin` refers to a loadable location,
-   ``False`` otherwise.  This value impacts how :attr:`origin` is interpreted
-   and how the module's :attr:`__file__` is populated.
+      ``True`` if the spec's :attr:`origin` refers to a loadable location,
+      ``False`` otherwise.  This value impacts how :attr:`origin` is interpreted
+      and how the module's :attr:`__file__` is populated.
 
 
 .. class:: AppleFrameworkLoader(name, path)