Merge remote-tracking branch 'upstream/main' into coformatname

Doc/Makefile

@@ -306,12 +306,12 @@ serve:
 # for development releases: always build
 .PHONY: autobuild-dev
 autobuild-dev:
-	$(MAKE) dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
+	$(MAKE) dist-no-html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
 
-# for quick rebuilds (HTML only)
+# for HTML-only rebuilds
 .PHONY: autobuild-dev-html
 autobuild-dev-html:
-	$(MAKE) html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
+	$(MAKE) dist-html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
 
 # for stable releases: only build if not in pre-release stage (alpha, beta)
 # release candidate downloads are okay, since the stable tree can be in that stage

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/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/argparse.rst

@@ -1823,7 +1823,7 @@ Sub-commands
      >>>
      >>> # create the parser for the "b" command
      >>> parser_b = subparsers.add_parser('b', help='b help')
-     >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
+     >>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz help')
      >>>
      >>> # parse some argument lists
      >>> parser.parse_args(['a', '12'])

Doc/library/pdb.rst

@@ -439,17 +439,20 @@ can be overridden by the local file.
 
    Specifying any command resuming execution
    (currently :pdbcmd:`continue`, :pdbcmd:`step`, :pdbcmd:`next`,
-   :pdbcmd:`return`, :pdbcmd:`jump`, :pdbcmd:`quit` and their abbreviations)
+   :pdbcmd:`return`, :pdbcmd:`until`, :pdbcmd:`jump`, :pdbcmd:`quit` and their abbreviations)
    terminates the command list (as if
    that command was immediately followed by end). This is because any time you
    resume execution (even with a simple next or step), you may encounter another
    breakpoint—which could have its own command list, leading to ambiguities about
    which list to execute.
 
-   If you use the ``silent`` command in the command list, the usual message about
-   stopping at a breakpoint is not printed.  This may be desirable for breakpoints
-   that are to print a specific message and then continue.  If none of the other
-   commands print anything, you see no sign that the breakpoint was reached.
+   If the list of commands contains the ``silent`` command, or a command that
+   resumes execution, then the breakpoint message containing information about
+   the frame is not displayed.
+
+   .. versionchanged:: 3.14
+      Frame information will not be displayed if a command that resumes execution
+      is present in the command list.
 
 .. pdbcommand:: s(tep)
 

Doc/library/typing.rst

@@ -2349,7 +2349,9 @@ types.
 
    Backward-compatible usage::
 
-       # For creating a generic NamedTuple on Python 3.11 or lower
+       # For creating a generic NamedTuple on Python 3.11
+       T = TypeVar("T")
+
        class Group(NamedTuple, Generic[T]):
            key: T
            group: list[T]

Doc/library/venv.rst

@@ -288,31 +288,31 @@ creation according to their needs, the :class:`EnvBuilder` class.
     The :class:`EnvBuilder` class accepts the following keyword arguments on
     instantiation:
 
-    * ``system_site_packages`` -- a Boolean value indicating that the system Python
+    * *system_site_packages* -- a boolean value indicating that the system Python
       site-packages should be available to the environment (defaults to ``False``).
 
-    * ``clear`` -- a Boolean value which, if true, will delete the contents of
+    * *clear* -- a boolean value which, if true, will delete the contents of
       any existing target directory, before creating the environment.
 
-    * ``symlinks`` -- a Boolean value indicating whether to attempt to symlink the
+    * *symlinks* -- a boolean value indicating whether to attempt to symlink the
       Python binary rather than copying.
 
-    * ``upgrade`` -- a Boolean value which, if true, will upgrade an existing
+    * *upgrade* -- a boolean value which, if true, will upgrade an existing
       environment with the running Python - for use when that Python has been
       upgraded in-place (defaults to ``False``).
 
-    * ``with_pip`` -- a Boolean value which, if true, ensures pip is
+    * *with_pip* -- a boolean value which, if true, ensures pip is
       installed in the virtual environment. This uses :mod:`ensurepip` with
       the ``--default-pip`` option.
 
