Merge branch 'main' into feature-143017

Author: prithviraj-chaudhuri

.github/workflows/lint.yml

@@ -22,7 +22,4 @@ jobs:
       - uses: actions/checkout@v4
         with:
           persist-credentials: false
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.x"
-      - uses: pre-commit/action@v3.0.1
+      - uses: j178/prek-action@v1

.github/zizmor.yml

@@ -1,4 +1,4 @@
-# Configuration for the zizmor static analysis tool, run via pre-commit in CI
+# Configuration for the zizmor static analysis tool, run via prek in CI
 # https://woodruffw.github.io/zizmor/configuration/
 rules:
   dangerous-triggers:

Doc/library/compression.zstd.rst

@@ -73,7 +73,7 @@ Reading and writing compressed files
    argument is not None, a :exc:`!TypeError` will be raised.
 
    When writing, the *options* argument can be a dictionary
-   providing advanced decompression parameters; see
+   providing advanced compression parameters; see
    :class:`CompressionParameter` for detailed information about supported
    parameters. The *level* argument is the compression level to use when
    writing compressed data. Only one of *level* or *options* may be non-None.
@@ -117,7 +117,7 @@ Reading and writing compressed files
    argument is not None, a :exc:`!TypeError` will be raised.
 
    When writing, the *options* argument can be a dictionary
-   providing advanced decompression parameters; see
+   providing advanced compression parameters; see
    :class:`CompressionParameter` for detailed information about supported
    parameters. The *level* argument is the compression level to use when
    writing compressed data. Only one of *level* or *options* may be passed. The

Doc/library/concurrent.futures.rst

@@ -308,7 +308,7 @@ the bytes over a shared :mod:`socket <socket>` or
 
    .. note::
       The executor may replace uncaught exceptions from *initializer*
-      with :class:`~concurrent.futures.interpreter.ExecutionFailed`.
+      with :class:`~concurrent.interpreters.ExecutionFailed`.
 
    Other caveats from parent :class:`ThreadPoolExecutor` apply here.
 
@@ -320,11 +320,11 @@ likewise serializes the return value when sending it back.
 When a worker's current task raises an uncaught exception, the worker
 always tries to preserve the exception as-is.  If that is successful
 then it also sets the ``__cause__`` to a corresponding
-:class:`~concurrent.futures.interpreter.ExecutionFailed`
+:class:`~concurrent.interpreters.ExecutionFailed`
 instance, which contains a summary of the original exception.
 In the uncommon case that the worker is not able to preserve the
 original as-is then it directly preserves the corresponding
-:class:`~concurrent.futures.interpreter.ExecutionFailed`
+:class:`~concurrent.interpreters.ExecutionFailed`
 instance instead.
 
 
@@ -379,6 +379,11 @@ in a REPL or a lambda should not be expected to work.
    default in absence of a *mp_context* parameter. This feature is incompatible
    with the "fork" start method.
 
+   .. note::
+      Bugs have been reported when using the *max_tasks_per_child* feature that
+      can result in the :class:`ProcessPoolExecutor` hanging in some
+      circumstances. Follow its eventual resolution in :gh:`115634`.
+
    .. versionchanged:: 3.3
       When one of the worker processes terminates abruptly, a
       :exc:`~concurrent.futures.process.BrokenProcessPool` error is now raised.
@@ -715,15 +720,6 @@ Exception classes
 
    .. versionadded:: 3.14
 
-.. exception:: ExecutionFailed
-
-   Raised from :class:`~concurrent.futures.InterpreterPoolExecutor` when
-   the given initializer fails or from
-   :meth:`~concurrent.futures.Executor.submit` when there's an uncaught
-   exception from the submitted task.
-
-   .. versionadded:: 3.14
-
 .. currentmodule:: concurrent.futures.process
 
 .. exception:: BrokenProcessPool

Doc/library/importlib.metadata.rst

@@ -418,6 +418,16 @@ Distributions
    equal, even if they relate to the same installed distribution and
    accordingly have the same attributes.
 
+   .. method:: discover(cls, *, context=None, **kwargs)
+
+      Returns an iterable of :class:`Distribution` instances for all packages.
+
+      The optional argument *context* is a :class:`DistributionFinder.Context`
+      instance, used to modify the search for distributions. Alternatively,
+      *kwargs* may contain keyword arguments for constructing a new
+      :class:`!DistributionFinder.Context`.
+
+
 While the module level API described above is the most common and convenient usage,
 you can get all of that information from the :class:`!Distribution` class.
 :class:`!Distribution` is an abstract object that represents the metadata for
@@ -466,6 +476,61 @@ This metadata finder search defaults to ``sys.path``, but varies slightly in how
 - ``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.
 
