Merge remote-tracking branch 'upstream/main' into pythongh-107265

Author: corona10

.github/workflows/build.yml

@@ -244,7 +244,7 @@ jobs:
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true'
     env:
-      OPENSSL_VER: 1.1.1u
+      OPENSSL_VER: 1.1.1v
       PYTHONSTRICTEXTENSIONBUILD: 1
     steps:
     - uses: actions/checkout@v3
@@ -313,7 +313,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        openssl_ver: [1.1.1u, 3.0.9, 3.1.1]
+        openssl_ver: [1.1.1v, 3.0.10, 3.1.2]
     env:
       OPENSSL_VER: ${{ matrix.openssl_ver }}
       MULTISSL_DIR: ${{ github.workspace }}/multissl
@@ -365,7 +365,7 @@ jobs:
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true' && needs.check_source.outputs.run_hypothesis == 'true'
     env:
-      OPENSSL_VER: 1.1.1u
+      OPENSSL_VER: 1.1.1v
       PYTHONSTRICTEXTENSIONBUILD: 1
     steps:
     - uses: actions/checkout@v3
@@ -474,7 +474,7 @@ jobs:
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true'
     env:
-      OPENSSL_VER: 1.1.1u
+      OPENSSL_VER: 1.1.1v
       PYTHONSTRICTEXTENSIONBUILD: 1
       ASAN_OPTIONS: detect_leaks=0:allocator_may_return_null=1:handle_segv=0
     steps:

.github/workflows/reusable-docs.yml

@@ -16,8 +16,30 @@ jobs:
     name: 'Docs'
     runs-on: ubuntu-latest
     timeout-minutes: 60
+    env:
+      branch_base: 'origin/${{ github.event.pull_request.base.ref }}'
+      branch_pr: 'origin/${{ github.event.pull_request.head.ref }}'
+      refspec_base: '+${{ github.event.pull_request.base.sha }}:remotes/origin/${{ github.event.pull_request.base.ref }}'
+      refspec_pr: '+${{ github.event.pull_request.head.sha }}:remotes/origin/${{ github.event.pull_request.head.ref }}'
     steps:
-    - uses: actions/checkout@v3
+    - name: 'Check out latest PR branch commit'
+      uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.pull_request.head.sha }}
+    # Adapted from https://github.com/actions/checkout/issues/520#issuecomment-1167205721
+    - name: 'Fetch commits to get branch diff'
+      run: |
+        # Fetch enough history to find a common ancestor commit (aka merge-base):
+        git fetch origin ${{ env.refspec_pr }} --depth=$(( ${{ github.event.pull_request.commits }} + 1 )) \
+          --no-tags --prune --no-recurse-submodules
+
+        # This should get the oldest commit in the local fetched history (which may not be the commit the PR branched from):
+        COMMON_ANCESTOR=$( git rev-list --first-parent --max-parents=0 --max-count=1 ${{ env.branch_pr }} )
+        DATE=$( git log --date=iso8601 --format=%cd "${COMMON_ANCESTOR}" )
+
+        # Get all commits since that commit date from the base branch (eg: master or main):
+        git fetch origin ${{ env.refspec_base }} --shallow-since="${DATE}" \
+          --no-tags --prune --no-recurse-submodules
     - name: 'Set up Python'
       uses: actions/setup-python@v4
       with:
@@ -28,13 +50,6 @@ jobs:
       run: make -C Doc/ venv
 
     # To annotate PRs with Sphinx nitpicks (missing references)
-    - name: 'Get list of changed files'
-      if: github.event_name == 'pull_request'
-      id: changed_files
-      uses: Ana06/[email protected]
-      with:
-        filter: "Doc/**"
-        format: csv  # works for paths with spaces
     - name: 'Build HTML documentation'
       continue-on-error: true
       run: |
@@ -45,7 +60,7 @@ jobs:
       if: github.event_name == 'pull_request'
       run: |
         python Doc/tools/check-warnings.py \
