Merge branch 'main' into gh-157058-waitfor

Author: kumaraditya303

Doc/c-api/module.rst

@@ -853,7 +853,7 @@ struct:
 
    .. versionadded:: 3.5
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyModule_FromSlotsAndSpec` in new code.
 
@@ -877,7 +877,7 @@ struct:
 
    .. versionadded:: 3.5
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyModule_FromSlotsAndSpec` in new code.
 
@@ -887,7 +887,7 @@ struct:
 
    .. versionadded:: 3.5
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       To run a module's own execution slots, prefer :c:func:`PyModule_Exec`,
       which works on modules that were not created from a

Doc/c-api/type.rst

@@ -828,7 +828,7 @@ They will continue to work, but new features will be added as slots for
 
    .. versionadded:: 3.12
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.
 
@@ -859,7 +859,7 @@ They will continue to work, but new features will be added as slots for
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.
 
@@ -885,7 +885,7 @@ They will continue to work, but new features will be added as slots for
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.
 
@@ -910,7 +910,7 @@ They will continue to work, but new features will be added as slots for
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.
 

Doc/c-api/typeobj.rst

@@ -1869,9 +1869,10 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
       PyObject *tp_iternext(PyObject *self);
 
-   When the iterator is exhausted, it must return ``NULL``; a :exc:`StopIteration`
-   exception may or may not be set.  When another error occurs, it must return
-   ``NULL`` too.  Its presence signals that the instances of this type are
+   When the iterator is :term:`exhausted`, the ``tp_iternext`` function must
+   return ``NULL``; a :exc:`StopIteration` exception may or may not be set.
+   When another error occurs, it must return ``NULL`` too.
+   The presence of ``tp_iternext`` signals that the instances of this type are
    iterators.
 
    Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` function, and that

Doc/glossary.rst

@@ -505,6 +505,14 @@ Glossary
       of an object, such as the value of type aliases created with the :keyword:`type`
       statement.
 
+   exhausted
+      An :term:`iterator` that has produced all of its values is said to be
+      :dfn:`exhausted`.
+      Further attempts to get the next value (for example, calls to
+      :func:`next`) raise :exc:`StopIteration`
+      (or :exc:`StopAsyncIteration` in the case of an :term:`asynchronous
+      iterator`).
+
    expression
       A piece of syntax which can be evaluated to some value.  In other words,
       an expression is an accumulation of expression elements like literals,
@@ -869,7 +877,7 @@ Glossary
       :meth:`~iterator.__next__` method (or passing it to the built-in function
       :func:`next`) return successive items in the stream.  When no more data
       are available a :exc:`StopIteration` exception is raised instead.  At this
-      point, the iterator object is exhausted and any further calls to its
+      point, the iterator object is :term:`exhausted` and any further calls to its
       :meth:`!__next__` method just raise :exc:`StopIteration` again.  Iterators
       are required to have an :meth:`~iterator.__iter__` method that returns the iterator
       object itself so every iterator is also iterable and may be used in most

Doc/howto/functional.rst

@@ -720,9 +720,10 @@ returns them in a tuple::
     zip(['a', 'b', 'c'], (1, 2, 3)) =>
       ('a', 1), ('b', 2), ('c', 3)
 
-It doesn't construct an in-memory list and exhaust all the input iterators
-before returning; instead tuples are constructed and returned only if they're
-requested.  (The technical term for this behaviour is `lazy evaluation
+It doesn't construct an in-memory list and :term:`exhaust <exhausted>` all
+the input iterators before returning; instead tuples are constructed and
+returned only if they're requested.
+(The technical term for this behaviour is `lazy evaluation
 <https://en.wikipedia.org/wiki/Lazy_evaluation>`__.)
 
 This iterator is intended to be used with iterables that are all of the same
@@ -783,7 +784,7 @@ element *n* times, or returns the element endlessly if *n* is not provided. ::
 :func:`itertools.chain(iterA, iterB, ...) <itertools.chain>` takes an arbitrary
 number of iterables as input, and returns all the elements of the first
 iterator, then all the elements of the second, and so on, until all of the
-iterables have been exhausted. ::
+iterables have been :term:`exhausted`. ::
 
     itertools.chain(['a', 'b', 'c'], (1, 2, 3)) =>
       a, b, c, 1, 2, 3
@@ -878,7 +879,7 @@ iterable's results. ::
 
 :func:`itertools.compress(data, selectors) <itertools.compress>` takes two
 iterators and returns only those elements of *data* for which the corresponding
-element of *selectors* is true, stopping whenever either one is exhausted::
+element of *selectors* is true, stopping whenever either one is :term:`exhausted`::
 
     itertools.compress([1, 2, 3, 4, 5], [True, True, False, False, True]) =>
        1, 2, 5
