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

.devcontainer/Dockerfile

@@ -2,7 +2,7 @@ FROM docker.io/library/fedora:40
 
 ENV CC=clang
 
-ENV WASI_SDK_VERSION=21
+ENV WASI_SDK_VERSION=22
 ENV WASI_SDK_PATH=/opt/wasi-sdk
 
 ENV WASMTIME_HOME=/opt/wasmtime

.github/workflows/build.yml

@@ -27,11 +27,31 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     outputs:
+      # Some of the referenced steps set outputs conditionally and there may be
+      # cases when referencing them evaluates to empty strings. It is nice to
+      # work with proper booleans so they have to be evaluated through JSON
+      # conversion in the expressions. However, empty strings used like that
+      # may trigger all sorts of undefined and hard-to-debug behaviors in
+      # GitHub Actions CI/CD. To help with this, all of the outputs set here
+      # that are meant to be used as boolean flags (and not arbitrary strings),
+      # MUST have fallbacks with default values set. A common pattern would be
+      # to add ` || false` to all such expressions here, in the output
+      # definitions. They can then later be safely used through the following
+      # idiom in job conditionals and other expressions. Here's some examples:
+      #
+      #   if: fromJSON(needs.check_source.outputs.run-docs)
+      #
+      #   ${{
+      #        fromJSON(needs.check_source.outputs.run_tests)
+      #        && 'truthy-branch'
+      #        || 'falsy-branch'
+      #   }}
+      #
       run-docs: ${{ steps.docs-changes.outputs.run-docs || false }}
-      run_tests: ${{ steps.check.outputs.run_tests }}
-      run_hypothesis: ${{ steps.check.outputs.run_hypothesis }}
-      run_cifuzz: ${{ steps.check.outputs.run_cifuzz }}
-      config_hash: ${{ steps.config_hash.outputs.hash }}
+      run_tests: ${{ steps.check.outputs.run_tests || false }}
+      run_hypothesis: ${{ steps.check.outputs.run_hypothesis || false }}
+      run_cifuzz: ${{ steps.check.outputs.run_cifuzz || false }}
+      config_hash: ${{ steps.config_hash.outputs.hash }}  # str
     steps:
       - uses: actions/checkout@v4
       - name: Check for source changes
@@ -222,31 +242,20 @@ jobs:
       os-matrix: '["ghcr.io/cirruslabs/macos-runner:sonoma", "macos-14"]'
 
   build_ubuntu:
-    name: 'Ubuntu'
-    needs: check_source
-    if: needs.check_source.outputs.run_tests == 'true'
-    uses: ./.github/workflows/reusable-ubuntu.yml
-    with:
-      config_hash: ${{ needs.check_source.outputs.config_hash }}
-      options: |
-        ../cpython-ro-srcdir/configure \
-          --config-cache \
-          --with-pydebug \
-          --with-openssl=$OPENSSL_DIR
-
-  build_ubuntu_free_threading:
-    name: 'Ubuntu (free-threading)'
+    name: >-
+      Ubuntu
+      ${{ fromJSON(matrix.free-threading) && '(free-threading)' || '' }}
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true'
+    strategy:
+      matrix:
+        free-threading:
+        - false
+        - true
     uses: ./.github/workflows/reusable-ubuntu.yml
     with:
       config_hash: ${{ needs.check_source.outputs.config_hash }}
-      options: |
-        ../cpython-ro-srcdir/configure \
-          --config-cache \
-          --with-pydebug \
-          --with-openssl=$OPENSSL_DIR \
-          --disable-gil
+      free-threading: ${{ matrix.free-threading }}
 
   build_ubuntu_ssltests:
     name: 'Ubuntu SSL tests with OpenSSL'
@@ -558,7 +567,6 @@ jobs:
     - build_macos
     - build_macos_free_threading
     - build_ubuntu
-    - build_ubuntu_free_threading
     - build_ubuntu_ssltests
     - build_wasi
     - build_windows
@@ -593,7 +601,6 @@ jobs:
             build_macos,
             build_macos_free_threading,
             build_ubuntu,
