Merge remote-tracking branch 'upstream/main' into fix-issue-46375

Author: marcelm

.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/data/stable_abi.dat

@@ -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/howto/regex.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-eventloop.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-task.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/asyncio.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/bz2.rst

@@ -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)