Merge branch 'main' into gh-132021

Author: ericvsmith

.github/workflows/build.yml

@@ -164,10 +164,12 @@ jobs:
           - false
           - true
         include:
-          - os: windows-latest # FIXME(diegorusso): change to os: windows-aarch64
+          # Forks don't have access to Windows on Arm runners. These jobs are skipped below:
+          - os: ${{ github.repository_owner == 'python' && 'windows-aarch64' || 'windows-latest' }}
             arch: arm64
             free-threading: false
-          - os: windows-latest # FIXME(diegorusso): change to os: windows-aarch64
+          # Forks don't have access to Windows on Arm runners. These jobs are skipped below:
+          - os: ${{ github.repository_owner == 'python' && 'windows-aarch64' || 'windows-latest' }}
             arch: arm64
             free-threading: true
           - os: windows-latest
@@ -187,12 +189,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        os:
+        - windows-latest
         arch:
         - x86
         - x64
-        - arm64
+        include:
+          # Forks don't have access to Windows on Arm runners. These jobs are skipped below:
+          - os: ${{ github.repository_owner == 'python' && 'windows-aarch64' || 'windows-latest' }}
+            arch: arm64
     uses: ./.github/workflows/reusable-windows-msi.yml
     with:
+      os: ${{ matrix.os }}
       arch: ${{ matrix.arch }}
 
   build-macos:

.github/workflows/jit.yml

@@ -74,7 +74,8 @@ jobs:
             runner: windows-latest
           - target: aarch64-pc-windows-msvc/msvc
             architecture: ARM64
-            runner: windows-latest
+            # Forks don't have access to Windows on Arm runners. These jobs are skipped below:
+            runner: ${{ github.repository_owner == 'python' && 'windows-aarch64' || 'windows-latest' }}
           - target: x86_64-apple-darwin/clang
             architecture: x86_64
             runner: macos-13
@@ -95,25 +96,19 @@ jobs:
         with:
           python-version: '3.11'
 
-      - name: Native Windows
-        if: runner.os == 'Windows' && matrix.architecture != 'ARM64'
+      - name: Windows
+        # Forks don't have access to Windows on Arm runners. Skip those:
+        if: runner.os == 'Windows' && (matrix.architecture != 'ARM64' || github.repository_owner == 'python')
         run: |
           choco install llvm --allow-downgrade --no-progress --version ${{ matrix.llvm }}.1.0
           ./PCbuild/build.bat --experimental-jit ${{ matrix.debug && '-d' || '' }} -p ${{ matrix.architecture }}
           ./PCbuild/rt.bat ${{ matrix.debug && '-d' || '' }} -p ${{ matrix.architecture }} -q --multiprocess 0 --timeout 4500 --verbose2 --verbose3
 
-      # No tests (yet):
-      - name: Emulated Windows
-        if: runner.os == 'Windows' && matrix.architecture == 'ARM64'
-        run: |
-          choco install llvm --allow-downgrade --no-progress --version ${{ matrix.llvm }}.1.0
-          ./PCbuild/build.bat --experimental-jit ${{ matrix.debug && '-d' || '' }} -p ${{ matrix.architecture }}
-
         # The `find` line is required as a result of https://github.com/actions/runner-images/issues/9966.
         # This is a bug in the macOS runner image where the pre-installed Python is installed in the same
         # directory as the Homebrew Python, which causes the build to fail for macos-13. This line removes
         # the symlink to the pre-installed Python so that the Homebrew Python is used instead.
-      - name: Native macOS
+      - name: macOS
         if: runner.os == 'macOS'
         run: |
           brew update
@@ -124,7 +119,7 @@ jobs:
           make all --jobs 4
           ./python.exe -m test --multiprocess 0 --timeout 4500 --verbose2 --verbose3
 
-      - name: Native Linux
+      - name: Linux
         if: runner.os == 'Linux'
         run: |
           sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)" ./llvm.sh ${{ matrix.llvm }}

.github/workflows/reusable-windows-msi.yml

@@ -3,6 +3,10 @@ name: Reusable Windows MSI
 on:
   workflow_call:
     inputs:
