Merge branch 'main' into fix-issue-128942-lockfree

Author: tom-pytel

Doc/c-api/arg.rst

@@ -5,7 +5,7 @@
 Parsing arguments and building values
 =====================================
 
-These functions are useful when creating your own extensions functions and
+These functions are useful when creating your own extension functions and
 methods.  Additional information and examples are available in
 :ref:`extending-index`.
 

Doc/c-api/intro.rst

@@ -30,6 +30,16 @@ familiar with writing an extension before  attempting to embed Python in a real
 application.
 
 
+Language version compatibility
+==============================
+
+Python's C API is compatible with C11 and C++11 versions of C and C++.
+
+This is a lower limit: the C API does not require features from later
+C/C++ versions.
+You do *not* need to enable your compiler's "c11 mode".
+
+
 Coding standards
 ================
 

Doc/c-api/structures.rst

@@ -63,6 +63,11 @@ under :ref:`reference counting <countingrefs>`.
    See documentation of :c:type:`PyVarObject` above.
 
 
+.. c:var:: PyTypeObject PyBaseObject_Type
+
+   The base class of all other objects, the same as :class:`object` in Python.
+
+
 .. c:function:: int Py_Is(PyObject *x, PyObject *y)
 
    Test if the *x* object is the *y* object, the same as ``x is y`` in Python.

Doc/conf.py

@@ -100,7 +100,7 @@
 
 # Minimum version of sphinx required
 # Keep this version in sync with ``Doc/requirements.txt``.
-needs_sphinx = '8.1.3'
+needs_sphinx = '8.2.0'
 
 # Create table of contents entries for domain objects (e.g. functions, classes,
 # attributes, etc.). Default is True.

Doc/deprecations/pending-removal-in-future.rst

@@ -127,6 +127,11 @@ although there is currently no date scheduled for their removal.
 
 * :class:`typing.Text` (:gh:`92332`).
 
+* The internal class ``typing._UnionGenericAlias`` is no longer used to implement
+  :class:`typing.Union`. To preserve compatibility with users using this private
+  class, a compatibility shim will be provided until at least Python 3.17. (Contributed by
+  Jelle Zijlstra in :gh:`105499`.)
+
 * :class:`unittest.IsolatedAsyncioTestCase`: it is deprecated to return a value
   that is not ``None`` from a test case.
 

Doc/extending/embedding.rst

@@ -196,8 +196,8 @@ interesting part with respect to embedding Python starts with ::
 
 After initializing the interpreter, the script is loaded using
 :c:func:`PyImport_Import`.  This routine needs a Python string as its argument,
-which is constructed using the :c:func:`PyUnicode_FromString` data conversion
-routine. ::
+which is constructed using the :c:func:`PyUnicode_DecodeFSDefault` data
+conversion routine. ::
 
    pFunc = PyObject_GetAttrString(pModule, argv[2]);
    /* pFunc is a new reference */

Doc/library/collections.rst

@@ -748,8 +748,8 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
         returns or raises is then returned or raised by :meth:`~object.__getitem__`.
 
         Note that :meth:`__missing__` is *not* called for any operations besides
-        :meth:`~object.__getitem__`. This means that :meth:`get` will, like normal
-        dictionaries, return ``None`` as a default rather than using
+        :meth:`~object.__getitem__`. This means that :meth:`~dict.get` will, like
+        normal dictionaries, return ``None`` as a default rather than using
         :attr:`default_factory`.
 
 
@@ -849,8 +849,9 @@ they add the ability to access fields by name instead of position index.
     Returns a new tuple subclass named *typename*.  The new subclass is used to
     create tuple-like objects that have fields accessible by attribute lookup as
     well as being indexable and iterable.  Instances of the subclass also have a
-    helpful docstring (with typename and field_names) and a helpful :meth:`__repr__`
-    method which lists the tuple contents in a ``name=value`` format.
+    helpful docstring (with *typename* and *field_names*) and a helpful
+    :meth:`~object.__repr__` method which lists the tuple contents in a ``name=value``
+    format.
 
     The *field_names* are a sequence of strings such as ``['x', 'y']``.
     Alternatively, *field_names* can be a single string with each fieldname
@@ -894,10 +895,10 @@ they add the ability to access fields by name instead of position index.
        Added the *module* parameter.
 
     .. versionchanged:: 3.7
