Merge branch 'main' into issue-151039

Author: sobolevn

Doc/c-api/long.rst

@@ -71,6 +71,12 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    on failure.
 
 
+.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long long`,
+   or ``NULL`` on failure.
+
+
 .. c:function:: PyObject* PyLong_FromInt32(int32_t value)
                 PyObject* PyLong_FromInt64(int64_t value)
 
@@ -81,12 +87,6 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.14
 
 
-.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
-
-   Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long long`,
-   or ``NULL`` on failure.
-
-
 .. c:function:: PyObject* PyLong_FromUInt32(uint32_t value)
                 PyObject* PyLong_FromUInt64(uint64_t value)
 

Doc/c-api/typeobj.rst

@@ -2975,13 +2975,13 @@ Buffer Object Structures
    steps:
 
    (1) Check if the request can be met. If not, raise :exc:`BufferError`,
-       set :c:expr:`view->obj` to ``NULL`` and return ``-1``.
+       set ``view->obj`` to ``NULL`` and return ``-1``.
 
    (2) Fill in the requested fields.
 
    (3) Increment an internal counter for the number of exports.
 
-   (4) Set :c:expr:`view->obj` to *exporter* and increment :c:expr:`view->obj`.
+   (4) Set ``view->obj`` to *exporter* and increment ``view->obj``.
 
    (5) Return ``0``.
 
@@ -3007,10 +3007,10 @@ Buffer Object Structures
    schemes can be used:
 
    * Re-export: Each member of the tree acts as the exporting object and
-     sets :c:expr:`view->obj` to a new reference to itself.
+     sets ``view->obj`` to a new reference to itself.
 
    * Redirect: The buffer request is redirected to the root object of the
-     tree. Here, :c:expr:`view->obj` will be a new reference to the root
+     tree. Here, ``view->obj`` will be a new reference to the root
      object.
 
    The individual fields of *view* are described in section
@@ -3064,7 +3064,7 @@ Buffer Object Structures
    *view* argument.
 
 
-   This function MUST NOT decrement :c:expr:`view->obj`, since that is
+   This function MUST NOT decrement ``view->obj``, since that is
    done automatically in :c:func:`PyBuffer_Release` (this scheme is
    useful for breaking reference cycles).
 

Doc/howto/functional.rst

@@ -1042,7 +1042,7 @@ first calculation. ::
     >>> functools.reduce(operator.concat, [])
     Traceback (most recent call last):
       ...
-    TypeError: reduce() of empty sequence with no initial value
+    TypeError: reduce() of empty iterable with no initial value
     >>> functools.reduce(operator.mul, [1, 2, 3], 1)
     6
     >>> functools.reduce(operator.mul, [], 1)

Doc/library/bisect.rst

@@ -200,7 +200,7 @@ example uses :py:func:`~bisect.bisect` to look up a letter grade for an exam sco
 based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is
 a 'B', and so on::
 
-   >>> def grade(score)
+   >>> def grade(score):
    ...     i = bisect([60, 70, 80, 90], score)
    ...     return "FDCBA"[i]
    ...

Doc/library/importlib.resources.rst

@@ -240,7 +240,6 @@ For all the following functions:
 
     .. versionchanged:: 3.13
         Multiple *path_names* are accepted.
-        *encoding* and *errors* must be given as keyword arguments.
 
 
 .. function:: is_resource(anchor, *path_names)

Doc/library/logging.handlers.rst

@@ -402,7 +402,8 @@ timed intervals.
    rollover interval.
 
    When computing the next rollover time for the first time (when the handler
-   is created), the last modification time of an existing log file, or else
+   is created), the creation time (if supported by the OS and file system)
+   or the last modification of an existing log file, or else
    the current time, is used to compute when the next rotation will occur.
 
    If the *utc* argument is true, times in UTC will be used; otherwise
@@ -449,6 +450,10 @@ timed intervals.
    .. versionchanged:: 3.9
       The *errors* parameter was added.
 
+   .. versionchanged:: next
+      Use the creation time instead of the last modification time, if supported by the OS and file system.
+
+
    .. method:: doRollover()
 
       Does a rollover, as described above.

