Merge branch 'main' into pythongh-120973-fix-local-clear

Author: colesbury

.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

.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,44 @@
+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/patchlevel.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/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).
 
 

Doc/c-api/module.rst

@@ -342,7 +342,8 @@ The available slot types are:
    The *value* pointer of this slot must point to a function of the signature:
 
    .. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
-      :noindex:
+      :no-index-entry:
+      :no-contents-entry:
 
    The function receives a :py:class:`~importlib.machinery.ModuleSpec`
    instance, as defined in :PEP:`451`, and the module definition.
@@ -377,7 +378,8 @@ The available slot types are:
    The signature of the function is:
 
    .. c:function:: int exec_module(PyObject* module)
-      :noindex:
+      :no-index-entry:
+      :no-contents-entry:
 
    If multiple ``Py_mod_exec`` slots are specified, they are processed in the
    order they appear in the *m_slots* array.

Doc/c-api/number.rst

@@ -51,8 +51,8 @@ Number Protocol
 
    Return a reasonable approximation for the mathematical value of *o1* divided by
    *o2*, or ``NULL`` on failure.  The return value is "approximate" because binary
-   floating point numbers are approximate; it is not possible to represent all real
-   numbers in base two.  This function can return a floating point value when
+   floating-point numbers are approximate; it is not possible to represent all real
+   numbers in base two.  This function can return a floating-point value when
    passed two integers.  This is the equivalent of the Python expression ``o1 / o2``.
 
 
@@ -177,8 +177,8 @@ Number Protocol
 
    Return a reasonable approximation for the mathematical value of *o1* divided by
    *o2*, or ``NULL`` on failure.  The return value is "approximate" because binary
-   floating point numbers are approximate; it is not possible to represent all real
-   numbers in base two.  This function can return a floating point value when
+   floating-point numbers are approximate; it is not possible to represent all real
+   numbers in base two.  This function can return a floating-point value when
    passed two integers.  The operation is done *in-place* when *o1* supports it.
    This is the equivalent of the Python statement ``o1 /= o2``.