-       Removed the *verbose* parameter and the :attr:`_source` attribute.
+       Removed the *verbose* parameter and the :attr:`!_source` attribute.
 
     .. versionchanged:: 3.7
-       Added the *defaults* parameter and the :attr:`_field_defaults`
+       Added the *defaults* parameter and the :attr:`~somenamedtuple._field_defaults`
        attribute.
 
 .. doctest::
@@ -1109,7 +1110,7 @@ Some differences from :class:`dict` still remain:
   A regular :class:`dict` can emulate the order sensitive equality test with
   ``p == q and all(k1 == k2 for k1, k2 in zip(p, q))``.
 
-* The :meth:`popitem` method of :class:`OrderedDict` has a different
+* The :meth:`~OrderedDict.popitem` method of :class:`OrderedDict` has a different
   signature.  It accepts an optional argument to specify which item is popped.
 
   A regular :class:`dict` can emulate OrderedDict's ``od.popitem(last=True)``
@@ -1119,7 +1120,7 @@ Some differences from :class:`dict` still remain:
   with ``(k := next(iter(d)), d.pop(k))`` which will return and remove the
   leftmost (first) item if it exists.
 
-* :class:`OrderedDict` has a :meth:`move_to_end` method to efficiently
+* :class:`OrderedDict` has a :meth:`~OrderedDict.move_to_end` method to efficiently
   reposition an element to an endpoint.
 
   A regular :class:`dict` can emulate OrderedDict's ``od.move_to_end(k,
@@ -1130,7 +1131,7 @@ Some differences from :class:`dict` still remain:
   OrderedDict's ``od.move_to_end(k, last=False)`` which moves the key
   and its associated value to the leftmost (first) position.
 
-* Until Python 3.8, :class:`dict` lacked a :meth:`__reversed__` method.
+* Until Python 3.8, :class:`dict` lacked a :meth:`~object.__reversed__` method.
 
 
 .. class:: OrderedDict([items])
@@ -1185,7 +1186,7 @@ anywhere a regular dictionary is used.
 
 .. versionchanged:: 3.6
    With the acceptance of :pep:`468`, order is retained for keyword arguments
-   passed to the :class:`OrderedDict` constructor and its :meth:`update`
+   passed to the :class:`OrderedDict` constructor and its :meth:`~dict.update`
    method.
 
 .. versionchanged:: 3.9

Doc/library/concurrent.futures.rst

@@ -415,6 +415,30 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
       require the *fork* start method for :class:`ProcessPoolExecutor` you must
       explicitly pass ``mp_context=multiprocessing.get_context("fork")``.
 
+   .. method:: terminate_workers()
+
+      Attempt to terminate all living worker processes immediately by calling
+      :meth:`Process.terminate <multiprocessing.Process.terminate>` on each of them.
+      Internally, it will also call :meth:`Executor.shutdown` to ensure that all
+      other resources associated with the executor are freed.
+
+      After calling this method the caller should no longer submit tasks to the
+      executor.
+
+      .. versionadded:: next
+
+   .. method:: kill_workers()
+
+      Attempt to kill all living worker processes immediately by calling
+      :meth:`Process.kill <multiprocessing.Process.kill>` on each of them.
+      Internally, it will also call :meth:`Executor.shutdown` to ensure that all
+      other resources associated with the executor are freed.
+
+      After calling this method the caller should no longer submit tasks to the
+      executor.
+
+      .. versionadded:: next
+
 .. _processpoolexecutor-example:
 
 ProcessPoolExecutor Example

Doc/library/constants.rst

@@ -46,11 +46,12 @@ A small number of constants live in the built-in namespace.  They are:
 
       See :ref:`implementing-the-arithmetic-operations` for examples.
 
-   .. note::
+   .. caution::
 
-      ``NotImplementedError`` and :data:`!NotImplemented` are not interchangeable,
-      even though they have similar names and purposes.
-      See :exc:`NotImplementedError` for details on when to use it.
+      :data:`!NotImplemented` and :exc:`!NotImplementedError` are not
+      interchangeable. This constant should only be used as described
+      above; see :exc:`NotImplementedError` for details on correct usage
+      of the exception.
 
    .. versionchanged:: 3.9
       Evaluating :data:`!NotImplemented` in a boolean context was deprecated.

Doc/library/email.errors.rst

