Merge remote-tracking branch 'upstream/main'

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.0
+    rev: v0.1.2
     hooks:
       - id: ruff
         name: Run Ruff on Lib/test/

Doc/c-api/call.rst

@@ -108,6 +108,8 @@ This is a pointer to a function with the following signature:
    Doing so will allow callables such as bound methods to make their onward
    calls (which include a prepended *self* argument) very efficiently.
 
+   .. versionadded:: 3.8
+
 To call an object that implements vectorcall, use a :ref:`call API <capi-call>`
 function as with any other callable.
 :c:func:`PyObject_Vectorcall` will usually be most efficient.

Doc/c-api/unicode.rst

@@ -971,8 +971,8 @@ These are the UTF-8 codec APIs:
    returned buffer always has an extra null byte appended (not included in
    *size*), regardless of whether there are any other null code points.
 
-   In the case of an error, ``NULL`` is returned with an exception set and no
-   *size* is stored.
+   On error, set an exception, set *size* to ``-1`` (if it's not NULL) and
+   return ``NULL``.
 
    This caches the UTF-8 representation of the string in the Unicode object, and
    subsequent calls will return a pointer to the same buffer.  The caller is not
@@ -992,11 +992,19 @@ These are the UTF-8 codec APIs:
 
    As :c:func:`PyUnicode_AsUTF8AndSize`, but does not store the size.
 
+   Raise an exception if the *unicode* string contains embedded null
+   characters. To accept embedded null characters and truncate on purpose
+   at the first null byte, ``PyUnicode_AsUTF8AndSize(unicode, NULL)`` can be
+   used instead.
+
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.7
       The return type is now ``const char *`` rather of ``char *``.
 
+   .. versionchanged:: 3.13
+      Raise an exception if the string contains embedded null characters.
+
 
 UTF-32 Codecs
 """""""""""""

Doc/howto/regex.rst

@@ -245,6 +245,9 @@ You can omit either *m* or *n*; in that case, a reasonable value is assumed for
 the missing value.  Omitting *m* is interpreted as a lower limit of 0, while
 omitting *n* results in an upper bound of infinity.
 
+The simplest case ``{m}`` matches the preceding item exactly *m* times.
+For example, ``a/{2}b`` will only match ``'a//b'``.
+
 Readers of a reductionist bent may notice that the three other quantifiers can
 all be expressed using this notation.  ``{0,}`` is the same as ``*``, ``{1,}``
 is equivalent to ``+``, and ``{0,1}`` is the same as ``?``.  It's better to use

Doc/library/asyncio-eventloop.rst

@@ -243,9 +243,9 @@ Scheduling callbacks
    See the :ref:`concurrency and multithreading <asyncio-multithreading>`
    section of the documentation.
 
-.. versionchanged:: 3.7
-   The *context* keyword-only parameter was added. See :pep:`567`
-   for more details.
+   .. versionchanged:: 3.7
+      The *context* keyword-only parameter was added. See :pep:`567`
+      for more details.
 
 .. _asyncio-pass-keywords:
 
@@ -661,6 +661,8 @@ Opening network connections
 Creating network servers
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. _loop_create_server:
+
 .. coroutinemethod:: loop.create_server(protocol_factory, \
                         host=None, port=None, *, \
                         family=socket.AF_UNSPEC, \
@@ -1191,6 +1193,8 @@ Working with pipes
 Unix signals
 ^^^^^^^^^^^^
 
+.. _loop_add_signal_handler:
+
 .. method:: loop.add_signal_handler(signum, callback, *args)
 
    Set *callback* as the handler for the *signum* signal.
@@ -1391,6 +1395,14 @@ Enabling debug mode
       The new :ref:`Python Development Mode <devmode>` can now also be used
       to enable the debug mode.
 
+.. attribute:: loop.slow_callback_duration
+
+   This attribute can be used to set the
+   minimum execution duration in seconds that is considered "slow".
+   When debug mode is enabled, "slow" callbacks are logged.
+
+   Default value is 100 milliseconds.
+
 .. seealso::
 
    The :ref:`debug mode of asyncio <asyncio-debug-mode>`.
@@ -1411,6 +1423,8 @@ async/await code consider using the high-level
    :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>` for
    details.
 
+.. _loop_subprocess_exec:
+
 .. coroutinemethod:: loop.subprocess_exec(protocol_factory, *args, \
                       stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
                       stderr=subprocess.PIPE, **kwargs)

Doc/library/asyncio-task.rst

@@ -592,7 +592,7 @@ Shielding From Cancellation
 
    is equivalent to::
 
-       res = await shield(something())
+       res = await something()
 
    *except* that if the coroutine containing it is cancelled, the
    Task running in ``something()`` is not cancelled.  From the point

Doc/library/asyncio.rst

@@ -46,9 +46,9 @@ Additionally, there are **low-level** APIs for
 *library and framework developers* to:
 
 * create and manage :ref:`event loops <asyncio-event-loop>`, which
-  provide asynchronous APIs for :meth:`networking <loop.create_server>`,
-  running :meth:`subprocesses <loop.subprocess_exec>`,
-  handling :meth:`OS signals <loop.add_signal_handler>`, etc;
+  provide asynchronous APIs for :ref:`networking <loop_create_server>`,
+  running :ref:`subprocesses <loop_subprocess_exec>`,
+  handling :ref:`OS signals <loop_add_signal_handler>`, etc;
 
 * implement efficient protocols using
   :ref:`transports <asyncio-transports-protocols>`;

Doc/library/bz2.rst

@@ -91,7 +91,7 @@ The :mod:`bz2` module contains:
    and :meth:`~io.IOBase.truncate`.
    Iteration and the :keyword:`with` statement are supported.
 
-   :class:`BZ2File` also provides the following method:
+   :class:`BZ2File` also provides the following methods:
 
    .. method:: peek([n])
 
@@ -106,14 +106,52 @@ The :mod:`bz2` module contains:
 
       .. versionadded:: 3.3
 
+   .. method:: fileno()
+
+      Return the file descriptor for the underlying file.
+
+      .. versionadded:: 3.3
+
+   .. method:: readable()
+
+      Return whether the file was opened for reading.
+
+      .. versionadded:: 3.3
+
+   .. method:: seekable()
+
+      Return whether the file supports seeking.
+
+      .. versionadded:: 3.3
+
+   .. method:: writable()
+
+      Return whether the file was opened for writing.
+
+      .. versionadded:: 3.3
+
+   .. method:: read1(size=-1)
+
+      Read up to *size* uncompressed bytes, while trying to avoid
+      making multiple reads from the underlying stream. Reads up to a
+      buffer's worth of data if size is negative.
+
+      Returns ``b''`` if the file is at EOF.
+
+      .. versionadded:: 3.3
+
+   .. method:: readinto(b)
+
+      Read bytes into *b*.
+
+      Returns the number of bytes read (0 for EOF).
+
+      .. versionadded:: 3.3
+
 
    .. versionchanged:: 3.1
       Support for the :keyword:`with` statement was added.
 
-   .. versionchanged:: 3.3
-      The :meth:`fileno`, :meth:`readable`, :meth:`seekable`, :meth:`writable`,
-      :meth:`read1` and :meth:`readinto` methods were added.
-
    .. versionchanged:: 3.3
       Support was added for *filename* being a :term:`file object` instead of an
       actual filename.

Doc/library/enum.rst

@@ -165,7 +165,7 @@ Data Types
    to subclass *EnumType* -- see :ref:`Subclassing EnumType <enumtype-examples>`
    for details.
 
-   *EnumType* is responsible for setting the correct :meth:`!__repr__`,
+   ``EnumType`` is responsible for setting the correct :meth:`!__repr__`,
    :meth:`!__str__`, :meth:`!__format__`, and :meth:`!__reduce__` methods on the
    final *enum*, as well as creating the enum members, properly handling
    duplicates, providing iteration over the enum class, etc.
@@ -198,11 +198,12 @@ Data Types
         >>> some_var = Color.RED
         >>> some_var in Color
         True
+        >>> Color.RED.value in Color
+        True
 
-      .. note::
+   .. versionchanged:: 3.12
 
-         In Python 3.12 it will be possible to check for member values and not
-         just members; until then, a ``TypeError`` will be raised if a
+         Before Python 3.12, a ``TypeError`` is raised if a
          non-Enum-member is used in a containment check.
 
    .. method:: EnumType.__dir__(cls)
@@ -405,7 +406,7 @@ Data Types
 
 .. class:: IntEnum
 
-   *IntEnum* is the same as *Enum*, but its members are also integers and can be
+   *IntEnum* is the same as :class:`Enum`, but its members are also integers and can be
    used anywhere that an integer can be used.  If any integer operation is performed
    with an *IntEnum* member, the resulting value loses its enumeration status.
 
@@ -436,7 +437,7 @@ Data Types
 
 .. class:: StrEnum
 
-   *StrEnum* is the same as *Enum*, but its members are also strings and can be used
+   ``StrEnum`` is the same as :class:`Enum`, but its members are also strings and can be used
    in most of the same places that a string can be used.  The result of any string
    operation performed on or with a *StrEnum* member is not part of the enumeration.
 
@@ -575,7 +576,7 @@ Data Types
 
 .. class:: IntFlag
 
-   *IntFlag* is the same as *Flag*, but its members are also integers and can be
+   ``IntFlag`` is the same as :class:`Flag`, but its members are also integers and can be
    used anywhere that an integer can be used.
 
       >>> from enum import IntFlag, auto
@@ -595,12 +596,12 @@ Data Types
         >>> Color.RED + 2
         3
 
-   If a *Flag* operation is performed with an *IntFlag* member and:
+   If a :class:`Flag` operation is performed with an *IntFlag* member and:
 
    * the result is a valid *IntFlag*: an *IntFlag* is returned
-   * the result is not a valid *IntFlag*: the result depends on the *FlagBoundary* setting
+   * the result is not a valid *IntFlag*: the result depends on the :class:`FlagBoundary` setting
 
-   The *repr()* of unnamed zero-valued flags has changed.  It is now:
+   The :func:`repr()` of unnamed zero-valued flags has changed.  It is now:
 
       >>> Color(0)
       <Color: 0>
@@ -696,7 +697,7 @@ Data Types
 
 .. class:: FlagBoundary
 
-   *FlagBoundary* controls how out-of-range values are handled in *Flag* and its
+   ``FlagBoundary`` controls how out-of-range values are handled in :class:`Flag` and its
    subclasses.
 
    .. attribute:: STRICT
@@ -719,7 +720,7 @@ Data Types
 
    .. attribute:: CONFORM
 
-      Out-of-range values have invalid values removed, leaving a valid *Flag*
+      Out-of-range values have invalid values removed, leaving a valid :class:`Flag`
       value::
 
          >>> from enum import Flag, CONFORM, auto
@@ -733,7 +734,7 @@ Data Types
 
    .. attribute:: EJECT
 
-      Out-of-range values lose their *Flag* membership and revert to :class:`int`.
+      Out-of-range values lose their :class:`Flag` membership and revert to :class:`int`.
 
          >>> from enum import Flag, EJECT, auto
          >>> class EjectFlag(Flag, boundary=EJECT):
@@ -746,7 +747,7 @@ Data Types
 
    .. attribute:: KEEP
 
-      Out-of-range values are kept, and the *Flag* membership is kept.
+      Out-of-range values are kept, and the :class:`Flag` membership is kept.
       This is the default for :class:`IntFlag`::
 
          >>> from enum import Flag, KEEP, auto
@@ -808,10 +809,10 @@ Utilities and Decorators
 .. class:: auto
 
    *auto* can be used in place of a value.  If used, the *Enum* machinery will
-   call an *Enum*'s :meth:`~Enum._generate_next_value_` to get an appropriate value.
-   For *Enum* and *IntEnum* that appropriate value will be the last value plus
-   one; for *Flag* and *IntFlag* it will be the first power-of-two greater
-   than the highest value; for *StrEnum* it will be the lower-cased version of
+   call an :class:`Enum`'s :meth:`~Enum._generate_next_value_` to get an appropriate value.
+   For :class:`Enum` and :class:`IntEnum` that appropriate value will be the last value plus
+   one; for :class:`Flag` and :class:`IntFlag` it will be the first power-of-two greater
+   than the highest value; for :class:`StrEnum` it will be the lower-cased version of
    the member's name.  Care must be taken if mixing *auto()* with manually
    specified values.
 

Doc/library/inspect.rst

@@ -640,6 +640,9 @@ function.
    Accepts a wide range of Python callables, from plain functions and classes to
    :func:`functools.partial` objects.
 
+   If the passed object has a ``__signature__`` attribute, this function
+   returns it without further computations.
+
    For objects defined in modules using stringized annotations
    (``from __future__ import annotations``), :func:`signature` will
    attempt to automatically un-stringize the annotations using
@@ -763,6 +766,8 @@ function.
          sig = MySignature.from_callable(min)
          assert isinstance(sig, MySignature)
 
+       Its behavior is otherwise identical to that of :func:`signature`.
+
        .. versionadded:: 3.5
 
        .. versionadded:: 3.10

Doc/library/locale.rst

@@ -303,7 +303,7 @@ The :mod:`locale` module defines the following exception and functions:
    *language code* and *encoding* may be ``None`` if their values cannot be
    determined.
 
-   .. deprecated-removed:: 3.11 3.13
+   .. deprecated-removed:: 3.11 3.15
 
 
 .. function:: getlocale(category=LC_CTYPE)

Doc/library/mmap.rst

@@ -19,7 +19,7 @@ the current file position, and :meth:`seek` through the file to different positi
 A memory-mapped file is created by the :class:`~mmap.mmap` constructor, which is
 different on Unix and on Windows.  In either case you must provide a file
 descriptor for a file opened for update. If you wish to map an existing Python
-file object, use its :meth:`fileno` method to obtain the correct value for the
+file object, use its :meth:`~io.IOBase.fileno` method to obtain the correct value for the
 *fileno* parameter.  Otherwise, you can open the file using the
 :func:`os.open` function, which returns a file descriptor directly (the file
 still needs to be closed when done).

Doc/library/multiprocessing.rst

@@ -2582,7 +2582,7 @@ multiple connections at the same time.
    **Windows**: An item in *object_list* must either be an integer
    handle which is waitable (according to the definition used by the
    documentation of the Win32 function ``WaitForMultipleObjects()``)
-   or it can be an object with a :meth:`fileno` method which returns a
+   or it can be an object with a :meth:`~io.IOBase.fileno` method which returns a
    socket handle or pipe handle.  (Note that pipe handles and socket
    handles are **not** waitable handles.)
 

Doc/library/selectors.rst

@@ -21,7 +21,7 @@ It defines a :class:`BaseSelector` abstract base class, along with several
 concrete implementations (:class:`KqueueSelector`, :class:`EpollSelector`...),
 that can be used to wait for I/O readiness notification on multiple file
 objects. In the following, "file object" refers to any object with a
-:meth:`fileno()` method, or a raw file descriptor. See :term:`file object`.
+:meth:`~io.IOBase.fileno` method, or a raw file descriptor. See :term:`file object`.
 
 :class:`DefaultSelector` is an alias to the most efficient implementation
 available on the current platform: this should be the default choice for most

Doc/library/socket.rst

@@ -858,7 +858,7 @@ The following functions all create :ref:`socket objects <socket-objects>`.
 .. function:: fromfd(fd, family, type, proto=0)
 
    Duplicate the file descriptor *fd* (an integer as returned by a file object's
-   :meth:`fileno` method) and build a socket object from the result.  Address
+   :meth:`~io.IOBase.fileno` method) and build a socket object from the result.  Address
    family, socket type and protocol number are as for the :func:`.socket` function
    above. The file descriptor should refer to a socket, but this is not checked ---
    subsequent operations on the object may fail if the file descriptor is invalid.