-          --check-and-annotate '${{ steps.changed_files.outputs.added_modified }}' \
+          --annotate-diff '${{ env.branch_base }}' '${{ env.branch_pr }}' \
           --fail-if-regression \
           --fail-if-improved
 

Doc/howto/clinic.rst

@@ -1941,54 +1941,70 @@ The generated docstring ends up looking like this:
 
 
 .. _clinic-howto-deprecate-positional:
+.. _clinic-howto-deprecate-keyword:
 
-How to deprecate passing parameters positionally
-------------------------------------------------
+How to deprecate passing parameters positionally or by keyword
+--------------------------------------------------------------
 
 Argument Clinic provides syntax that makes it possible to generate code that
-deprecates passing :term:`arguments <argument>` positionally.
+deprecates passing :term:`arguments <argument>` for positional-or-keyword
+:term:`parameters <parameter>` positionally or by keyword.
 For example, say we've got a module-level function :py:func:`!foo.myfunc`
-that has three :term:`parameters <parameter>`:
-positional-or-keyword parameters *a* and *b*, and a keyword-only parameter *c*::
+that has five parameters: a positional-only parameter *a*, three
+positional-or-keyword parameters *b*, *c* and *d*, and a keyword-only
+parameter *e*::
 
    /*[clinic input]
    module foo
    myfunc
        a: int
+       /
        b: int
-       *
        c: int
+       d: int
+       *
+       e: int
    [clinic start generated output]*/
 
-We now want to make the *b* parameter keyword-only;
-however, we'll have to wait two releases before making this change,
+We now want to make the *b* parameter positional-only and the *d* parameter
+keyword-only;
+however, we'll have to wait two releases before making these changes,
 as mandated by Python's backwards-compatibility policy (see :pep:`387`).
 For this example, imagine we're in the development phase for Python 3.12:
 that means we'll be allowed to introduce deprecation warnings in Python 3.12
-whenever the *b* parameter is passed positionally,
-and we'll be allowed to make it keyword-only in Python 3.14 at the earliest.
+whenever an argument for the *b* parameter is passed by keyword or an argument
+for the *d* parameter is passed positionally, and we'll be allowed to make
+them positional-only and keyword-only respectively in Python 3.14 at
+the earliest.
 
 We can use Argument Clinic to emit the desired deprecation warnings
-using the ``* [from ...]`` syntax,
-by adding the line ``* [from 3.14]`` right above the *b* parameter::
+using the ``[from ...]`` syntax, by adding the line ``/ [from 3.14]`` right
+below the *b* parameter and adding the line ``* [from 3.14]`` right above
+the *d* parameter::
 
    /*[clinic input]
    module foo
    myfunc
        a: int
-       * [from 3.14]
+       /
        b: int
-       *
+       / [from 3.14]
        c: int
+       * [from 3.14]
+       d: int
+       *
+       e: int
    [clinic start generated output]*/
 
 Next, regenerate Argument Clinic code (``make clinic``),
 and add unit tests for the new behaviour.
 
 The generated code will now emit a :exc:`DeprecationWarning`
-when an :term:`argument` for the :term:`parameter` *b* is passed positionally.
+when an :term:`argument` for the :term:`parameter` *d* is passed positionally
+(e.g ``myfunc(1, 2, 3, 4, e=5)``) or an argument for the parameter *b* is
+passed by keyword (e.g ``myfunc(1, b=2, c=3, d=4, e=5)``).
 C preprocessor directives are also generated for emitting
-compiler warnings if the ``* [from ...]`` line has not been removed
+compiler warnings if the ``[from ...]`` lines have not been removed
 from the Argument Clinic input when the deprecation period is over,
 which means when the alpha phase of the specified Python version kicks in.
 
@@ -2001,21 +2017,26 @@ Luckily for us, compiler warnings are now generated:
 .. code-block:: none
 
    In file included from Modules/foomodule.c:139:
