Merge branch 'main' into hack-night2

Author: brandtbucher

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

@@ -518,7 +518,7 @@ The :mod:`functools` module defines the following functions:
      ...     for i, elem in enumerate(arg):
      ...         print(i, elem)
 
-   :data:`types.UnionType` and :data:`typing.Union` can also be used::
+   :class:`typing.Union` can also be used::
 
     >>> @fun.register
     ... def _(arg: int | float, verbose=False):
@@ -654,8 +654,8 @@ The :mod:`functools` module defines the following functions:
       The :func:`register` attribute now supports using type annotations.
 
    .. versionchanged:: 3.11
-      The :func:`register` attribute now supports :data:`types.UnionType`
-      and :data:`typing.Union` as type annotations.
+      The :func:`register` attribute now supports
+      :class:`typing.Union` as a type annotation.
 
 
 .. class:: singledispatchmethod(func)

Doc/library/pdb.rst

@@ -245,6 +245,10 @@ access further features, you have to do this yourself:
    .. versionadded:: 3.14
       Added the *mode* argument.
 
+   .. versionchanged:: 3.14
+      Inline breakpoints like :func:`breakpoint` or :func:`pdb.set_trace` will
+      always stop the program at calling frame, ignoring the *skip* pattern (if any).
+
    .. method:: run(statement, globals=None, locals=None)
                runeval(expression, globals=None, locals=None)
                runcall(function, *args, **kwds)

Doc/library/stdtypes.rst

@@ -5364,7 +5364,7 @@ Union Type
 A union object holds the value of the ``|`` (bitwise or) operation on
 multiple :ref:`type objects <bltin-type-objects>`.  These types are intended
 primarily for :term:`type annotations <annotation>`. The union type expression
-enables cleaner type hinting syntax compared to :data:`typing.Union`.
+enables cleaner type hinting syntax compared to subscripting :class:`typing.Union`.
 
 .. describe:: X | Y | ...
 
@@ -5400,9 +5400,10 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`.
 
       int | str == str | int
 
-   * It is compatible with :data:`typing.Union`::
+   * It creates instances of :class:`typing.Union`::
 
       int | str == typing.Union[int, str]
+      type(int | str) is typing.Union
 
    * Optional types can be spelled as a union with ``None``::
 
@@ -5428,16 +5429,15 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`.
       TypeError: isinstance() argument 2 cannot be a parameterized generic
 
 The user-exposed type for the union object can be accessed from
-:data:`types.UnionType` and used for :func:`isinstance` checks.  An object cannot be
-instantiated from the type::
+:class:`typing.Union` and used for :func:`isinstance` checks::
 
-   >>> import types
-   >>> isinstance(int | str, types.UnionType)
+   >>> import typing
+   >>> isinstance(int | str, typing.Union)
    True
-   >>> types.UnionType()
+   >>> typing.Union()
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
-   TypeError: cannot create 'types.UnionType' instances
+   TypeError: cannot create 'typing.Union' instances
 
 .. note::
    The :meth:`!__or__` method for type objects was added to support the syntax
@@ -5464,6 +5464,11 @@ instantiated from the type::
 
 .. versionadded:: 3.10
 
+.. versionchanged:: 3.14
+
+   Union objects are now instances of :class:`typing.Union`. Previously, they were instances
+   of :class:`types.UnionType`, which remains an alias for :class:`typing.Union`.
+
 
 .. _typesother: