Merge remote-tracking branch 'upstream/main' into sha2_hacl

Doc/Makefile

@@ -9,6 +9,7 @@ VENVDIR      = ./venv
 SPHINXBUILD  = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
 SPHINXLINT   = PATH=$(VENVDIR)/bin:$$PATH sphinx-lint
 BLURB        = PATH=$(VENVDIR)/bin:$$PATH blurb
+JOBS         = auto
 PAPER        =
 SOURCES      =
 DISTVERSION  = $(shell $(PYTHON) tools/extensions/patchlevel.py)
@@ -18,7 +19,7 @@ SPHINXERRORHANDLING = -W
 PAPEROPT_a4     = -D latex_elements.papersize=a4paper
 PAPEROPT_letter = -D latex_elements.papersize=letterpaper
 
-ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees $(PAPEROPT_$(PAPER)) -j auto \
+ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees $(PAPEROPT_$(PAPER)) -j $(JOBS) \
                 $(SPHINXOPTS) $(SPHINXERRORHANDLING) . build/$(BUILDER) $(SOURCES)
 
 .PHONY: help

Doc/bugs.rst

@@ -19,6 +19,9 @@ If you find a bug in this documentation or would like to propose an improvement,
 please submit a bug report on the :ref:`tracker <using-the-tracker>`.  If you
 have a suggestion on how to fix it, include that as well.
 
+You can also open a discussion item on our
+`Documentation Discourse forum <https://discuss.python.org/c/documentation/26>`_.
+
 If you're short on time, you can also email documentation bug reports to
 [email protected] (behavioral bugs can be sent to [email protected]).
 'docs@' is a mailing list run by volunteers; your request will be noticed,

Doc/c-api/code.rst

@@ -77,6 +77,8 @@ bound into a function.
 
    Returns ``1`` if the function succeeds and 0 otherwise.
 
+   .. versionadded:: 3.11
+
 .. c:function:: PyObject* PyCode_GetCode(PyCodeObject *co)
 
    Equivalent to the Python code ``getattr(co, 'co_code')``.

Doc/faq/general.rst

@@ -248,8 +248,8 @@ Are there any published articles about Python that I can reference?
 
 It's probably best to cite your favorite book about Python.
 
-The very first article about Python was written in 1991 and is now quite
-outdated.
+The `very first article <https://ir.cwi.nl/pub/18204>`_ about Python was
+written in 1991 and is now quite outdated.
 
     Guido van Rossum and Jelke de Boer, "Interactively Testing Remote Servers
     Using the Python Programming Language", CWI Quarterly, Volume 4, Issue 4

Doc/howto/logging-cookbook.rst

@@ -307,7 +307,7 @@ Suppose you configure logging with the following JSON:
                 "class": "logging.StreamHandler",
                 "level": "INFO",
                 "formatter": "simple",
