Merge branch 'main' into gh-128520-local-module-move

Author: barneygale

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/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/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.

Doc/library/exceptions.rst

@@ -333,11 +333,13 @@ The following exceptions are the exceptions that are usually raised.
       meant to be supported at all -- in that case either leave the operator /
       method undefined or, if a subclass, set it to :data:`None`.
 
-   .. note::
+   .. caution::
+
+      :exc:`!NotImplementedError` and :data:`!NotImplemented` are not
+      interchangeable. This exception should only be used as described
+      above; see :data:`NotImplemented` for details on correct usage of
+      the built-in constant.
 
-      ``NotImplementedError`` and :data:`NotImplemented` are not interchangeable,
-      even though they have similar names and purposes.  See
-      :data:`!NotImplemented` for details on when to use it.
 
 .. exception:: OSError([arg])
                OSError(errno, strerror[, filename[, winerror[, filename2]]])

Doc/library/importlib.metadata.rst

@@ -268,8 +268,9 @@ Distribution versions
 
 .. function:: version(distribution_name)
 
-   Return the installed distribution package version for the named
-   distribution package.
+   Return the installed distribution package
+   `version <https://packaging.python.org/en/latest/specifications/core-metadata/#version>`__
+   for the named distribution package.
 
    Raises :exc:`PackageNotFoundError` if the named distribution
    package is not installed in the current Python environment.

Doc/library/traceback.rst

@@ -508,7 +508,9 @@ the module-level functions described above.
 A :class:`!FrameSummary` object represents a single :ref:`frame <frame-objects>`
 in a :ref:`traceback <traceback-objects>`.
 
-.. class:: FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)
+.. class:: FrameSummary(filename, lineno, name, *,\
+                        lookup_line=True, locals=None,\
+                        line=None, end_lineno=None, colno=None, end_colno=None)
 
    Represents a single :ref:`frame <frame-objects>` in the
    :ref:`traceback <traceback-objects>` or stack that is being formatted
@@ -544,6 +546,25 @@ in a :ref:`traceback <traceback-objects>`.
       trailing whitespace stripped.
       If the source is not available, it is ``None``.
 
+   .. attribute:: FrameSummary.end_lineno
+
+      The last line number of the source code for this frame.
+      By default, it is set to ``lineno`` and indexation starts from 1.
+
+      .. versionchanged:: 3.13
+         The default value changed from ``None`` to ``lineno``.
+
+   .. attribute:: FrameSummary.colno
+
+      The column number of the source code for this frame.
+      By default, it is ``None`` and indexation starts from 0.
+
+   .. attribute:: FrameSummary.end_colno
+
+      The last column number of the source code for this frame.
+      By default, it is ``None`` and indexation starts from 0.
+
+
 .. _traceback-example:
 
 Examples of Using the Module-Level Functions

Doc/library/uuid.rst

@@ -12,8 +12,8 @@
 
 This module provides immutable :class:`UUID` objects (the :class:`UUID` class)
 and the functions :func:`uuid1`, :func:`uuid3`, :func:`uuid4`, :func:`uuid5`,
-and :func:`uuid.uuid8` for generating version 1, 3, 4, 5, and 8 UUIDs as
-specified in :rfc:`9562` (which supersedes :rfc:`4122`).
+:func:`uuid6`, and :func:`uuid8` for generating version 1, 3, 4, 5, 6,
+and 8 UUIDs as specified in :rfc:`9562` (which supersedes :rfc:`4122`).
 
 If all you want is a unique ID, you should probably call :func:`uuid1` or
 :func:`uuid4`.  Note that :func:`uuid1` may compromise privacy since it creates
@@ -153,8 +153,8 @@ which relays any information about the UUID's safety, using this enumeration:
    The UUID version number (1 through 8, meaningful only when the variant is
    :const:`RFC_4122`).
 
-   .. versionchanged:: 3.14
-      Added UUID version 8.
+   .. versionchanged:: next
+      Added UUID versions 6 and 8.
 
 
 .. attribute:: UUID.is_safe
@@ -212,6 +212,22 @@ The :mod:`uuid` module defines the following functions:
    that will be encoded using UTF-8).
 
 
+.. function:: uuid6(node=None, clock_seq=None)
+
+   Generate a UUID from a sequence number and the current time according to
+   :rfc:`9562`.
+   This is an alternative to :func:`uuid1` to improve database locality.
+
+   When *node* is not specified, :func:`getnode` is used to obtain the hardware
+   address as a 48-bit positive integer. When a sequence number *clock_seq* is
+   not specified, a pseudo-random 14-bit positive integer is generated.
+
+   If *node* or *clock_seq* exceed their expected bit count, only their least
+   significant bits are kept.
+
+   .. versionadded:: next
+
+
 .. function:: uuid8(a=None, b=None, c=None)
 
    Generate a pseudo-random UUID according to
@@ -314,7 +330,7 @@ The :mod:`uuid` module can be executed as a script from the command line.
 
 .. code-block:: sh
 
-   python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid8}] [-n NAMESPACE] [-N NAME]
+   python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid8}] [-n NAMESPACE] [-N NAME]
 
 The following options are accepted:
 
@@ -330,8 +346,8 @@ The following options are accepted:
    Specify the function name to use to generate the uuid. By default :func:`uuid4`
    is used.
 
-   .. versionadded:: 3.14
-      Allow generating UUID version 8.
+   .. versionchanged:: next
+      Allow generating UUID versions 6 and 8.
 
 .. option:: -n <namespace>
             --namespace <namespace>