Merge branch 'main' into fix-issue-116180

Author: NGRsoftlab

.github/workflows/stale.yml

@@ -2,7 +2,7 @@ name: Mark stale pull requests
 
 on:
   schedule:
-  - cron: "0 0 * * *"
+  - cron: "0 */12 * * *"
 
 permissions:
   pull-requests: write

Doc/faq/design.rst

@@ -259,9 +259,11 @@ is evaluated in all cases.
 Why isn't there a switch or case statement in Python?
 -----------------------------------------------------
 
-You can do this easily enough with a sequence of ``if... elif... elif... else``.
-For literal values, or constants within a namespace, you can also use a
-``match ... case`` statement.
+In general, structured switch statements execute one block of code
+when an expression has a particular value or set of values.
+Since Python 3.10 one can easily match literal values, or constants
+within a namespace, with a ``match ... case`` statement.
+An older alternative is a sequence of ``if... elif... elif... else``.
 
 For cases where you need to choose from a very large number of possibilities,
 you can create a dictionary mapping case values to functions to call.  For
@@ -290,6 +292,9 @@ It's suggested that you use a prefix for the method names, such as ``visit_`` in
 this example.  Without such a prefix, if values are coming from an untrusted
 source, an attacker would be able to call any method on your object.
 
+Imitating switch with fallthrough, as with C's switch-case-default,
+is possible, much harder, and less needed.
+
 
 Can't you emulate threads in the interpreter instead of relying on an OS-specific thread implementation?
 --------------------------------------------------------------------------------------------------------

Doc/faq/extending.rst

@@ -50,7 +50,7 @@ to learn Python's C API.
 If you need to interface to some C or C++ library for which no Python extension
 currently exists, you can try wrapping the library's data types and functions
 with a tool such as `SWIG <https://www.swig.org>`_.  `SIP
-<https://riverbankcomputing.com/software/sip/intro>`__, `CXX
+<https://github.com/Python-SIP/sip>`__, `CXX
 <https://cxx.sourceforge.net/>`_ `Boost
 <https://www.boost.org/libs/python/doc/index.html>`_, or `Weave
 <https://github.com/scipy/weave>`_ are also

Doc/glossary.rst

@@ -841,10 +841,11 @@ Glossary
       Some named tuples are built-in types (such as the above examples).
       Alternatively, a named tuple can be created from a regular class
       definition that inherits from :class:`tuple` and that defines named
-      fields.  Such a class can be written by hand or it can be created with
-      the factory function :func:`collections.namedtuple`.  The latter
-      technique also adds some extra methods that may not be found in
-      hand-written or built-in named tuples.
+      fields.  Such a class can be written by hand, or it can be created by
+      inheriting :class:`typing.NamedTuple`, or with the factory function
+      :func:`collections.namedtuple`.  The latter techniques also add some
+      extra methods that may not be found in hand-written or built-in named
+      tuples.
 
    namespace
       The place where a variable is stored.  Namespaces are implemented as

Doc/library/itertools.rst

@@ -902,18 +902,19 @@ which incur interpreter overhead.
        # iter_index('AABCADEAF', 'A') --> 0 1 4 7
        seq_index = getattr(iterable, 'index', None)
        if seq_index is None:
-           # Slow path for general iterables
+           # Path for general iterables
            it = islice(iterable, start, stop)
            for i, element in enumerate(it, start):
                if element is value or element == value:
                    yield i
        else:
-           # Fast path for sequences
+           # Path for sequences with an index() method
            stop = len(iterable) if stop is None else stop
-           i = start - 1
+           i = start
            try:
                while True:
-                   yield (i := seq_index(value, i+1, stop))
+                   yield (i := seq_index(value, i, stop))
+                   i += 1
            except ValueError:
                pass
 
@@ -931,31 +932,25 @@ which incur interpreter overhead.
        # grouper('ABCDEFG', 3, fillvalue='x') --> ABC DEF Gxx
        # grouper('ABCDEFG', 3, incomplete='strict') --> ABC DEF ValueError
        # grouper('ABCDEFG', 3, incomplete='ignore') --> ABC DEF
-       args = [iter(iterable)] * n
+       iterators = [iter(iterable)] * n
        match incomplete:
            case 'fill':
-               return zip_longest(*args, fillvalue=fillvalue)
+               return zip_longest(*iterators, fillvalue=fillvalue)
            case 'strict':
