Merge branch 'python:main' into main

Author: znsoooo

Doc/c-api/typeobj.rst

@@ -2523,11 +2523,11 @@ Slot Type typedefs
 
 .. c:type:: PyObject *(*descrgetfunc)(PyObject *, PyObject *, PyObject *)
 
-   See :c:member:`~PyTypeObject.tp_descrget`.
+   See :c:member:`~PyTypeObject.tp_descr_get`.
 
 .. c:type:: int (*descrsetfunc)(PyObject *, PyObject *, PyObject *)
 
-   See :c:member:`~PyTypeObject.tp_descrset`.
+   See :c:member:`~PyTypeObject.tp_descr_set`.
 
 .. c:type:: Py_hash_t (*hashfunc)(PyObject *)
 

Doc/faq/programming.rst

@@ -409,8 +409,9 @@ What is the difference between arguments and parameters?
 
 :term:`Parameters <parameter>` are defined by the names that appear in a
 function definition, whereas :term:`arguments <argument>` are the values
-actually passed to a function when calling it.  Parameters define what types of
-arguments a function can accept.  For example, given the function definition::
+actually passed to a function when calling it.  Parameters define what
+:term:`kind of arguments <parameter>` a function can accept.  For
+example, given the function definition::
 
    def func(foo, bar=None, **kwargs):
        pass

Doc/library/dis.rst

@@ -446,12 +446,13 @@ result back on the stack.
 
 **Binary and in-place operations**
 
-Binary operations remove the top of the stack (TOS) and the second top-most
-stack item (TOS1) from the stack.  They perform the operation, and put the
-result back on the stack.
+In the following, TOS is the top-of-stack.
+TOS1, TOS2, TOS3 are the second, thrid and fourth items on the stack, respectively.
+
+Binary operations remove the top two items from the stack (TOS and TOS1).
+They perform the operation, then put the result back on the stack.
 
-In-place operations are like binary operations, in that they remove TOS and
-TOS1, and push the result back on the stack, but the operation is done in-place
+In-place operations are like binary operations, but the operation is done in-place
 when TOS1 supports it, and the resulting TOS may be (but does not have to be)
 the original TOS1.
 
@@ -460,6 +461,7 @@ the original TOS1.
 
    Implements the binary and in-place operators (depending on the value of
    *op*).
+   ``TOS = TOS1 op TOS``.
 
    .. versionadded:: 3.11
 
@@ -479,6 +481,20 @@ the original TOS1.
    Implements ``del TOS1[TOS]``.
 
 
+.. opcode:: BINARY_SLICE
+
+   Implements ``TOS = TOS2[TOS1:TOS]``.
+
+   .. versionadded:: 3.12
+
+
+.. opcode:: STORE_SLICE
+
+   Implements ``TOS2[TOS1:TOS] = TOS3``.
+
+   .. versionadded:: 3.12
+
+
 **Coroutine opcodes**
 
 .. opcode:: GET_AWAITABLE (where)
@@ -512,8 +528,8 @@ the original TOS1.
 
 .. opcode:: GET_ANEXT
 
-   Implements ``PUSH(get_awaitable(TOS.__anext__()))``.  See ``GET_AWAITABLE``
-   for details about ``get_awaitable``
+   Pushes ``get_awaitable(TOS.__anext__())`` to the stack.  See
+   ``GET_AWAITABLE`` for details about ``get_awaitable``.
 
    .. versionadded:: 3.5
 

Doc/library/idle.rst

@@ -357,7 +357,7 @@ for more on Help menu choices.
    single: Clear Breakpoint
    single: breakpoints
 
-Context Menus
+Context menus
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Open a context menu by right-clicking in a window (Control-click on macOS).
@@ -398,7 +398,7 @@ Squeeze
 
 .. _editing-and-navigation:
 
-Editing and navigation
+Editing and Navigation
 ----------------------
 
 Editor windows
@@ -576,17 +576,29 @@ line to the top of the editor.
 The text and background colors for the context pane can be configured under
 the Highlights tab in the Configure IDLE dialog.
 
