merge with main

Author: sweeneyde

.github/CODEOWNERS

@@ -60,6 +60,8 @@ Python/pythonrun.c            @iritkatriel
 # bytecode.
 **/*import*.c                 @brettcannon @encukou @ericsnowcurrently @ncoghlan @warsaw
 **/*import*.py                @brettcannon @encukou @ericsnowcurrently @ncoghlan @warsaw
+**/importlib/resources/*      @jaraco @warsaw @brettcannon
+**/importlib/metadata/*       @jaraco @warsaw
 
 # Dates and times
 **/*datetime*                 @pganssle @abalkin

.github/workflows/doc.yml

@@ -23,6 +23,7 @@ on:
     paths:
     - 'Doc/**'
     - 'Misc/**'
+    - '.github/workflows/doc.yml'
 
 permissions:
   contents: read
@@ -35,6 +36,38 @@ jobs:
     - uses: actions/checkout@v3
     - name: Register Sphinx problem matcher
       run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
+    - name: 'Set up Python'
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3'
+        cache: 'pip'
+        cache-dependency-path: 'Doc/requirements.txt'
+    - name: 'Install build dependencies'
+      run: make -C Doc/ venv
+    - name: 'Check documentation'
+      run: make -C Doc/ check
+    - name: 'Build HTML documentation'
+      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
+    - name: 'Upload'
+      uses: actions/upload-artifact@v3
+      with:
+        name: doc-html
+        path: Doc/build/html
+
+  # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
+  doctest:
+    name: 'Doctest'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Register Sphinx problem matcher
+      run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
+    - uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ubuntu-doc-${{ hashFiles('Doc/requirements.txt') }}
+        restore-keys: |
+          ubuntu-doc-
     - name: 'Install Dependencies'
       run: sudo ./.github/workflows/posix-deps-apt.sh && sudo apt-get install wamerican
     - name: 'Configure CPython'
@@ -43,17 +76,6 @@ jobs:
       run: make -j4
     - name: 'Install build dependencies'
       run: make -C Doc/ PYTHON=../python venv
-    # Run "check doctest html" as 3 steps to get a more readable output
-    # in the web UI
-    - name: 'Check documentation'
-      run: make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going" check
     # Use "xvfb-run" since some doctest tests open GUI windows
     - name: 'Run documentation doctest'
-      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going" doctest
-    - name: 'Build HTML documentation'
-      run: make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going" html
-    - name: 'Upload'
-      uses: actions/upload-artifact@v3
-      with:
-        name: doc-html
-        path: Doc/build/html
+      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" doctest

Doc/c-api/sys.rst

@@ -21,10 +21,12 @@ Operating System Utilities
 
    Return true (nonzero) if the standard I/O file *fp* with name *filename* is
    deemed interactive.  This is the case for files for which ``isatty(fileno(fp))``
-   is true.  If the global flag :c:data:`Py_InteractiveFlag` is true, this function
+   is true.  If the :c:member:`PyConfig.interactive` is non-zero, this function
    also returns true if the *filename* pointer is ``NULL`` or if the name is equal to
    one of the strings ``'<stdin>'`` or ``'???'``.
 
+   This function must not be called before Python is initialized.
+
 
 .. c:function:: void PyOS_BeforeFork()
 

Doc/library/asyncio-llapi-index.rst

@@ -358,6 +358,10 @@ pipes, etc).  Returned from methods like
 
     * - :meth:`transport.get_write_buffer_size()
         <WriteTransport.get_write_buffer_size>`
+      - Return the current size of the output buffer.
+
+    * - :meth:`transport.get_write_buffer_limits()
+        <WriteTransport.get_write_buffer_limits>`
       - Return high and low water marks for write flow control.
 
     * - :meth:`transport.set_write_buffer_limits()

Doc/library/cgi.rst

@@ -19,6 +19,12 @@
    The :mod:`cgi` module is deprecated
    (see :pep:`PEP 594 <594#cgi>` for details and alternatives).
 
+   The :class:`FieldStorage` class can typically be replaced with
+   :func:`urllib.parse.parse_qsl` for ``GET`` and ``HEAD`` requests,
+   and the :mod:`email.message` module or
+   `multipart <https://pypi.org/project/multipart/>`_ for ``POST`` and ``PUT``.
+   Most :ref:`utility functions <functions-in-cgi-module>` have replacements.
+
 --------------
 
 Support module for Common Gateway Interface (CGI) scripts.
