Merge branch '3.12' into backport-8a00c9a-3.12

Author: graingert

.gitignore

@@ -38,6 +38,7 @@ tags
 TAGS
 .vs/
 .vscode/
+.cache/
 gmon.out
 .coverage
 .mypy_cache/

Doc/faq/programming.rst

@@ -986,8 +986,8 @@ There are various techniques.
      f()
 
 
-Is there an equivalent to Perl's chomp() for removing trailing newlines from strings?
--------------------------------------------------------------------------------------
+Is there an equivalent to Perl's ``chomp()`` for removing trailing newlines from strings?
+-----------------------------------------------------------------------------------------
 
 You can use ``S.rstrip("\r\n")`` to remove all occurrences of any line
 terminator from the end of the string ``S`` without removing other trailing
@@ -1005,8 +1005,8 @@ Since this is typically only desired when reading text one line at a time, using
 ``S.rstrip()`` this way works well.
 
 
-Is there a scanf() or sscanf() equivalent?
-------------------------------------------
+Is there a ``scanf()`` or ``sscanf()`` equivalent?
+--------------------------------------------------
 
 Not as such.
 
@@ -1020,8 +1020,8 @@ For more complicated input parsing, regular expressions are more powerful
 than C's ``sscanf`` and better suited for the task.
 
 
-What does 'UnicodeDecodeError' or 'UnicodeEncodeError' error  mean?
--------------------------------------------------------------------
+What does ``UnicodeDecodeError`` or ``UnicodeEncodeError`` error mean?
+----------------------------------------------------------------------
 
 See the :ref:`unicode-howto`.
 
@@ -1036,7 +1036,7 @@ A raw string ending with an odd number of backslashes will escape the string's q
    >>> r'C:\this\will\not\work\'
      File "<stdin>", line 1
        r'C:\this\will\not\work\'
-            ^
+       ^
    SyntaxError: unterminated string literal (detected at line 1)
 
 There are several workarounds for this. One is to use regular strings and double
@@ -1868,15 +1868,15 @@ object identity is assured.  Generally, there are three circumstances where
 identity is guaranteed:
 
 1) Assignments create new names but do not change object identity.  After the
-assignment ``new = old``, it is guaranteed that ``new is old``.
+   assignment ``new = old``, it is guaranteed that ``new is old``.
 
 2) Putting an object in a container that stores object references does not
-change object identity.  After the list assignment ``s[0] = x``, it is
-guaranteed that ``s[0] is x``.
+   change object identity.  After the list assignment ``s[0] = x``, it is
+   guaranteed that ``s[0] is x``.
 
 3) If an object is a singleton, it means that only one instance of that object
-can exist.  After the assignments ``a = None`` and ``b = None``, it is
-guaranteed that ``a is b`` because ``None`` is a singleton.
+   can exist.  After the assignments ``a = None`` and ``b = None``, it is
+   guaranteed that ``a is b`` because ``None`` is a singleton.
 
 In most other circumstances, identity tests are inadvisable and equality tests
 are preferred.  In particular, identity tests should not be used to check

Doc/library/cmath.rst

@@ -55,13 +55,13 @@ segment that joins the origin to *z*.
 The following functions can be used to convert from the native
 rectangular coordinates to polar coordinates and back.
 
-.. function:: phase(x)
+.. function:: phase(z)
 
-   Return the phase of *x* (also known as the *argument* of *x*), as a float.
-   ``phase(x)`` is equivalent to ``math.atan2(x.imag, x.real)``.  The result
+   Return the phase of *z* (also known as the *argument* of *z*), as a float.
+   ``phase(z)`` is equivalent to ``math.atan2(z.imag, z.real)``.  The result
    lies in the range [-\ *π*, *π*], and the branch cut for this operation lies
    along the negative real axis.  The sign of the result is the same as the
-   sign of ``x.imag``, even when ``x.imag`` is zero::
+   sign of ``z.imag``, even when ``z.imag`` is zero::
 
       >>> phase(complex(-1.0, 0.0))
       3.141592653589793
@@ -71,147 +71,147 @@ rectangular coordinates to polar coordinates and back.
 
 .. note::
 
-   The modulus (absolute value) of a complex number *x* can be
+   The modulus (absolute value) of a complex number *z* can be
    computed using the built-in :func:`abs` function.  There is no
    separate :mod:`cmath` module function for this operation.
 
 
-.. function:: polar(x)
+.. function:: polar(z)
 