-Python Shell window
-^^^^^^^^^^^^^^^^^^^
+Shell window
+^^^^^^^^^^^^
 
-With IDLE's Shell, one enters, edits, and recalls complete statements.
-Most consoles and terminals only work with a single physical line at a time.
+In IDLE's Shell, enter, edit, and recall complete statements. (Most
+consoles and terminals only work with a single physical line at a time).
+
+Submit a single-line statement for execution by hitting :kbd:`Return`
+with the cursor anywhere on the line.  If a line is extended with
+Backslash (:kbd:`\\`), the cursor must be on the last physical line.
+Submit a multi-line compound statement by entering a blank line after
+the statement.
 
 When one pastes code into Shell, it is not compiled and possibly executed
-until one hits :kbd:`Return`.  One may edit pasted code first.
-If one pastes more that one statement into Shell, the result will be a
+until one hits :kbd:`Return`, as specified above.
+One may edit pasted code first.
+If one pastes more than one statement into Shell, the result will be a
 :exc:`SyntaxError` when multiple statements are compiled as if they were one.
 
+Lines containing`'RESTART'` mean that the user execution process has been
+re-started.  This occurs when the user execution process has crashed,
+when one requests a restart on the Shell menu, or when one runs code
+in an editor window.
+
 The editing features described in previous subsections work when entering
 code interactively.  IDLE's Shell window also responds to the following keys.
 
@@ -603,7 +615,8 @@ code interactively.  IDLE's Shell window also responds to the following keys.
 
   * :kbd:`Alt-n` retrieves next. On macOS use :kbd:`C-n`.
 
-  * :kbd:`Return` while on any previous command retrieves that command
+  * :kbd:`Return` while the cursor is on any previous command
+    retrieves that command
 
 Text colors
 ^^^^^^^^^^^
@@ -627,7 +640,7 @@ Highlighting tab.  The marking of debugger breakpoint lines in the editor and
 text in popups and dialogs is not user-configurable.
 
 
-Startup and code execution
+Startup and Code Execution
 --------------------------
 
 Upon startup with the ``-s`` option, IDLE will execute the file referenced by
@@ -894,7 +907,7 @@ with the default subprocess if at all possible.
 .. deprecated:: 3.4
 
 
-Help and preferences
+Help and Preferences
 --------------------
 
 .. _help-sources:

Doc/library/importlib.metadata.rst

@@ -13,13 +13,13 @@
 
 **Source code:** :source:`Lib/importlib/metadata/__init__.py`
 
-``importlib.metadata`` is a library that provides for access to installed
-package metadata.  Built in part on Python's import system, this library
+``importlib.metadata`` is a library that provides access to installed
+package metadata, such as its entry points or its
+top-level name.  Built in part on Python's import system, this library
 intends to replace similar functionality in the `entry point
 API`_ and `metadata API`_ of ``pkg_resources``.  Along with
-:mod:`importlib.resources` (with new features backported to the
-`importlib_resources`_ package), this can eliminate the need to use the older
-and less efficient
+:mod:`importlib.resources`,
+this package can eliminate the need to use the older and less efficient
 ``pkg_resources`` package.
 
 By "installed package" we generally mean a third-party package installed into
@@ -32,6 +32,13 @@ By default, package metadata can live on the file system or in zip archives on
 anywhere.
 
 
+.. seealso::
+
+   https://importlib-metadata.readthedocs.io/
+      The documentation for ``importlib_metadata``, which supplies a
+      backport of ``importlib.metadata``.
+
+
 Overview
 ========
 
@@ -54,9 +61,9 @@ You can get the version string for ``wheel`` by running the following:
     >>> version('wheel')  # doctest: +SKIP
     '0.32.3'
 
-You can also get the set of entry points keyed by group, such as
+You can also get a collection of entry points selectable by properties of the EntryPoint (typically 'group' or 'name'), such as
 ``console_scripts``, ``distutils.commands`` and others.  Each group contains a
