Merge branch 'main' into whatsnew-3.13-sort-removals

.github/ISSUE_TEMPLATE/bug.yml

@@ -39,6 +39,7 @@ body:
         - "3.10"
         - "3.11"
         - "3.12"
+        - "3.13"
         - "CPython main branch"
     validations:
       required: true

Doc/c-api/unicode.rst

@@ -971,8 +971,8 @@ These are the UTF-8 codec APIs:
    returned buffer always has an extra null byte appended (not included in
    *size*), regardless of whether there are any other null code points.
 
-   In the case of an error, ``NULL`` is returned with an exception set and no
-   *size* is stored.
+   On error, set an exception, set *size* to ``-1`` (if it's not NULL) and
+   return ``NULL``.
 
    This caches the UTF-8 representation of the string in the Unicode object, and
    subsequent calls will return a pointer to the same buffer.  The caller is not
@@ -992,11 +992,19 @@ These are the UTF-8 codec APIs:
 
    As :c:func:`PyUnicode_AsUTF8AndSize`, but does not store the size.
 
+   Raise an exception if the *unicode* string contains embedded null
+   characters. To accept embedded null characters and truncate on purpose
+   at the first null byte, ``PyUnicode_AsUTF8AndSize(unicode, NULL)`` can be
+   used instead.
+
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.7
       The return type is now ``const char *`` rather of ``char *``.
 
+   .. versionchanged:: 3.13
+      Raise an exception if the string contains embedded null characters.
+
 
 UTF-32 Codecs
 """""""""""""

Doc/glossary.rst

@@ -239,7 +239,7 @@ Glossary
 
    context manager
       An object which controls the environment seen in a :keyword:`with`
-      statement by defining :meth:`__enter__` and :meth:`__exit__` methods.
+      statement by defining :meth:`~object.__enter__` and :meth:`~object.__exit__` methods.
       See :pep:`343`.
 
    context variable
@@ -636,7 +636,7 @@ Glossary
       iterables include all sequence types (such as :class:`list`, :class:`str`,
       and :class:`tuple`) and some non-sequence types like :class:`dict`,
       :term:`file objects <file object>`, and objects of any classes you define
-      with an :meth:`__iter__` method or with a :meth:`__getitem__` method
+      with an :meth:`__iter__` method or with a :meth:`~object.__getitem__` method
       that implements :term:`sequence` semantics.
 
       Iterables can be
@@ -1078,17 +1078,17 @@ Glossary
 
    sequence
       An :term:`iterable` which supports efficient element access using integer
-      indices via the :meth:`__getitem__` special method and defines a
+      indices via the :meth:`~object.__getitem__` special method and defines a
       :meth:`__len__` method that returns the length of the sequence.
       Some built-in sequence types are :class:`list`, :class:`str`,
       :class:`tuple`, and :class:`bytes`. Note that :class:`dict` also
-      supports :meth:`__getitem__` and :meth:`__len__`, but is considered a
+      supports :meth:`~object.__getitem__` and :meth:`__len__`, but is considered a
       mapping rather than a sequence because the lookups use arbitrary
       :term:`immutable` keys rather than integers.
 
       The :class:`collections.abc.Sequence` abstract base class
       defines a much richer interface that goes beyond just
-      :meth:`__getitem__` and :meth:`__len__`, adding :meth:`count`,
+      :meth:`~object.__getitem__` and :meth:`__len__`, adding :meth:`count`,
       :meth:`index`, :meth:`__contains__`, and
       :meth:`__reversed__`. Types that implement this expanded
       interface can be registered explicitly using

Doc/library/abc.rst

@@ -154,7 +154,7 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
    Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
    even though it does not define an :meth:`~iterator.__iter__` method (it uses
    the old-style iterable protocol, defined in terms of :meth:`__len__` and
-   :meth:`__getitem__`).  Note that this will not make ``get_iterator``
+   :meth:`~object.__getitem__`).  Note that this will not make ``get_iterator``
    available as a method of ``Foo``, so it is provided separately.
 
 

Doc/library/code.rst

@@ -23,27 +23,34 @@ build applications which provide an interactive interpreter prompt.
    ``'__doc__'`` set to ``None``.
 
 
-.. class:: InteractiveConsole(locals=None, filename="<console>")
+.. class:: InteractiveConsole(locals=None, filename="<console>", local_exit=False)
 
    Closely emulate the behavior of the interactive Python interpreter. This class
    builds on :class:`InteractiveInterpreter` and adds prompting using the familiar