-               return zip(*args, strict=True)
+               return zip(*iterators, strict=True)
            case 'ignore':
-               return zip(*args)
+               return zip(*iterators)
            case _:
                raise ValueError('Expected fill, strict, or ignore')
 
    def roundrobin(*iterables):
        "Visit input iterables in a cycle until each is exhausted."
        # roundrobin('ABC', 'D', 'EF') --> A D E B F C
-       # Recipe credited to George Sakkis
-       num_active = len(iterables)
-       nexts = cycle(iter(it).__next__ for it in iterables)
-       while num_active:
-           try:
-               for next in nexts:
-                   yield next()
-           except StopIteration:
-               # Remove the iterator we just exhausted from the cycle.
-               num_active -= 1
-               nexts = cycle(islice(nexts, num_active))
+       # Algorithm credited to George Sakkis
+       iterators = map(iter, iterables)
+       for num_active in range(len(iterables), 0, -1):
+           iterators = cycle(islice(iterators, num_active))
+           yield from map(next, iterators)
 
    def partition(predicate, iterable):
        """Partition entries into false entries and true entries.
@@ -996,10 +991,10 @@ The following recipes have a more mathematical flavor:
        s = list(iterable)
        return chain.from_iterable(combinations(s, r) for r in range(len(s)+1))
 
-   def sum_of_squares(it):
+   def sum_of_squares(iterable):
        "Add up the squares of the input values."
-       # sum_of_squares([10, 20, 30]) -> 1400
-       return math.sumprod(*tee(it))
+       # sum_of_squares([10, 20, 30]) --> 1400
+       return math.sumprod(*tee(iterable))
 
    def reshape(matrix, cols):
        "Reshape a 2-D matrix to have a given number of columns."
@@ -1019,17 +1014,16 @@ The following recipes have a more mathematical flavor:
 
    def convolve(signal, kernel):
        """Discrete linear convolution of two iterables.
+       Equivalent to polynomial multiplication.
 
-       The kernel is fully consumed before the calculations begin.
-       The signal is consumed lazily and can be infinite.
-
-       Convolutions are mathematically commutative.
-       If the signal and kernel are swapped,
-       the output will be the same.
+       Convolutions are mathematically commutative; however, the inputs are
+       evaluated differently.  The signal is consumed lazily and can be
+       infinite. The kernel is fully consumed before the calculations begin.
 
        Article:  https://betterexplained.com/articles/intuitive-convolution/
        Video:    https://www.youtube.com/watch?v=KuXjwB4LzSA
        """
+       # convolve([1, -1, -20], [1, -3]) --> 1 -4 -17 60
        # convolve(data, [0.25, 0.25, 0.25, 0.25]) --> Moving average (blur)
        # convolve(data, [1/2, 0, -1/2]) --> 1st derivative estimate
        # convolve(data, [1, -2, 1]) --> 2nd derivative estimate
@@ -1067,7 +1061,7 @@ The following recipes have a more mathematical flavor:
           f(x)  =  x³ -4x² -17x + 60
           f'(x) = 3x² -8x  -17
        """
-       # polynomial_derivative([1, -4, -17, 60]) -> [3, -8, -17]
+       # polynomial_derivative([1, -4, -17, 60]) --> [3, -8, -17]
        n = len(coefficients)
        powers = reversed(range(1, n))
        return list(map(operator.mul, coefficients, powers))