+      os:
+        description: OS to run on
+        required: true
+        type: string
       arch:
         description: CPU architecture
         required: true
@@ -17,7 +21,7 @@ env:
 jobs:
   build:
     name: installer for ${{ inputs.arch }}
-    runs-on: windows-latest
+    runs-on: ${{ inputs.os }}
     timeout-minutes: 60
     env:
       ARCH: ${{ inputs.arch }}
@@ -27,5 +31,7 @@ jobs:
       with:
         persist-credentials: false
     - name: Build CPython installer
+      # Forks don't have access to Windows on Arm runners. Skip those:
+      if: inputs.arch != 'arm64' || github.repository_owner == 'python'
       run: ./Tools/msi/build.bat --doc -"${ARCH}"
       shell: bash

.github/workflows/reusable-windows.yml

@@ -24,7 +24,7 @@ env:
 
 jobs:
   build:
-    name: ${{ inputs.arch == 'arm64' && 'build' || 'build and test' }} (${{ inputs.arch }})
+    name: Build and test (${{ inputs.arch }})
     runs-on: ${{ inputs.os }}
     timeout-minutes: 60
     env:
@@ -37,17 +37,21 @@ jobs:
       if: inputs.arch != 'Win32'
       run: echo "::add-matcher::.github/problem-matchers/msvc.json"
     - name: Build CPython
+      # Forks don't have access to Windows on Arm runners. Skip those:
+      if: inputs.arch != 'arm64' || github.repository_owner == 'python'
       run: >-
         .\\PCbuild\\build.bat
         -e -d -v
         -p "${ARCH}"
         ${{ fromJSON(inputs.free-threading) && '--disable-gil' || '' }}
       shell: bash
-    - name: Display build info  # FIXME(diegorusso): remove the `if`
-      if: inputs.arch != 'arm64'
+    - name: Display build info
+      # Forks don't have access to Windows on Arm runners. Skip those:
+      if: inputs.arch != 'arm64' || github.repository_owner == 'python'
       run: .\\python.bat -m test.pythoninfo
-    - name: Tests  # FIXME(diegorusso): remove the `if`
-      if: inputs.arch != 'arm64'
+    - name: Tests
+      # Forks don't have access to Windows on Arm runners. Skip those:
+      if: inputs.arch != 'arm64' || github.repository_owner == 'python'
       run: >-
         .\\PCbuild\\rt.bat
         -p "${ARCH}"

.github/workflows/tail-call.yml

@@ -45,7 +45,7 @@ jobs:
           - aarch64-unknown-linux-gnu/gcc
           - free-threading
         llvm:
-          - 19
+          - 20
         include:
 #          - target: i686-pc-windows-msvc/msvc
 #            architecture: Win32
@@ -83,9 +83,9 @@ jobs:
         if: runner.os == 'Windows' && matrix.architecture != 'ARM64'
         shell: cmd
         run: |
-          choco install llvm --allow-downgrade --no-progress --version ${{ matrix.llvm }}.1.5
+          choco install llvm --allow-downgrade --no-progress --version ${{ matrix.llvm }}.1.0
           set PlatformToolset=clangcl
-          set LLVMToolsVersion=${{ matrix.llvm }}.1.5
+          set LLVMToolsVersion=${{ matrix.llvm }}.1.0
           set LLVMInstallDir=C:\Program Files\LLVM
           call ./PCbuild/build.bat --tail-call-interp -d -p ${{ matrix.architecture }}
           call ./PCbuild/rt.bat -d -p ${{ matrix.architecture }} -q --multiprocess 0 --timeout 4500 --verbose2 --verbose3
@@ -95,26 +95,28 @@ jobs:
         if: runner.os == 'Windows' && matrix.architecture == 'ARM64'
         shell: cmd
         run: |
-          choco install llvm --allow-downgrade --no-progress --version ${{ matrix.llvm }}.1.5
+          choco install llvm --allow-downgrade --no-progress --version ${{ matrix.llvm }}.1.0
           set PlatformToolset=clangcl
