Merge branch 'main' into gh-130804-pyrepl-unicode-chars

Author: sergey-miryanov

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/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/extending/windows.rst

@@ -96,6 +96,13 @@ gives you access to spam's names, but does not create a separate copy.  On Unix,
 linking with a library is more like ``from spam import *``; it does create a
 separate copy.
 
+.. c:macro:: Py_NO_LINK_LIB
+
+   Turn off the implicit, ``#pragma``-based linkage with the Python
+   library, performed inside CPython header files.
+
+   .. versionadded:: 3.14
+
 
 .. _win-dlls:
 
@@ -108,21 +115,46 @@ Using DLLs in Practice
 Windows Python is built in Microsoft Visual C++; using other compilers may or
 may not work.  The rest of this section is MSVC++ specific.
 
-When creating DLLs in Windows, you must pass :file:`pythonXY.lib` to the linker.
-To build two DLLs, spam and ni (which uses C functions found in spam), you could
-use these commands::
+When creating DLLs in Windows, you can use the CPython library in two ways:
+
+1. By default, inclusion of :file:`PC/pyconfig.h` directly or via
+   :file:`Python.h` triggers an implicit, configure-aware link with the
+   library.  The header file chooses :file:`pythonXY_d.lib` for Debug,
+   :file:`pythonXY.lib` for Release, and :file:`pythonX.lib` for Release with
+   the `Limited API <stable-application-binary-interface>`_ enabled.
+
+   To build two DLLs, spam and ni (which uses C functions found in spam), you
+   could use these commands::
+
+       cl /LD /I/python/include spam.c
+       cl /LD /I/python/include ni.c spam.lib
+
+   The first command created three files: :file:`spam.obj`, :file:`spam.dll`
+   and :file:`spam.lib`.  :file:`Spam.dll` does not contain any Python
+   functions (such as :c:func:`PyArg_ParseTuple`), but it does know how to find
+   the Python code thanks to the implicitly linked :file:`pythonXY.lib`.
+
+   The second command created :file:`ni.dll` (and :file:`.obj` and
+   :file:`.lib`), which knows how to find the necessary functions from spam,
+   and also from the Python executable.
+
+2. Manually by defining :c:macro:`Py_NO_LINK_LIB` macro before including
+   :file:`Python.h`. You must pass :file:`pythonXY.lib` to the linker.
+
+   To build two DLLs, spam and ni (which uses C functions found in spam), you
+   could use these commands::
 
-   cl /LD /I/python/include spam.c ../libs/pythonXY.lib
-   cl /LD /I/python/include ni.c spam.lib ../libs/pythonXY.lib
+      cl /LD /DPy_NO_LINK_LIB /I/python/include spam.c ../libs/pythonXY.lib
+      cl /LD /DPy_NO_LINK_LIB /I/python/include ni.c spam.lib ../libs/pythonXY.lib
 
-The first command created three files: :file:`spam.obj`, :file:`spam.dll` and
-:file:`spam.lib`.  :file:`Spam.dll` does not contain any Python functions (such
-as :c:func:`PyArg_ParseTuple`), but it does know how to find the Python code
-thanks to :file:`pythonXY.lib`.
+   The first command created three files: :file:`spam.obj`, :file:`spam.dll`
+   and :file:`spam.lib`.  :file:`Spam.dll` does not contain any Python
+   functions (such as :c:func:`PyArg_ParseTuple`), but it does know how to find
+   the Python code thanks to :file:`pythonXY.lib`.
 
-The second command created :file:`ni.dll` (and :file:`.obj` and :file:`.lib`),
-which knows how to find the necessary functions from spam, and also from the
-Python executable.
+   The second command created :file:`ni.dll` (and :file:`.obj` and
+   :file:`.lib`), which knows how to find the necessary functions from spam,
+   and also from the Python executable.
 
 Not every identifier is exported to the lookup table.  If you want any other
 modules (including Python) to be able to see your identifiers, you have to say

Doc/library/asyncio-subprocess.rst

@@ -68,7 +68,7 @@ Creating Subprocesses
    Create a subprocess.
 
    The *limit* argument sets the buffer limit for :class:`StreamReader`