-    * ``prompt`` -- a String to be used after virtual environment is activated
+    * *prompt* -- a string to be used after virtual environment is activated
       (defaults to ``None`` which means directory name of the environment would
       be used). If the special string ``"."`` is provided, the basename of the
       current directory is used as the prompt.
 
-    * ``upgrade_deps`` -- Update the base venv modules to the latest on PyPI
+    * *upgrade_deps* -- Update the base venv modules to the latest on PyPI
 
-    * ``scm_ignore_files`` -- Create ignore files based for the specified source
+    * *scm_ignore_files* -- Create ignore files based for the specified source
       control managers (SCM) in the iterable. Support is defined by having a
       method named ``create_{scm}_ignore_file``. The only value supported by
       default is ``"git"`` via :meth:`create_git_ignore_file`.
@@ -330,10 +330,7 @@ creation according to their needs, the :class:`EnvBuilder` class.
     .. versionchanged:: 3.13
        Added the ``scm_ignore_files`` parameter
 
-    Creators of third-party virtual environment tools will be free to use the
-    provided :class:`EnvBuilder` class as a base class.
-
-    The returned env-builder is an object which has a method, ``create``:
+    :class:`EnvBuilder` may be used as a base class.
 
     .. method:: create(env_dir)
 
@@ -433,37 +430,27 @@ creation according to their needs, the :class:`EnvBuilder` class.
 
     .. method:: upgrade_dependencies(context)
 
-       Upgrades the core venv dependency packages (currently ``pip``)
+       Upgrades the core venv dependency packages (currently :pypi:`pip`)
        in the environment. This is done by shelling out to the
        ``pip`` executable in the environment.
 
        .. versionadded:: 3.9
        .. versionchanged:: 3.12
 
-          ``setuptools`` is no longer a core venv dependency.
+          :pypi:`setuptools` is no longer a core venv dependency.
 
     .. method:: post_setup(context)
 
         A placeholder method which can be overridden in third party
         implementations to pre-install packages in the virtual environment or
         perform other post-creation steps.
 
-    .. versionchanged:: 3.7.2
-       Windows now uses redirector scripts for ``python[w].exe`` instead of
-       copying the actual binaries. In 3.7.2 only :meth:`setup_python` does
-       nothing unless running from a build in the source tree.
-
-    .. versionchanged:: 3.7.3
-       Windows copies the redirector scripts as part of :meth:`setup_python`
-       instead of :meth:`setup_scripts`. This was not the case in 3.7.2.
-       When using symlinks, the original executables will be linked.
-
-    In addition, :class:`EnvBuilder` provides this utility method that can be
-    called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to
-    assist in installing custom scripts into the virtual environment.
-
     .. method:: install_scripts(context, path)
 
+        This method can be
+        called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to
+        assist in installing custom scripts into the virtual environment.
+
         *path* is the path to a directory that should contain subdirectories
         ``common``, ``posix``, ``nt``; each containing scripts destined for the
         ``bin`` directory in the environment.  The contents of ``common`` and the
@@ -495,6 +482,16 @@ creation according to their needs, the :class:`EnvBuilder` class.
 
        .. versionadded:: 3.13
 
+    .. versionchanged:: 3.7.2
+       Windows now uses redirector scripts for ``python[w].exe`` instead of
+       copying the actual binaries. In 3.7.2 only :meth:`setup_python` does
+       nothing unless running from a build in the source tree.
+
+    .. versionchanged:: 3.7.3
+       Windows copies the redirector scripts as part of :meth:`setup_python`
+       instead of :meth:`setup_scripts`. This was not the case in 3.7.2.
+       When using symlinks, the original executables will be linked.
+
 There is also a module-level convenience function:
 
 .. function:: create(env_dir, system_site_packages=False, clear=False, \

Doc/reference/datamodel.rst

@@ -1080,7 +1080,10 @@ Special attributes
        .. versionadded:: 3.13
 
    * - .. attribute:: type.__firstlineno__
-     - The line number of the first line of the class definition, including decorators.
+     - The line number of the first line of the class definition,
+       including decorators.
+       Setting the :attr:`__module__` attribute removes the
+       :attr:`!__firstlineno__` item from the type's dictionary.
 
        .. versionadded:: 3.13