@@ -1028,7 +1029,7 @@ that takes two elements and returns a single value.  :func:`functools.reduce`
 takes the first two elements A and B returned by the iterator and calculates
 ``func(A, B)``.  It then requests the third element, C, calculates
 ``func(func(A, B), C)``, combines this result with the fourth element returned,
-and continues until the iterable is exhausted.  If the iterable returns no
+and continues until the iterable is :term:`exhausted`.  If the iterable returns no
 values at all, a :exc:`TypeError` exception is raised.  If the initial value is
 supplied, it's used as a starting point and ``func(initial_value, A)`` is the
 first calculation. ::

Doc/howto/logging-cookbook.rst

@@ -3920,7 +3920,7 @@ subclassed handler which looks something like this::
 
 You'll need to be familiar with RFC 5424 to fully understand the above code, and it
 may be that you have slightly different needs (e.g. for how you pass structural data
-to the log). Nevertheless, the above should be adaptable to your speciric needs. With
+to the log). Nevertheless, the above should be adaptable to your specific needs. With
 the above handler, you'd pass structured data using something like this::
 
     sd = {

Doc/howto/mro.rst

@@ -189,7 +189,7 @@ prescription:
   the tail of any of the other lists, then add it to the linearization
   of C and remove it from the lists in the merge, otherwise look at the
   head of the next list and take it, if it is a good head.  Then repeat
-  the operation until all the class are removed or it is impossible to
+  the operation until all the classes are removed or it is impossible to
   find good heads.  In this case, it is impossible to construct the
   merge, Python 2.3 will refuse to create the class C and will raise an
   exception.*

Doc/library/collections.rst

@@ -699,7 +699,7 @@ added elements by appending to the right and popping to the left::
 A `round-robin scheduler
 <https://en.wikipedia.org/wiki/Round-robin_scheduling>`_ can be implemented with
 input iterators stored in a :class:`deque`.  Values are yielded from the active
-iterator in position zero.  If that iterator is exhausted, it can be removed
+iterator in position zero.  If that iterator is :term:`exhausted`, it can be removed
 with :meth:`~deque.popleft`; otherwise, it can be cycled back to the end with
 the :meth:`~deque.rotate` method::
 

Doc/library/colorsys.rst

@@ -19,7 +19,7 @@ spaces, the coordinates are all between 0 and 1.
 .. seealso::
 
    More information about color spaces can be found at
-   https://poynton.ca/ColorFAQ.html and
+   https://www.poynton.ca/pdf/ColourFAQ.pdf and
    https://www.cambridgeincolour.com/tutorials/color-spaces.htm.
 
 The :mod:`!colorsys` module defines the following functions:

Doc/library/ctypes.rst

@@ -708,7 +708,7 @@ Specifying function pointers using type annotations
 
       @wrap_dll_function(dll_to_wrap)
       def function_ptr_name(arg_name: ctypes_type, ...) -> ctypes_type:
-         """Optional docstring. There should be no function body."""
+          """Optional docstring. There should be no function body."""
 
    The body of the decorated function is ignored, and any parameters that are
    missing type annotations are skipped. The names of the parameters are ignored
@@ -728,7 +728,7 @@ Specifying function pointers using type annotations
 
       @wrap_dll_function(ctypes.pythonapi)
       def PyObject_GetAttrString(op: ctypes.py_object, attr: ctypes.c_char_p) -> ctypes.py_object:
-         pass
+          pass
 
       PyObject_GetAttrString(42, b"real")
 
@@ -3207,7 +3207,7 @@ fields, or any other data types containing pointer type fields.
       that should be merged into a containing structure or union.
 
 
-.. decorator:: struct(*, align=None, layout, endian='native', pack=None)
+.. decorator:: struct(*, align=None, layout=None, endian='native', pack=None)
    :module: ctypes.util
 
    A :term:`decorator` that allows generating structure types using an
@@ -3244,14 +3244,18 @@ fields, or any other data types containing pointer type fields.
 
    .. code-block:: python
 
+      from typing import Annotated
+      from ctypes import c_ssize_t, c_void_p
+      from ctypes.util import struct, CFieldInfo
+
       @struct
       class PyObject:
-         ob_refcnt: c_ssize_t
-         ob_type: c_void_p
+          ob_refcnt: c_ssize_t
+          ob_type: c_void_p
 
       @struct
       class PyHovercraftObject:
-         ob_base: Annotated[PyObject, CFieldInfo(anonymous=True)]
+          ob_base: Annotated[PyObject, CFieldInfo(anonymous=True)]
 
    .. versionadded:: next