Merge branch 'main' into hy/drop_useless_code_in_zipimport

Author: brettcannon

Doc/c-api/iter.rst

@@ -54,6 +54,6 @@ There are two functions specifically for working with iterators.
 
    - ``PYGEN_RETURN`` if iterator returns. Return value is returned via *presult*.
    - ``PYGEN_NEXT`` if iterator yields. Yielded value is returned via *presult*.
-   - ``PYGEN_ERROR`` if iterator has raised and exception. *presult* is set to ``NULL``.
+   - ``PYGEN_ERROR`` if iterator has raised an exception. *presult* is set to ``NULL``.
 
    .. versionadded:: 3.10

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

@@ -8,6 +8,7 @@ Pending removal in Python 3.20
   - :mod:`argparse`
   - :mod:`csv`
   - :mod:`!ctypes.macholib`
+  - :mod:`imaplib`
   - :mod:`ipaddress`
   - :mod:`json`
   - :mod:`logging` (``__date__`` also deprecated)

Doc/library/functools.rst

@@ -190,7 +190,7 @@ The :mod:`functools` module defines the following functions:
 
    Note, type specificity applies only to the function's immediate arguments
    rather than their contents.  The scalar arguments, ``Decimal(42)`` and
-   ``Fraction(42)`` are be treated as distinct calls with distinct results.
+   ``Fraction(42)`` are treated as distinct calls with distinct results.
    In contrast, the tuple arguments ``('answer', Decimal(42))`` and
    ``('answer', Fraction(42))`` are treated as equivalent.
 

Doc/library/glob.rst

@@ -18,23 +18,27 @@
    single: - (minus); in glob-style wildcards
    single: . (dot); in glob-style wildcards
 
-The :mod:`glob` module finds all the pathnames matching a specified pattern
-according to the rules used by the Unix shell, although results are returned in
-arbitrary order.  No tilde expansion is done, but ``*``, ``?``, and character
+The :mod:`!glob` module finds pathnames
+using pattern matching rules similar to the Unix shell.
+No tilde expansion is done, but ``*``, ``?``, and character
 ranges expressed with ``[]`` will be correctly matched.  This is done by using
 the :func:`os.scandir` and :func:`fnmatch.fnmatch` functions in concert, and
 not by actually invoking a subshell.
 
-Note that files beginning with a dot (``.``) can only be matched by
+.. note::
+   The pathnames are returned in no particular order.  If you need a specific
+   order, sort the results.
+
+Files beginning with a dot (``.``) can only be matched by
 patterns that also start with a dot,
 unlike :func:`fnmatch.fnmatch` or :func:`pathlib.Path.glob`.
-(For tilde and shell variable expansion, use :func:`os.path.expanduser` and
-:func:`os.path.expandvars`.)
+For tilde and shell variable expansion, use :func:`os.path.expanduser` and
+:func:`os.path.expandvars`.
 
 For a literal match, wrap the meta-characters in brackets.
 For example, ``'[?]'`` matches the character ``'?'``.
 
-The :mod:`glob` module defines the following functions:
+The :mod:`!glob` module defines the following functions:
 
 
 .. function:: glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, \
@@ -51,7 +55,7 @@ The :mod:`glob` module defines the following functions:
 
    If *root_dir* is not ``None``, it should be a :term:`path-like object`
    specifying the root directory for searching.  It has the same effect on
-   :func:`glob` as changing the current directory before calling it.  If
+   :func:`!glob` as changing the current directory before calling it.  If
    *pathname* is relative, the result will contain paths relative to
    *root_dir*.
 

Doc/library/os.rst

@@ -3451,7 +3451,10 @@ features:
 
    .. attribute:: stx_mnt_id
 
-      Mount ID.
+      Mount identifier.
+
+      Equal to ``None`` if :data:`STATX_MNT_ID` is missing from
+      :attr:`~os.statx_result.stx_mask`.
 
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
          userspace API headers >= 5.8.
@@ -3460,19 +3463,28 @@ features:
 
       Direct I/O memory buffer alignment requirement.
 
+      Equal to ``None`` if :data:`STATX_DIOALIGN` is missing from
+      :attr:`~os.statx_result.stx_mask`.
+
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
          userspace API headers >= 6.1.
 
    .. attribute:: stx_dio_offset_align
 
       Direct I/O file offset alignment requirement.
 
+      Equal to ``None`` if :data:`STATX_DIOALIGN` is missing from
+      :attr:`~os.statx_result.stx_mask`.
+
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
          userspace API headers >= 6.1.
 
    .. attribute:: stx_subvol
 
-      Subvolume ID.
+      Subvolume identifier.
+
+      Equal to ``None`` if :data:`STATX_SUBVOL` is missing from
+      :attr:`~os.statx_result.stx_mask`.
 
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
          userspace API headers >= 6.10.
@@ -3481,34 +3493,49 @@ features:
 
       Minimum size for direct I/O with torn-write protection.
 
+      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
+      :attr:`~os.statx_result.stx_mask`.
+
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
          userspace API headers >= 6.11.
 
    .. attribute:: stx_atomic_write_unit_max
 
       Maximum size for direct I/O with torn-write protection.
 
+      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
+      :attr:`~os.statx_result.stx_mask`.
+
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
          userspace API headers >= 6.11.
 
    .. attribute:: stx_atomic_write_unit_max_opt
 
       Maximum optimized size for direct I/O with torn-write protection.
 
+      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
+      :attr:`~os.statx_result.stx_mask`.
+
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
          userspace API headers >= 6.16.
 
    .. attribute:: stx_atomic_write_segments_max
 
       Maximum iovecs for direct I/O with torn-write protection.
 
+      Equal to ``None`` if :data:`STATX_WRITE_ATOMIC` is missing from
+      :attr:`~os.statx_result.stx_mask`.
+
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
          userspace API headers >= 6.11.
 
    .. attribute:: stx_dio_read_offset_align
 
       Direct I/O file offset alignment requirement for reads.
 
+      Equal to ``None`` if :data:`STATX_DIO_READ_ALIGN` is missing from
+      :attr:`~os.statx_result.stx_mask`.
+
       .. availability:: Linux >= 4.11 with glibc >= 2.28 and build-time kernel
          userspace API headers >= 6.14.
 

Doc/library/resource.rst

@@ -141,7 +141,7 @@ platform.
 .. data:: RLIMIT_CPU
 
    The maximum amount of processor time (in seconds) that a process can use. If