-sequence of :ref:`EntryPoint <entry-points>` objects.
+collection of :ref:`EntryPoint <entry-points>` objects.
 
 You can get the :ref:`metadata for a distribution <metadata>`::
 
@@ -91,7 +98,7 @@ Query all entry points::
     >>> eps = entry_points()  # doctest: +SKIP
 
 The ``entry_points()`` function returns an ``EntryPoints`` object,
-a sequence of all ``EntryPoint`` objects with ``names`` and ``groups``
+a collection of all ``EntryPoint`` objects with ``names`` and ``groups``
 attributes for convenience::
 
     >>> sorted(eps.groups)  # doctest: +SKIP
@@ -174,6 +181,13 @@ all the metadata in a JSON-compatible form per :PEP:`566`::
     >>> wheel_metadata.json['requires_python']
     '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
 
+.. note::
+
+    The actual type of the object returned by ``metadata()`` is an
+    implementation detail and should be accessed only through the interface
+    described by the
+    `PackageMetadata protocol <https://importlib-metadata.readthedocs.io/en/latest/api.html#importlib_metadata.PackageMetadata>`.
+
 .. versionchanged:: 3.10
    The ``Description`` is now included in the metadata when presented
    through the payload. Line continuation characters have been removed.
@@ -295,6 +309,15 @@ The full set of available metadata is not described here.  See :pep:`566`
 for additional details.
 
 
+Distribution Discovery
+======================
+
+By default, this package provides built-in support for discovery of metadata for file system and zip file packages. This metadata finder search defaults to ``sys.path``, but varies slightly in how it interprets those values from how other import machinery does. In particular:
+
+- ``importlib.metadata`` does not honor :class:`bytes` objects on ``sys.path``.
+- ``importlib.metadata`` will incidentally honor :py:class:`pathlib.Path` objects on ``sys.path`` even though such values will be ignored for imports.
+
+
 Extending the search algorithm
 ==============================
 

Doc/library/locale.rst

@@ -412,18 +412,6 @@ The :mod:`locale` module defines the following exception and functions:
       The *monetary* keyword parameter was added.
 
 
-.. function:: format(format, val, grouping=False, monetary=False)
-
-   Please note that this function works like :meth:`format_string` but will
-   only work for exactly one ``%char`` specifier.  For example, ``'%f'`` and
-   ``'%.0f'`` are both valid specifiers, but ``'%f KiB'`` is not.
-
-   For whole format strings, use :func:`format_string`.
-
-   .. deprecated:: 3.7
-      Use :meth:`format_string` instead.
-
-
 .. function:: currency(val, symbol=True, grouping=False, international=False)
 
    Formats a number *val* according to the current :const:`LC_MONETARY` settings.
@@ -507,7 +495,7 @@ The :mod:`locale` module defines the following exception and functions:
 
 .. data:: LC_NUMERIC
 
-   Locale category for formatting numbers.  The functions :func:`.format`,
+   Locale category for formatting numbers.  The functions :func:`format_string`,
    :func:`atoi`, :func:`atof` and :func:`.str` of the :mod:`locale` module are
    affected by that category.  All other numeric formatting operations are not
    affected.
@@ -569,7 +557,7 @@ document that your module is not compatible with non-\ ``C`` locale settings.
 
 The only way to perform numeric operations according to the locale is to use the
 special functions defined by this module: :func:`atof`, :func:`atoi`,
-:func:`.format`, :func:`.str`.
+:func:`format_string`, :func:`.str`.
 
 There is no way to perform case conversions and character classifications
 according to the locale.  For (Unicode) text strings these are done according

Doc/library/unittest.rst

@@ -1261,9 +1261,6 @@ Test cases
          :meth:`.assertRegex`.
       .. versionadded:: 3.2
          :meth:`.assertNotRegex`.
-      .. versionadded:: 3.5
-         The name ``assertNotRegexpMatches`` is a deprecated alias
-         for :meth:`.assertNotRegex`.
 
 
    .. method:: assertCountEqual(first, second, msg=None)