-   ``sys.ps1`` and ``sys.ps2``, and input buffering.
+   ``sys.ps1`` and ``sys.ps2``, and input buffering. If *local_exit* is True,
+   ``exit()`` and ``quit()`` in the console will not raise :exc:`SystemExit`, but
+   instead return to the calling code.
 
+   .. versionchanged:: 3.13
+      Added *local_exit* parameter.
 
-.. function:: interact(banner=None, readfunc=None, local=None, exitmsg=None)
+.. function:: interact(banner=None, readfunc=None, local=None, exitmsg=None, local_exit=False)
 
    Convenience function to run a read-eval-print loop.  This creates a new
    instance of :class:`InteractiveConsole` and sets *readfunc* to be used as
    the :meth:`InteractiveConsole.raw_input` method, if provided.  If *local* is
    provided, it is passed to the :class:`InteractiveConsole` constructor for
-   use as the default namespace for the interpreter loop.  The :meth:`interact`
+   use as the default namespace for the interpreter loop.  If *local_exit* is provided,
+   it is passed to the :class:`InteractiveConsole` constructor.  The :meth:`interact`
    method of the instance is then run with *banner* and *exitmsg* passed as the
    banner and exit message to use, if provided.  The console object is discarded
    after use.
 
    .. versionchanged:: 3.6
       Added *exitmsg* parameter.
 
+   .. versionchanged:: 3.13
+      Added *local_exit* parameter.
 
 .. function:: compile_command(source, filename="<input>", symbol="single")
 

Doc/library/codecs.rst

@@ -520,44 +520,46 @@ The base :class:`Codec` class defines these methods which also define the
 function interfaces of the stateless encoder and decoder:
 
 
-.. method:: Codec.encode(input, errors='strict')
+.. class:: Codec
 
-   Encodes the object *input* and returns a tuple (output object, length consumed).
-   For instance, :term:`text encoding` converts
-   a string object to a bytes object using a particular
-   character set encoding (e.g., ``cp1252`` or ``iso-8859-1``).
+   .. method:: encode(input, errors='strict')
 
-   The *errors* argument defines the error handling to apply.
-   It defaults to ``'strict'`` handling.
+      Encodes the object *input* and returns a tuple (output object, length consumed).
+      For instance, :term:`text encoding` converts
+      a string object to a bytes object using a particular
+      character set encoding (e.g., ``cp1252`` or ``iso-8859-1``).
 
-   The method may not store state in the :class:`Codec` instance. Use
-   :class:`StreamWriter` for codecs which have to keep state in order to make
-   encoding efficient.
+      The *errors* argument defines the error handling to apply.
+      It defaults to ``'strict'`` handling.
 
-   The encoder must be able to handle zero length input and return an empty object
-   of the output object type in this situation.
+      The method may not store state in the :class:`Codec` instance. Use
+      :class:`StreamWriter` for codecs which have to keep state in order to make
+      encoding efficient.
 
+      The encoder must be able to handle zero length input and return an empty object
+      of the output object type in this situation.
 
-.. method:: Codec.decode(input, errors='strict')
 
-   Decodes the object *input* and returns a tuple (output object, length
-   consumed). For instance, for a :term:`text encoding`, decoding converts
-   a bytes object encoded using a particular
-   character set encoding to a string object.
+   .. method:: decode(input, errors='strict')
 
-   For text encodings and bytes-to-bytes codecs,
-   *input* must be a bytes object or one which provides the read-only
-   buffer interface -- for example, buffer objects and memory mapped files.
+      Decodes the object *input* and returns a tuple (output object, length
+      consumed). For instance, for a :term:`text encoding`, decoding converts
+      a bytes object encoded using a particular
+      character set encoding to a string object.
 
-   The *errors* argument defines the error handling to apply.
-   It defaults to ``'strict'`` handling.
+      For text encodings and bytes-to-bytes codecs,
+      *input* must be a bytes object or one which provides the read-only
+      buffer interface -- for example, buffer objects and memory mapped files.
 
-   The method may not store state in the :class:`Codec` instance. Use
-   :class:`StreamReader` for codecs which have to keep state in order to make
-   decoding efficient.
+      The *errors* argument defines the error handling to apply.
+      It defaults to ``'strict'`` handling.
 
-   The decoder must be able to handle zero length input and return an empty object
-   of the output object type in this situation.
+      The method may not store state in the :class:`Codec` instance. Use
+      :class:`StreamReader` for codecs which have to keep state in order to make
+      decoding efficient.
+
+      The decoder must be able to handle zero length input and return an empty object
+      of the output object type in this situation.
 
 
 Incremental Encoding and Decoding
@@ -705,7 +707,7 @@ Stream Encoding and Decoding
 
 The :class:`StreamWriter` and :class:`StreamReader` classes provide generic
 working interfaces which can be used to implement new encoding submodules very