-            build_ubuntu_free_threading,
             build_ubuntu_ssltests,
             build_wasi,
             build_windows,

.github/workflows/reusable-tsan.yml

@@ -36,11 +36,11 @@ jobs:
         # Install clang-18
         wget https://apt.llvm.org/llvm.sh
         chmod +x llvm.sh
-        sudo ./llvm.sh 18
-        sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-18 100
-        sudo update-alternatives --set clang /usr/bin/clang-18
-        sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-18 100
-        sudo update-alternatives --set clang++ /usr/bin/clang++-18
+        sudo ./llvm.sh 17  # gh-121946: llvm-18 package is temporarily broken
+        sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-17 100
+        sudo update-alternatives --set clang /usr/bin/clang-17
+        sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-17 100
+        sudo update-alternatives --set clang++ /usr/bin/clang++-17
         # Reduce ASLR to avoid TSAN crashing
         sudo sysctl -w vm.mmap_rnd_bits=28
     - name: TSAN Option Setup

.github/workflows/reusable-ubuntu.yml

@@ -4,9 +4,11 @@ on:
       config_hash:
         required: true
         type: string
-      options:
-        required: true
-        type: string
+      free-threading:
+        description: Whether to use free-threaded mode
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build_ubuntu_reusable:
@@ -63,7 +65,12 @@ jobs:
         key: ${{ github.job }}-${{ runner.os }}-${{ env.IMAGE_VERSION }}-${{ inputs.config_hash }}
     - name: Configure CPython out-of-tree
       working-directory: ${{ env.CPYTHON_BUILDDIR }}
-      run: ${{ inputs.options }}
+      run: >-
+        ../cpython-ro-srcdir/configure
+        --config-cache
+        --with-pydebug
+        --with-openssl=$OPENSSL_DIR
+        ${{ fromJSON(inputs.free-threading) && '--disable-gil' || '' }}
     - name: Build CPython out-of-tree
       working-directory: ${{ env.CPYTHON_BUILDDIR }}
       run: make -j4

.github/workflows/reusable-wasi.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-22.04
     env:
       WASMTIME_VERSION: 22.0.0
-      WASI_SDK_VERSION: 21
+      WASI_SDK_VERSION: 22
       WASI_SDK_PATH: /opt/wasi-sdk
       CROSS_BUILD_PYTHON: cross-build/build
       CROSS_BUILD_WASI: cross-build/wasm32-wasi

.github/workflows/reusable-windows.yml

@@ -6,7 +6,7 @@ on:
         required: true
         type: string
       free-threading:
-        description: Whether to use no-GIL mode
+        description: Whether to compile CPython in free-threading mode
         required: false
         type: boolean
         default: false

.pre-commit-config.yaml

@@ -3,13 +3,21 @@ repos:
     rev: v0.3.4
     hooks:
       - id: ruff
-        name: Run Ruff on Lib/test/
+        name: Run Ruff (lint) on Doc/
+        args: [--exit-non-zero-on-fix]
+        files: ^Doc/
+      - id: ruff
+        name: Run Ruff (lint) on Lib/test/
         args: [--exit-non-zero-on-fix]
         files: ^Lib/test/
       - id: ruff
-        name: Run Ruff on Argument Clinic
+        name: Run Ruff (lint) on Argument Clinic
         args: [--exit-non-zero-on-fix, --config=Tools/clinic/.ruff.toml]
         files: ^Tools/clinic/|Lib/test/test_clinic.py
+      - id: ruff-format
+        name: Run Ruff (format) on Doc/
+        args: [--check]
+        files: ^Doc/
 
   - repo: https://github.com/psf/black-pre-commit-mirror
     rev: 24.4.2

Doc/.ruff.toml