-                "stream": "ext://sys.stdout",
+                "stream": "ext://sys.stdout"
             },
             "stderr": {
                 "class": "logging.StreamHandler",

Doc/library/argparse.rst

@@ -31,7 +31,7 @@ Core Functionality
 
 The :mod:`argparse` module's support for command-line interfaces is built
 around an instance of :class:`argparse.ArgumentParser`.  It is a container for
-argument specifications and has options that apply the parser as whole::
+argument specifications and has options that apply to the parser as whole::
 
    parser = argparse.ArgumentParser(
                        prog = 'ProgramName',

Doc/library/array.rst

@@ -60,7 +60,7 @@ Notes:
 
 The actual representation of values is determined by the machine architecture
 (strictly speaking, by the C implementation).  The actual size can be accessed
-through the :attr:`itemsize` attribute.
+through the :attr:`array.itemsize` attribute.
 
 The module defines the following item:
 
@@ -85,161 +85,160 @@ The module defines the following type:
    to add initial items to the array.  Otherwise, the iterable initializer is
    passed to the :meth:`extend` method.
 
-   .. audit-event:: array.__new__ typecode,initializer array.array
+   Array objects support the ordinary sequence operations of indexing, slicing,
+   concatenation, and multiplication.  When using slice assignment, the assigned
+   value must be an array object with the same type code; in all other cases,
+   :exc:`TypeError` is raised. Array objects also implement the buffer interface,
+   and may be used wherever :term:`bytes-like objects <bytes-like object>` are supported.
 
+   .. audit-event:: array.__new__ typecode,initializer array.array
 
-Array objects support the ordinary sequence operations of indexing, slicing,
-concatenation, and multiplication.  When using slice assignment, the assigned
-value must be an array object with the same type code; in all other cases,
-:exc:`TypeError` is raised. Array objects also implement the buffer interface,
-and may be used wherever :term:`bytes-like objects <bytes-like object>` are supported.
 
-The following data items and methods are also supported:
+   .. attribute:: typecode
 
-.. attribute:: array.typecode
+      The typecode character used to create the array.
 
-   The typecode character used to create the array.
 
+   .. attribute:: itemsize
 
-.. attribute:: array.itemsize
+      The length in bytes of one array item in the internal representation.
 
-   The length in bytes of one array item in the internal representation.
 
+   .. method:: append(x)
 
-.. method:: array.append(x)
+      Append a new item with value *x* to the end of the array.
 
-   Append a new item with value *x* to the end of the array.
 
+   .. method:: buffer_info()
 
-.. method:: array.buffer_info()
+      Return a tuple ``(address, length)`` giving the current memory address and the
+      length in elements of the buffer used to hold array's contents.  The size of the
+      memory buffer in bytes can be computed as ``array.buffer_info()[1] *
+      array.itemsize``.  This is occasionally useful when working with low-level (and
+      inherently unsafe) I/O interfaces that require memory addresses, such as certain
+      :c:func:`!ioctl` operations.  The returned numbers are valid as long as the array
+      exists and no length-changing operations are applied to it.
 
-   Return a tuple ``(address, length)`` giving the current memory address and the
-   length in elements of the buffer used to hold array's contents.  The size of the
-   memory buffer in bytes can be computed as ``array.buffer_info()[1] *
-   array.itemsize``.  This is occasionally useful when working with low-level (and
-   inherently unsafe) I/O interfaces that require memory addresses, such as certain
-   :c:func:`ioctl` operations.  The returned numbers are valid as long as the array
-   exists and no length-changing operations are applied to it.
+      .. note::
 
-   .. note::
+         When using array objects from code written in C or C++ (the only way to
+         effectively make use of this information), it makes more sense to use the buffer
+         interface supported by array objects.  This method is maintained for backward
+         compatibility and should be avoided in new code.  The buffer interface is
+         documented in :ref:`bufferobjects`.
 
-      When using array objects from code written in C or C++ (the only way to
-      effectively make use of this information), it makes more sense to use the buffer
-      interface supported by array objects.  This method is maintained for backward
-      compatibility and should be avoided in new code.  The buffer interface is
-      documented in :ref:`bufferobjects`.
 
+   .. method:: byteswap()
 
-.. method:: array.byteswap()
+      "Byteswap" all items of the array.  This is only supported for values which are
+      1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
+      raised.  It is useful when reading data from a file written on a machine with a
+      different byte order.
 
-   "Byteswap" all items of the array.  This is only supported for values which are
-   1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
-   raised.  It is useful when reading data from a file written on a machine with a
-   different byte order.
 
+   .. method:: count(x)
 
-.. method:: array.count(x)
+      Return the number of occurrences of *x* in the array.
 
-   Return the number of occurrences of *x* in the array.
 
+   .. method:: extend(iterable)
 
-.. method:: array.extend(iterable)
+      Append items from *iterable* to the end of the array.  If *iterable* is another
+      array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
+      be raised.  If *iterable* is not an array, it must be iterable and its elements
+      must be the right type to be appended to the array.
 
-   Append items from *iterable* to the end of the array.  If *iterable* is another
-   array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
-   be raised.  If *iterable* is not an array, it must be iterable and its elements
-   must be the right type to be appended to the array.
 
+   .. method:: frombytes(s)
 
-.. method:: array.frombytes(s)
+      Appends items from the string, interpreting the string as an array of machine
+      values (as if it had been read from a file using the :meth:`fromfile` method).
 
-   Appends items from the string, interpreting the string as an array of machine
-   values (as if it had been read from a file using the :meth:`fromfile` method).
+      .. versionadded:: 3.2
+         :meth:`!fromstring` is renamed to :meth:`frombytes` for clarity.
 
-   .. versionadded:: 3.2
-      :meth:`fromstring` is renamed to :meth:`frombytes` for clarity.
 
+   .. method:: fromfile(f, n)
 
-.. method:: array.fromfile(f, n)
+      Read *n* items (as machine values) from the :term:`file object` *f* and append
+      them to the end of the array.  If less than *n* items are available,
+      :exc:`EOFError` is raised, but the items that were available are still
+      inserted into the array.
 
-   Read *n* items (as machine values) from the :term:`file object` *f* and append
-   them to the end of the array.  If less than *n* items are available,
-   :exc:`EOFError` is raised, but the items that were available are still
-   inserted into the array.
 
+   .. method:: fromlist(list)
 
-.. method:: array.fromlist(list)
+      Append items from the list.  This is equivalent to ``for x in list:
+      a.append(x)`` except that if there is a type error, the array is unchanged.
 
-   Append items from the list.  This is equivalent to ``for x in list:
-   a.append(x)`` except that if there is a type error, the array is unchanged.
 
+   .. method:: fromunicode(s)
 
-.. method:: array.fromunicode(s)
+      Extends this array with data from the given unicode string.  The array must
+      be a type ``'u'`` array; otherwise a :exc:`ValueError` is raised.  Use
+      ``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to an
+      array of some other type.
 
-   Extends this array with data from the given unicode string.  The array must
-   be a type ``'u'`` array; otherwise a :exc:`ValueError` is raised.  Use
-   ``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to an
-   array of some other type.
 
+   .. method:: index(x[, start[, stop]])
 
-.. method:: array.index(x[, start[, stop]])
+      Return the smallest *i* such that *i* is the index of the first occurrence of
+      *x* in the array.  The optional arguments *start* and *stop* can be
+      specified to search for *x* within a subsection of the array.  Raise
+      :exc:`ValueError` if *x* is not found.
 
-   Return the smallest *i* such that *i* is the index of the first occurrence of
-   *x* in the array.  The optional arguments *start* and *stop* can be
-   specified to search for *x* within a subsection of the array.  Raise
-   :exc:`ValueError` if *x* is not found.
+      .. versionchanged:: 3.10
+         Added optional *start* and *stop* parameters.
 
-   .. versionchanged:: 3.10
-      Added optional *start* and *stop* parameters.
 
-.. method:: array.insert(i, x)
+   .. method:: insert(i, x)
 
-   Insert a new item with value *x* in the array before position *i*. Negative
-   values are treated as being relative to the end of the array.
+      Insert a new item with value *x* in the array before position *i*. Negative
+      values are treated as being relative to the end of the array.
 
 
-.. method:: array.pop([i])
+   .. method:: pop([i])
 
-   Removes the item with the index *i* from the array and returns it. The optional
-   argument defaults to ``-1``, so that by default the last item is removed and
-   returned.
+      Removes the item with the index *i* from the array and returns it. The optional
+      argument defaults to ``-1``, so that by default the last item is removed and
+      returned.
 
 
-.. method:: array.remove(x)
+   .. method:: remove(x)
 
-   Remove the first occurrence of *x* from the array.
+      Remove the first occurrence of *x* from the array.
 
 
-.. method:: array.reverse()
+   .. method:: reverse()
 
-   Reverse the order of the items in the array.
+      Reverse the order of the items in the array.
 
 
-.. method:: array.tobytes()
+   .. method:: tobytes()
 
-   Convert the array to an array of machine values and return the bytes
-   representation (the same sequence of bytes that would be written to a file by
-   the :meth:`tofile` method.)
+      Convert the array to an array of machine values and return the bytes
+      representation (the same sequence of bytes that would be written to a file by
+      the :meth:`tofile` method.)
 
-   .. versionadded:: 3.2
-      :meth:`tostring` is renamed to :meth:`tobytes` for clarity.
+      .. versionadded:: 3.2
+         :meth:`!tostring` is renamed to :meth:`tobytes` for clarity.
 
 
-.. method:: array.tofile(f)
+   .. method:: tofile(f)
 
-   Write all items (as machine values) to the :term:`file object` *f*.
+      Write all items (as machine values) to the :term:`file object` *f*.
 
 
-.. method:: array.tolist()
+   .. method:: tolist()
 
-   Convert the array to an ordinary list with the same items.
+      Convert the array to an ordinary list with the same items.
 
 
-.. method:: array.tounicode()
+   .. method:: tounicode()
 
-   Convert the array to a unicode string.  The array must be a type ``'u'`` array;
-   otherwise a :exc:`ValueError` is raised. Use ``array.tobytes().decode(enc)`` to
-   obtain a unicode string from an array of some other type.
+      Convert the array to a unicode string.  The array must be a type ``'u'`` array;
+      otherwise a :exc:`ValueError` is raised. Use ``array.tobytes().decode(enc)`` to
+      obtain a unicode string from an array of some other type.
 
 
 When an array object is printed or converted to a string, it is represented as

Doc/library/asyncio-eventloop.rst

@@ -186,19 +186,24 @@ Running and stopping the loop
 .. coroutinemethod:: loop.shutdown_default_executor(timeout=None)
 
    Schedule the closure of the default executor and wait for it to join all of
-   the threads in the :class:`ThreadPoolExecutor`. After calling this method, a
-   :exc:`RuntimeError` will be raised if :meth:`loop.run_in_executor` is called
-   while using the default executor.
+   the threads in the :class:`~concurrent.futures.ThreadPoolExecutor`.
+   Once this method has been called,
+   using the default executor with :meth:`loop.run_in_executor`
+   will raise a :exc:`RuntimeError`.
 
-   The *timeout* parameter specifies the amount of time the executor will
-   be given to finish joining. The default value is ``None``, which means the
-   executor will be given an unlimited amount of time.
+   The *timeout* parameter specifies the amount of time
+   (in :class:`float` seconds) the executor will be given to finish joining.
+   With the default, ``None``,
+   the executor is allowed an unlimited amount of time.
 
-   If the timeout duration is reached, a warning is emitted and executor is
-   terminated without waiting for its threads to finish joining.
+   If the *timeout* is reached, a :exc:`RuntimeWarning` is emitted
+   and the default executor is terminated
+   without waiting for its threads to finish joining.
 
-   Note that there is no need to call this function when
-   :func:`asyncio.run` is used.
+   .. note::
+
+      Do not call this method when using :func:`asyncio.run`,
+      as the latter handles default executor shutdown automatically.
 
    .. versionadded:: 3.9
 
@@ -213,22 +218,23 @@ Scheduling callbacks
    Schedule the *callback* :term:`callback` to be called with
    *args* arguments at the next iteration of the event loop.
 
+   Return an instance of :class:`asyncio.Handle`,
+   which can be used later to cancel the callback.
+
    Callbacks are called in the order in which they are registered.
    Each callback will be called exactly once.
 
-   An optional keyword-only *context* argument allows specifying a
+   The optional keyword-only *context* argument specifies a
    custom :class:`contextvars.Context` for the *callback* to run in.
-   The current context is used when no *context* is provided.
-
-   An instance of :class:`asyncio.Handle` is returned, which can be
-   used later to cancel the callback.
+   Callbacks use the current context when no *context* is provided.
 
-   This method is not thread-safe.
+   Unlike :meth:`call_soon_threadsafe`, this method is not thread-safe.
 
 .. method:: loop.call_soon_threadsafe(callback, *args, context=None)
 
-   A thread-safe variant of :meth:`call_soon`.  Must be used to
-   schedule callbacks *from another thread*.
+   A thread-safe variant of :meth:`call_soon`. When scheduling callbacks from
+   another thread, this function *must* be used, since :meth:`call_soon` is not
+   thread-safe.
 
    Raises :exc:`RuntimeError` if called on a loop that's been closed.
    This can happen on a secondary thread when the main application is