-easily. See :mod:`encodings.utf_8` for an example of how this is done.
+easily. See :mod:`!encodings.utf_8` for an example of how this is done.
 
 
 .. _stream-writer-objects:
@@ -895,9 +897,10 @@ The design is such that one can use the factory functions returned by the
 .. class:: StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')
 
    Creates a :class:`StreamRecoder` instance which implements a two-way conversion:
-   *encode* and *decode* work on the frontend — the data visible to
-   code calling :meth:`read` and :meth:`write`, while *Reader* and *Writer*
-   work on the backend — the data in *stream*.
+   *encode* and *decode* work on the frontend — the data visible to
+   code calling :meth:`~StreamReader.read` and :meth:`~StreamWriter.write`,
+   while *Reader* and *Writer*
+   work on the backend — the data in *stream*.
 
    You can use these objects to do transparent transcodings, e.g., from Latin-1
    to UTF-8 and back.
@@ -1417,8 +1420,8 @@ to :class:`bytes` mappings. They are not supported by :meth:`bytes.decode`
 |                      | quotedprintable, | quoted printable.            | ``quotetabs=True`` /         |
 |                      | quoted_printable |                              | :meth:`quopri.decode`        |
 +----------------------+------------------+------------------------------+------------------------------+
-| uu_codec             | uu               | Convert the operand using    | :meth:`uu.encode` /          |
-|                      |                  | uuencode.                    | :meth:`uu.decode`            |
+| uu_codec             | uu               | Convert the operand using    |                              |
+|                      |                  | uuencode.                    |                              |
 +----------------------+------------------+------------------------------+------------------------------+
 | zlib_codec           | zip, zlib        | Compress the operand using   | :meth:`zlib.compress` /      |
 |                      |                  | gzip.                        | :meth:`zlib.decompress`      |

Doc/library/collections.abc.rst

@@ -192,7 +192,7 @@ ABC                            Inherits from          Abstract Methods        Mi
 .. [2] Checking ``isinstance(obj, Iterable)`` detects classes that are
    registered as :class:`Iterable` or that have an :meth:`__iter__`
    method, but it does not detect classes that iterate with the
-   :meth:`__getitem__` method.  The only reliable way to determine
+   :meth:`~object.__getitem__` method.  The only reliable way to determine
    whether an object is :term:`iterable` is to call ``iter(obj)``.
 
 
@@ -222,7 +222,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
 
    Checking ``isinstance(obj, Iterable)`` detects classes that are registered
    as :class:`Iterable` or that have an :meth:`__iter__` method, but it does
-   not detect classes that iterate with the :meth:`__getitem__` method.
+   not detect classes that iterate with the :meth:`~object.__getitem__` method.
    The only reliable way to determine whether an object is :term:`iterable`
    is to call ``iter(obj)``.
 
@@ -262,8 +262,8 @@ Collections Abstract Base Classes -- Detailed Descriptions
 
    Implementation note: Some of the mixin methods, such as
    :meth:`__iter__`, :meth:`__reversed__` and :meth:`index`, make
-   repeated calls to the underlying :meth:`__getitem__` method.
-   Consequently, if :meth:`__getitem__` is implemented with constant
+   repeated calls to the underlying :meth:`~object.__getitem__` method.
+   Consequently, if :meth:`~object.__getitem__` is implemented with constant
    access speed, the mixin methods will have linear performance;
    however, if the underlying method is linear (as it would be with a
    linked list), the mixins will have quadratic performance and will

Doc/library/collections.rst

@@ -743,12 +743,12 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
         If calling :attr:`default_factory` raises an exception this exception is
         propagated unchanged.
 
-        This method is called by the :meth:`__getitem__` method of the
+        This method is called by the :meth:`~object.__getitem__` method of the
         :class:`dict` class when the requested key is not found; whatever it
-        returns or raises is then returned or raised by :meth:`__getitem__`.
+        returns or raises is then returned or raised by :meth:`~object.__getitem__`.
 
         Note that :meth:`__missing__` is *not* called for any operations besides
-        :meth:`__getitem__`. This means that :meth:`get` will, like normal
+        :meth:`~object.__getitem__`. This means that :meth:`get` will, like normal
         dictionaries, return ``None`` as a default rather than using
         :attr:`default_factory`.
 

Doc/library/contextlib.rst

@@ -45,7 +45,7 @@ Functions and classes provided:
 
    This function is a :term:`decorator` that can be used to define a factory
    function for :keyword:`with` statement context managers, without needing to