@@ -293,6 +299,12 @@ algorithms implemented in this module in other circumstances.
    ``sys.stdin``).  The *keep_blank_values*, *strict_parsing* and *separator* parameters are
    passed to :func:`urllib.parse.parse_qs` unchanged.
 
+   .. deprecated-removed:: 3.11 3.13
+      This function, like the rest of the :mod:`cgi` module, is deprecated.
+      It can be replaced by calling :func:`urllib.parse.parse_qs` directly
+      on the desired query string (except for ``multipart/form-data`` input,
+      which can be handled as described for :func:`parse_multipart`).
+
 
 .. function:: parse_multipart(fp, pdict, encoding="utf-8", errors="replace", separator="&")
 
@@ -316,12 +328,31 @@ algorithms implemented in this module in other circumstances.
    .. versionchanged:: 3.10
       Added the *separator* parameter.
 
+   .. deprecated-removed:: 3.11 3.13
+      This function, like the rest of the :mod:`cgi` module, is deprecated.
+      It can be replaced with the functionality in the :mod:`email` package
+      (e.g. :class:`email.message.EmailMessage`/:class:`email.message.Message`)
+      which implements the same MIME RFCs, or with the
+      `multipart <https://pypi.org/project/multipart/>`__ PyPI project.
+
 
 .. function:: parse_header(string)
 
    Parse a MIME header (such as :mailheader:`Content-Type`) into a main value and a
    dictionary of parameters.
 
+   .. deprecated-removed:: 3.11 3.13
+      This function, like the rest of the :mod:`cgi` module, is deprecated.
+      It can be replaced with the functionality in the :mod:`email` package,
+      which implements the same MIME RFCs.
+
+      For example, with :class:`email.message.EmailMessage`::
+
+          from email.message import EmailMessage
+          msg = EmailMessage()
+          msg['content-type'] = 'application/json; charset="utf8"'
+          main, params = msg.get_content_type(), msg['content-type'].params
+
 
 .. function:: test()
 

Doc/library/dis.rst

@@ -887,7 +887,20 @@ iterations of the loop.
 
 .. opcode:: LOAD_ATTR (namei)
 
-   Replaces TOS with ``getattr(TOS, co_names[namei])``.
+   If the low bit of ``namei`` is not set, this replaces TOS with
+   ``getattr(TOS, co_names[namei>>1])``.
+
+   If the low bit of ``namei`` is set, this will attempt to load a method named
+   ``co_names[namei>>1]`` from the TOS object. TOS is popped.
+   This bytecode distinguishes two cases: if TOS has a method with the correct
+   name, the bytecode pushes the unbound method and TOS. TOS will be used as
+   the first argument (``self``) by :opcode:`CALL` when calling the
+   unbound method. Otherwise, ``NULL`` and the object return by the attribute
+   lookup are pushed.
+
+   .. versionchanged:: 3.12
+      If the low bit of ``namei`` is set, then a ``NULL`` or ``self`` is
+      pushed to the stack before the attribute or unbound method respectively.
 
 
 .. opcode:: COMPARE_OP (opname)
@@ -1189,18 +1202,6 @@ iterations of the loop.
    .. versionadded:: 3.6
 
 
-.. opcode:: LOAD_METHOD (namei)
-
-   Loads a method named ``co_names[namei]`` from the TOS object. TOS is popped.
-   This bytecode distinguishes two cases: if TOS has a method with the correct
-   name, the bytecode pushes the unbound method and TOS. TOS will be used as
-   the first argument (``self``) by :opcode:`CALL` when calling the
-   unbound method. Otherwise, ``NULL`` and the object return by the attribute
-   lookup are pushed.
-
-   .. versionadded:: 3.7
-
-
 .. opcode:: PUSH_NULL
 
     Pushes a ``NULL`` to the stack.

Doc/library/socket.rst

@@ -2076,10 +2076,10 @@ the interface::
    # Include IP headers
    s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)
 
-   # receive all packages
+   # receive all packets
    s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)
 
-   # receive a package
+   # receive a packet
    print(s.recvfrom(65565))
 
    # disabled promiscuous mode

Doc/library/sqlite3.rst

@@ -336,9 +336,9 @@ Module functions and constants
    float, str or bytes.
 
 
-.. function:: complete_statement(sql)
+.. function:: complete_statement(statement)
 
-   Returns :const:`True` if the string *sql* contains one or more complete SQL
+   Returns :const:`True` if the string *statement* contains one or more complete SQL
    statements terminated by semicolons. It does not verify that the SQL is
    syntactically correct, only that there are no unclosed string literals and the
    statement is terminated by a semicolon.
