Merge branch 'main' into claude/elegant-faraday-p69m3r

Author: gpshead

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/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/library/ctypes.rst

@@ -3675,6 +3675,12 @@ fields, or any other data types containing pointer type fields.
 
       point = Point(1, 2)
 
+   .. note::
+
+      Calling :func:`super` without arguments in methods of the decorated
+      class raises a :exc:`TypeError`. Use the two-argument form instead, for example
+      ``super(Point, self).__init__(x, y)``.
+
    *align*, *layout*, and *pack* supply the value for the :attr:`~ctypes.Structure._align_`,
    :attr:`~ctypes.Structure._layout_`, and :attr:`~ctypes.Structure._pack_`
    attributes, respectively.

Lib/bdb.py

@@ -747,7 +747,7 @@ def clear_all_file_breaks(self, filename):
             return 'There are no breakpoints in %s' % filename
         for line in self.breaks[filename]:
             blist = Breakpoint.bplist[filename, line]
-            for bp in blist:
+            for bp in blist[:]:
                 bp.deleteMe()
         del self.breaks[filename]
         return None

Lib/test/test_bdb.py

@@ -965,6 +965,17 @@ def main():
             with TracerRun(self) as tracer:
                 tracer.runcall(tfunc_import)
 
+    def test_clear_all_file_breaks_same_line(self):
+        reset_Breakpoint()
+        self.addCleanup(reset_Breakpoint)
+        debugger = Bdb()
+        for _ in range(3):
+            self.assertIsNone(debugger.set_break(__file__, 1))
+        self.assertIsNone(debugger.clear_all_file_breaks(__file__))
+        self.assertEqual(debugger.get_all_breaks(), {})
+        self.assertEqual(_bdb.Breakpoint.bplist, {})
+        self.assertTrue(all(bp is None for bp in _bdb.Breakpoint.bpbynumber))
+
     def test_clear_at_no_bp(self):
         self.expect_set = [
             ('line', 2, 'tfunc_import'), ('clear', (__file__, 1))

Lib/test/test_ctypes/test_simplesubclasses.py

@@ -1,5 +1,6 @@
 import unittest
-from ctypes import Structure, CFUNCTYPE, c_int, _SimpleCData
+from collections.abc import Hashable
+from ctypes import Structure, CFUNCTYPE, c_int, _SimpleCData, POINTER
 from ._support import (_CData, PyCSimpleType, Py_TPFLAGS_DISALLOW_INSTANTIATION,
                        Py_TPFLAGS_IMMUTABLETYPE)
 
@@ -26,6 +27,28 @@ def test_type_flags(self):
                 self.assertTrue(_SimpleCData.__flags__ & Py_TPFLAGS_IMMUTABLETYPE)
                 self.assertFalse(_SimpleCData.__flags__ & Py_TPFLAGS_DISALLOW_INSTANTIATION)
 
+    def test_unhashable(self):
+        # gh-78327: CData objects are mutable and must not be hashable.
+        class S(Structure):
+            _fields_ = [("a", c_int)]
+
+        for cls in c_int, S, c_int * 2, POINTER(c_int), CFUNCTYPE(None):
+            with self.subTest(cls=cls):
+                self.assertIsNone(cls.__hash__)
+                obj = cls()
+                self.assertNotIsInstance(obj, Hashable)
+                with self.assertRaisesRegex(TypeError,
+                                            f"unhashable type: '{cls.__name__}'"):
+                    hash(obj)
+
+        # Subclasses can still opt in to hashing.
+        class H(S):
+            def __hash__(self):
+                return 42
+
+        self.assertEqual(hash(H()), 42)
+        self.assertIsInstance(H(), Hashable)
+
     def test_metaclass_details(self):
         # Abstract classes (whose metaclass __init__ was not called) can't be
         # instantiated directly

Lib/test/test_embed.py

@@ -273,16 +273,27 @@ def test_create_module_from_initfunc(self):
         out, err = self.run_embedded_interpreter("test_create_module_from_initfunc")
         self.assertEqual(self._nogil_filtered_err(err, "embedded_ext"), "")
         self.assertEqual(out,
-                         "<module 'my_test_extension' (static-extension)>\n"
-                         "my_test_extension.executed='yes'\n"
-                         "my_test_extension.exec_slot_ran='yes'\n"
-                         "<module 'embedded_ext' (static-extension)>\n"
-                         "embedded_ext.executed='yes'\n"
-                         "<module 'sp_pkg.sp_submod' (static-extension)>\n"
-                         "sp_pkg.sp_submod.__name__='sp_pkg.sp_submod'\n"
-                         "sys.modules[\"sp_pkg.sp_submod\"] is sp_pkg.sp_submod=True\n"
-                         "\"sp_submod\" in sys.modules=False\n"
-                         )
+            # multi-phase init: not in sys.modules until importlib adds it
+            "created my_test_extension: in sys.modules=False\n"
+            "<module 'my_test_extension' (static-extension)>\n"
+            "my_test_extension.executed='yes'\n"
+            "my_test_extension.exec_slot_ran='yes'\n"
+            # single-phase init: added to sys.modules by the init function
+            "created embedded_ext: in sys.modules=True\n"
+            "<module 'embedded_ext' (static-extension)>\n"
+            "embedded_ext.executed='yes'\n"
+            # same name, different initfuncs: the cached module is
+            # returned and the second initfunc is never called
+            "a.which='A' b.which='A' a is b=True\n"
+            "create_static_module.initfunc_calls()=(1, 0)\n"
+            # Static extension
+            "created sp_pkg: in sys.modules=False\n"
+            "created sp_pkg.sp_submod: in sys.modules=True\n"
+            "<module 'sp_pkg.sp_submod' (static-extension)>\n"
+            "sp_pkg.sp_submod.__name__='sp_pkg.sp_submod'\n"
+            "sys.modules[\"sp_pkg.sp_submod\"] is sp_pkg.sp_submod=True\n"
+            "\"sp_submod\" in sys.modules=False\n"
+        )
 
     def test_inittab_submodule_multiphase(self):
         out, err = self.run_embedded_interpreter("test_inittab_submodule_multiphase")