Merge branch 'main' into doc-unicode-compact

Author: ZeroIntensity

Doc/c-api/apiabiversion.rst

@@ -34,6 +34,23 @@ See :ref:`stable` for a discussion of API and ABI stability across versions.
    This can be ``0xA`` for alpha, ``0xB`` for beta, ``0xC`` for release
    candidate or ``0xF`` for final.
 
+
+   .. c:namespace:: NULL
+   .. c:macro:: PY_RELEASE_LEVEL_ALPHA
+      :no-typesetting:
+   .. c:macro:: PY_RELEASE_LEVEL_BETA
+      :no-typesetting:
+   .. c:macro:: PY_RELEASE_LEVEL_GAMMA
+      :no-typesetting:
+   .. c:macro:: PY_RELEASE_LEVEL_FINAL
+      :no-typesetting:
+
+   For completeness, the values are available as macros:
+   :c:macro:`!PY_RELEASE_LEVEL_ALPHA` (``0xA``),
+   :c:macro:`!PY_RELEASE_LEVEL_BETA` (``0xB``),
+   :c:macro:`!PY_RELEASE_LEVEL_GAMMA` (``0xC``), and
+   :c:macro:`!PY_RELEASE_LEVEL_FINAL` (``0xF``).
+
 .. c:macro:: PY_RELEASE_SERIAL
 
    The ``2`` in ``3.4.1a2``. Zero for final releases.
@@ -46,6 +63,10 @@ See :ref:`stable` for a discussion of API and ABI stability across versions.
    Use this for numeric comparisons, for example,
    ``#if PY_VERSION_HEX >= ...``.
 
+.. c:macro:: PY_VERSION
+
+   The Python version as a string, for example, ``"3.4.1a2"``.
+
 
 Run-time version
 ----------------

Doc/c-api/module.rst

@@ -820,15 +820,18 @@ struct:
    .. versionadded:: 3.5
 
 .. c:macro:: PYTHON_API_VERSION
+             PYTHON_API_STRING
 
-   The C API version. Defined for backwards compatibility.
+   The C API version, as an integer (``1013``) and string (``"1013"``), respectively.
+   Defined for backwards compatibility.
 
    Currently, this constant is not updated in new Python versions, and is not
    useful for versioning. This may change in the future.
 
 .. c:macro:: PYTHON_ABI_VERSION
+             PYTHON_ABI_STRING
 
-   Defined as ``3`` for backwards compatibility.
+   Defined as ``3`` and ``"3"``, respectively, for backwards compatibility.
 
    Currently, this constant is not updated in new Python versions, and is not
    useful for versioning. This may change in the future.

Doc/library/concurrent.futures.rst

@@ -21,6 +21,11 @@ or separate processes, using :class:`ProcessPoolExecutor`.
 Each implements the same interface, which is defined
 by the abstract :class:`Executor` class.
 
+:class:`concurrent.futures.Future` must not be confused with
+:class:`asyncio.Future`, which is designed for use with :mod:`asyncio`
+tasks and coroutines. See the :doc:`asyncio's Future <asyncio-future>`
+documentation for a detailed comparison of the two.
+
 .. include:: ../includes/wasm-notavail.rst
 
 Executor Objects

Doc/library/dis.rst

@@ -768,7 +768,7 @@ not have to be) the original ``STACK[-2]``.
       end = STACK.pop()
       start = STACK.pop()
       container = STACK.pop()
-      values = STACK.pop()
+      value = STACK.pop()
       container[start:end] = value
 
    .. versionadded:: 3.12

Doc/library/email.message.rst

@@ -57,7 +57,7 @@ message objects.
    :class:`~email.policy.default` policy, which follows the rules of the email
    RFCs except for line endings (instead of the RFC mandated ``\r\n``, it uses
    the Python standard ``\n`` line endings).  For more information see the
-   :mod:`~email.policy` documentation.
+   :mod:`~email.policy` documentation. [2]_
 
    .. method:: as_string(unixfrom=False, maxheaderlen=None, policy=None)
 
@@ -749,3 +749,9 @@ message objects.
 .. [1] Originally added in 3.4 as a :term:`provisional module <provisional
        package>`.  Docs for legacy message class moved to
        :ref:`compat32_message`.
+
+.. [2] The :class:`EmailMessage` class requires a policy that provides a
+       ``content_manager`` attribute for content management methods like
+       ``set_content()`` and ``get_content()`` to work. The legacy
+       :const:`~email.policy.compat32` policy does not support these methods
+       and should not be used with :class:`EmailMessage`.

Doc/library/email.policy.rst

@@ -662,6 +662,13 @@ The header objects and their attributes are described in
    An instance of :class:`Compat32`, providing  backward compatibility with the
    behavior of the email package in Python 3.2.
 
+   .. note::
+
+      The :const:`compat32` policy should not be used as a policy for
+      :class:`~email.message.EmailMessage` objects, and should only be used
+      to serialize messages that were created using the :const:`compat32`
+      policy.
+
 
 .. rubric:: Footnotes
 

Doc/library/ftplib.rst

@@ -524,14 +524,9 @@ FTP_TLS objects
    :class:`!FTP_TLS` class inherits from :class:`FTP`,
    defining these additional methods and attributes:
 
-   .. attribute:: FTP_TLS.ssl_version
-
-      The SSL version to use (defaults to :data:`ssl.PROTOCOL_SSLv23`).
-
    .. method:: FTP_TLS.auth()
 
-      Set up a secure control connection by using TLS or SSL, depending on what
-      is specified in the :attr:`ssl_version` attribute.
+      Set up a secure control connection by using TLS.
 
       .. versionchanged:: 3.4
          The method now supports hostname check with