+.. class:: DistributionFinder
+
+   A :class:`~importlib.abc.MetaPathFinder` subclass capable of discovering
+   installed distributions.
+
+   Custom providers should implement this interface in order to
+   supply metadata.
+
+    .. class:: Context(**kwargs)
+
+       A :class:`!Context` gives a custom provider a means to
+       solicit additional details from the callers of distribution discovery
+       functions like :func:`distributions` or :meth:`Distribution.discover`
+       beyond :attr:`!.name` and :attr:`!.path` when searching
+       for distributions.
+
+       For example, a provider could expose suites of packages in either a
+       "public" or "private" ``realm``. A caller of distribution discovery
+       functions may wish to query only for distributions in a particular realm
+       and could call ``distributions(realm="private")`` to signal to the
+       custom provider to only include distributions from that
+       realm.
+
+       Each :class:`!DistributionFinder` must expect any parameters and should
+       attempt to honor the canonical parameters defined below when
+       appropriate.
+
+       See the section on :ref:`implementing-custom-providers` for more details.
+
+       .. attribute:: name
+
+          Specific name for which a distribution finder should match.
+
+          A :attr:`!.name` of ``None`` matches all distributions.
+
+       .. attribute:: path
+
+          A property providing the sequence of directory paths that a
+          distribution finder should search.
+
+          Typically refers to Python installed package paths such as
+          "site-packages" directories and defaults to :attr:`sys.path`.
+
+
+.. function:: distributions(**kwargs)
+
+   Returns an iterable of :class:`Distribution` instances for all packages.
+
+   The *kwargs* argument may contain either a keyword argument ``context``, a
+   :class:`DistributionFinder.Context` instance, or pass keyword arguments for
+   constructing a new :class:`!DistributionFinder.Context`. The
+   :class:`!DistributionFinder.Context` is used to modify the search for
+   distributions.
+
+.. _implementing-custom-providers:
 
 Implementing Custom Providers
 =============================
@@ -493,7 +558,7 @@ interface expected of finders by Python's import system.
 ``importlib.metadata`` extends this protocol by looking for an optional
 ``find_distributions`` callable on the finders from
 :data:`sys.meta_path` and presents this extended interface as the
-``DistributionFinder`` abstract base class, which defines this abstract
+:class:`DistributionFinder` abstract base class, which defines this abstract
 method::
 
     @abc.abstractmethod
@@ -502,9 +567,11 @@ method::
         loading the metadata for packages for the indicated ``context``.
         """
 
-The ``DistributionFinder.Context`` object provides ``.path`` and ``.name``
-properties indicating the path to search and name to match and may
-supply other relevant context sought by the consumer.
+The :class:`DistributionFinder.Context` object provides
+:attr:`~DistributionFinder.Context.path` and
+:attr:`~DistributionFinder.Context.name` properties indicating the path to
+search and name to match and may supply other relevant context sought by the
+consumer.
 
 In practice, to support finding distribution package
 metadata in locations other than the file system, subclass
@@ -529,7 +596,7 @@ Imagine a custom finder that loads Python modules from a database::
 That importer now presumably provides importable modules from a
 database, but it provides no metadata or entry points. For this
 custom importer to provide metadata, it would also need to implement
-``DistributionFinder``::
+:class:`DistributionFinder`::
 
     from importlib.metadata import DistributionFinder
 

Doc/library/inspect.rst

@@ -273,6 +273,9 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 +-----------------+-------------------+---------------------------+
 |                 | ag_running        | is the generator running? |
 +-----------------+-------------------+---------------------------+
+|                 | ag_suspended      | is the generator          |
+|                 |                   | suspended?                |
++-----------------+-------------------+---------------------------+
 |                 | ag_code           | code                      |
 +-----------------+-------------------+---------------------------+
 | coroutine       | __name__          | name                      |
@@ -286,6 +289,9 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 +-----------------+-------------------+---------------------------+
 |                 | cr_running        | is the coroutine running? |
 +-----------------+-------------------+---------------------------+
+|                 | cr_suspended      | is the coroutine          |
+|                 |                   | suspended?                |
++-----------------+-------------------+---------------------------+
 |                 | cr_code           | code                      |
 +-----------------+-------------------+---------------------------+
 |                 | cr_origin         | where coroutine was       |
@@ -319,6 +325,18 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 
    Add ``__builtins__`` attribute to functions.
 
+.. versionchanged:: 3.11
+
+   Add ``gi_suspended`` attribute to generators.
+
+.. versionchanged:: 3.11
+
+   Add ``cr_suspended`` attribute to coroutines.
+
+.. versionchanged:: 3.12
+
+   Add ``ag_suspended`` attribute to async generators.
+
 .. versionchanged:: 3.14
 
    Add ``f_generator`` attribute to frames.

Doc/library/multiprocessing.rst

@@ -1693,11 +1693,14 @@ inherited by child processes.
    value is actually a synchronized wrapper for the array.
 
    *typecode_or_type* determines the type of the elements of the returned array:
-   it is either a ctypes type or a one character typecode of the kind used by
-   the :mod:`array` module.  If *size_or_initializer* is an integer, then it
-   determines the length of the array, and the array will be initially zeroed.
-   Otherwise, *size_or_initializer* is a sequence which is used to initialize
-   the array and whose length determines the length of the array.
+   it is either a :ref:`ctypes type <ctypes-fundamental-data-types>` or a one
+   character typecode of the kind used by the :mod:`array` module with the
+   exception of ``'w'``, which is not supported.  In addition, the ``'c'``
+   typecode is an alias for :class:`ctypes.c_char`.  If *size_or_initializer*
+   is an integer, then it determines the length of the array, and the array
+   will be initially zeroed. Otherwise, *size_or_initializer* is a sequence
+   which is used to initialize the array and whose length determines the length
+   of the array.
 
    If *lock* is ``True`` (the default) then a new lock object is created to
    synchronize access to the value.  If *lock* is a :class:`Lock` or

Doc/library/profiling.sampling.rst

@@ -878,9 +878,9 @@ interesting functions that highlights:
 
 Use :option:`--no-summary` to suppress both the legend and summary sections.
 
-To save pstats output to a file instead of stdout::
+To save pstats output to a binary file instead of stdout::
 
-   python -m profiling.sampling run -o profile.txt script.py
+   python -m profiling.sampling run -o profile.pstats script.py
 
 The pstats format supports several options for controlling the display.
 The :option:`--sort` option determines the column used for ordering results::
@@ -1455,7 +1455,9 @@ Output options
 
 .. option:: --pstats
 
-   Generate text statistics output. This is the default.
+   Generate pstats statistics. This is the default.
+   When written to stdout, the output is a text table; with :option:`-o`,
+   it is a binary pstats file.
 
 .. option:: --collapsed
 
@@ -1486,10 +1488,18 @@ Output options
 .. option:: -o <path>, --output <path>
 
    Output file or directory path. Default behavior varies by format:
-   :option:`--pstats` writes to stdout, while other formats generate a file
-   named ``<format>_<PID>.<ext>`` (for example, ``flamegraph_12345.html``).
+   :option:`--pstats` prints a text table to stdout, while ``-o`` writes a
+   binary pstats file. Other formats generate a file named
+   ``<format>_<PID>.<ext>`` (for example, ``flamegraph_12345.html``).
    :option:`--heatmap` creates a directory named ``heatmap_<PID>``.
 
+.. option:: --browser
+
+   Automatically open HTML output (:option:`--flamegraph` and
+   :option:`--heatmap`) in your default web browser after generation.
+   When profiling with :option:`--subprocesses`, only the main process
+   opens the browser; subprocess outputs are never auto-opened.
+
 
 pstats display options
 ----------------------

Doc/library/socket.rst

@@ -1072,10 +1072,16 @@ The :mod:`socket` module also offers various network-related services:
    a string representing the canonical name of the *host* if
    :const:`AI_CANONNAME` is part of the *flags* argument; else *canonname*
    will be empty.  *sockaddr* is a tuple describing a socket address, whose
-   format depends on the returned *family* (a ``(address, port)`` 2-tuple for
-   :const:`AF_INET`, a ``(address, port, flowinfo, scope_id)`` 4-tuple for
-   :const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect`
-   method.
+   format depends on the returned *family* and flags Python was compiled with,
+   and is meant to be passed to the :meth:`socket.connect` method.
+
+   *sockaddr* can be one of the following:
+
+   * a ``(address, port)`` 2-tuple for :const:`AF_INET`
+   * a ``(address, port, flowinfo, scope_id)`` 4-tuple for :const:`AF_INET6` if
+     Python was compiled with ``--enable-ipv6`` (the default)
+   * a 2-tuple containing raw data for :const:`AF_INET6` if Python was
+     compiled with ``--disable-ipv6``
 
    .. note::
 

Doc/library/textwrap.rst

@@ -102,6 +102,10 @@ functions should be good enough; otherwise, you should use an instance of
           print(repr(s))          # prints '    hello\n      world\n    '
           print(repr(dedent(s)))  # prints 'hello\n  world\n'
 
+   .. versionchanged:: 3.14
+      The :func:`!dedent` function now correctly normalizes blank lines containing
+      only whitespace characters. Previously, the implementation only normalized
+      blank lines containing tabs and spaces.
 
 .. function:: indent(text, prefix, predicate=None)