@@ -457,11 +457,11 @@ Connection Objects
       :meth:`~Cursor.executescript` on it with the given *sql_script*.
       Return the new cursor object.
 
-   .. method:: create_function(name, num_params, func, *, deterministic=False)
+   .. method:: create_function(name, narg, func, *, deterministic=False)
 
       Creates a user-defined function that you can later use from within SQL
-      statements under the function name *name*. *num_params* is the number of
-      parameters the function accepts (if *num_params* is -1, the function may
+      statements under the function name *name*. *narg* is the number of
+      parameters the function accepts (if *narg* is -1, the function may
       take any number of arguments), and *func* is a Python callable that is
       called as the SQL function. If *deterministic* is true, the created function
       is marked as `deterministic <https://sqlite.org/deterministic.html>`_, which
@@ -480,12 +480,12 @@ Connection Objects
       .. literalinclude:: ../includes/sqlite3/md5func.py
 
 
-   .. method:: create_aggregate(name, num_params, aggregate_class)
+   .. method:: create_aggregate(name, n_arg, aggregate_class)
 
       Creates a user-defined aggregate function.
 
       The aggregate class must implement a ``step`` method, which accepts the number
-      of parameters *num_params* (if *num_params* is -1, the function may take
+      of parameters *n_arg* (if *n_arg* is -1, the function may take
       any number of arguments), and a ``finalize`` method which will return the
       final result of the aggregate.
 
@@ -580,15 +580,15 @@ Connection Objects
          Added support for disabling the authorizer using :const:`None`.
 
 
-   .. method:: set_progress_handler(handler, n)
+   .. method:: set_progress_handler(progress_handler, n)
 
       This routine registers a callback. The callback is invoked for every *n*
       instructions of the SQLite virtual machine. This is useful if you want to
       get called from SQLite during long-running operations, for example to update
       a GUI.
 
       If you want to clear any previously installed progress handler, call the
-      method with :const:`None` for *handler*.
+      method with :const:`None` for *progress_handler*.
 
       Returning a non-zero value from the handler function will terminate the
       currently executing query and cause it to raise a :exc:`DatabaseError`
@@ -628,7 +628,7 @@ Connection Objects
 
       Loadable extensions are disabled by default. See [#f1]_.
 
-      .. audit-event:: sqlite3.enable_load_extension connection,enabled sqlite3.enable_load_extension
+      .. audit-event:: sqlite3.enable_load_extension connection,enabled sqlite3.Connection.enable_load_extension
 
       .. versionadded:: 3.2
 
@@ -645,7 +645,7 @@ Connection Objects
 
       Loadable extensions are disabled by default. See [#f1]_.
 
-      .. audit-event:: sqlite3.load_extension connection,path sqlite3.load_extension
+      .. audit-event:: sqlite3.load_extension connection,path sqlite3.Connection.load_extension
 
       .. versionadded:: 3.2
 

Doc/library/test.rst

@@ -413,6 +413,51 @@ The :mod:`test.support` module defines the following constants:
 
 The :mod:`test.support` module defines the following functions:
 
+.. function:: busy_retry(timeout, err_msg=None, /, *, error=True)
+
+   Run the loop body until ``break`` stops the loop.
+
+   After *timeout* seconds, raise an :exc:`AssertionError` if *error* is true,
+   or just stop the loop if *error* is false.
+
+   Example::
+
+       for _ in support.busy_retry(support.SHORT_TIMEOUT):
+           if check():
+               break
+
+   Example of error=False usage::
+
+       for _ in support.busy_retry(support.SHORT_TIMEOUT, error=False):
+           if check():
+               break
+       else:
+           raise RuntimeError('my custom error')
+
+.. function:: sleeping_retry(timeout, err_msg=None, /, *, init_delay=0.010, max_delay=1.0, error=True)
+
+   Wait strategy that applies exponential backoff.
+
+   Run the loop body until ``break`` stops the loop. Sleep at each loop
+   iteration, but not at the first iteration. The sleep delay is doubled at
+   each iteration (up to *max_delay* seconds).
+
+   See :func:`busy_retry` documentation for the parameters usage.
+
+   Example raising an exception after SHORT_TIMEOUT seconds::
+
+       for _ in support.sleeping_retry(support.SHORT_TIMEOUT):
+           if check():
+               break
+
+   Example of error=False usage::
+
+       for _ in support.sleeping_retry(support.SHORT_TIMEOUT, error=False):
+           if check():
+               break
+       else:
+           raise RuntimeError('my custom error')
+
 .. function:: is_resource_enabled(resource)
 
    Return ``True`` if *resource* is enabled and available. The list of