Merge branch 'main' into str-format-errors

Author: serhiy-storchaka

Doc/howto/functional.rst

@@ -4,7 +4,7 @@
   Functional Programming HOWTO
 ********************************
 
-:Author: A. M. Kuchling
+:Author: \A. M. Kuchling
 :Release: 0.32
 
 In this document, we'll take a tour of Python's features suitable for

Doc/howto/urllib2.rst

@@ -15,7 +15,7 @@ Introduction
     You may also find useful the following article on fetching web resources
     with Python:
 
-    * `Basic Authentication <https://web.archive.org/web/20201215133350/http://www.voidspace.org.uk/python/articles/authentication.shtml>`_
+    * `Basic Authentication <https://web.archive.org/web/20201215133350/http://www.voidspace.org.uk/python/articles/authentication.shtml>`__
 
         A tutorial on *Basic Authentication*, with examples in Python.
 

Doc/library/argparse.rst

@@ -767,9 +767,9 @@ how the command-line arguments should be handled. The supplied actions are:
     Namespace(foo=42)
 
 * ``'store_true'`` and ``'store_false'`` - These are special cases of
-  ``'store_const'`` used for storing the values ``True`` and ``False``
-  respectively.  In addition, they create default values of ``False`` and
-  ``True`` respectively::
+  ``'store_const'`` that respectively store the values ``True`` and ``False``
+  with default values of ``False`` and
+  ``True``::
 
     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='store_true')
@@ -789,8 +789,8 @@ how the command-line arguments should be handled. The supplied actions are:
     >>> parser.parse_args('--foo 1 --foo 2'.split())
     Namespace(foo=['0', '1', '2'])
 
-* ``'append_const'`` - This stores a list, and appends the value specified by
-  the const_ keyword argument to the list; note that the const_ keyword
+* ``'append_const'`` - This appends the value specified by
+  the const_ keyword argument to a list; note that the const_ keyword
   argument defaults to ``None``. The ``'append_const'`` action is typically
   useful when multiple arguments need to store constants to the same list. For
   example::
@@ -801,8 +801,8 @@ how the command-line arguments should be handled. The supplied actions are:
     >>> parser.parse_args('--str --int'.split())
     Namespace(types=[<class 'str'>, <class 'int'>])
 
-* ``'extend'`` - This stores a list and appends each item from the multi-value
-  argument list to it.
+* ``'extend'`` - This appends each item from a multi-value
+  argument to a list.
   The ``'extend'`` action is typically used with the nargs_ keyword argument
   value ``'+'`` or ``'*'``.
   Note that when nargs_ is ``None`` (the default) or ``'?'``, each
@@ -816,7 +816,7 @@ how the command-line arguments should be handled. The supplied actions are:
 
   .. versionadded:: 3.8
 
-* ``'count'`` - This counts the number of times a keyword argument occurs. For
+* ``'count'`` - This counts the number of times an argument occurs. For
   example, this is useful for increasing verbosity levels::
 
     >>> parser = argparse.ArgumentParser()

Doc/library/decimal.rst

@@ -2109,20 +2109,20 @@ to work with the :class:`Decimal` class::
 Decimal FAQ
 -----------
 
-Q. It is cumbersome to type ``decimal.Decimal('1234.5')``.  Is there a way to
+Q: It is cumbersome to type ``decimal.Decimal('1234.5')``.  Is there a way to
 minimize typing when using the interactive interpreter?
 
-A. Some users abbreviate the constructor to just a single letter:
+A: Some users abbreviate the constructor to just a single letter:
 
    >>> D = decimal.Decimal
    >>> D('1.23') + D('3.45')
    Decimal('4.68')
 
-Q. In a fixed-point application with two decimal places, some inputs have many
+Q: In a fixed-point application with two decimal places, some inputs have many
 places and need to be rounded.  Others are not supposed to have excess digits
 and need to be validated.  What methods should be used?
 
-A. The :meth:`~Decimal.quantize` method rounds to a fixed number of decimal places. If
+A: The :meth:`~Decimal.quantize` method rounds to a fixed number of decimal places. If
 the :const:`Inexact` trap is set, it is also useful for validation:
 
    >>> TWOPLACES = Decimal(10) ** -2       # same as Decimal('0.01')