-          set LLVMToolsVersion=${{ matrix.llvm }}.1.5
+          set LLVMToolsVersion=${{ matrix.llvm }}.1.0
           set LLVMInstallDir=C:\Program Files\LLVM
           ./PCbuild/build.bat --tail-call-interp -p ${{ matrix.architecture }}
 
         # The `find` line is required as a result of https://github.com/actions/runner-images/issues/9966.
         # This is a bug in the macOS runner image where the pre-installed Python is installed in the same
         # directory as the Homebrew Python, which causes the build to fail for macos-13. This line removes
         # the symlink to the pre-installed Python so that the Homebrew Python is used instead.
+        # Note: when a new LLVM is released, the homebrew installation directory changes, so the builds will fail.
+        # We either need to upgrade LLVM or change the directory being pointed to.
       - name: Native macOS (release)
         if: runner.os == 'macOS'
         run: |
           brew update
           find /usr/local/bin -lname '*/Library/Frameworks/Python.framework/*' -delete
           brew install llvm@${{ matrix.llvm }}
           export SDKROOT="$(xcrun --show-sdk-path)"
-          export PATH="/opt/homebrew/opt/llvm@${{ matrix.llvm }}/bin:$PATH"
-          export PATH="/usr/local/opt/llvm@${{ matrix.llvm }}/bin:$PATH"
-          CC=clang-19 ./configure --with-tail-call-interp
+          export PATH="/usr/local/opt/llvm/bin:$PATH"
+          export PATH="/opt/homebrew/opt/llvm/bin:$PATH"
+          CC=clang-20 ./configure --with-tail-call-interp
           make all --jobs 4
           ./python.exe -m test --multiprocess 0 --timeout 4500 --verbose2 --verbose3
 
@@ -123,7 +125,7 @@ jobs:
         run: |
           sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)" ./llvm.sh ${{ matrix.llvm }}
           export PATH="$(llvm-config-${{ matrix.llvm }} --bindir):$PATH"
-          CC=clang-19 ./configure --with-tail-call-interp --with-pydebug
+          CC=clang-20 ./configure --with-tail-call-interp --with-pydebug
           make all --jobs 4
           ./python -m test --multiprocess 0 --timeout 4500 --verbose2 --verbose3
 
@@ -132,7 +134,7 @@ jobs:
         run: |
           sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)" ./llvm.sh ${{ matrix.llvm }}
           export PATH="$(llvm-config-${{ matrix.llvm }} --bindir):$PATH"
-          CC=clang-19 ./configure --with-tail-call-interp --disable-gil
+          CC=clang-20 ./configure --with-tail-call-interp --disable-gil
           make all --jobs 4
           ./python -m test --multiprocess 0 --timeout 4500 --verbose2 --verbose3
 

.gitignore

@@ -38,6 +38,7 @@ tags
 TAGS
 .vs/
 .vscode/
+.cache/
 gmon.out
 .coverage
 .mypy_cache/

Doc/Makefile

@@ -204,6 +204,7 @@ dist-html:
 	find dist -name 'python-$(DISTVERSION)-docs-html*' -exec rm -rf {} \;
 	$(MAKE) html
 	cp -pPR build/html dist/python-$(DISTVERSION)-docs-html
+	rm -rf dist/python-$(DISTVERSION)-docs-html/_images/social_previews/
 	tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html
 	bzip2 -9 -k dist/python-$(DISTVERSION)-docs-html.tar
 	(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-html.zip python-$(DISTVERSION)-docs-html)

Doc/conf.py

@@ -624,11 +624,19 @@
 # Options for sphinxext-opengraph
 # -------------------------------
 
-ogp_site_url = 'https://docs.python.org/3/'
+ogp_canonical_url = 'https://docs.python.org/3/'
 ogp_site_name = 'Python documentation'
-ogp_image = '_static/og-image.png'
+ogp_social_cards = {  # Used when matplotlib is installed
+    'image': '_static/og-image.png',
+    'line_color': '#3776ab',
+}
 ogp_custom_meta_tags = [
-    '<meta property="og:image:width" content="200" />',
-    '<meta property="og:image:height" content="200" />',
     '<meta name="theme-color" content="#3776ab" />',
 ]