Doc/library/math.rst

@@ -83,13 +83,20 @@ noted otherwise, all return values are floats.
 
 **Trigonometric functions**
 --------------------------------------------------------------------------------------------------
-:func:`acos(x) <acos>`                                Arc cosine of *x*
-:func:`asin(x) <asin>`                                Arc sine of *x*
-:func:`atan(x) <atan>`                                Arc tangent of *x*
-:func:`atan2(y, x) <atan2>`                           ``atan(y / x)``
-:func:`cos(x) <cos>`                                  Cosine of *x*
-:func:`sin(x) <sin>`                                  Sine of *x*
-:func:`tan(x) <tan>`                                  Tangent of *x*
+:func:`acos(x) <acos>`                                Arc cosine of *x*, in radians
+:func:`acospi(x) <acospi>`                            Arc cosine of *x*, in half-turns
+:func:`asin(x) <asin>`                                Arc sine of *x*, in radians
+:func:`asinpi(x) <asinpi>`                            Arc sine of *x*, in half-turns
+:func:`atan(x) <atan>`                                Arc tangent of *x*, in radians
+:func:`atanpi(x) <atanpi>`                            Arc tangent of *x*, in half-turns
+:func:`atan2(y, x) <atan2>`                           ``atan(y / x)``, in radians
+:func:`atan2pi(y, x) <atan2pi>`                       ``atan(y / x)``, in half-turns
+:func:`cos(x) <cos>`                                  Cosine of *x* radians
+:func:`cospi(x) <cospi>`                              Cosine of *x⋅π* radians
+:func:`sin(x) <sin>`                                  Sine of *x* radians
+:func:`sinpi(x) <sinpi>`                              Sine of *x⋅π* radians
+:func:`tan(x) <tan>`                                  Tangent of *x* radians
+:func:`tanpi(x) <tanpi>`                              Tangent of *x⋅π* radians
 
 **Hyperbolic functions**
 --------------------------------------------------------------------------------------------------
@@ -599,18 +606,42 @@ Trigonometric functions
    ``pi``.
 
 
+.. function:: acospi(x)
+
+   Return the arc cosine of *x*, in half-turns. The result is between ``0`` and
+   ``1``.
+
+   .. versionadded:: next
+
+
 .. function:: asin(x)
 
    Return the arc sine of *x*, in radians. The result is between ``-pi/2`` and
    ``pi/2``.
 
 
+.. function:: asinpi(x)
+
+   Return the arc sine of *x*, in half-turns. The result is between ``-0.5`` and
+   ``0.5``.
+
+   .. versionadded:: next
+
+
 .. function:: atan(x)
 
    Return the arc tangent of *x*, in radians. The result is between ``-pi/2`` and
    ``pi/2``.
 
 
+.. function:: atanpi(x)
+
+   Return the arc tangent of *x*, in half-turns. The result is between ``-0.5`` and
+   ``0.5``.
+
+   .. versionadded:: next
+
+
 .. function:: atan2(y, x)
 
    Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``.
@@ -621,21 +652,54 @@ Trigonometric functions
    -1)`` is ``-3*pi/4``.
 
 
+.. function:: atan2pi(y, x)
+
+   Return ``atanpi(y / x)``, in half-turns. The result is between ``-1`` and ``1``.
+   The vector in the plane from the origin to point ``(x, y)`` makes this angle
+   with the positive X axis. The point of :func:`atan2pi` is that the signs of both
+   inputs are known to it, so it can compute the correct quadrant for the angle.
+   For example, ``atanpi(1)`` and ``atan2pi(1, 1)`` are both ``0.25``, but
+   ``atan2pi(-1, -1)`` is ``-0.75``.
+
+   .. versionadded:: next
+
+
 .. function:: cos(x)
 
    Return the cosine of *x* radians.
 
 
+.. function:: cospi(x)
+
+   Return the cosine of *x* half-turns (*x⋅π* radians).
+
+   .. versionadded:: next
+
+
 .. function:: sin(x)
 
    Return the sine of *x* radians.
 
 