@@ -2140,10 +2140,10 @@ the :const:`Inexact` trap is set, it is also useful for validation:
       ...
    Inexact: None
 
-Q. Once I have valid two place inputs, how do I maintain that invariant
+Q: Once I have valid two place inputs, how do I maintain that invariant
 throughout an application?
 
-A. Some operations like addition, subtraction, and multiplication by an integer
+A: Some operations like addition, subtraction, and multiplication by an integer
 will automatically preserve fixed point.  Others operations, like division and
 non-integer multiplication, will change the number of decimal places and need to
 be followed-up with a :meth:`~Decimal.quantize` step:
@@ -2175,21 +2175,21 @@ to handle the :meth:`~Decimal.quantize` step:
     >>> div(b, a)
     Decimal('0.03')
 
-Q. There are many ways to express the same value.  The numbers ``200``,
+Q: There are many ways to express the same value.  The numbers ``200``,
 ``200.000``, ``2E2``, and ``.02E+4`` all have the same value at
 various precisions. Is there a way to transform them to a single recognizable
 canonical value?
 
-A. The :meth:`~Decimal.normalize` method maps all equivalent values to a single
+A: The :meth:`~Decimal.normalize` method maps all equivalent values to a single
 representative:
 
    >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
    >>> [v.normalize() for v in values]
    [Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]
 
-Q. When does rounding occur in a computation?
+Q: When does rounding occur in a computation?
 
-A. It occurs *after* the computation.  The philosophy of the decimal
+A: It occurs *after* the computation.  The philosophy of the decimal
 specification is that numbers are considered exact and are created
 independent of the current context.  They can even have greater
 precision than current context.  Computations process with those
@@ -2207,10 +2207,10 @@ applied to the *result* of the computation::
    >>> pi + 0 - Decimal('0.00005').   # Intermediate values are rounded
    Decimal('3.1416')
 
-Q. Some decimal values always print with exponential notation.  Is there a way
+Q: Some decimal values always print with exponential notation.  Is there a way
 to get a non-exponential representation?
 
-A. For some values, exponential notation is the only way to express the number
+A: For some values, exponential notation is the only way to express the number
 of significant places in the coefficient.  For example, expressing
 ``5.0E+3`` as ``5000`` keeps the value constant but cannot show the
 original's two-place significance.
@@ -2225,9 +2225,9 @@ value unchanged:
     >>> remove_exponent(Decimal('5E+3'))
     Decimal('5000')
 
-Q. Is there a way to convert a regular float to a :class:`Decimal`?
+Q: Is there a way to convert a regular float to a :class:`Decimal`?
 
-A. Yes, any binary floating-point number can be exactly expressed as a
+A: Yes, any binary floating-point number can be exactly expressed as a
 Decimal though an exact conversion may take more precision than intuition would
 suggest:
 
@@ -2236,19 +2236,19 @@ suggest:
     >>> Decimal(math.pi)
     Decimal('3.141592653589793115997963468544185161590576171875')
 
-Q. Within a complex calculation, how can I make sure that I haven't gotten a
+Q: Within a complex calculation, how can I make sure that I haven't gotten a
 spurious result because of insufficient precision or rounding anomalies.
 
-A. The decimal module makes it easy to test results.  A best practice is to
+A: The decimal module makes it easy to test results.  A best practice is to
 re-run calculations using greater precision and with various rounding modes.
 Widely differing results indicate insufficient precision, rounding mode issues,
 ill-conditioned inputs, or a numerically unstable algorithm.
 
-Q. I noticed that context precision is applied to the results of operations but
+Q: I noticed that context precision is applied to the results of operations but
 not to the inputs.  Is there anything to watch out for when mixing values of
 different precisions?
 
-A. Yes.  The principle is that all values are considered to be exact and so is
+A: Yes.  The principle is that all values are considered to be exact and so is
 the arithmetic on those values.  Only the results are rounded.  The advantage
 for inputs is that "what you type is what you get".  A disadvantage is that the
 results can look odd if you forget that the inputs haven't been rounded:
