Merge branch 'main' of github.com:python/cpython into mimallocv3

Author: DinoV

.github/CODEOWNERS

@@ -283,11 +283,10 @@ Programs/_bootstrap_python.c  @ericsnowcurrently @FFY00
 Programs/python.c             @ericsnowcurrently @FFY00
 
 # JIT
-.github/workflows/jit.yml     @savannahostrowski
-Include/internal/pycore_jit.h @brandtbucher @savannahostrowski @diegorusso
-Python/jit.c                  @brandtbucher @savannahostrowski @diegorusso
-Tools/jit/                    @brandtbucher @savannahostrowski @diegorusso
-InternalDocs/jit.md           @brandtbucher @savannahostrowski @diegorusso @AA-Turner
+Include/internal/pycore_jit.h @brandtbucher @diegorusso
+Python/jit.c                  @brandtbucher @diegorusso
+Tools/jit/                    @brandtbucher @diegorusso
+InternalDocs/jit.md           @brandtbucher @diegorusso @AA-Turner
 
 # Lazy imports (PEP 810)
 .github/workflows/reusable-test-lazy-imports-all.yml    @yhg1s @DinoV @pablogsal
@@ -297,9 +296,9 @@ Lib/test/test_lazy_import                               @yhg1s @DinoV @pablogsal
 
 # Micro-op / μop / Tier 2 Optimiser
 Python/optimizer.c            @markshannon @Fidget-Spinner
-Python/optimizer_analysis.c   @markshannon @tomasr8 @Fidget-Spinner @savannahostrowski
-Python/optimizer_bytecodes.c  @markshannon @tomasr8 @Fidget-Spinner @savannahostrowski
-Python/optimizer_symbols.c    @markshannon @tomasr8 @Fidget-Spinner @savannahostrowski
+Python/optimizer_analysis.c   @markshannon @tomasr8 @Fidget-Spinner
+Python/optimizer_bytecodes.c  @markshannon @tomasr8 @Fidget-Spinner
+Python/optimizer_symbols.c    @markshannon @tomasr8 @Fidget-Spinner
 
 # Parser, Lexer, and Grammar
 Grammar/python.gram           @pablogsal @lysnikolaou

Doc/c-api/extension-modules.rst

@@ -313,16 +313,32 @@ This is typically done using :c:func:`PyModule_Create` and functions like
 Single-phase initialization differs from the :ref:`default <multi-phase-initialization>`
 in the following ways:
 
-* Single-phase modules are, or rather *contain*, “singletons”.
+* Single-phase modules with :c:member:`PyModuleDef.m_size` set to -1 are,
+  or rather *contain*, “singletons”.
 
-  When the module is first initialized, Python saves the contents of
+  When such a module is first initialized, Python saves the contents of
   the module's ``__dict__`` (that is, typically, the module's functions and
   types).
 
   For subsequent imports, Python does not call the initialization function
   again.
   Instead, it creates a new module object with a new ``__dict__``, and copies
   the saved contents to it.
+  Modules are matched to the saved contents by a (*module_name*, *file_name*)
+  tuple where:
+
+  - *module_name* is the module's full dotted name, taken from
+    :py:attr:`ModuleSpec.name <importlib.machinery.ModuleSpec.name>`
+    (or the equivalent argument of the importing function).
+    Note that names that the initialization function uses to create the module
+    (for example, :c:member:`PyModuleDef.m_name`) are not taken into account.
+  - *file_name* is the extension's file name.
+    It is unset for modules not loaded from a file, such as built-ins and
+    modules added with :c:func:`PyImport_CreateModuleFromInitfunc` or
+    :c:func:`PyImport_AppendInittab`.
+
+  As part of the first initialization, Python also adds the module to
+  :data:`sys.modules` under its name.
   For example, given a single-phase module ``_testsinglephase``
   [#testsinglephase]_ that defines a function ``sum`` and an exception class
   ``error``:
@@ -344,6 +360,16 @@ in the following ways:
 
   The exact behavior should be considered a CPython implementation detail.
 
+* For single-phase modules with non-negative :c:member:`PyModuleDef.m_size`,
+  Python may cache a pointer to the initialization function under the
+  (*module_name*, *file_name*) key as for ``m_size == -1``.
+
+  Subsequent imports that specify a different initialization function
+  (for example, using :c:func:`PyImport_CreateModuleFromInitfunc`)
+  may call either the cached function or the provided "new" one.
+
+  The exact behavior should again be considered a CPython implementation detail.
+
 * To work around the fact that ``PyInit_modulename`` does not take a *spec*
   argument, some state of the import machinery is saved and applied to the
   first suitable module created during the ``PyInit_modulename`` call.

Doc/c-api/file.rst

@@ -60,6 +60,29 @@ the :mod:`io` APIs instead.
    raised if the end of the file is reached immediately.
 
 
+.. c:function:: char* Py_UniversalNewlineFgets(char *buf, int n, FILE *stream, PyObject *fobj)
+
+   Read a line from the C stream *stream* into the buffer *buf*, like the
+   C standard library function :c:func:`!fgets`, but treating all of ``\n``,
+   ``\r`` and ``\r\n`` as line endings (see :term:`universal newlines`).
+   Any ``\r`` or ``\r\n`` read from the stream is stored in *buf* as a
+   single ``\n``.
+
+   At most ``n - 1`` characters are stored in *buf*; reading stops after a
+   newline has been stored or when the end of the file is reached.
+   The result is always null-terminated.
+   *stream* should be opened in binary mode, so that the C library does not
+   perform its own newline translation.
+
+   Return *buf* on success.
+   Return ``NULL`` if no characters could be read, because *stream* is at
+   end of file, a read error occurred, or *n* is less than 2.
+   Like :c:func:`!fgets`, this function does not distinguish between end of
+   file and a read error, and it does not set an exception.
+
+   *fobj* exists only for backward compatibility and must be ``NULL``.
+
+
 .. c:function:: int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)
 
    Overrides the normal behavior of :func:`io.open_code` to pass its parameter