-   this limit is exceeded, a :const:`SIGXCPU` signal is sent to the process. (See
+   this limit is exceeded, a :const:`~signal.SIGXCPU` signal is sent to the process. (See
    the :mod:`signal` module documentation for information about how to catch this
    signal and do something useful, e.g. flush open files to disk.)
 
@@ -363,47 +363,47 @@ These functions are used to retrieve resource usage information:
    For backward compatibility, the return value is also accessible as a tuple of 16
    elements.
 
-   The fields :attr:`ru_utime` and :attr:`ru_stime` of the return value are
+   The fields :attr:`!ru_utime` and :attr:`!ru_stime` of the return value are
    floating-point values representing the amount of time spent executing in user
    mode and the amount of time spent executing in system mode, respectively. The
    remaining values are integers. Consult the :manpage:`getrusage(2)` man page for
    detailed information about these values. A brief summary is presented here:
 
-   +--------+---------------------+---------------------------------------+
-   | Index  | Field               | Resource                              |
-   +========+=====================+=======================================+
-   | ``0``  | :attr:`ru_utime`    | time in user mode (float seconds)     |
-   +--------+---------------------+---------------------------------------+
-   | ``1``  | :attr:`ru_stime`    | time in system mode (float seconds)   |
-   +--------+---------------------+---------------------------------------+
-   | ``2``  | :attr:`ru_maxrss`   | maximum resident set size             |
-   +--------+---------------------+---------------------------------------+
-   | ``3``  | :attr:`ru_ixrss`    | shared memory size                    |
-   +--------+---------------------+---------------------------------------+
-   | ``4``  | :attr:`ru_idrss`    | unshared memory size                  |
-   +--------+---------------------+---------------------------------------+
-   | ``5``  | :attr:`ru_isrss`    | unshared stack size                   |
-   +--------+---------------------+---------------------------------------+
-   | ``6``  | :attr:`ru_minflt`   | page faults not requiring I/O         |
-   +--------+---------------------+---------------------------------------+
-   | ``7``  | :attr:`ru_majflt`   | page faults requiring I/O             |
-   +--------+---------------------+---------------------------------------+
-   | ``8``  | :attr:`ru_nswap`    | number of swap outs                   |
-   +--------+---------------------+---------------------------------------+
-   | ``9``  | :attr:`ru_inblock`  | block input operations                |
-   +--------+---------------------+---------------------------------------+
-   | ``10`` | :attr:`ru_oublock`  | block output operations               |
-   +--------+---------------------+---------------------------------------+
-   | ``11`` | :attr:`ru_msgsnd`   | messages sent                         |
-   +--------+---------------------+---------------------------------------+
-   | ``12`` | :attr:`ru_msgrcv`   | messages received                     |
-   +--------+---------------------+---------------------------------------+
-   | ``13`` | :attr:`ru_nsignals` | signals received                      |
-   +--------+---------------------+---------------------------------------+
-   | ``14`` | :attr:`ru_nvcsw`    | voluntary context switches            |
-   +--------+---------------------+---------------------------------------+
-   | ``15`` | :attr:`ru_nivcsw`   | involuntary context switches          |
-   +--------+---------------------+---------------------------------------+
+   +--------+----------------------+---------------------------------------+
+   | Index  | Field                | Resource                              |
+   +========+======================+=======================================+
+   | ``0``  | :attr:`!ru_utime`    | time in user mode (float seconds)     |
+   +--------+----------------------+---------------------------------------+
+   | ``1``  | :attr:`!ru_stime`    | time in system mode (float seconds)   |
+   +--------+----------------------+---------------------------------------+
+   | ``2``  | :attr:`!ru_maxrss`   | maximum resident set size             |
+   +--------+----------------------+---------------------------------------+
+   | ``3``  | :attr:`!ru_ixrss`    | shared memory size                    |
+   +--------+----------------------+---------------------------------------+
+   | ``4``  | :attr:`!ru_idrss`    | unshared memory size                  |
+   +--------+----------------------+---------------------------------------+
+   | ``5``  | :attr:`!ru_isrss`    | unshared stack size                   |
+   +--------+----------------------+---------------------------------------+
+   | ``6``  | :attr:`!ru_minflt`   | page faults not requiring I/O         |
+   +--------+----------------------+---------------------------------------+
+   | ``7``  | :attr:`!ru_majflt`   | page faults requiring I/O             |
+   +--------+----------------------+---------------------------------------+
+   | ``8``  | :attr:`!ru_nswap`    | number of swap outs                   |
+   +--------+----------------------+---------------------------------------+
+   | ``9``  | :attr:`!ru_inblock`  | block input operations                |
+   +--------+----------------------+---------------------------------------+
+   | ``10`` | :attr:`!ru_oublock`  | block output operations               |
+   +--------+----------------------+---------------------------------------+
+   | ``11`` | :attr:`!ru_msgsnd`   | messages sent                         |
+   +--------+----------------------+---------------------------------------+
+   | ``12`` | :attr:`!ru_msgrcv`   | messages received                     |
+   +--------+----------------------+---------------------------------------+
+   | ``13`` | :attr:`!ru_nsignals` | signals received                      |
+   +--------+----------------------+---------------------------------------+
+   | ``14`` | :attr:`!ru_nvcsw`    | voluntary context switches            |
+   +--------+----------------------+---------------------------------------+
+   | ``15`` | :attr:`!ru_nivcsw`   | involuntary context switches          |
+   +--------+----------------------+---------------------------------------+
 
    This function will raise a :exc:`ValueError` if an invalid *who* parameter is
    specified. It may also raise :exc:`error` exception in unusual circumstances.

Doc/library/signal.rst

@@ -265,6 +265,12 @@ The variables defined in the :mod:`signal` module are:
 
    .. availability:: Unix.
 
+.. data:: SIGXCPU
+
+   CPU time limit exceeded.
+
+   .. availability:: Unix.
+
 .. data:: SIG*
 
    All the signal numbers are defined symbolically.  For example, the hangup signal

Doc/library/zlib.rst

@@ -56,21 +56,20 @@ The available exception and functions in this module are:
 
    .. versionadded:: 3.15
 
-.. function:: compress(data, /, level=-1, wbits=MAX_WBITS)
+.. function:: compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)
 
    Compresses the bytes in *data*, returning a bytes object containing compressed data.
    *level* is an integer from ``0`` to ``9`` or ``-1`` controlling the level of compression;
-   ``1`` (Z_BEST_SPEED) is fastest and produces the least compression, ``9`` (Z_BEST_COMPRESSION)
-   is slowest and produces the most.  ``0`` (Z_NO_COMPRESSION) is no compression.
-   The default value is ``-1`` (Z_DEFAULT_COMPRESSION).  Z_DEFAULT_COMPRESSION represents a default
-   compromise between speed and compression (currently equivalent to level 6).
+   See :const:`Z_BEST_SPEED` (``1``), :const:`Z_BEST_COMPRESSION` (``9``),
+   :const:`Z_NO_COMPRESSION` (``0``), and the default,
+   :const:`Z_DEFAULT_COMPRESSION` (``-1``) for more information about these values.
 
    .. _compress-wbits:
 
    The *wbits* argument controls the size of the history buffer (or the
    "window size") used when compressing data, and whether a header and
    trailer is included in the output.  It can take several ranges of values,
-   defaulting to ``15`` (MAX_WBITS):
+   defaulting to ``15`` (:const:`MAX_WBITS`):
 
    * +9 to +15: The base-two logarithm of the window size, which
      therefore ranges between 512 and 32768.  Larger values produce
@@ -94,17 +93,15 @@ The available exception and functions in this module are:
       The *wbits* parameter is now available to set window bits and
       compression type.
 
-.. function:: compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])
+.. function:: compressobj(level=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])
 
    Returns a compression object, to be used for compressing data streams that won't
    fit into memory at once.
 
    *level* is the compression level -- an integer from ``0`` to ``9`` or ``-1``.
-   A value of ``1`` (Z_BEST_SPEED) is fastest and produces the least compression,
-   while a value of ``9`` (Z_BEST_COMPRESSION) is slowest and produces the most.
-   ``0`` (Z_NO_COMPRESSION) is no compression.  The default value is ``-1`` (Z_DEFAULT_COMPRESSION).
-   Z_DEFAULT_COMPRESSION represents a default compromise between speed and compression
-   (currently equivalent to level 6).
+   See :const:`Z_BEST_SPEED` (``1``), :const:`Z_BEST_COMPRESSION` (``9``),
+   :const:`Z_NO_COMPRESSION` (``0``), and the default,
+   :const:`Z_DEFAULT_COMPRESSION` (``-1``) for more information about these values.
 
    *method* is the compression algorithm. Currently, the only supported value is
    :const:`DEFLATED`.
@@ -119,7 +116,7 @@ The available exception and functions in this module are:
 
    *strategy* is used to tune the compression algorithm. Possible values are
    :const:`Z_DEFAULT_STRATEGY`, :const:`Z_FILTERED`, :const:`Z_HUFFMAN_ONLY`,
-   :const:`Z_RLE` (zlib 1.2.0.1) and :const:`Z_FIXED` (zlib 1.2.2.2).
+   :const:`Z_RLE` and :const:`Z_FIXED`.
 
    *zdict* is a predefined compression dictionary. This is a sequence of bytes
    (such as a :class:`bytes` object) containing subsequences that are expected
@@ -247,7 +244,7 @@ Compression objects support the following methods:
    All pending input is processed, and a bytes object containing the remaining compressed
    output is returned.  *mode* can be selected from the constants
    :const:`Z_NO_FLUSH`, :const:`Z_PARTIAL_FLUSH`, :const:`Z_SYNC_FLUSH`,
-   :const:`Z_FULL_FLUSH`, :const:`Z_BLOCK` (zlib 1.2.3.4), or :const:`Z_FINISH`,
+   :const:`Z_FULL_FLUSH`, :const:`Z_BLOCK`, or :const:`Z_FINISH`,
    defaulting to :const:`Z_FINISH`.  Except :const:`Z_FINISH`, all constants
    allow compressing further bytestrings of data, while :const:`Z_FINISH` finishes the
    compressed stream and prevents compressing any more data.  After calling :meth:`flush`
@@ -365,24 +362,25 @@ behavior:
 
 .. data:: Z_NO_COMPRESSION
 
-   Compression level ``0``.
+   Compression level ``0``; no compression.
 
    .. versionadded:: 3.6
 
 
 .. data:: Z_BEST_SPEED
 
-   Compression level ``1``.
+   Compression level ``1``; fastest and produces the least compression.
 
 
 .. data:: Z_BEST_COMPRESSION
 
-   Compression level ``9``.
+   Compression level ``9``; slowest and produces the most compression.
 
 
 .. data:: Z_DEFAULT_COMPRESSION
 
-   Default compression level (``-1``).
+   Default compression level (``-1``); a compromise between speed and
+   compression. Currently equivalent to compression level ``6``.
 
 
 .. data:: Z_DEFAULT_STRATEGY