+if 'create-social-cards' not in tags:  # noqa: F821
+    # Define a static preview image when not creating social cards
+    ogp_image = '_static/og-image.png'
+    ogp_custom_meta_tags += [
+        '<meta property="og:image:width" content="200" />',
+        '<meta property="og:image:height" content="200" />',
+    ]

Doc/faq/programming.rst

@@ -1868,15 +1868,15 @@ object identity is assured.  Generally, there are three circumstances where
 identity is guaranteed:
 
 1) Assignments create new names but do not change object identity.  After the
-assignment ``new = old``, it is guaranteed that ``new is old``.
+   assignment ``new = old``, it is guaranteed that ``new is old``.
 
 2) Putting an object in a container that stores object references does not
-change object identity.  After the list assignment ``s[0] = x``, it is
-guaranteed that ``s[0] is x``.
+   change object identity.  After the list assignment ``s[0] = x``, it is
+   guaranteed that ``s[0] is x``.
 
 3) If an object is a singleton, it means that only one instance of that object
-can exist.  After the assignments ``a = None`` and ``b = None``, it is
-guaranteed that ``a is b`` because ``None`` is a singleton.
+   can exist.  After the assignments ``a = None`` and ``b = None``, it is
+   guaranteed that ``a is b`` because ``None`` is a singleton.
 
 In most other circumstances, identity tests are inadvisable and equality tests
 are preferred.  In particular, identity tests should not be used to check

Doc/library/annotationlib.rst

@@ -172,36 +172,38 @@ Classes
       :class:`~ForwardRef`. The string may not be exactly equivalent
       to the original source.
 
-   .. method:: evaluate(*, globals=None, locals=None, type_params=None, owner=None)
+   .. method:: evaluate(*, owner=None, globals=None, locals=None, type_params=None)
 
       Evaluate the forward reference, returning its value.
 
       This may throw an exception, such as :exc:`NameError`, if the forward
-      reference refers to names that do not exist. The arguments to this
+      reference refers to a name that cannot be resolved. The arguments to this
       method can be used to provide bindings for names that would otherwise
       be undefined.
 
+      The *owner* parameter provides the preferred mechanism for passing scope
+      information to this method. The owner of a :class:`~ForwardRef` is the
+      object that contains the annotation from which the :class:`~ForwardRef`
+      derives, such as a module object, type object, or function object.
+
+      The *globals*, *locals*, and *type_params* parameters provide a more precise
+      mechanism for influencing the names that are available when the :class:`~ForwardRef`
+      is evaluated. *globals* and *locals* are passed to :func:`eval`, representing
+      the global and local namespaces in which the name is evaluated.
+      The *type_params* parameter is relevant for objects created using the native
+      syntax for :ref:`generic classes <generic-classes>` and :ref:`functions <generic-functions>`.
+      It is a tuple of :ref:`type parameters <type-params>` that are in scope
+      while the forward reference is being evaluated. For example, if evaluating a
+      :class:`~ForwardRef` retrieved from an annotation found in the class namespace
+      of a generic class ``C``, *type_params* should be set to ``C.__type_params__``.
+
       :class:`~ForwardRef` instances returned by :func:`get_annotations`
       retain references to information about the scope they originated from,
       so calling this method with no further arguments may be sufficient to
       evaluate such objects. :class:`~ForwardRef` instances created by other
       means may not have any information about their scope, so passing
       arguments to this method may be necessary to evaluate them successfully.
 
-      *globals* and *locals* are passed to :func:`eval`, representing
-      the global and local namespaces in which the name is evaluated.
-      *type_params*, if given, must be a tuple of
-      :ref:`type parameters <type-params>` that are in scope while the forward
-      reference is being evaluated. *owner* is the object that owns the
-      annotation from which the forward reference derives, usually a function,
-      class, or module.
-
-      .. important::
-
-         Once a :class:`~ForwardRef` instance has been evaluated, it caches
-         the evaluated value, and future calls to :meth:`evaluate` will return
-         the cached value, regardless of the parameters passed in.
-
    .. versionadded:: 3.14