+.. function:: sinpi(x)
+
+   Return the sine of *x* half-turns (*x⋅π* radians).
+
+   .. versionadded:: next
+
+
 .. function:: tan(x)
 
    Return the tangent of *x* radians.
 
 
+.. function:: tanpi(x)
+
+   Return the tangent of *x* half-turns (*x⋅π* radians).
+
+   .. versionadded:: next
+
+
 Hyperbolic functions
 --------------------
 

Doc/library/operator.rst

@@ -110,7 +110,7 @@ The mathematical and bitwise operations are the most numerous:
 .. function:: and_(a, b)
               __and__(a, b)
 
-   Return the bitwise and of *a* and *b*.
+   Return ``a & b``.
 
 
 .. function:: floordiv(a, b)
@@ -134,13 +134,13 @@ The mathematical and bitwise operations are the most numerous:
               __inv__(obj)
               __invert__(obj)
 
-   Return the bitwise inverse of the number *obj*.  This is equivalent to ``~obj``.
+   Return ``~obj``.
 
 
 .. function:: lshift(a, b)
               __lshift__(a, b)
 
-   Return *a* shifted left by *b*.
+   Return ``a << b``.
 
 
 .. function:: mod(a, b)
@@ -152,7 +152,7 @@ The mathematical and bitwise operations are the most numerous:
 .. function:: mul(a, b)
               __mul__(a, b)
 
-   Return ``a * b``, for *a* and *b* numbers.
+   Return ``a * b``.
 
 
 .. function:: matmul(a, b)
@@ -172,25 +172,25 @@ The mathematical and bitwise operations are the most numerous:
 .. function:: or_(a, b)
               __or__(a, b)
 
-   Return the bitwise or of *a* and *b*.
+   Return ``a | b``.
 
 
 .. function:: pos(obj)
               __pos__(obj)
 
-   Return *obj* positive (``+obj``).
+   Return ``+obj``.
 
 
 .. function:: pow(a, b)
               __pow__(a, b)
 
-   Return ``a ** b``, for *a* and *b* numbers.
+   Return ``a ** b``.
 
 
 .. function:: rshift(a, b)
               __rshift__(a, b)
 
-   Return *a* shifted right by *b*.
+   Return ``a >> b``.
 
 
 .. function:: sub(a, b)
@@ -209,7 +209,7 @@ The mathematical and bitwise operations are the most numerous:
 .. function:: xor(a, b)
               __xor__(a, b)
 
-   Return the bitwise exclusive or of *a* and *b*.
+   Return ``a ^ b``.
 
 
 Operations which work with sequences (some of them with mappings too) include:
@@ -403,13 +403,18 @@ Python syntax and the functions in the :mod:`!operator` module.
 +-----------------------+-------------------------+---------------------------------------+
 | Division              | ``a // b``              | ``floordiv(a, b)``                    |
 +-----------------------+-------------------------+---------------------------------------+
-| Bitwise And           | ``a & b``               | ``and_(a, b)``                        |
+| Bitwise And, or       | ``a & b``               | ``and_(a, b)``                        |
+| Intersection          |                         |                                       |
 +-----------------------+-------------------------+---------------------------------------+
-| Bitwise Exclusive Or  | ``a ^ b``               | ``xor(a, b)``                         |
+| Bitwise Exclusive Or, | ``a ^ b``               | ``xor(a, b)``                         |
+| or Symmetric          |                         |                                       |
+| Difference            |                         |                                       |
 +-----------------------+-------------------------+---------------------------------------+
-| Bitwise Inversion     | ``~ a``                 | ``invert(a)``                         |
+| Bitwise Inversion, or | ``~ a``                 | ``invert(a)``                         |
+| Complement            |                         |                                       |
 +-----------------------+-------------------------+---------------------------------------+
-| Bitwise Or            | ``a | b``               | ``or_(a, b)``                         |
+| Bitwise Or, or        | ``a | b``               | ``or_(a, b)``                         |
+| Union                 |                         |                                       |
 +-----------------------+-------------------------+---------------------------------------+
 | Exponentiation        | ``a ** b``              | ``pow(a, b)``                         |
 +-----------------------+-------------------------+---------------------------------------+