-   wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
+   wrappers for :attr:`~asyncio.subprocess.Process.stdout` and :attr:`~asyncio.subprocess.Process.stderr`
    (if :const:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
 
    Return a :class:`~asyncio.subprocess.Process` instance.
@@ -87,7 +87,7 @@ Creating Subprocesses
    Run the *cmd* shell command.
 
    The *limit* argument sets the buffer limit for :class:`StreamReader`
-   wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
+   wrappers for :attr:`~asyncio.subprocess.Process.stdout` and :attr:`~asyncio.subprocess.Process.stderr`
    (if :const:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
 
    Return a :class:`~asyncio.subprocess.Process` instance.
@@ -132,12 +132,12 @@ Constants
 
    If *PIPE* is passed to *stdin* argument, the
    :attr:`Process.stdin <asyncio.subprocess.Process.stdin>` attribute
-   will point to a :class:`StreamWriter` instance.
+   will point to a :class:`~asyncio.StreamWriter` instance.
 
    If *PIPE* is passed to *stdout* or *stderr* arguments, the
    :attr:`Process.stdout <asyncio.subprocess.Process.stdout>` and
    :attr:`Process.stderr <asyncio.subprocess.Process.stderr>`
-   attributes will point to :class:`StreamReader` instances.
+   attributes will point to :class:`~asyncio.StreamReader` instances.
 
 .. data:: asyncio.subprocess.STDOUT
    :module:
@@ -165,7 +165,7 @@ their completion.
    :module:
 
    An object that wraps OS processes created by the
-   :func:`create_subprocess_exec` and :func:`create_subprocess_shell`
+   :func:`~asyncio.create_subprocess_exec` and :func:`~asyncio.create_subprocess_shell`
    functions.
 
    This class is designed to have a similar API to the
@@ -263,24 +263,24 @@ their completion.
 
       Kill the child process.
 
-      On POSIX systems this method sends :py:data:`SIGKILL` to the child
+      On POSIX systems this method sends :py:data:`~signal.SIGKILL` to the child
       process.
 
       On Windows this method is an alias for :meth:`terminate`.
 
    .. attribute:: stdin
 
-      Standard input stream (:class:`StreamWriter`) or ``None``
+      Standard input stream (:class:`~asyncio.StreamWriter`) or ``None``
       if the process was created with ``stdin=None``.
 
    .. attribute:: stdout
 
-      Standard output stream (:class:`StreamReader`) or ``None``
+      Standard output stream (:class:`~asyncio.StreamReader`) or ``None``
       if the process was created with ``stdout=None``.
 
    .. attribute:: stderr
 
-      Standard error stream (:class:`StreamReader`) or ``None``
+      Standard error stream (:class:`~asyncio.StreamReader`) or ``None``
       if the process was created with ``stderr=None``.
 
    .. warning::
@@ -296,7 +296,7 @@ their completion.
 
       Process identification number (PID).
 
-      Note that for processes created by the :func:`create_subprocess_shell`
+      Note that for processes created by the :func:`~asyncio.create_subprocess_shell`
       function, this attribute is the PID of the spawned shell.
 
    .. attribute:: returncode

Doc/library/functions.rst

@@ -1405,10 +1405,10 @@ are always available.  They are listed here in alphabetical order.
    :func:`io.TextIOWrapper.reconfigure`. When no *buffering* argument is
    given, the default buffering policy works as follows:
 
-   * Binary files are buffered in fixed-size chunks; the size of the buffer is
-     chosen using a heuristic trying to determine the underlying device's "block
-     size" and falling back on :const:`io.DEFAULT_BUFFER_SIZE`.  On many systems,
-     the buffer will typically be 4096 or 8192 bytes long.
+   * Binary files are buffered in fixed-size chunks; the size of the buffer
+     is ``max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE)``
+     when the device block size is available.
+     On most systems, the buffer will typically be 128 kilobytes long.
 
    * "Interactive" text files (files for which :meth:`~io.IOBase.isatty`
      returns ``True``) use line buffering.  Other text files use the policy

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

@@ -1147,6 +1147,55 @@ Text I/O
    It inherits from :class:`codecs.IncrementalDecoder`.
 
 
+Static Typing
+-------------
+
+The following protocols can be used for annotating function and method
+arguments for simple stream reading or writing operations. They are decorated
+with :deco:`typing.runtime_checkable`.
+
+.. class:: Reader[T]
+
+   Generic protocol for reading from a file or other input stream. ``T`` will
+   usually be :class:`str` or :class:`bytes`, but can be any type that is
+   read from the stream.
+
+   .. versionadded:: next
+
+   .. method:: read()
+               read(size, /)
+
+      Read data from the input stream and return it. If *size* is
+      specified, it should be an integer, and at most *size* items
+      (bytes/characters) will be read.
+
+   For example::
+
+     def read_it(reader: Reader[str]):
+         data = reader.read(11)
+         assert isinstance(data, str)
+
+.. class:: Writer[T]
+
+   Generic protocol for writing to a file or other output stream. ``T`` will
+   usually be :class:`str` or :class:`bytes`, but can be any type that can be
+   written to the stream.
+
+   .. versionadded:: next
+
+   .. method:: write(data, /)
+
+      Write *data* to the output stream and return the number of items
+      (bytes/characters) written.
+
+   For example::
+
+     def write_binary(writer: Writer[bytes]):
+         writer.write(b"Hello world!\n")
+
+See :ref:`typing-io` for other I/O related protocols and classes that can be
+used for static type checking.
+
 Performance
 -----------
 

Doc/library/pdb.rst

@@ -75,25 +75,34 @@ The debugger's prompt is ``(Pdb)``, which is the indicator that you are in debug
    arguments of the ``p`` command.
 
 
+.. program:: pdb
+
 You can also invoke :mod:`pdb` from the command line to debug other scripts.  For
 example::
 
-   python -m pdb myscript.py
+   python -m pdb [-c command] (-m module | pyfile) [args ...]
 
 When invoked as a module, pdb will automatically enter post-mortem debugging if
 the program being debugged exits abnormally.  After post-mortem debugging (or
 after normal exit of the program), pdb will restart the program.  Automatic
 restarting preserves pdb's state (such as breakpoints) and in most cases is more
 useful than quitting the debugger upon program's exit.
 
-.. versionchanged:: 3.2
-   Added the ``-c`` option to execute commands as if given
-   in a :file:`.pdbrc` file; see :ref:`debugger-commands`.
+.. option:: -c, --command <command>
 
-.. versionchanged:: 3.7
-   Added the ``-m`` option to execute modules similar to the way
-   ``python -m`` does. As with a script, the debugger will pause execution just
-   before the first line of the module.
+   To execute commands as if given in a :file:`.pdbrc` file; see
+   :ref:`debugger-commands`.
+
+   .. versionchanged:: 3.2
+      Added the ``-c`` option.
+
+.. option:: -m <module>
+
+   To execute modules similar to the way ``python -m`` does. As with a script,
+   the debugger will pause execution just before the first line of the module.
+
+   .. versionchanged:: 3.7
+      Added the ``-m`` option.
 
 Typical usage to execute a statement under control of the debugger is::
 
@@ -245,6 +254,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)