Merge branch 'main' into gh-137238-slot_tp_getattr_hook

Author: colesbury

.github/CODEOWNERS

@@ -8,7 +8,7 @@
 .github/**                    @ezio-melotti @hugovk @AA-Turner
 
 # pre-commit
-.pre-commit-config.yaml       @hugovk @AlexWaygood
+.pre-commit-config.yaml       @hugovk
 .ruff.toml                    @hugovk @AlexWaygood @AA-Turner
 
 # Build system

.github/workflows/jit.yml

@@ -117,6 +117,10 @@ jobs:
           find /usr/local/bin -lname '*/Library/Frameworks/Python.framework/*' -delete
           brew install llvm@${{ matrix.llvm }}
           export SDKROOT="$(xcrun --show-sdk-path)"
+          # Set MACOSX_DEPLOYMENT_TARGET and -Werror=unguarded-availability to
+          # make sure we don't break downstream distributors (like uv):
+          export CFLAGS_JIT='-Werror=unguarded-availability'
+          export MACOSX_DEPLOYMENT_TARGET=10.15
           ./configure --enable-experimental-jit --enable-universalsdk --with-universal-archs=universal2 ${{ matrix.debug && '--with-pydebug' || '' }}
           make all --jobs 4
           ./python.exe -m test --multiprocess 0 --timeout 4500 --verbose2 --verbose3

Doc/c-api/complex.rst

@@ -43,24 +43,36 @@ pointers.  This is consistent throughout the API.
    Return the sum of two complex numbers, using the C :c:type:`Py_complex`
    representation.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 .. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
 
    Return the difference between two complex numbers, using the C
    :c:type:`Py_complex` representation.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 .. c:function:: Py_complex _Py_c_neg(Py_complex num)
 
    Return the negation of the complex number *num*, using the C
    :c:type:`Py_complex` representation.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 .. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
 
    Return the product of two complex numbers, using the C :c:type:`Py_complex`
    representation.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 .. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
 
@@ -70,6 +82,9 @@ pointers.  This is consistent throughout the API.
    If *divisor* is null, this method returns zero and sets
    :c:data:`errno` to :c:macro:`!EDOM`.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 .. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
 
@@ -81,6 +96,19 @@ pointers.  This is consistent throughout the API.
 
    Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
+
+.. c:function:: double _Py_c_abs(Py_complex num)
+
+   Return the absolute value of the complex number *num*.
+
+   Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
+
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 Complex Numbers as Python Objects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Doc/c-api/long.rst

@@ -372,6 +372,10 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    Set *\*value* to a signed C :c:expr:`int32_t` or :c:expr:`int64_t`
    representation of *obj*.
 
+   If *obj* is not an instance of :c:type:`PyLongObject`, first call its
+   :meth:`~object.__index__` method (if present) to convert it to a
+   :c:type:`PyLongObject`.
+
    If the *obj* value is out of range, raise an :exc:`OverflowError`.
 
    Set *\*value* and return ``0`` on success.

Doc/c-api/object.rst

@@ -197,7 +197,7 @@ Object Protocol
    in favour of using :c:func:`PyObject_DelAttr`, but there are currently no
    plans to remove it.
 
-   The function must not be called with ``NULL`` *v* and an an exception set.
+   The function must not be called with a ``NULL`` *v* and an exception set.
    This case can arise from forgetting ``NULL`` checks and would delete the
    attribute.
 
@@ -214,7 +214,7 @@ Object Protocol
    If *v* is ``NULL``, the attribute is deleted, but this feature is
    deprecated in favour of using :c:func:`PyObject_DelAttrString`.
 
-   The function must not be called with ``NULL`` *v* and an an exception set.
+   The function must not be called with a ``NULL`` *v* and an exception set.
    This case can arise from forgetting ``NULL`` checks and would delete the
    attribute.
 

Doc/library/calendar.rst

@@ -501,6 +501,14 @@ The :mod:`calendar` module exports the following data attributes:
        >>> list(calendar.month_name)
        ['', 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
 
+   .. caution::
+
+      In locales with alternative month names forms, the :data:`!month_name` sequence
+      may not be suitable when a month name stands by itself and not as part of a date.
+      For instance, in Greek and in many Slavic and Baltic languages, :data:`!month_name`
+      will produce the month in genitive case. Use :data:`standalone_month_name` for a form
+      suitable for standalone use.
+
 
 .. data:: month_abbr
 
@@ -512,6 +520,31 @@ The :mod:`calendar` module exports the following data attributes:
        >>> list(calendar.month_abbr)
        ['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
 
+   .. caution::
+
+      In locales with alternative month names forms, the :data:`!month_abbr` sequence
+      may not be suitable when a month name stands by itself and not as part of a date.
+      Use :data:`standalone_month_abbr` for a form suitable for standalone use.
+
+
+.. data:: standalone_month_name
+
+   A sequence that represents the months of the year in the current locale
+   in the standalone form if the locale provides one. Else it is equivalent
+   to :data:`month_name`.
+
+   .. versionadded:: next
+
+
+.. data:: standalone_month_abbr
+
+   A sequence that represents the abbreviated months of the year in the current
+   locale in the standalone form if the locale provides one. Else it is
+   equivalent to :data:`month_abbr`.
+
+   .. versionadded:: next
+
+
 .. data:: JANUARY
           FEBRUARY
           MARCH

Doc/library/ctypes.rst

@@ -700,14 +700,10 @@ compiler does it.  It is possible to override this behavior entirely by specifyi
 :attr:`~Structure._layout_` class attribute in the subclass definition; see
 the attribute documentation for details.
 
-It is possible to specify the maximum alignment for the fields by setting
-the :attr:`~Structure._pack_` class attribute to a positive integer.
-This matches what ``#pragma pack(n)`` does in MSVC.
-
-It is also possible to set a minimum alignment for how the subclass itself is packed in the
-same way ``#pragma align(n)`` works in MSVC.
-This can be achieved by specifying a :attr:`~Structure._align_` class attribute
-in the subclass definition.
+It is possible to specify the maximum alignment for the fields and/or for the
+structure itself by setting the class attributes :attr:`~Structure._pack_`
+and/or :attr:`~Structure._align_`, respectively.
+See the attribute documentation for details.
 
 :mod:`ctypes` uses the native byte order for Structures and Unions.  To build
 structures with non-native byte order, you can use one of the
@@ -2792,11 +2788,18 @@ fields, or any other data types containing pointer type fields.
    .. attribute:: _pack_
 
       An optional small integer that allows overriding the alignment of
-      structure fields in the instance.  :attr:`_pack_` must already be defined
-      when :attr:`_fields_` is assigned, otherwise it will have no effect.
-      Setting this attribute to 0 is the same as not setting it at all.
+      structure fields in the instance.
+
+      This is only implemented for the MSVC-compatible memory layout
+      (see :attr:`_layout_`).
 
-      This is only implemented for the MSVC-compatible memory layout.
+      Setting :attr:`!_pack_` to 0 is the same as not setting it at all.
+      Otherwise, the value must be a positive power of two.
+      The effect is equivalent to ``#pragma pack(N)`` in C, except
+      :mod:`ctypes` may allow larger *n* than what the compiler accepts.
+
+      :attr:`!_pack_` must already be defined
+      when :attr:`_fields_` is assigned, otherwise it will have no effect.
 
       .. deprecated-removed:: 3.14 3.19
 
@@ -2809,9 +2812,22 @@ fields, or any other data types containing pointer type fields.
 
    .. attribute:: _align_
 
-      An optional small integer that allows overriding the alignment of
+      An optional small integer that allows increasing the alignment of
       the structure when being packed or unpacked to/from memory.
-      Setting this attribute to 0 is the same as not setting it at all.
+
+      The value must not be negative.
+      The effect is equivalent to ``__attribute__((aligned(N)))`` on GCC
+      or ``#pragma align(N)`` on MSVC, except :mod:`ctypes` may allow
+      values that the compiler would reject.
+
+      :attr:`!_align_` can only *increase* a structure's alignment
+      requirements. Setting it to 0 or 1 has no effect.
+
+      Using values that are not powers of two is discouraged and may lead to
+      surprising behavior.
+
+      :attr:`!_align_` must already be defined
+      when :attr:`_fields_` is assigned, otherwise it will have no effect.
 
       .. versionadded:: 3.13
 

Doc/library/fractions.rst

@@ -14,8 +14,8 @@
 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.
+A Fraction instance can be constructed from a pair of rational numbers, from
+a single number, or from a string.
 
 .. index:: single: as_integer_ratio()
 
@@ -25,8 +25,8 @@ another rational number, or from a string.
 
    The first version requires that *numerator* and *denominator* are instances
    of :class:`numbers.Rational` and returns a new :class:`Fraction` instance
-   with value equal to ``numerator/denominator`` where the denominator is positive.
-   If *denominator* is ``0``, it raises a :exc:`ZeroDivisionError`.
+   with a value equal to ``numerator/denominator``.
+   If *denominator* is zero, it 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
@@ -125,7 +125,8 @@ another rational number, or from a string.
 
    .. attribute:: denominator
 
-      Denominator of the Fraction in lowest term.
+      Denominator of the Fraction in lowest terms.
+      Guaranteed to be positive.
 
 
    .. method:: as_integer_ratio()

Doc/library/heapq.rst

@@ -231,6 +231,42 @@ Heap elements can be tuples.  This is useful for assigning comparison values
     (1, 'write spec')
 
 
+Other Applications
+------------------
+
+`Medians <https://en.wikipedia.org/wiki/Median>`_ are a measure of
+central tendency for a set of numbers.  In distributions skewed by
+outliers, the median provides a more stable estimate than an average
+(arithmetic mean).  A running median is an `online algorithm
+<https://en.wikipedia.org/wiki/Online_algorithm>`_ that updates
+continuously as new data arrives.
+
+A running median can be efficiently implemented by balancing two heaps,
+a max-heap for values at or below the midpoint and a min-heap for values
+above the midpoint.  When the two heaps have the same size, the new
+median is the average of the tops of the two heaps; otherwise, the
+median is at the top of the larger heap::
+
+    def running_median(iterable):
+        "Yields the cumulative median of values seen so far."
+
+        lo = []  # max-heap
+        hi = []  # min-heap (same size as or one smaller than lo)
+
+        for x in iterable:
+            if len(lo) == len(hi):
+                heappush_max(lo, heappushpop(hi, x))
+                yield lo[0]
+            else:
+                heappush(hi, heappushpop_max(lo, x))
+                yield (lo[0] + hi[0]) / 2
+
+For example::
+
+    >>> list(running_median([5.0, 9.0, 4.0, 12.0, 8.0, 9.0]))
+    [5.0, 7.0, 5.0, 7.0, 8.0, 8.5]
+
+
 Priority Queue Implementation Notes
 -----------------------------------
 

Doc/library/numbers.rst

@@ -69,11 +69,11 @@ The numeric tower
 
    .. attribute:: numerator
 
-      Abstract.
+      Abstract.  The numerator of this rational number.
 
    .. attribute:: denominator
 
-      Abstract.
+      Abstract.  The denominator of this rational number.
 
 
 .. class:: Integral