Merge branch 'main' into warn_explicit-no-module

Author: serhiy-storchaka

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.15.rst

@@ -92,7 +92,7 @@ Pending removal in Python 3.15
     Use ``class TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})``
     to create a TypedDict with zero field.
 
-  * The :func:`typing.no_type_check_decorator` decorator function
+  * The :func:`!typing.no_type_check_decorator` decorator function
     has been deprecated since Python 3.13.
     After eight years in the :mod:`typing` module,
     it has yet to be supported by any major type checker.

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/faq/general.rst

@@ -186,7 +186,7 @@ How do I get documentation on Python?
 -------------------------------------
 
 The standard documentation for the current stable version of Python is available
-at https://docs.python.org/3/.  PDF, plain text, and downloadable HTML versions are
+at https://docs.python.org/3/.  EPUB, plain text, and downloadable HTML versions are
 also available at https://docs.python.org/3/download.html.
 
 The documentation is written in reStructuredText and processed by `the Sphinx

Doc/library/annotationlib.rst

@@ -340,14 +340,29 @@ Functions
 
    * VALUE: :attr:`!object.__annotations__` is tried first; if that does not exist,
      the :attr:`!object.__annotate__` function is called if it exists.
+
    * FORWARDREF: If :attr:`!object.__annotations__` exists and can be evaluated successfully,
      it is used; otherwise, the :attr:`!object.__annotate__` function is called. If it
      does not exist either, :attr:`!object.__annotations__` is tried again and any error
      from accessing it is re-raised.
+
+     * When calling :attr:`!object.__annotate__` it is first called with :attr:`~Format.FORWARDREF`.
+       If this is not implemented, it will then check if :attr:`~Format.VALUE_WITH_FAKE_GLOBALS`
+       is supported and use that in the fake globals environment.
+       If neither of these formats are supported, it will fall back to using :attr:`~Format.VALUE`.
+       If :attr:`~Format.VALUE` fails, the error from this call will be raised.
+
    * STRING: If :attr:`!object.__annotate__` exists, it is called first;
      otherwise, :attr:`!object.__annotations__` is used and stringified
      using :func:`annotations_to_string`.
 
+     * When calling :attr:`!object.__annotate__` it is first called with :attr:`~Format.STRING`.
+       If this is not implemented, it will then check if :attr:`~Format.VALUE_WITH_FAKE_GLOBALS`
+       is supported and use that in the fake globals environment.
+       If neither of these formats are supported, it will fall back to using :attr:`~Format.VALUE`
+       with the result converted using :func:`annotations_to_string`.
+       If :attr:`~Format.VALUE` fails, the error from this call will be raised.
+
    Returns a dict. :func:`!get_annotations` returns a new dict every time
    it's called; calling it twice on the same object will return two
    different but equivalent dicts.

Doc/library/codecs.rst

@@ -989,17 +989,22 @@ defined in Unicode. A simple and straightforward way that can store each Unicode
 code point, is to store each code point as four consecutive bytes. There are two
 possibilities: store the bytes in big endian or in little endian order. These
 two encodings are called ``UTF-32-BE`` and ``UTF-32-LE`` respectively. Their
-disadvantage is that if e.g. you use ``UTF-32-BE`` on a little endian machine you
-will always have to swap bytes on encoding and decoding. ``UTF-32`` avoids this
-problem: bytes will always be in natural endianness. When these bytes are read
-by a CPU with a different endianness, then bytes have to be swapped though. To
-be able to detect the endianness of a ``UTF-16`` or ``UTF-32`` byte sequence,
-there's the so called BOM ("Byte Order Mark"). This is the Unicode character
-``U+FEFF``. This character can be prepended to every ``UTF-16`` or ``UTF-32``
-byte sequence. The byte swapped version of this character (``0xFFFE``) is an
-illegal character that may not appear in a Unicode text. So when the
-first character in a ``UTF-16`` or ``UTF-32`` byte sequence
-appears to be a ``U+FFFE`` the bytes have to be swapped on decoding.
+disadvantage is that if, for example, you use ``UTF-32-BE`` on a little endian
+machine you will always have to swap bytes on encoding and decoding.
+Python's ``UTF-16`` and ``UTF-32`` codecs avoid this problem by using the
+platform's native byte order when no BOM is present.
+Python follows prevailing platform
+practice, so native-endian data round-trips without redundant byte swapping,
+even though the Unicode Standard defaults to big-endian when the byte order is
+unspecified. When these bytes are read by a CPU with a different endianness,
+the bytes have to be swapped. To be able to detect the endianness of a
+``UTF-16`` or ``UTF-32`` byte sequence, a BOM ("Byte Order Mark") is used.
+This is the Unicode character ``U+FEFF``. This character can be prepended to every
+``UTF-16`` or ``UTF-32`` byte sequence. The byte swapped version of this character
+(``0xFFFE``) is an illegal character that may not appear in a Unicode text.
+When the first character of a ``UTF-16`` or ``UTF-32`` byte sequence is
+``U+FFFE``, the bytes have to be swapped on decoding.
+
 Unfortunately the character ``U+FEFF`` had a second purpose as
 a ``ZERO WIDTH NO-BREAK SPACE``: a character that has no width and doesn't allow
 a word to be split. It can e.g. be used to give hints to a ligature algorithm.

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.
 
@@ -3539,9 +3566,9 @@ features:
           STATX_WRITE_ATOMIC
           STATX_DIO_READ_ALIGN
 
-   Bitflags for use in the *mask* parameter to :func:`os.statx`.  Flags
-   including and after :const:`!STATX_MNT_ID` are only available when their
-   corresponding members in :class:`statx_result` are available.
+   Bitflags for use in the *mask* parameter to :func:`os.statx`.  Some of these
+   flags may be available even when their corresponding members in
+   :class:`statx_result` are not available.
 
    .. availability:: Linux >= 4.11 with glibc >= 2.28.
 

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.