@@ -548,7 +543,7 @@ FTP_TLS objects
 
    .. method:: FTP_TLS.prot_p()
 
-      Set up secure data connection.
+      Set up secure data connection by using TLS.
 
    .. method:: FTP_TLS.prot_c()
 

Doc/library/importlib.resources.abc.rst

@@ -63,11 +63,14 @@
        If the resource does not concretely exist on the file system,
        raise :exc:`FileNotFoundError`.
 
-    .. method:: is_resource(name)
+    .. method:: is_resource(path)
        :abstractmethod:
 
-       Returns ``True`` if the named *name* is considered a resource.
-       :exc:`FileNotFoundError` is raised if *name* does not exist.
+       Returns ``True`` if the named *path* is considered a resource.
+       :exc:`FileNotFoundError` is raised if *path* does not exist.
+
+       .. versionchanged:: 3.10
+          The argument *name* was renamed to *path*.
 
     .. method:: contents()
        :abstractmethod:

Doc/library/importlib.rst

@@ -210,12 +210,6 @@ Functions
        :exc:`ModuleNotFoundError` is raised when the module being reloaded lacks
        a :class:`~importlib.machinery.ModuleSpec`.
 
-   .. versionchanged:: 3.15
-       If *module* is a lazy module that has not yet been materialized (i.e.,
-       loaded via :class:`importlib.util.LazyLoader` and not yet accessed),
-       calling :func:`reload` is a no-op and returns the module unchanged.
-       This prevents the reload from unintentionally triggering the lazy load.
-
    .. warning::
       This function is not thread-safe. Calling it from multiple threads can result
       in unexpected behavior. It's recommended to use the :class:`threading.Lock`

Doc/library/stdtypes.rst

@@ -1844,6 +1844,14 @@ expression support in the :mod:`re` module).
    lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already
    lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold`
    converts it to ``"ss"``.
+   For example:
+
+   .. doctest::
+
+      >>> 'straße'.lower()
+      'straße'
+      >>> 'straße'.casefold()
+      'strasse'
 
    The casefolding algorithm is `described in section 3.13.3 'Default Case
    Folding' of the Unicode Standard
@@ -2045,7 +2053,18 @@ expression support in the :mod:`re` module).
 .. method:: str.index(sub[, start[, end]])
 
    Like :meth:`~str.find`, but raise :exc:`ValueError` when the substring is
-   not found.
+   not found. For example:
+
+   .. doctest::
+
+      >>> 'spam, spam, spam'.index('eggs')
+      Traceback (most recent call last):
+        File "<python-input-0>", line 1, in <module>
+          'spam, spam, spam'.index('eggs')
+          ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
+      ValueError: substring not found
+
+   See also :meth:`rindex`.
 
 
 .. method:: str.isalnum()
@@ -2289,7 +2308,12 @@ expression support in the :mod:`re` module).
 .. method:: str.lower()
 
    Return a copy of the string with all the cased characters [4]_ converted to
-   lowercase.
+   lowercase. For example:
+
+   .. doctest::
+
+      >>> 'Lower Method Example'.lower()
+      'lower method example'
 
    The lowercasing algorithm used is `described in section 3.13.2 'Default Case
    Conversion' of the Unicode Standard
@@ -2345,7 +2369,9 @@ expression support in the :mod:`re` module).
 
    If the string starts with the *prefix* string, return
    ``string[len(prefix):]``. Otherwise, return a copy of the original
-   string::
+   string:
+
+   .. doctest::
 
       >>> 'TestHook'.removeprefix('Test')
       'Hook'
@@ -2354,12 +2380,16 @@ expression support in the :mod:`re` module).
 
    .. versionadded:: 3.9
 
+   See also :meth:`removesuffix` and :meth:`startswith`.
+
 
 .. method:: str.removesuffix(suffix, /)
 
    If the string ends with the *suffix* string and that *suffix* is not empty,
    return ``string[:-len(suffix)]``. Otherwise, return a copy of the
-   original string::
+   original string:
+
+   .. doctest::
 
       >>> 'MiscTests'.removesuffix('Tests')
       'Misc'
@@ -2368,12 +2398,22 @@ expression support in the :mod:`re` module).
 
    .. versionadded:: 3.9
 
+   See also :meth:`removeprefix` and :meth:`endswith`.
+
 
 .. method:: str.replace(old, new, /, count=-1)
 
    Return a copy of the string with all occurrences of substring *old* replaced by
    *new*.  If *count* is given, only the first *count* occurrences are replaced.
    If *count* is not specified or ``-1``, then all occurrences are replaced.
+   For example:
+
+   .. doctest::
+
+      >>> 'spam, spam, spam'.replace('spam', 'eggs')
+      'eggs, eggs, eggs'
+      >>> 'spam, spam, spam'.replace('spam', 'eggs', 1)
+      'eggs, spam, spam'
 
    .. versionchanged:: 3.13
       *count* is now supported as a keyword argument.
@@ -2384,6 +2424,16 @@ expression support in the :mod:`re` module).
    Return the highest index in the string where substring *sub* is found, such
    that *sub* is contained within ``s[start:end]``.  Optional arguments *start*
    and *end* are interpreted as in slice notation.  Return ``-1`` on failure.
+   For example:
+
+   .. doctest::
+
+      >>> 'spam, spam, spam'.rfind('sp')
+      12
+      >>> 'spam, spam, spam'.rfind('sp', 0, 10)
+      6
+
+   See also :meth:`find` and :meth:`rindex`.
 
 
 .. method:: str.rindex(sub[, start[, end]])