@@ -1660,40 +1657,6 @@ Test cases
    :mod:`unittest`-based test framework.
 
 
-.. _deprecated-aliases:
-
-Deprecated aliases
-##################
-
-For historical reasons, some of the :class:`TestCase` methods had one or more
-aliases that are now deprecated.  The following table lists the correct names
-along with their deprecated aliases:
-
-   ==============================  ====================== =======================
-    Method Name                     Deprecated alias       Deprecated alias
-   ==============================  ====================== =======================
-    :meth:`.assertEqual`            failUnlessEqual        assertEquals
-    :meth:`.assertNotEqual`         failIfEqual            assertNotEquals
-    :meth:`.assertTrue`             failUnless             assert\_
-    :meth:`.assertFalse`            failIf
-    :meth:`.assertRaises`           failUnlessRaises
-    :meth:`.assertAlmostEqual`      failUnlessAlmostEqual  assertAlmostEquals
-    :meth:`.assertNotAlmostEqual`   failIfAlmostEqual      assertNotAlmostEquals
-    :meth:`.assertRegex`                                   assertRegexpMatches
-    :meth:`.assertNotRegex`                                assertNotRegexpMatches
-    :meth:`.assertRaisesRegex`                             assertRaisesRegexp
-   ==============================  ====================== =======================
-
-   .. deprecated:: 3.1
-         The fail* aliases listed in the second column have been deprecated.
-   .. deprecated:: 3.2
-         The assert* aliases listed in the third column have been deprecated.
-   .. deprecated:: 3.2
-         ``assertRegexpMatches`` and ``assertRaisesRegexp`` have been renamed to
-         :meth:`.assertRegex` and :meth:`.assertRaisesRegex`.
-   .. deprecated:: 3.5
-         The ``assertNotRegexpMatches`` name is deprecated in favor of :meth:`.assertNotRegex`.
-
 .. _testsuite-objects:
 
 Grouping tests
@@ -1819,7 +1782,7 @@ Loading and running tests
       case is created for that method instead.
 
 
-   .. method:: loadTestsFromModule(module, pattern=None)
+   .. method:: loadTestsFromModule(module, *, pattern=None)
 
       Return a suite of all test cases contained in the given module. This
       method searches *module* for classes derived from :class:`TestCase` and
@@ -1843,10 +1806,11 @@ Loading and running tests
          Support for ``load_tests`` added.
 
       .. versionchanged:: 3.5
-         The undocumented and unofficial *use_load_tests* default argument is
-         deprecated and ignored, although it is still accepted for backward
-         compatibility.  The method also now accepts a keyword-only argument
-         *pattern* which is passed to ``load_tests`` as the third argument.
+         Support for a keyword-only argument *pattern* has been added.
+
+      .. versionchanged:: 3.12
+         The undocumented and unofficial *use_load_tests* parameter has been
+         removed.
 
 
    .. method:: loadTestsFromName(name, module=None)
@@ -2203,8 +2167,6 @@ Loading and running tests
    :class:`TextTestRunner`.
 
    .. versionadded:: 3.2
-      This class was previously named ``_TextTestResult``. The old name still
-      exists as an alias but is deprecated.
 
 
 .. data:: defaultTestLoader
@@ -2227,10 +2189,7 @@ Loading and running tests
    By default this runner shows :exc:`DeprecationWarning`,
    :exc:`PendingDeprecationWarning`, :exc:`ResourceWarning` and
    :exc:`ImportWarning` even if they are :ref:`ignored by default
-   <warning-ignored>`. Deprecation warnings caused by :ref:`deprecated unittest
-   methods <deprecated-aliases>` are also special-cased and, when the warning
-   filters are ``'default'`` or ``'always'``, they will appear only once
-   per-module, in order to avoid too many warning messages.  This behavior can
+   <warning-ignored>`.  This behavior can
    be overridden using Python's :option:`!-Wd` or :option:`!-Wa` options
    (see :ref:`Warning control <using-on-warnings>`) and leaving
    *warnings* to ``None``.