-   Modules/clinic/foomodule.c.h:139:8: warning: In 'foomodule.c', update parameter(s) 'a' and 'b' in the clinic input of 'mymod.myfunc' to be keyword-only. [-W#warnings]
-    #    warning "In 'foomodule.c', update parameter(s) 'a' and 'b' in the clinic input of 'mymod.myfunc' to be keyword-only. [-W#warnings]"
+   Modules/clinic/foomodule.c.h:139:8: warning: In 'foomodule.c', update the clinic input of 'mymod.myfunc'. [-W#warnings]
+    #    warning "In 'foomodule.c', update the clinic input of 'mymod.myfunc'. [-W#warnings]"
          ^
 
-We now close the deprecation phase by making *b* keyword-only;
-replace the ``* [from ...]`` line above *b*
-with the ``*`` from the line above *c*::
+We now close the deprecation phase by making *a* positional-only and *c*
+keyword-only;
+replace the ``/ [from ...]`` line below *b* with the ``/`` from the line
+below *a* and the ``* [from ...]`` line above *d* with the ``*`` from
+the line above *e*::
 
    /*[clinic input]
    module foo
    myfunc
        a: int
-       *
        b: int
+       /
        c: int
+       *
+       d: int
+       e: int
    [clinic start generated output]*/
 
 Finally, run ``make clinic`` to regenerate the Argument Clinic code,

Doc/library/asyncio-task.rst

@@ -631,9 +631,9 @@ Shielding From Cancellation
 Timeouts
 ========
 
-.. coroutinefunction:: timeout(delay)
+.. function:: timeout(delay)
 
-    An :ref:`asynchronous context manager <async-context-managers>`
+    Return an :ref:`asynchronous context manager <async-context-managers>`
     that can be used to limit the amount of time spent waiting on
     something.
 
@@ -724,7 +724,7 @@ Timeouts
 
     .. versionadded:: 3.11
 
-.. coroutinefunction:: timeout_at(when)
+.. function:: timeout_at(when)
 
    Similar to :func:`asyncio.timeout`, except *when* is the absolute time
    to stop waiting, or ``None``.

Doc/library/ctypes.rst

@@ -2029,17 +2029,17 @@ Utility functions
    specifying an address, or a ctypes instance.
 
 
-.. function:: POINTER(type)
+.. function:: POINTER(type, /)
 
-   This factory function creates and returns a new ctypes pointer type. Pointer
-   types are cached and reused internally, so calling this function repeatedly is
-   cheap. *type* must be a ctypes type.
+   Create and return a new ctypes pointer type. Pointer types are cached and
+   reused internally, so calling this function repeatedly is cheap.
+   *type* must be a ctypes type.
 
 
-.. function:: pointer(obj)
+.. function:: pointer(obj, /)
 
-   This function creates a new pointer instance, pointing to *obj*. The returned
-   object is of the type ``POINTER(type(obj))``.
+   Create a new pointer instance, pointing to *obj*.
+   The returned object is of the type ``POINTER(type(obj))``.
 
    Note: If you just want to pass a pointer to an object to a foreign function
    call, you should use ``byref(obj)`` which is much faster.

Doc/library/functools.rst

@@ -226,8 +226,9 @@ The :mod:`functools` module defines the following functions:
 
    In general, the LRU cache should only be used when you want to reuse
    previously computed values.  Accordingly, it doesn't make sense to cache
-   functions with side-effects, functions that need to create distinct mutable
-   objects on each call, or impure functions such as time() or random().
+   functions with side-effects, functions that need to create
+   distinct mutable objects on each call (such as generators and async functions),
+   or impure functions such as time() or random().
 
    Example of an LRU cache for static web content::
 

Doc/library/itertools.rst

@@ -1048,9 +1048,7 @@ The following recipes have a more mathematical flavor:
        # factor(1_000_000_000_000_007) --> 47 59 360620266859
        # factor(1_000_000_000_000_403) --> 1000000000000403
        for prime in sieve(math.isqrt(n) + 1):
-           while True:
-               if n % prime:
-                   break
+           while not n % prime:
                yield prime
                n //= prime
                if n == 1: