Merge branch 'main' into docs/deprecated-removed

# Conflicts:
#	Doc/tools/extensions/pyspecific.py

.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

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/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/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``.
 

Doc/conf.py

@@ -18,11 +18,10 @@
 # ---------------------
 
 extensions = [
-    'asdl_highlight',
     'c_annotations',
     'escape4chm',
     'glossary_search',
-    'peg_highlight',
+    'lexers',
     'pyspecific',
     'sphinx.ext.coverage',
     'sphinx.ext.doctest',
@@ -83,7 +82,7 @@
 highlight_language = 'python3'
 
 # Minimum version of sphinx required
-needs_sphinx = '4.2'
+needs_sphinx = '6.2.1'
 
 # Create table of contents entries for domain objects (e.g. functions, classes,
 # attributes, etc.). Default is True.

Doc/faq/design.rst

@@ -70,7 +70,7 @@ operations. This means that as far as floating-point operations are concerned,
 Python behaves like many popular languages including C and Java.
 
 Many numbers that can be written easily in decimal notation cannot be expressed
-exactly in binary floating-point.  For example, after::
+exactly in binary floating point.  For example, after::
 
     >>> x = 1.2
 
@@ -87,7 +87,7 @@ which is exactly::
 The typical precision of 53 bits provides Python floats with 15--16
 decimal digits of accuracy.
 
-For a fuller explanation, please see the :ref:`floating point arithmetic
+For a fuller explanation, please see the :ref:`floating-point arithmetic
 <tut-fp-issues>` chapter in the Python tutorial.
 
 

Doc/faq/library.rst

@@ -718,12 +718,12 @@ is simple::
    import random
    random.random()
 
-This returns a random floating point number in the range [0, 1).
+This returns a random floating-point number in the range [0, 1).
 
 There are also many other specialized generators in this module, such as:
 
 * ``randrange(a, b)`` chooses an integer in the range [a, b).
-* ``uniform(a, b)`` chooses a floating point number in the range [a, b).
+* ``uniform(a, b)`` chooses a floating-point number in the range [a, b).
 * ``normalvariate(mean, sdev)`` samples the normal (Gaussian) distribution.
 
 Some higher-level functions operate on sequences directly, such as:

Doc/faq/programming.rst

@@ -869,7 +869,7 @@ How do I convert a string to a number?
 --------------------------------------
 
 For integers, use the built-in :func:`int` type constructor, e.g. ``int('144')
-== 144``.  Similarly, :func:`float` converts to floating-point,
+== 144``.  Similarly, :func:`float` converts to a floating-point number,
 e.g. ``float('144') == 144.0``.
 
 By default, these interpret the number as decimal, so that ``int('0144') ==

Doc/library/array.rst

@@ -9,7 +9,7 @@
 --------------
 
 This module defines an object type which can compactly represent an array of
-basic values: characters, integers, floating point numbers.  Arrays are sequence
+basic values: characters, integers, floating-point numbers.  Arrays are sequence
 types and behave very much like lists, except that the type of objects stored in
 them is constrained.  The type is specified at object creation time by using a
 :dfn:`type code`, which is a single character.  The following type codes are
@@ -263,7 +263,7 @@ The string representation is guaranteed to be able to be converted back to an
 array with the same type and value using :func:`eval`, so long as the
 :class:`~array.array` class has been imported using ``from array import array``.
 Variables ``inf`` and ``nan`` must also be defined if it contains
-corresponding floating point values.
+corresponding floating-point values.
 Examples::
 
    array('l')

Doc/library/colorsys.rst

@@ -14,7 +14,7 @@ The :mod:`colorsys` module defines bidirectional conversions of color values
 between colors expressed in the RGB (Red Green Blue) color space used in
 computer monitors and three other coordinate systems: YIQ, HLS (Hue Lightness
 Saturation) and HSV (Hue Saturation Value).  Coordinates in all of these color
-spaces are floating point values.  In the YIQ space, the Y coordinate is between
+spaces are floating-point values.  In the YIQ space, the Y coordinate is between
 0 and 1, but the I and Q coordinates can be positive or negative.  In all other
 spaces, the coordinates are all between 0 and 1.
 

Doc/library/configparser.rst

@@ -1183,7 +1183,7 @@ ConfigParser Objects
    .. method:: getfloat(section, option, *, raw=False, vars=None[, fallback])
 
       A convenience method which coerces the *option* in the specified *section*
-      to a floating point number.  See :meth:`get` for explanation of *raw*,
+      to a floating-point number.  See :meth:`get` for explanation of *raw*,
       *vars* and *fallback*.
 
 

Doc/library/decimal.rst

@@ -1,4 +1,4 @@
-:mod:`!decimal` --- Decimal fixed point and floating point arithmetic
+:mod:`!decimal` --- Decimal fixed-point and floating-point arithmetic
 =====================================================================
 
 .. module:: decimal
@@ -31,7 +31,7 @@
 --------------
 
 The :mod:`decimal` module provides support for fast correctly rounded
-decimal floating point arithmetic. It offers several advantages over the
+decimal floating-point arithmetic. It offers several advantages over the
 :class:`float` datatype:
 
 * Decimal "is based on a floating-point model which was designed with people
@@ -207,7 +207,7 @@ a decimal raises :class:`InvalidOperation`::
 .. versionchanged:: 3.3
 
 Decimals interact well with much of the rest of Python.  Here is a small decimal
-floating point flying circus:
+floating-point flying circus:
 
 .. doctest::
    :options: +NORMALIZE_WHITESPACE
@@ -373,7 +373,7 @@ Decimal objects
    digits, and an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))``
    returns ``Decimal('1.414')``.
 
-   If *value* is a :class:`float`, the binary floating point value is losslessly
+   If *value* is a :class:`float`, the binary floating-point value is losslessly
    converted to its exact decimal equivalent.  This conversion can often require
    53 or more digits of precision.  For example, ``Decimal(float('1.1'))``
    converts to
@@ -403,7 +403,7 @@ Decimal objects
       Underscores are allowed for grouping, as with integral and floating-point
       literals in code.
 
-   Decimal floating point objects share many properties with the other built-in
+   Decimal floating-point objects share many properties with the other built-in
    numeric types such as :class:`float` and :class:`int`.  All of the usual math
    operations and special methods apply.  Likewise, decimal objects can be
    copied, pickled, printed, used as dictionary keys, used as set elements,
@@ -445,7 +445,7 @@ Decimal objects
       Mixed-type comparisons between :class:`Decimal` instances and other
       numeric types are now fully supported.
 
-   In addition to the standard numeric properties, decimal floating point
+   In addition to the standard numeric properties, decimal floating-point
    objects also have a number of specialized methods:
 
 
@@ -1741,7 +1741,7 @@ The following table summarizes the hierarchy of signals::
 
 .. _decimal-notes:
 
-Floating Point Notes
+Floating-Point Notes
 --------------------
 
 
@@ -1754,7 +1754,7 @@ can still incur round-off error when non-zero digits exceed the fixed precision.
 
 The effects of round-off error can be amplified by the addition or subtraction
 of nearly offsetting quantities resulting in loss of significance.  Knuth
-provides two instructive examples where rounded floating point arithmetic with
+provides two instructive examples where rounded floating-point arithmetic with
 insufficient precision causes the breakdown of the associative and distributive
 properties of addition:
 
@@ -1844,7 +1844,7 @@ treated as equal and their sign is informational.
 In addition to the two signed zeros which are distinct yet equal, there are
 various representations of zero with differing precisions yet equivalent in
 value.  This takes a bit of getting used to.  For an eye accustomed to
-normalized floating point representations, it is not immediately obvious that
+normalized floating-point representations, it is not immediately obvious that
 the following calculation returns a value equal to zero:
 
    >>> 1 / Decimal('Infinity')
@@ -2171,7 +2171,7 @@ value unchanged:
 
 Q. Is there a way to convert a regular float to a :class:`Decimal`?
 
-A. Yes, any binary floating point number can be exactly expressed as a
+A. Yes, any binary floating-point number can be exactly expressed as a
 Decimal though an exact conversion may take more precision than intuition would
 suggest:
 
@@ -2225,7 +2225,7 @@ Q. Is the CPython implementation fast for large numbers?
 A. Yes.  In the CPython and PyPy3 implementations, the C/CFFI versions of
 the decimal module integrate the high speed `libmpdec
 <https://www.bytereef.org/mpdecimal/doc/libmpdec/index.html>`_ library for
-arbitrary precision correctly rounded decimal floating point arithmetic [#]_.
+arbitrary precision correctly rounded decimal floating-point arithmetic [#]_.
 ``libmpdec`` uses `Karatsuba multiplication
 <https://en.wikipedia.org/wiki/Karatsuba_algorithm>`_
 for medium-sized numbers and the `Number Theoretic Transform

Doc/library/dis.rst

@@ -1727,7 +1727,7 @@ iterations of the loop.
    | ``INTRINSIC_STOPITERATION_ERROR`` | Extracts the return value from a  |
    |                                   | ``StopIteration`` exception.      |
    +-----------------------------------+-----------------------------------+
-   | ``INTRINSIC_ASYNC_GEN_WRAP``      | Wraps an aync generator value     |
+   | ``INTRINSIC_ASYNC_GEN_WRAP``      | Wraps an async generator value    |
    +-----------------------------------+-----------------------------------+
    | ``INTRINSIC_UNARY_POSITIVE``      | Performs the unary ``+``          |
    |                                   | operation                         |

Doc/library/email.utils.rst

@@ -158,7 +158,7 @@ of the new API.
 
       Fri, 09 Nov 2001 01:08:47 -0000
 
-   Optional *timeval* if given is a floating point time value as accepted by
+   Optional *timeval* if given is a floating-point time value as accepted by
    :func:`time.gmtime` and :func:`time.localtime`, otherwise the current time is
    used.
 

Doc/library/exceptions.rst

@@ -412,8 +412,8 @@ The following exceptions are the exceptions that are usually raised.
    represented.  This cannot occur for integers (which would rather raise
    :exc:`MemoryError` than give up).  However, for historical reasons,
    OverflowError is sometimes raised for integers that are outside a required
-   range.   Because of the lack of standardization of floating point exception
-   handling in C, most floating point operations are not checked.
+   range.   Because of the lack of standardization of floating-point exception
+   handling in C, most floating-point operations are not checked.
 
 
 .. exception:: PythonFinalizationError

Doc/library/fractions.rst

@@ -17,25 +17,30 @@ The :mod:`fractions` module provides support for rational number arithmetic.
 A Fraction instance can be constructed from a pair of integers, from
 another rational number, or from a string.
 
+.. index:: single: as_integer_ratio()
+
 .. class:: Fraction(numerator=0, denominator=1)
-           Fraction(other_fraction)
-           Fraction(float)
-           Fraction(decimal)
+           Fraction(number)
            Fraction(string)
 
    The first version requires that *numerator* and *denominator* are instances
    of :class:`numbers.Rational` and returns a new :class:`Fraction` instance
    with value ``numerator/denominator``. If *denominator* is ``0``, it
-   raises a :exc:`ZeroDivisionError`. The second version requires that
-   *other_fraction* is an instance of :class:`numbers.Rational` and returns a
-   :class:`Fraction` instance with the same value.  The next two versions accept
-   either a :class:`float` or a :class:`decimal.Decimal` instance, and return a
-   :class:`Fraction` instance with exactly the same value.  Note that due to the
-   usual issues with binary floating-point (see :ref:`tut-fp-issues`), the
+   raises a :exc:`ZeroDivisionError`.
+
+   The second version requires that *number* is an instance of
+   :class:`numbers.Rational` or has the :meth:`!as_integer_ratio` method
+   (this includes :class:`float` and :class:`decimal.Decimal`).
+   It returns a :class:`Fraction` instance with exactly the same value.
+   Assumed, that the :meth:`!as_integer_ratio` method returns a pair
+   of coprime integers and last one is positive.
+   Note that due to the
+   usual issues with binary point (see :ref:`tut-fp-issues`), the
    argument to ``Fraction(1.1)`` is not exactly equal to 11/10, and so
    ``Fraction(1.1)`` does *not* return ``Fraction(11, 10)`` as one might expect.
    (But see the documentation for the :meth:`limit_denominator` method below.)
-   The last version of the constructor expects a string or unicode instance.
+
+   The last version of the constructor expects a string.
    The usual form for this instance is::
 
       [sign] numerator ['/' denominator]
@@ -110,6 +115,10 @@ another rational number, or from a string.
       Formatting of :class:`Fraction` instances without a presentation type
       now supports fill, alignment, sign handling, minimum width and grouping.
 
+   .. versionchanged:: 3.14
+      The :class:`Fraction` constructor now accepts any objects with the
+      :meth:`!as_integer_ratio` method.
+
    .. attribute:: numerator
 
       Numerator of the Fraction in lowest term.