-   Return the representation of *x* in polar coordinates.  Returns a
-   pair ``(r, phi)`` where *r* is the modulus of *x* and phi is the
-   phase of *x*.  ``polar(x)`` is equivalent to ``(abs(x),
-   phase(x))``.
+   Return the representation of *z* in polar coordinates.  Returns a
+   pair ``(r, phi)`` where *r* is the modulus of *z* and *phi* is the
+   phase of *z*.  ``polar(z)`` is equivalent to ``(abs(z),
+   phase(z))``.
 
 
 .. function:: rect(r, phi)
 
-   Return the complex number *x* with polar coordinates *r* and *phi*.
+   Return the complex number *z* with polar coordinates *r* and *phi*.
    Equivalent to ``complex(r * math.cos(phi), r * math.sin(phi))``.
 
 
 Power and logarithmic functions
 -------------------------------
 
-.. function:: exp(x)
+.. function:: exp(z)
 
-   Return *e* raised to the power *x*, where *e* is the base of natural
+   Return *e* raised to the power *z*, where *e* is the base of natural
    logarithms.
 
 
-.. function:: log(x[, base])
+.. function:: log(z[, base])
 
-   Returns the logarithm of *x* to the given *base*. If the *base* is not
-   specified, returns the natural logarithm of *x*. There is one branch cut,
+   Return the logarithm of *z* to the given *base*. If the *base* is not
+   specified, returns the natural logarithm of *z*. There is one branch cut,
    from 0 along the negative real axis to -∞.
 
 
-.. function:: log10(x)
+.. function:: log10(z)
 
-   Return the base-10 logarithm of *x*. This has the same branch cut as
+   Return the base-10 logarithm of *z*. This has the same branch cut as
    :func:`log`.
 
 
-.. function:: sqrt(x)
+.. function:: sqrt(z)
 
-   Return the square root of *x*. This has the same branch cut as :func:`log`.
+   Return the square root of *z*. This has the same branch cut as :func:`log`.
 
 
 Trigonometric functions
 -----------------------
 
-.. function:: acos(x)
+.. function:: acos(z)
 
-   Return the arc cosine of *x*. There are two branch cuts: One extends right
+   Return the arc cosine of *z*. There are two branch cuts: One extends right
    from 1 along the real axis to ∞. The other extends left from -1 along the
    real axis to -∞.
 
 
-.. function:: asin(x)
+.. function:: asin(z)
 
-   Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
+   Return the arc sine of *z*. This has the same branch cuts as :func:`acos`.
 
 
-.. function:: atan(x)
+.. function:: atan(z)
 
-   Return the arc tangent of *x*. There are two branch cuts: One extends from
+   Return the arc tangent of *z*. There are two branch cuts: One extends from
    ``1j`` along the imaginary axis to ``∞j``. The other extends from ``-1j``
    along the imaginary axis to ``-∞j``.
 
 
-.. function:: cos(x)
+.. function:: cos(z)
 
-   Return the cosine of *x*.
+   Return the cosine of *z*.
 
 
-.. function:: sin(x)
+.. function:: sin(z)
 
-   Return the sine of *x*.
+   Return the sine of *z*.
 
 
-.. function:: tan(x)
+.. function:: tan(z)
 
-   Return the tangent of *x*.
+   Return the tangent of *z*.
 
 
 Hyperbolic functions
 --------------------
 
-.. function:: acosh(x)
+.. function:: acosh(z)
 
-   Return the inverse hyperbolic cosine of *x*. There is one branch cut,
+   Return the inverse hyperbolic cosine of *z*. There is one branch cut,
    extending left from 1 along the real axis to -∞.
 
 
-.. function:: asinh(x)
+.. function:: asinh(z)
 
-   Return the inverse hyperbolic sine of *x*. There are two branch cuts:
+   Return the inverse hyperbolic sine of *z*. There are two branch cuts:
    One extends from ``1j`` along the imaginary axis to ``∞j``.  The other
    extends from ``-1j`` along the imaginary axis to ``-∞j``.
 
 
-.. function:: atanh(x)
+.. function:: atanh(z)
 
-   Return the inverse hyperbolic tangent of *x*. There are two branch cuts: One
+   Return the inverse hyperbolic tangent of *z*. There are two branch cuts: One
    extends from ``1`` along the real axis to ``∞``. The other extends from
    ``-1`` along the real axis to ``-∞``.
 
 
-.. function:: cosh(x)
+.. function:: cosh(z)
 