@@ -1169,6 +1163,12 @@ The following recipes have a more mathematical flavor:
 
     >>> take(10, count())
     [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+    >>> # Verify that the input is consumed lazily
+    >>> it = iter('abcdef')
+    >>> take(3, it)
+    ['a', 'b', 'c']
+    >>> list(it)
+    ['d', 'e', 'f']
 
     >>> list(prepend(1, [2, 3, 4]))
     [1, 2, 3, 4]
@@ -1181,25 +1181,45 @@ The following recipes have a more mathematical flavor:
 
     >>> list(tail(3, 'ABCDEFG'))
     ['E', 'F', 'G']
+    >>> # Verify the input is consumed greedily
+    >>> input_iterator = iter('ABCDEFG')
+    >>> output_iterator = tail(3, input_iterator)
+    >>> list(input_iterator)
+    []
 
     >>> it = iter(range(10))
     >>> consume(it, 3)
+    >>> # Verify the input is consumed lazily
     >>> next(it)
     3
+    >>> # Verify the input is consumed completely
     >>> consume(it)
     >>> next(it, 'Done')
     'Done'
 
     >>> nth('abcde', 3)
     'd'
-
     >>> nth('abcde', 9) is None
     True
+    >>> # Verify that the input is consumed lazily
+    >>> it = iter('abcde')
+    >>> nth(it, 2)
+    'c'
+    >>> list(it)
+    ['d', 'e']
 
     >>> [all_equal(s) for s in ('', 'A', 'AAAA', 'AAAB', 'AAABA')]
     [True, True, True, False, False]
     >>> [all_equal(s, key=str.casefold) for s in ('', 'A', 'AaAa', 'AAAB', 'AAABA')]
     [True, True, True, False, False]
+    >>> # Verify that the input is consumed lazily and that only
+    >>> # one element of a second equivalence class is used to disprove
+    >>> # the assertion that all elements are equal.
+    >>> it = iter('aaabbbccc')
+    >>> all_equal(it)
+    False
+    >>> ''.join(it)
+    'bbccc'
 
     >>> quantify(range(99), lambda x: x%2==0)
     50
@@ -1222,6 +1242,11 @@ The following recipes have a more mathematical flavor:
 
     >>> list(ncycles('abc', 3))
     ['a', 'b', 'c', 'a', 'b', 'c', 'a', 'b', 'c']
+    >>> # Verify greedy consumption of input iterator
+    >>> input_iterator = iter('abc')
+    >>> output_iterator = ncycles(input_iterator, 3)
+    >>> list(input_iterator)
+    []
 
     >>> sum_of_squares([10, 20, 30])
     1400
@@ -1248,19 +1273,41 @@ The following recipes have a more mathematical flavor:
 
     >>> list(transpose([(1, 2, 3), (11, 22, 33)]))
     [(1, 11), (2, 22), (3, 33)]
+    >>> # Verify that the inputs are consumed lazily
+    >>> input1 = iter([1, 2, 3])
+    >>> input2 = iter([11, 22, 33])
+    >>> output_iterator = transpose([input1, input2])
+    >>> next(output_iterator)
+    (1, 11)
+    >>> list(zip(input1, input2))
+    [(2, 22), (3, 33)]
 
     >>> list(matmul([(7, 5), (3, 5)], [[2, 5], [7, 9]]))
     [(49, 80), (41, 60)]
     >>> list(matmul([[2, 5], [7, 9], [3, 4]], [[7, 11, 5, 4, 9], [3, 5, 2, 6, 3]]))
     [(29, 47, 20, 38, 33), (76, 122, 53, 82, 90), (33, 53, 23, 36, 39)]
 
+    >>> list(convolve([1, -1, -20], [1, -3])) == [1, -4, -17, 60]
+    True
     >>> data = [20, 40, 24, 32, 20, 28, 16]
     >>> list(convolve(data, [0.25, 0.25, 0.25, 0.25]))
     [5.0, 15.0, 21.0, 29.0, 29.0, 26.0, 24.0, 16.0, 11.0, 4.0]
     >>> list(convolve(data, [1, -1]))
     [20, 20, -16, 8, -12, 8, -12, -16]
     >>> list(convolve(data, [1, -2, 1]))
     [20, 0, -36, 24, -20, 20, -20, -4, 16]
+    >>> # Verify signal is consumed lazily and the kernel greedily
+    >>> signal_iterator = iter([10, 20, 30, 40, 50])
+    >>> kernel_iterator = iter([1, 2, 3])
+    >>> output_iterator = convolve(signal_iterator, kernel_iterator)
+    >>> list(kernel_iterator)
+    []
+    >>> next(output_iterator)
+    10
+    >>> next(output_iterator)
+    40
+    >>> list(signal_iterator)
+    [30, 40, 50]
 
     >>> from fractions import Fraction
     >>> from decimal import Decimal
@@ -1348,6 +1395,33 @@ The following recipes have a more mathematical flavor:
     >>> # Test list input. Lists do not support None for the stop argument
     >>> list(iter_index(list('AABCADEAF'), 'A'))
     [0, 1, 4, 7]
+    >>> # Verify that input is consumed lazily
+    >>> input_iterator = iter('AABCADEAF')
+    >>> output_iterator = iter_index(input_iterator, 'A')
+    >>> next(output_iterator)
+    0
+    >>> next(output_iterator)
+    1
+    >>> next(output_iterator)
+    4
+    >>> ''.join(input_iterator)
+    'DEAF'
+
+    >>> # Verify that the target value can be a sequence.
+    >>> seq = [[10, 20], [30, 40], 30, 40, [30, 40], 50]
+    >>> target = [30, 40]
+    >>> list(iter_index(seq, target))
+    [1, 4]
+
+    >>> # Verify faithfulness to type specific index() method behaviors.
+    >>> # For example, bytes and str perform subsequence searches
+    >>> # that do not match the general behavior specified
+    >>> # in collections.abc.Sequence.index().
+    >>> seq = 'abracadabra'
+    >>> target = 'ab'
+    >>> list(iter_index(seq, target))
+    [0, 7]
+
 
     >>> list(sieve(30))
     [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
@@ -1490,6 +1564,9 @@ The following recipes have a more mathematical flavor:
 
     >>> list(roundrobin('abc', 'd', 'ef'))
     ['a', 'd', 'e', 'b', 'f', 'c']
+    >>> ranges = [range(5, 1000), range(4, 3000), range(0), range(3, 2000), range(2, 5000), range(1, 3500)]
+    >>> collections.Counter(roundrobin(ranges)) == collections.Counter(ranges)
+    True
 
     >>> def is_odd(x):
     ...     return x % 2 == 1
@@ -1499,6 +1576,17 @@ The following recipes have a more mathematical flavor:
     [0, 2, 4, 6, 8]
     >>> list(odds)
     [1, 3, 5, 7, 9]
+    >>> # Verify that the input is consumed lazily
+    >>> input_iterator = iter(range(10))
+    >>> evens, odds = partition(is_odd, input_iterator)
+    >>> next(odds)
+    1
+    >>> next(odds)
+    3
+    >>> next(evens)
+    0
+    >>> list(input_iterator)
+    [4, 5, 6, 7, 8, 9]
 
     >>> list(subslices('ABCD'))
     ['A', 'AB', 'ABC', 'ABCD', 'B', 'BC', 'BCD', 'C', 'CD', 'D']
@@ -1518,13 +1606,27 @@ The following recipes have a more mathematical flavor:
     ['A', 'B', 'C', 'D']
     >>> list(unique_everseen('ABBcCAD', str.casefold))
     ['A', 'B', 'c', 'D']
+    >>> # Verify that the input is consumed lazily
+    >>> input_iterator = iter('AAAABBBCCDAABBB')
+    >>> output_iterator = unique_everseen(input_iterator)
+    >>> next(output_iterator)
+    'A'
+    >>> ''.join(input_iterator)
+    'AAABBBCCDAABBB'
 
     >>> list(unique_justseen('AAAABBBCCDAABBB'))
     ['A', 'B', 'C', 'D', 'A', 'B']
     >>> list(unique_justseen('ABBCcAD', str.casefold))
     ['A', 'B', 'C', 'A', 'D']
     >>> list(unique_justseen('ABBcCAD', str.casefold))
     ['A', 'B', 'c', 'A', 'D']
+    >>> # Verify that the input is consumed lazily
+    >>> input_iterator = iter('AAAABBBCCDAABBB')
+    >>> output_iterator = unique_justseen(input_iterator)
+    >>> next(output_iterator)
+    'A'
+    >>> ''.join(input_iterator)
+    'AAABBBCCDAABBB'
 
     >>> d = dict(a=1, b=2, c=3)
     >>> it = iter_except(d.popitem, KeyError)
@@ -1545,6 +1647,12 @@ The following recipes have a more mathematical flavor:
 
     >>> first_true('ABC0DEF1', '9', str.isdigit)
     '0'
+    >>> # Verify that inputs are consumed lazily
+    >>> it = iter('ABC0DEF1')
+    >>> first_true(it, predicate=str.isdigit)
+    '0'
+    >>> ''.join(it)
+    'DEF1'
 
 
 .. testcode::

Doc/library/math.rst

@@ -592,7 +592,7 @@ Special functions
 
    The :func:`erf` function can be used to compute traditional statistical
    functions such as the `cumulative standard normal distribution
-   <https://en.wikipedia.org/wiki/Normal_distribution#Cumulative_distribution_functions>`_::
+   <https://en.wikipedia.org/wiki/Cumulative_distribution_function>`_::
 
      def phi(x):
          'Cumulative distribution function for the standard normal distribution'