Doc/c-api/float.rst

@@ -214,7 +214,7 @@ Pack functions
 The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
 :c:expr:`int` argument, non-zero if you want the bytes string in little-endian
 format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` and ``p+7``), zero if you
-want big-endian format (exponent first, at *p*). Use the :c:macro:`!PY_LITTLE_ENDIAN`
+want big-endian format (exponent first, at *p*). Use the :c:macro:`PY_LITTLE_ENDIAN`
 constant to select the native endian: it is equal to ``0`` on big
 endian processor, or ``1`` on little endian processor.
 
@@ -240,7 +240,7 @@ Unpack functions
 The unpack routines read 2, 4 or 8 bytes, starting at *p*.  *le* is an
 :c:expr:`int` argument, non-zero if the bytes string is in little-endian format
 (exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian
-(exponent first, at *p*). Use the :c:macro:`!PY_LITTLE_ENDIAN` constant to
+(exponent first, at *p*). Use the :c:macro:`PY_LITTLE_ENDIAN` constant to
 select the native endian: it is equal to ``0`` on big endian processor, or ``1``
 on little endian processor.
 

Doc/c-api/import.rst

@@ -408,7 +408,7 @@ Importing Modules
 
    *spec* must be a :class:`~importlib.machinery.ModuleSpec` object.
 
-   *initfunc* must be an :ref:`initialization function <extension-export-hook>`,
+   *initfunc* must be an :ref:`initialization function <extension-pyinit>`,
    the same as for :c:func:`PyImport_AppendInittab`.
 
    On success, create and return a module object.
@@ -417,10 +417,27 @@ Importing Modules
    (Custom importers should do this in their
    :py:meth:`~importlib.abc.Loader.exec_module` method.)
 
-   If the spec's name is dotted and *initfunc* creates the module using only
-   the last component of the name, the module's :attr:`~module.__name__`
-   is set to the full name from the spec.
-
    On error, return NULL with an exception set.
 
+   For modules using :ref:`legacy single-phase initialization <single-phase-initialization>`,
+   most of the import process is done in this function, rather than in
+   extra steps that importers typically take after
+   :py:meth:`~importlib.abc.Loader.create_module`.
+   Specifically:
+
+   - The module is added to :data:`sys.modules` under the *spec*'s
+     :py:attr:`~importlib.machinery.ModuleSpec.name` as part of initialization.
+   - If a single-phase module was previously imported under the
+     same :py:attr:`~importlib.machinery.ModuleSpec.name` by this function
+     or as a built-in module (for example, one registered with
+     :c:func:`PyImport_AppendInittab`), Python may reuse the previous module's
+     contents instead of calling *initfunc* again.
+   - The module will be fully initialized by *initfunc*.
+     Calling :c:func:`PyModule_Exec` on it will have no effect, though it is
+     still recommended, in case the module later switches to
+     :ref:`multi-phase initialization <multi-phase-initialization>`.
+   - Also, if the *spec*'s :py:attr:`!name` contains dots, this name is used
+     for prepending a parent package to the new module's
+     :attr:`~module.__name__`.
+
    .. versionadded:: 3.15

Doc/c-api/interp-lifecycle.rst

@@ -265,6 +265,48 @@ Initializing and finalizing the interpreter
    first initialized).
 
 
+.. c:function:: int Py_FrozenMain(int argc, char **argv)
+
+   .. index:: single: freeze utility
+
+   The main program for a "frozen" Python program (an executable that embeds
+   the interpreter together with the bytecode of the program's modules, as
+   produced by the :program:`freeze` utility; see :source:`Tools/freeze`).
+
+   This function initializes the interpreter, imports the frozen module named
+   ``__main__``, and finalizes the interpreter.
+   The frozen modules must have been registered in
+   :c:var:`PyImport_FrozenModules` before calling this function;
+   it is a fatal error if ``__main__`` is not among them.
+
+   *argc* and *argv* are byte strings like the arguments of a C program's
+   ``main`` function, and are passed to the interpreter with
+   :c:func:`PyConfig_SetBytesArgv`.
+   Unlike :c:func:`Py_Main`, the arguments are not parsed as Python command
+   line options (:c:member:`PyConfig.parse_argv` is ``0``), so all of them
+   are made available to the program in :data:`sys.argv`.
+   Apart from that, the interpreter uses the
+   :ref:`Python Configuration <init-python-config>`, so environment variables
+   such as :envvar:`PYTHONPATH` are honored.
+   Warnings about the path configuration
+   (:c:member:`PyConfig.pathconfig_warnings`) are suppressed.
+   If :envvar:`PYTHONINSPECT` is set and standard input is a terminal, an
+   interactive prompt is run after ``__main__`` has finished, as with the
+   :option:`-i` option.
+
+   Return ``0`` if ``__main__`` ran without an unhandled exception, ``1``
+   otherwise, and ``120`` if finalizing the interpreter failed (see
+   :c:func:`Py_FinalizeEx`).
+   An unhandled :exc:`SystemExit` terminates the process.
+   If the interpreter cannot be initialized, the process exits via
+   :c:func:`Py_ExitStatusException`.
+
+   On Windows, this function is not exported by the Python DLL.
+   The :program:`freeze` utility compiles :file:`Python/frozenmain.c` into the
+   frozen program instead, together with the Windows-specific hooks that the
+   function requires.
+
+
 .. c:function:: int Py_RunMain(void)
 
    Executes the main module in a fully configured CPython runtime.

Doc/c-api/intro.rst

@@ -299,6 +299,12 @@ Numeric utilities
    Argument must be a character or an integer in the range [-128, 127] or [0,
    255].  This macro returns ``c`` cast to an ``unsigned char``.
 
+.. c:macro:: PY_BIG_ENDIAN
+             PY_LITTLE_ENDIAN
+
+   Constants describing the byte order of the platform that Python was built
+   for. Exactly one of them is ``1`` and the other is ``0``.
+
 
 Assertion utilities
 ^^^^^^^^^^^^^^^^^^^
@@ -916,8 +922,13 @@ use them.
 
    A signed integral type such that ``sizeof(Py_ssize_t) == sizeof(size_t)``.
    C99 doesn't define such a thing directly (size_t is an unsigned integral type).
-   See :pep:`353` for details. ``PY_SSIZE_T_MAX`` is the largest positive value
-   of type :c:type:`Py_ssize_t`.
+   See :pep:`353` for details.
+
+.. c:macro:: PY_SSIZE_T_MAX
+             PY_SSIZE_T_MIN
+
+   The limit values (largest positive one and smallest negative one,
+   respecitvely) of type :c:type:`Py_ssize_t`.
 
 
 .. _api-exceptions:

Doc/c-api/structures.rst

@@ -760,11 +760,20 @@ The following flags can be used with :c:member:`PyMemberDef.flags`:
 .. versionchanged:: 3.12
 
    The :c:macro:`!READONLY` macro was renamed to :c:macro:`Py_READONLY`.
-   The :c:macro:`!PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix.
+   The :c:macro:`PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix.
    The new names are now always available.
    Previously, these required ``#include "structmember.h"``.
    The header is still available and it provides the old names.
 
+.. c:macro:: PY_AUDIT_READ
+
+   Soft-deprecated alias of :c:macro:`Py_AUDIT_READ` (note capitalization of
+   the ``y``).
+   Only available with  ``#include "structmember.h"``.
+
+   .. soft-deprecated:: 3.12
+      Use :c:macro:`Py_AUDIT_READ` instead.
+
 .. _PyMemberDef-types:
 
 Member types

Doc/library/bdb.rst

@@ -17,6 +17,10 @@ The following exception is defined:
 
    Exception raised by the :class:`Bdb` class for quitting the debugger.
 
+   .. versionchanged:: 3.16
+      :exc:`BdbQuit` now inherits from :exc:`BaseException` instead of
+      :exc:`Exception`.
+
 
 The :mod:`!bdb` module also defines two classes: