Merge branch 'main' into windows-use-py-debug

Author: XuehaiPan

Doc/conf.py

@@ -631,12 +631,12 @@
     'line_color': '#3776ab',
 }
 ogp_custom_meta_tags = [
-    '<meta name="theme-color" content="#3776ab" />',
+    '<meta name="theme-color" content="#3776ab">',
 ]
 if 'create-social-cards' not in tags:  # noqa: F821
     # Define a static preview image when not creating social cards
     ogp_image = '_static/og-image.png'
     ogp_custom_meta_tags += [
-        '<meta property="og:image:width" content="200" />',
-        '<meta property="og:image:height" content="200" />',
+        '<meta property="og:image:width" content="200">',
+        '<meta property="og:image:height" content="200">',
     ]

Doc/includes/email-alternative.py

@@ -36,7 +36,7 @@
             recette
         </a> sera sûrement un très bon repas.
     </p>
-    <img src="cid:{asparagus_cid}" />
+    <img src="cid:{asparagus_cid}">
   </body>
 </html>
 """.format(asparagus_cid=asparagus_cid[1:-1]), subtype='html')

Doc/library/cmath.rst

@@ -38,6 +38,57 @@ the function is then applied to the result of the conversion.
       1.4142135623730951j
 
 
+====================================================  ============================================
+**Conversions to and from polar coordinates**
+--------------------------------------------------------------------------------------------------
+:func:`phase(z) <phase>`                              Return the phase of *z*
+:func:`polar(z) <polar>`                              Return the representation of *z* in polar coordinates
+:func:`rect(r, phi) <rect>`                           Return the complex number *z* with polar coordinates *r* and *phi*
+
+**Power and logarithmic functions**
+--------------------------------------------------------------------------------------------------
+:func:`exp(z) <exp>`                                  Return *e* raised to the power *z*
+:func:`log(z[, base]) <log>`                          Return the logarithm of *z* to the given *base* (*e* by default)
+:func:`log10(z) <log10>`                              Return the base-10 logarithm of *z*
+:func:`sqrt(z) <sqrt>`                                Return the square root of *z*
+
+**Trigonometric functions**
+--------------------------------------------------------------------------------------------------
+:func:`acos(z) <acos>`                                Return the arc cosine of *z*
+:func:`asin(z) <asin>`                                Return the arc sine of *z*
+:func:`atan(z) <atan>`                                Return the arc tangent of *z*
+:func:`cos(z) <cos>`                                  Return the cosine of *z*
+:func:`sin(z) <sin>`                                  Return the sine of *z*
+:func:`tan(z) <tan>`                                  Return the tangent of *z*
+
+**Hyperbolic functions**
+--------------------------------------------------------------------------------------------------
+:func:`acosh(z) <acosh>`                              Return the inverse hyperbolic cosine of *z*
+:func:`asinh(z) <asinh>`                              Return the inverse hyperbolic sine of *z*
+:func:`atanh(z) <atanh>`                              Return the inverse hyperbolic tangent of *z*
+:func:`cosh(z) <cosh>`                                Return the hyperbolic cosine of *z*
+:func:`sinh(z) <sinh>`                                Return the hyperbolic sine of *z*
+:func:`tanh(z) <tanh>`                                Return the hyperbolic tangent of *z*
+
+**Classification functions**
+--------------------------------------------------------------------------------------------------
+:func:`isfinite(z) <isfinite>`                        Check if all components of *z* are finite
+:func:`isinf(z) <isinf>`                              Check if any component of *z* is infinite
+:func:`isnan(z) <isnan>`                              Check if any component of *z* is a NaN
+:func:`isclose(a, b, *, rel_tol, abs_tol) <isclose>`  Check if the values *a* and *b* are close to each other
+
+**Constants**
+--------------------------------------------------------------------------------------------------
+:data:`pi`                                            *π* = 3.141592...
+:data:`e`                                             *e* = 2.718281...
+:data:`tau`                                           *τ* = 2\ *π* = 6.283185...
+:data:`inf`                                           Positive infinity
+:data:`infj`                                          Pure imaginary infinity
+:data:`nan`                                           "Not a number" (NaN)
+:data:`nanj`                                          Pure imaginary NaN
+====================================================  ============================================
+
+
 Conversions to and from polar coordinates
 -----------------------------------------
 

Doc/library/ctypes.rst

@@ -2632,6 +2632,9 @@ These are the fundamental ctypes data types:
    Represents the C :c:expr:`PyObject *` datatype.  Calling this without an
    argument creates a ``NULL`` :c:expr:`PyObject *` pointer.
 
+   .. versionchanged:: next
+      :class:`!py_object` is now a :term:`generic type`.
+
 The :mod:`!ctypes.wintypes` module provides quite some other Windows specific
 data types, for example :c:type:`!HWND`, :c:type:`!WPARAM`, or :c:type:`!DWORD`.
 Some useful structures like :c:type:`!MSG` or :c:type:`!RECT` are also defined.

Doc/library/dataclasses.rst

@@ -164,7 +164,7 @@ Module contents
 
    - *match_args*: If true (the default is ``True``), the
      :attr:`~object.__match_args__` tuple will be created from the list of
-     parameters to the generated :meth:`~object.__init__` method (even if
+     non keyword-only parameters to the generated :meth:`~object.__init__` method (even if
      :meth:`!__init__` is not generated, see above).  If false, or if
      :attr:`!__match_args__` is already defined in the class, then
      :attr:`!__match_args__` will not be generated.
@@ -175,11 +175,12 @@ Module contents
      fields will be marked as keyword-only.  If a field is marked as
      keyword-only, then the only effect is that the :meth:`~object.__init__`
      parameter generated from a keyword-only field must be specified
-     with a keyword when :meth:`!__init__` is called.  There is no
-     effect on any other aspect of dataclasses.  See the
-     :term:`parameter` glossary entry for details.  Also see the
+     with a keyword when :meth:`!__init__` is called. See the :term:`parameter`
+     glossary entry for details.  Also see the
      :const:`KW_ONLY` section.
 
+     Keyword-only fields are not included in :attr:`!__match_args__`.
+
     .. versionadded:: 3.10
 
    - *slots*: If true (the default is ``False``), :attr:`~object.__slots__` attribute
@@ -299,6 +300,8 @@ Module contents
      This is used when the generated :meth:`~object.__init__` method's
      parameters are computed.
 
+     Keyword-only fields are also not included in :attr:`!__match_args__`.
+
     .. versionadded:: 3.10
 
    - ``doc``: optional docstring for this field.

Doc/library/string.rst

@@ -737,10 +737,10 @@ Using the comma or the underscore as a digit group separator::
    '4996_02d2'
    >>> '{:_}'.format(123456789.123456789)
    '123_456_789.12345679'
-   >>> '{:._}'.format(123456789.123456789)
-   '123456789.123_456_79'
-   >>> '{:_._}'.format(123456789.123456789)
-   '123_456_789.123_456_79'
+   >>> '{:.,}'.format(123456789.123456789)
+   '123456789.123,456,79'
+   >>> '{:,._}'.format(123456789.123456789)
+   '123,456,789.123_456_79'
 
 Expressing a percentage::
 

Doc/library/uuid.rst

@@ -121,8 +121,10 @@ which relays any information about the UUID's safety, using this enumeration:
      - The last 48 bits of the UUID. Only relevant to version 1.
 
    * - .. attribute:: UUID.time
-     - The 60-bit timestamp for version 1 and 6,
-       or the 48-bit timestamp for version 7.
+     - The 60-bit timestamp as a count of 100-nanosecond intervals since
+       Gregorian epoch (1582-10-15 00:00:00) for versions 1 and 6, or the
+       48-bit timestamp in milliseconds since Unix epoch (1970-01-01 00:00:00)
+       for version 7.
 
    * - .. attribute:: UUID.clock_seq
      - The 14-bit sequence number. Only relevant to versions 1 and 6.
@@ -434,6 +436,15 @@ Here are some examples of typical usage of the :mod:`uuid` module::
    >>> uuid.MAX
    UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')
 
+   >>> # get UUIDv7 creation (local) time as a timestamp in milliseconds
+   >>> u = uuid.uuid7()
+   >>> u.time  # doctest: +SKIP
+   1743936859822
+   >>> # get UUIDv7 creation (local) time as a datetime object
+   >>> import datetime as dt
+   >>> dt.datetime.fromtimestamp(u.time / 1000)  # doctest: +SKIP
+   datetime.datetime(...)
+
 
 .. _uuid-cli-example:
 

Doc/library/zipfile.rst

@@ -538,6 +538,14 @@ The following data attributes are also available:
    it should be no longer than 65535 bytes.  Comments longer than this will be
    truncated.
 
+.. attribute:: ZipFile.data_offset
+
+   The offset to the start of ZIP data from the beginning of the file. When the
+   :class:`ZipFile` is opened in either mode ``'w'`` or ``'x'`` and the
+   underlying file does not support ``tell()``, the value will be ``None``
+   instead.
+
+   .. versionadded:: 3.14
 
 .. _path-objects:
 

Doc/tools/templates/indexcontent.html

@@ -10,47 +10,47 @@ <h1>{{ docstitle|e }}</h1>
   <p><strong>{% trans %}Documentation sections:{% endtrans %}</strong></p>
   <table class="contentstable" align="center"><tr>
     <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("whatsnew/" + version) }}">{% trans %}What's new in Python {{ version }}?{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("whatsnew/" + version) }}">{% trans %}What's new in Python {{ version }}?{% endtrans %}</a><br>
          <span class="linkdescr"> {% trans whatsnew_index=pathto("whatsnew/index") %}Or <a href="{{ whatsnew_index }}">all "What's new" documents since Python 2.0</a>{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">{% trans %}Tutorial{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">{% trans %}Tutorial{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Start here: a tour of Python's syntax and features{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("library/index") }}">{% trans %}Library reference{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("library/index") }}">{% trans %}Library reference{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Standard library and builtins{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">{% trans %}Language reference{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">{% trans %}Language reference{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Syntax and language elements{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("using/index") }}">{% trans %}Python setup and usage{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("using/index") }}">{% trans %}Python setup and usage{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}How to install, configure, and use Python{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">{% trans %}Python HOWTOs{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">{% trans %}Python HOWTOs{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}In-depth topic manuals{% endtrans %}</span></p>
     </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("installing/index") }}">{% trans %}Installing Python modules{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("installing/index") }}">{% trans %}Installing Python modules{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Third-party modules and PyPI.org{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("distributing/index") }}">{% trans %}Distributing Python modules{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("distributing/index") }}">{% trans %}Distributing Python modules{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Publishing modules for use by other people{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">{% trans %}Extending and embedding{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">{% trans %}Extending and embedding{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}For C/C++ programmers{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">{% trans %}Python's C API{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">{% trans %}Python's C API{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}C API reference{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">{% trans %}FAQs{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">{% trans %}FAQs{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Frequently asked questions (with answers!){% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("deprecations/index") }}">{% trans %}Deprecations{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("deprecations/index") }}">{% trans %}Deprecations{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Deprecated functionality{% endtrans %}</span></p>
     </td></tr>
   </table>
 
   <p><strong>{% trans %}Indices, glossary, and search:{% endtrans %}</strong></p>
   <table class="contentstable" align="center"><tr>
     <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("py-modindex") }}">{% trans %}Global module index{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("py-modindex") }}">{% trans %}Global module index{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}All modules and libraries{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{% trans %}General index{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{% trans %}General index{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}All functions, classes, and terms{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("glossary") }}">{% trans %}Glossary{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("glossary") }}">{% trans %}Glossary{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Terms explained{% endtrans %}</span></p>
     </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{% trans %}Search page{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{% trans %}Search page{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Search this documentation{% endtrans %}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{% trans %}Complete table of contents{% endtrans %}</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{% trans %}Complete table of contents{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Lists all sections and subsections{% endtrans %}</span></p>
     </td></tr>
   </table>

Doc/tools/templates/layout.html

@@ -29,7 +29,7 @@
     {% if builder == "html" and enable_analytics %}
       <script defer data-domain="docs.python.org" src="https://plausible.io/js/script.js"></script>
     {% endif %}
-    <link rel="canonical" href="https://docs.python.org/3/{{pagename}}.html" />
+    <link rel="canonical" href="https://docs.python.org/3/{{pagename}}.html">
     {% if builder != "htmlhelp" %}
       {% if pagename == 'whatsnew/changelog' and not embedded %}
       <script type="text/javascript" src="{{ pathto('_static/changelog_search.js', 1) }}"></script>{% endif %}