Merge branch 'main' into crash-bytesio-getbuffer-gc

.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/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

@@ -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.
@@ -1419,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

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

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.

Doc/library/sys.monitoring.rst

@@ -44,21 +44,21 @@ Identifiers are integers in the range 0 to 5 inclusive.
 Registering and using tools
 '''''''''''''''''''''''''''
 
-.. function:: use_tool_id(id: int, name: str) -> None
+.. function:: use_tool_id(tool_id: int, name: str) -> None
 
-   Must be called before *id* can be used.
-   *id* must be in the range 0 to 5 inclusive.
-   Raises a :exc:`ValueError` if *id* is in use.
+   Must be called before *tool_id* can be used.
+   *tool_id* must be in the range 0 to 5 inclusive.
+   Raises a :exc:`ValueError` if *tool_id* is in use.
 
-.. function:: free_tool_id(id: int) -> None
+.. function:: free_tool_id(tool_id: int) -> None
 
-   Should be called once a tool no longer requires *id*.
+   Should be called once a tool no longer requires *tool_id*.
 
-.. function:: get_tool(id: int) -> str | None
+.. function:: get_tool(tool_id: int) -> str | None
 
-   Returns the name of the tool if *id* is in use,
+   Returns the name of the tool if *tool_id* is in use,
    otherwise it returns ``None``.
-   *id* must be in the range 0 to 5 inclusive.
+   *tool_id* must be in the range 0 to 5 inclusive.
 
 All IDs are treated the same by the VM with regard to events, but the
 following IDs are pre-defined to make co-operation of tools easier::

Doc/library/sys.rst

@@ -1780,7 +1780,7 @@ always available.
       However, if you are writing a library (and do not control in which
       context its code will be executed), be aware that the standard streams
       may be replaced with file-like objects like :class:`io.StringIO` which
-      do not support the :attr:!buffer` attribute.
+      do not support the :attr:`!buffer` attribute.
 
 
 .. data:: __stdin__

Doc/library/tempfile.rst

@@ -147,7 +147,7 @@ The module defines the following user-callable items:
 
    This class operates exactly as :func:`TemporaryFile` does, except that
    data is spooled in memory until the file size exceeds *max_size*, or
-   until the file's :func:`fileno` method is called, at which point the
+   until the file's :func:`~io.IOBase.fileno` method is called, at which point the
    contents are written to disk and operation proceeds as with
    :func:`TemporaryFile`.
 

Doc/library/test.rst

@@ -508,34 +508,6 @@ The :mod:`test.support` module defines the following functions:
    Define match patterns on test filenames and test method names for filtering tests.
 
 
-.. function:: run_unittest(*classes)
-
-   Execute :class:`unittest.TestCase` subclasses passed to the function. The
-   function scans the classes for methods starting with the prefix ``test_``
-   and executes the tests individually.
-
-   It is also legal to pass strings as parameters; these should be keys in
-   ``sys.modules``. Each associated module will be scanned by
-   ``unittest.TestLoader.loadTestsFromModule()``. This is usually seen in the
-   following :func:`test_main` function::
-
-      def test_main():
-          support.run_unittest(__name__)
-
-   This will run all tests defined in the named module.
-
-
-.. function:: run_doctest(module, verbosity=None, optionflags=0)
-
-   Run :func:`doctest.testmod` on the given *module*.  Return
-   ``(failure_count, test_count)``.
-
-   If *verbosity* is ``None``, :func:`doctest.testmod` is run with verbosity
-   set to :data:`verbose`.  Otherwise, it is run with verbosity set to
-   ``None``.  *optionflags* is passed as ``optionflags`` to
-   :func:`doctest.testmod`.
-
-
 .. function:: get_pagesize()
 
    Get size of a page in bytes.

Doc/library/typing.rst

@@ -304,7 +304,7 @@ a callable with any arbitrary parameter list would be acceptable:
    x = concat  # Also OK
 
 ``Callable`` cannot express complex signatures such as functions that take a
-variadic number of arguments, :func:`overloaded functions <overload>`, or
+variadic number of arguments, :ref:`overloaded functions <overload>`, or
 functions that have keyword-only parameters. However, these signatures can be
 expressed by defining a :class:`Protocol` class with a
 :meth:`~object.__call__` method:
@@ -526,7 +526,7 @@ A user-defined class can be defined as a generic class.
            self.logger.info('%s: %s', self.name, message)
 
 This syntax indicates that the class ``LoggedVar`` is parameterised around a
-single :class:`type variable <TypeVar>` ``T`` . This also makes ``T`` valid as
+single :ref:`type variable <typevar>` ``T`` . This also makes ``T`` valid as
 a type within the class body.
 
 Generic classes implicitly inherit from :class:`Generic`. For compatibility
@@ -1493,7 +1493,7 @@ These can be used as types in annotations. They all support subscription using
    Typing operator to conceptually mark an object as having been unpacked.
 
    For example, using the unpack operator ``*`` on a
-   :class:`type variable tuple <TypeVarTuple>` is equivalent to using ``Unpack``
+   :ref:`type variable tuple <typevartuple>` is equivalent to using ``Unpack``
    to mark the type variable tuple as having been unpacked::
 
       Ts = TypeVarTuple('Ts')
@@ -1584,6 +1584,8 @@ without the dedicated syntax, as documented below.
               ...
               # Etc.
 
+.. _typevar:
+
 .. class:: TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False)
 
    Type variable.
@@ -1728,9 +1730,11 @@ without the dedicated syntax, as documented below.
       :ref:`type parameter <type-params>` syntax introduced by :pep:`695`.
       The ``infer_variance`` parameter was added.
 
+.. _typevartuple:
+
 .. class:: TypeVarTuple(name)
 
-   Type variable tuple. A specialized form of :class:`type variable <TypeVar>`
+   Type variable tuple. A specialized form of :ref:`type variable <typevar>`
    that enables *variadic* generics.
 
    Type variable tuples can be declared in :ref:`type parameter lists <type-params>`
@@ -1848,7 +1852,7 @@ without the dedicated syntax, as documented below.
 .. class:: ParamSpec(name, *, bound=None, covariant=False, contravariant=False)
 
    Parameter specification variable.  A specialized version of
-   :class:`type variables <TypeVar>`.
+   :ref:`type variables <typevar>`.
 
    In :ref:`type parameter lists <type-params>`, parameter specifications
    can be declared with two asterisks (``**``)::
@@ -2772,6 +2776,8 @@ Functions and decorators
 
    .. versionadded:: 3.11
 
+.. _overload:
+
 .. decorator:: overload
 
    Decorator for creating overloaded functions and methods.

Doc/library/xml.etree.elementtree.rst

@@ -154,6 +154,7 @@ elements, call :meth:`XMLPullParser.read_events`.  Here is an example::
    ...     print(elem.tag, 'text=', elem.text)
    ...
    end
+   mytag text= sometext more text
 
 The obvious use case is applications that operate in a non-blocking fashion
 where the XML data is being received from a socket or read incrementally from

Doc/tools/.nitignore

@@ -38,7 +38,6 @@ Doc/library/asyncio-subprocess.rst
 Doc/library/asyncio-task.rst
 Doc/library/bdb.rst
 Doc/library/bisect.rst
-Doc/library/bz2.rst
 Doc/library/calendar.rst
 Doc/library/cmd.rst
 Doc/library/collections.abc.rst
@@ -100,7 +99,6 @@ Doc/library/reprlib.rst
 Doc/library/resource.rst
 Doc/library/rlcompleter.rst
 Doc/library/select.rst
-Doc/library/selectors.rst
 Doc/library/shelve.rst
 Doc/library/signal.rst
 Doc/library/smtplib.rst

Doc/whatsnew/2.5.rst

@@ -1347,7 +1347,7 @@ complete list of changes, or look through the SVN logs for all the details.
   :func:`input` function to allow opening files in binary or :term:`universal
   newlines` mode.  Another new parameter, *openhook*, lets you use a function
   other than :func:`open`  to open the input files.  Once you're iterating over
-  the set of files, the :class:`FileInput` object's new :meth:`fileno` returns
+  the set of files, the :class:`FileInput` object's new :meth:`~fileinput.fileno` returns
   the file descriptor for the currently opened file. (Contributed by Georg
   Brandl.)