-   create a class or separate :meth:`__enter__` and :meth:`__exit__` methods.
+   create a class or separate :meth:`~object.__enter__` and :meth:`~object.__exit__` methods.
 
    While many objects natively support use in with statements, sometimes a
    resource needs to be managed that isn't a context manager in its own right,
@@ -515,7 +515,7 @@ Functions and classes provided:
           # the with statement, even if attempts to open files later
           # in the list raise an exception
 
-   The :meth:`__enter__` method returns the :class:`ExitStack` instance, and
+   The :meth:`~object.__enter__` method returns the :class:`ExitStack` instance, and
    performs no additional operations.
 
    Each instance maintains a stack of registered callbacks that are called in
@@ -543,9 +543,9 @@ Functions and classes provided:
 
    .. method:: enter_context(cm)
 
-      Enters a new context manager and adds its :meth:`__exit__` method to
+      Enters a new context manager and adds its :meth:`~object.__exit__` method to
       the callback stack. The return value is the result of the context
-      manager's own :meth:`__enter__` method.
+      manager's own :meth:`~object.__enter__` method.
 
       These context managers may suppress exceptions just as they normally
       would if used directly as part of a :keyword:`with` statement.
@@ -556,18 +556,18 @@ Functions and classes provided:
 
    .. method:: push(exit)
 
-      Adds a context manager's :meth:`__exit__` method to the callback stack.
+      Adds a context manager's :meth:`~object.__exit__` method to the callback stack.
 
       As ``__enter__`` is *not* invoked, this method can be used to cover
-      part of an :meth:`__enter__` implementation with a context manager's own
-      :meth:`__exit__` method.
+      part of an :meth:`~object.__enter__` implementation with a context manager's own
+      :meth:`~object.__exit__` method.
 
       If passed an object that is not a context manager, this method assumes
       it is a callback with the same signature as a context manager's
-      :meth:`__exit__` method and adds it directly to the callback stack.
+      :meth:`~object.__exit__` method and adds it directly to the callback stack.
 
       By returning true values, these callbacks can suppress exceptions the
-      same way context manager :meth:`__exit__` methods can.
+      same way context manager :meth:`~object.__exit__` methods can.
 
       The passed in object is returned from the function, allowing this
       method to be used as a function decorator.
@@ -714,7 +714,7 @@ Cleaning up in an ``__enter__`` implementation
 
 As noted in the documentation of :meth:`ExitStack.push`, this
 method can be useful in cleaning up an already allocated resource if later
-steps in the :meth:`__enter__` implementation fail.
+steps in the :meth:`~object.__enter__` implementation fail.
 
 Here's an example of doing this for a context manager that accepts resource
 acquisition and release functions, along with an optional validation function,
@@ -871,7 +871,7 @@ And also as a function decorator::
 
 Note that there is one additional limitation when using context managers
 as function decorators: there's no way to access the return value of
-:meth:`__enter__`. If that value is needed, then it is still necessary to use
+:meth:`~object.__enter__`. If that value is needed, then it is still necessary to use
 an explicit ``with`` statement.
 
 .. seealso::

Doc/library/doctest.rst

@@ -277,13 +277,34 @@ Which Docstrings Are Examined?
 The module docstring, and all function, class and method docstrings are
 searched.  Objects imported into the module are not searched.
 
-In addition, if ``M.__test__`` exists and "is true", it must be a dict, and each
+In addition, there are cases when you want tests to be part of a module but not part
+of the help text, which requires that the tests not be included in the docstring.
+Doctest looks for a module-level variable called ``__test__`` and uses it to locate other
+tests. If ``M.__test__`` exists and is truthy, it must be a dict, and each
 entry maps a (string) name to a function object, class object, or string.
 Function and class object docstrings found from ``M.__test__`` are searched, and
 strings are treated as if they were docstrings.  In output, a key ``K`` in
-``M.__test__`` appears with name ::
+``M.__test__`` appears with name ``M.__test__.K``.
 
-   <name of M>.__test__.K
+For example, place this block of code at the top of :file:`example.py`:
+
+.. code-block:: python
+
+   __test__ = {
+       'numbers': """
+   >>> factorial(6)
+   720
+
+   >>> [factorial(n) for n in range(6)]
+   [1, 1, 2, 6, 24, 120]
+   """
+   }
+
+The value of ``example.__test__["numbers"]`` will be treated as a
+docstring and all the tests inside it will be run. It is
+important to note that the value can be mapped to a function,
+class object, or module; if so, :mod:`!doctest`
+searches them recursively for docstrings, which are then scanned for tests.
 
 Any classes found are recursively searched similarly, to test docstrings in
 their contained methods and nested classes.