@@ -2276,9 +2276,9 @@ Alternatively, inputs can be rounded upon creation using the
    >>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
    Decimal('1.2345')
 
-Q. Is the CPython implementation fast for large numbers?
+Q: Is the CPython implementation fast for large numbers?
 
-A. Yes.  In the CPython and PyPy3 implementations, the C/CFFI versions of
+A: Yes.  In the CPython and PyPy3 implementations, the C/CFFI versions of
 the decimal module integrate the high speed `libmpdec
 <https://www.bytereef.org/mpdecimal/doc/libmpdec/index.html>`_ library for
 arbitrary precision correctly rounded decimal floating-point arithmetic [#]_.

Doc/library/multiprocessing.rst

@@ -832,8 +832,8 @@ raising an exception.
 
 One difference from other Python queue implementations, is that :mod:`multiprocessing`
 queues serializes all objects that are put into them using :mod:`pickle`.
-The object return by the get method is a re-created object that does not share memory
-with the original object.
+The object returned by the get method is a re-created object that does not share
+memory with the original object.
 
 Note that one can also create a shared queue by using a manager object -- see
 :ref:`multiprocessing-managers`.
@@ -890,7 +890,7 @@ For an example of the usage of queues for interprocess communication see
 :ref:`multiprocessing-examples`.
 
 
-.. function:: Pipe([duplex])
+.. function:: Pipe(duplex=True)
 
    Returns a pair ``(conn1, conn2)`` of
    :class:`~multiprocessing.connection.Connection` objects representing the
@@ -1577,12 +1577,22 @@ object -- see :ref:`multiprocessing-managers`.
    A solitary difference from its close analog exists: its ``acquire`` method's
    first argument is named *block*, as is consistent with :meth:`Lock.acquire`.
 
+
+   .. method:: get_value()
+
+      Return the current value of semaphore.
+
+      Note that this may raise :exc:`NotImplementedError` on platforms like
+      macOS where ``sem_getvalue()`` is not implemented.
+
+
    .. method:: locked()
 
       Return a boolean indicating whether this object is locked right now.
 
       .. versionadded:: 3.14
 
+
 .. note::
 
    On macOS, ``sem_timedwait`` is unsupported, so calling ``acquire()`` with

Doc/library/socket.rst

@@ -2095,11 +2095,8 @@ to sockets.
       Accepts any real number, not only integer or float.
 
 
-.. method:: socket.setsockopt(level, optname, value: int)
-.. method:: socket.setsockopt(level, optname, value: buffer)
-   :noindex:
-.. method:: socket.setsockopt(level, optname, None, optlen: int)
-   :noindex:
+.. method:: socket.setsockopt(level, optname, value: int | Buffer)
+            socket.setsockopt(level, optname, None, optlen: int)
 
    .. index:: pair: module; struct
 

Doc/library/ssl.rst

@@ -2959,16 +2959,16 @@ of TLS/SSL. Some new TLS 1.3 features are not yet available.
        Steve Kent
 
    :rfc:`RFC 4086: Randomness Requirements for Security <4086>`
-       Donald E., Jeffrey I. Schiller
+       Donald E. Eastlake, Jeffrey I. Schiller, Steve Crocker
 
    :rfc:`RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile <5280>`
-       D. Cooper
+       David Cooper et al.
 
    :rfc:`RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 <5246>`
-       T. Dierks et. al.
+       Tim Dierks and Eric Rescorla.
 
    :rfc:`RFC 6066: Transport Layer Security (TLS) Extensions <6066>`
-       D. Eastlake
+       Donald E. Eastlake
 
    `IANA TLS: Transport Layer Security (TLS) Parameters <https://www.iana.org/assignments/tls-parameters/tls-parameters.xml>`_
        IANA

Doc/library/subprocess.rst

@@ -831,7 +831,9 @@ Instances of the :class:`Popen` class have the following methods:
 
    If the process does not terminate after *timeout* seconds, a
    :exc:`TimeoutExpired` exception will be raised.  Catching this exception and
-   retrying communication will not lose any output.
+   retrying communication will not lose any output.  Supplying *input* to a
+   subsequent post-timeout :meth:`communicate` call is in undefined behavior
+   and may become an error in the future.
 
    The child process is not killed if the timeout expires, so in order to
    cleanup properly a well-behaved application should kill the child process and
@@ -844,6 +846,11 @@ Instances of the :class:`Popen` class have the following methods:
           proc.kill()
           outs, errs = proc.communicate()
 
+   After a call to :meth:`~Popen.communicate` raises :exc:`TimeoutExpired`, do
+   not call :meth:`~Popen.wait`. Use an additional :meth:`~Popen.communicate`
+   call to finish handling pipes and populate the :attr:`~Popen.returncode`
+   attribute.
+
    .. note::
 
       The data read is buffered in memory, so do not use this method if the data

Doc/library/xml.sax.handler.rst

@@ -96,6 +96,14 @@ for the feature and property names.
 
 .. data:: feature_external_ges
 
+   .. warning::
+
+      Enabling opens a vulnerability to
+      `external entity attacks <https://en.wikipedia.org/wiki/XML_external_entity_attack>`_
+      if the parser is used with user-provided XML content.
+      Please reflect on your `threat model <https://en.wikipedia.org/wiki/Threat_model>`_
+      before enabling this feature.
+
    | value: ``"http://xml.org/sax/features/external-general-entities"``
    | true: Include all external general (text) entities.
    | false: Do not include external general entities.

Doc/library/zipfile.rst

@@ -16,10 +16,10 @@ provides tools to create, read, write, append, and list a ZIP file.  Any
 advanced use of this module will require an understanding of the format, as
 defined in `PKZIP Application Note`_.
 
-This module does not currently handle multi-disk ZIP files.
+This module does not handle multipart ZIP files.
 It can handle ZIP files that use the ZIP64 extensions
 (that is ZIP files that are more than 4 GiB in size).  It supports
-decryption of encrypted files in ZIP archives, but it currently cannot
+decryption of encrypted files in ZIP archives, but it cannot
 create an encrypted file.  Decryption is extremely slow as it is
 implemented in native Python rather than C.
 
@@ -175,7 +175,7 @@ The module defines the following items:
 
 .. _zipfile-objects:
 
-ZipFile Objects
+ZipFile objects
 ---------------
 
 
@@ -248,7 +248,7 @@ ZipFile Objects
    .. note::
 
       *metadata_encoding* is an instance-wide setting for the ZipFile.
-      It is not currently possible to set this on a per-member basis.
+      It is not possible to set this on a per-member basis.
 
       This attribute is a workaround for legacy implementations which produce
       archives with names in the current locale encoding or code page (mostly
@@ -571,7 +571,7 @@ The following data attributes are also available:
 
 .. _path-objects:
 
-Path Objects
+Path objects
 ------------
 
 .. class:: Path(root, at='')
@@ -707,7 +707,7 @@ changes.
 
 .. _pyzipfile-objects:
 
-PyZipFile Objects
+PyZipFile objects
 -----------------
 
 The :class:`PyZipFile` constructor takes the same parameters as the
@@ -784,7 +784,7 @@ The :class:`PyZipFile` constructor takes the same parameters as the
 
 .. _zipinfo-objects:
 
-ZipInfo Objects
+ZipInfo objects
 ---------------
 
 Instances of the :class:`ZipInfo` class are returned by the :meth:`.getinfo` and
@@ -954,7 +954,7 @@ Instances have the following methods and attributes:
 .. _zipfile-commandline:
 .. program:: zipfile
 
-Command-Line Interface
+Command-line interface
 ----------------------
 
 The :mod:`zipfile` module provides a simple command-line interface to interact
@@ -1029,7 +1029,7 @@ From file itself
 Decompression may fail due to incorrect password / CRC checksum / ZIP format or
 unsupported compression method / decryption.
 
-File System limitations
+File system limitations
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Exceeding limitations on different file systems can cause decompression failed.