@@ -0,0 +1,43 @@
+target-version = "py312"  # Align with the version in oldest_supported_sphinx
+fix = true
+output-format = "full"
+line-length = 79
+extend-exclude = [
+    "includes/*",
+    # Temporary exclusions:
+    "tools/extensions/escape4chm.py",
+    "tools/extensions/pyspecific.py",
+]
+
+[lint]
+preview = true
+select = [
+    "C4",    # flake8-comprehensions
+    "B",     # flake8-bugbear
+    "E",     # pycodestyle
+    "F",     # pyflakes
+    "FA",    # flake8-future-annotations
+    "FLY",   # flynt
+    "FURB",  # refurb
+    "G",     # flake8-logging-format
+    "I",     # isort
+    "LOG",   # flake8-logging
+    "N",     # pep8-naming
+    "PERF",  # perflint
+    "PGH",   # pygrep-hooks
+    "PT",    # flake8-pytest-style
+    "TCH",   # flake8-type-checking
+    "UP",    # pyupgrade
+    "W",     # pycodestyle
+]
+ignore = [
+    "E501",  # Ignore line length errors (we use auto-formatting)
+]
+
+[format]
+preview = true
+quote-style = "preserve"
+docstring-code-format = true
+exclude = [
+    "tools/extensions/lexers/*",
+]

Doc/c-api/arg.rst

@@ -280,10 +280,10 @@ Numbers
    length 1, to a C :c:expr:`int`.
 
 ``f`` (:class:`float`) [float]
-   Convert a Python floating point number to a C :c:expr:`float`.
+   Convert a Python floating-point number to a C :c:expr:`float`.
 
 ``d`` (:class:`float`) [double]
-   Convert a Python floating point number to a C :c:expr:`double`.
+   Convert a Python floating-point number to a C :c:expr:`double`.
 
 ``D`` (:class:`complex`) [Py_complex]
    Convert a Python complex number to a C :c:type:`Py_complex` structure.
@@ -642,10 +642,10 @@ Building values
       object of length 1.
 
    ``d`` (:class:`float`) [double]
-      Convert a C :c:expr:`double` to a Python floating point number.
+      Convert a C :c:expr:`double` to a Python floating-point number.
 
    ``f`` (:class:`float`) [float]
-      Convert a C :c:expr:`float` to a Python floating point number.
+      Convert a C :c:expr:`float` to a Python floating-point number.
 
    ``D`` (:class:`complex`) [Py_complex \*]
       Convert a C :c:type:`Py_complex` structure to a Python complex number.

Doc/c-api/complex.rst

@@ -25,12 +25,16 @@ pointers.  This is consistent throughout the API.
 
    The C structure which corresponds to the value portion of a Python complex
    number object.  Most of the functions for dealing with complex number objects
-   use structures of this type as input or output values, as appropriate.  It is
-   defined as::
+   use structures of this type as input or output values, as appropriate.
+
+   .. c:member:: double real
+                 double imag
+
+   The structure is defined as::
 
       typedef struct {
-         double real;
-         double imag;
+          double real;
+          double imag;
       } Py_complex;
 
 
@@ -106,11 +110,13 @@ Complex Numbers as Python Objects
 .. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
 
    Create a new Python complex number object from a C :c:type:`Py_complex` value.
+   Return ``NULL`` with an exception set on error.
 
 
 .. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
 
    Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
+   Return ``NULL`` with an exception set on error.
 
 
 .. c:function:: double PyComplex_RealAsDouble(PyObject *op)
@@ -121,7 +127,9 @@ Complex Numbers as Python Objects
    :meth:`~object.__complex__` method, this method will first be called to
    convert *op* to a Python complex number object.  If :meth:`!__complex__` is
    not defined then it falls back to call :c:func:`PyFloat_AsDouble` and
-   returns its result.  Upon failure, this method returns ``-1.0``, so one
+   returns its result.
+
+   Upon failure, this method returns ``-1.0`` with an exception set, so one
    should call :c:func:`PyErr_Occurred` to check for errors.
 
    .. versionchanged:: 3.13
@@ -135,8 +143,10 @@ Complex Numbers as Python Objects
    :meth:`~object.__complex__` method, this method will first be called to
    convert *op* to a Python complex number object.  If :meth:`!__complex__` is
    not defined then it falls back to call :c:func:`PyFloat_AsDouble` and