-   Return the hyperbolic cosine of *x*.
+   Return the hyperbolic cosine of *z*.
 
 
-.. function:: sinh(x)
+.. function:: sinh(z)
 
-   Return the hyperbolic sine of *x*.
+   Return the hyperbolic sine of *z*.
 
 
-.. function:: tanh(x)
+.. function:: tanh(z)
 
-   Return the hyperbolic tangent of *x*.
+   Return the hyperbolic tangent of *z*.
 
 
 Classification functions
 ------------------------
 
-.. function:: isfinite(x)
+.. function:: isfinite(z)
 
-   Return ``True`` if both the real and imaginary parts of *x* are finite, and
+   Return ``True`` if both the real and imaginary parts of *z* are finite, and
    ``False`` otherwise.
 
    .. versionadded:: 3.2
 
 
-.. function:: isinf(x)
+.. function:: isinf(z)
 
-   Return ``True`` if either the real or the imaginary part of *x* is an
+   Return ``True`` if either the real or the imaginary part of *z* is an
    infinity, and ``False`` otherwise.
 
 
-.. function:: isnan(x)
+.. function:: isnan(z)
 
-   Return ``True`` if either the real or the imaginary part of *x* is a NaN,
+   Return ``True`` if either the real or the imaginary part of *z* is a NaN,
    and ``False`` otherwise.
 
 

Doc/library/plistlib.rst

@@ -74,8 +74,7 @@ This module defines the following functions:
    exceptions on ill-formed XML.  Unknown elements will simply be ignored
    by the plist parser.
 
-   The parser for the binary format raises :exc:`InvalidFileException`
-   when the file cannot be parsed.
+   The parser raises :exc:`InvalidFileException` when the file cannot be parsed.
 
    .. versionadded:: 3.4
 
@@ -154,6 +153,15 @@ The following constants are available:
    .. versionadded:: 3.4
 
 
+The module defines the following exceptions:
+
+.. exception:: InvalidFileException
+
+   Raised when a file cannot be parsed.
+
+   .. versionadded:: 3.4
+
+
 Examples
 --------
 

Doc/library/socket.rst

@@ -833,10 +833,10 @@ The following functions all create :ref:`socket objects <socket-objects>`.
    , a default reasonable value is chosen.
    *reuse_port* dictates whether to set the :data:`SO_REUSEPORT` socket option.
 
-   If *dualstack_ipv6* is true and the platform supports it the socket will
-   be able to accept both IPv4 and IPv6 connections, else it will raise
-   :exc:`ValueError`. Most POSIX platforms and Windows are supposed to support
-   this functionality.
+   If *dualstack_ipv6* is true, *family* is :data:`AF_INET6` and the platform
+   supports it the socket will be able to accept both IPv4 and IPv6 connections,
+   else it will raise :exc:`ValueError`. Most POSIX platforms and Windows are
+   supposed to support this functionality.
    When this functionality is enabled the address returned by
    :meth:`socket.getpeername` when an IPv4 connection occurs will be an IPv6
    address represented as an IPv4-mapped IPv6 address.

Doc/library/stdtypes.rst

@@ -4577,7 +4577,7 @@ can be used interchangeably to index the same dictionary entry.
       such as an empty list.  To get distinct values, use a :ref:`dict
       comprehension <dict>` instead.
 
-   .. method:: get(key, default=None)
+   .. method:: get(key, default=None, /)
 
       Return the value for *key* if *key* is in the dictionary, else *default*.
       If *default* is not given, it defaults to ``None``, so that this method
@@ -4619,7 +4619,7 @@ can be used interchangeably to index the same dictionary entry.
 
       .. versionadded:: 3.8
 
-   .. method:: setdefault(key, default=None)
+   .. method:: setdefault(key, default=None, /)
 
       If *key* is in the dictionary, return its value.  If not, insert *key*
       with a value of *default* and return *default*.  *default* defaults to

Lib/http/server.py

@@ -1098,7 +1098,7 @@ def run_cgi(self):
                     "CGI script is not executable (%r)" % scriptname)
                 return
 
-        # Reference: http://hoohoo.ncsa.uiuc.edu/cgi/env.html
+        # Reference: https://www6.uniovi.es/~antonio/ncsa_httpd/cgi/env.html
         # XXX Much of the following could be prepared ahead of time!
         env = copy.deepcopy(os.environ)
         env['SERVER_SOFTWARE'] = self.version_string()