Merge branch 'main' into decimal-version

Author: hugovk

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

@@ -9,6 +9,7 @@ Pending removal in Python 3.20
   - :mod:`csv`
   - :mod:`!ctypes.macholib`
   - :mod:`decimal` (Use :data:`decimal.SPEC_VERSION` instead)
+  - :mod:`imaplib`
   - :mod:`ipaddress`
   - :mod:`json`
   - :mod:`logging` (``__date__`` also deprecated)

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

@@ -839,8 +839,7 @@ geometry
    For example: ``fred["geometry"] = "200x100"``.
 
 justify
-   Legal values are the strings: ``"left"``, ``"center"``, ``"right"``, and
-   ``"fill"``.
+   Legal values are the strings: ``"left"``, ``"center"``, and ``"right"``.
 
 region
    This is a string with four space-delimited elements, each of which is a legal

Doc/library/warnings.rst

@@ -480,14 +480,21 @@ Available Functions
 .. function:: warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)
 
    This is a low-level interface to the functionality of :func:`warn`, passing in
-   explicitly the message, category, filename and line number, and optionally the
-   module name and the registry (which should be the ``__warningregistry__``
-   dictionary of the module).  The module name defaults to the filename with
-   ``.py`` stripped; if no registry is passed, the warning is never suppressed.
+   explicitly the message, category, filename and line number, and optionally
+   other arguments.
    *message* must be a string and *category* a subclass of :exc:`Warning` or
    *message* may be a :exc:`Warning` instance, in which case *category* will be
    ignored.
 
+   *module*, if supplied, should be the module name.
+   If no module is passed, the filename with ``.py`` stripped is used.
+
+   *registry*, if supplied, should be the ``__warningregistry__`` dictionary
+   of the module.
+   If no registry is passed, each warning is treated as the first occurrence,
+   that is, filter actions ``"default"``, ``"module"`` and ``"once"`` are
+   handled as ``"always"``.
+
    *module_globals*, if supplied, should be the global namespace in use by the code
    for which the warning is issued.  (This argument is used to support displaying
    source for modules found in zipfiles or other non-filesystem import

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