-   returns ``0.0`` on success.  Upon failure, this method returns ``-1.0``, so
-   one should call :c:func:`PyErr_Occurred` to check for errors.
+   returns ``0.0`` on success.
+
+   Upon failure, this method returns ``-1.0`` with an exception set, so one
+   should call :c:func:`PyErr_Occurred` to check for errors.
 
    .. versionchanged:: 3.13
       Use :meth:`~object.__complex__` if available.
@@ -149,8 +159,11 @@ Complex Numbers as Python Objects
    method, this method will first be called to convert *op* to a Python complex
    number object.  If :meth:`!__complex__` is not defined then it falls back to
    :meth:`~object.__float__`.  If :meth:`!__float__` is not defined then it falls back
-   to :meth:`~object.__index__`.  Upon failure, this method returns ``-1.0`` as a real
-   value.
+   to :meth:`~object.__index__`.
+
+   Upon failure, this method returns :c:type:`Py_complex`
+   with :c:member:`~Py_complex.real` set to ``-1.0`` and with an exception set, so one
+   should call :c:func:`PyErr_Occurred` to check for errors.
 
    .. versionchanged:: 3.8
       Use :meth:`~object.__index__` if available.

Doc/c-api/float.rst

@@ -2,20 +2,20 @@
 
 .. _floatobjects:
 
-Floating Point Objects
+Floating-Point Objects
 ======================
 
-.. index:: pair: object; floating point
+.. index:: pair: object; floating-point
 
 
 .. c:type:: PyFloatObject
 
-   This subtype of :c:type:`PyObject` represents a Python floating point object.
+   This subtype of :c:type:`PyObject` represents a Python floating-point object.
 
 
 .. c:var:: PyTypeObject PyFloat_Type
 
-   This instance of :c:type:`PyTypeObject` represents the Python floating point
+   This instance of :c:type:`PyTypeObject` represents the Python floating-point
    type.  This is the same object as :class:`float` in the Python layer.
 
 
@@ -45,7 +45,7 @@ Floating Point Objects
 .. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
 
    Return a C :c:expr:`double` representation of the contents of *pyfloat*.  If
-   *pyfloat* is not a Python floating point object but has a :meth:`~object.__float__`
+   *pyfloat* is not a Python floating-point object but has a :meth:`~object.__float__`
    method, this method will first be called to convert *pyfloat* into a float.
    If :meth:`!__float__` is not defined then it falls back to :meth:`~object.__index__`.
    This method returns ``-1.0`` upon failure, so one should call

Doc/c-api/init_config.rst

@@ -509,7 +509,7 @@ PyConfig
       The :c:func:`PyConfig_Read` function only parses
       :c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
       is set to ``2`` after arguments are parsed. Since Python arguments are
-      strippped from :c:member:`PyConfig.argv`, parsing arguments twice would
+      stripped from :c:member:`PyConfig.argv`, parsing arguments twice would
       parse the application options as Python options.
 
       :ref:`Preinitialize Python <c-preinit>` if needed.
@@ -1041,7 +1041,7 @@ PyConfig
       The :c:func:`PyConfig_Read` function only parses
       :c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
       is set to ``2`` after arguments are parsed. Since Python arguments are
-      strippped from :c:member:`PyConfig.argv`, parsing arguments twice would
+      stripped from :c:member:`PyConfig.argv`, parsing arguments twice would
       parse the application options as Python options.
 
       Default: ``1`` in Python mode, ``0`` in isolated mode.

Doc/c-api/marshal.rst

@@ -15,7 +15,7 @@ Numeric values are stored with the least significant byte first.
 
 The module supports two versions of the data format: version 0 is the
 historical version, version 1 shares interned strings in the file, and upon
-unmarshalling.  Version 2 uses a binary format for floating point numbers.
+unmarshalling.  Version 2 uses a binary format for floating-point numbers.
 ``Py_MARSHAL_VERSION`` indicates the current file format (currently 2).