@@ -77,51 +77,72 @@ object would have a defect, but the containing messages would not.
 
 All defect classes are subclassed from :class:`email.errors.MessageDefect`.
 
-* :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart,
-  but had no :mimetype:`boundary` parameter.
+.. exception:: NoBoundaryInMultipartDefect
 
-* :class:`StartBoundaryNotFoundDefect` -- The start boundary claimed in the
-  :mailheader:`Content-Type` header was never found.
+   A message claimed to be a multipart, but had no :mimetype:`boundary`
+   parameter.
 
-* :class:`CloseBoundaryNotFoundDefect` -- A start boundary was found, but
-  no corresponding close boundary was ever found.
+.. exception:: StartBoundaryNotFoundDefect
 
-  .. versionadded:: 3.3
+   The start boundary claimed in the :mailheader:`Content-Type` header was
+   never found.
 
-* :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation
-  line as its first header line.
+.. exception:: CloseBoundaryNotFoundDefect
 
-* :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the
-  middle of a header block.
+   A start boundary was found, but no corresponding close boundary was ever
+   found.
 
-* :class:`MissingHeaderBodySeparatorDefect` - A line was found while parsing
-  headers that had no leading white space but contained no ':'.  Parsing
-  continues assuming that the line represents the first line of the body.
+   .. versionadded:: 3.3
 
-  .. versionadded:: 3.3
+.. exception:: FirstHeaderLineIsContinuationDefect
 
-* :class:`MalformedHeaderDefect` -- A header was found that was missing a colon,
-  or was otherwise malformed.
+   The message had a continuation line as its first header line.
 
-  .. deprecated:: 3.3
-     This defect has not been used for several Python versions.
+.. exception:: MisplacedEnvelopeHeaderDefect
 
-* :class:`MultipartInvariantViolationDefect` -- A message claimed to be a
-  :mimetype:`multipart`, but no subparts were found.  Note that when a message
-  has this defect, its :meth:`~email.message.Message.is_multipart` method may
-  return ``False`` even though its content type claims to be :mimetype:`multipart`.
+   A "Unix From" header was found in the middle of a header block.
 
-* :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64
-  encoded bytes, the padding was not correct.  Enough padding is added to
-  perform the decode, but the resulting decoded bytes may be invalid.
+.. exception:: MissingHeaderBodySeparatorDefect
 
-* :class:`InvalidBase64CharactersDefect` -- When decoding a block of base64
-  encoded bytes, characters outside the base64 alphabet were encountered.
-  The characters are ignored, but the resulting decoded bytes may be invalid.
+   A line was found while parsing headers that had no leading white space but
+   contained no ':'.  Parsing continues assuming that the line represents the
+   first line of the body.
 
-* :class:`InvalidBase64LengthDefect` -- When decoding a block of base64 encoded
-  bytes, the number of non-padding base64 characters was invalid (1 more than
-  a multiple of 4).  The encoded block was kept as-is.
+   .. versionadded:: 3.3
 
-* :class:`InvalidDateDefect` -- When decoding an invalid or unparsable date field.
-  The original value is kept as-is.
+.. exception:: MalformedHeaderDefect
+
+   A header was found that was missing a colon, or was otherwise malformed.
+
+   .. deprecated:: 3.3
+      This defect has not been used for several Python versions.
+
+.. exception:: MultipartInvariantViolationDefect
+
+   A message claimed to be a :mimetype:`multipart`, but no subparts were found.
+   Note that when a message has this defect, its
+   :meth:`~email.message.Message.is_multipart` method may return ``False``
+   even though its content type claims to be :mimetype:`multipart`.
+
+.. exception:: InvalidBase64PaddingDefect
+
+   When decoding a block of base64 encoded bytes, the padding was not correct.
+   Enough padding is added to perform the decode, but the resulting decoded
+   bytes may be invalid.
+
+.. exception:: InvalidBase64CharactersDefect
+
+   When decoding a block of base64 encoded bytes, characters outside the base64
+   alphabet were encountered.  The characters are ignored, but the resulting
+   decoded bytes may be invalid.
+
+.. exception:: InvalidBase64LengthDefect
+
+   When decoding a block of base64 encoded bytes, the number of non-padding
+   base64 characters was invalid (1 more than a multiple of 4).  The encoded
+   block was kept as-is.
+
+.. exception:: InvalidDateDefect
+
+   When decoding an invalid or unparsable date field.  The original value is
+   kept as-is.