gh-155742: Check singletons consistency at Python exit (#157572)

In debug mode at Python exit, check if immutable singleton objects
have been modified by mistake to detect bugs in C extensions.

Add tests corrupting bytes, str, bool and int singleton objects.

Add pycore_global_objects_fini.h internal header file.
pycore_global_objects_fini_generated.h is now fully generated by the
script.

Co-authored-by: Petr Viktorin <encukou@gmail.com>

Author: vstinner

Include/internal/pycore_global_objects_fini.h

@@ -0,0 +1,94 @@
+#ifndef Py_INTERNAL_GLOBAL_OBJECTS_FINI_H
+#define Py_INTERNAL_GLOBAL_OBJECTS_FINI_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef Py_BUILD_CORE
+#  error "this header requires Py_BUILD_CORE define"
+#endif
+
+#ifdef Py_DEBUG
+
+#include "pycore_bytesobject.h"   // _PyBytes_CheckOverflow()
+#include "pycore_long.h"          // TAG_FROM_SIGN_AND_SIZE()
+
+static inline void
+_PyStaticObject_CheckSingleton(PyObject *obj, PyTypeObject *type)
+{
+    // Check PyObject.ob_refcnt
+    _PyObject_ASSERT(obj, _Py_IsImmortal(obj));
+
+    // Check PyObject.ob_type
+    _PyObject_ASSERT(obj, Py_TYPE(obj) == type);
+}
+
+
+static void
+_PyStaticObject_CheckLongSingleton(PyObject *obj, long value, int is_bool)
+{
+    PyTypeObject *type = is_bool ? &PyBool_Type : &PyLong_Type;
+    _PyStaticObject_CheckSingleton(obj, type);
+
+    // Check _PyLong_CompactValue()
+    Py_ssize_t compact = _PyLong_CompactValue((const PyLongObject *)obj);
+    _PyObject_ASSERT(obj, compact == value);
+
+    // Check tv_tag and ob_digit[0]
+    _PyLongValue *long_value = &((PyLongObject*)obj)->long_value;
+    int sign = (value == 0) ? 0 : ((value < 0) ? -1 : 1);
+    uintptr_t lv_tag = TAG_FROM_SIGN_AND_SIZE(sign, (value == 0) ? 0 : 1);
+    if (!is_bool) {
+        lv_tag |= IMMORTALITY_BIT_MASK;
+    }
+    _PyObject_ASSERT(obj, long_value->lv_tag == lv_tag);
+    _PyObject_ASSERT(obj, long_value->ob_digit[0] == Py_ABS(value));
+}
+
+
+static inline void
+_PyStaticObject_CheckBytesSingleton(PyObject *obj,
+                                    Py_ssize_t size, unsigned char ch)
+{
+    _PyStaticObject_CheckSingleton(obj, &PyBytes_Type);
+    _PyObject_ASSERT(obj, PyBytes_GET_SIZE(obj) == size);
+    const unsigned char *str = (const unsigned char *)PyBytes_AS_STRING(obj);
+    _PyObject_ASSERT(obj, str[0] == ch);
+    _PyBytes_CheckOverflow(obj, obj, "bytes singleton");
+}
+
+static void
+_PyStaticObject_CheckUnicode(PyObject *obj, const char *str, Py_ssize_t length)
+{
+    _PyStaticObject_CheckSingleton(obj, &PyUnicode_Type);
+    _PyObject_ASSERT(obj, _PyUnicode_CheckConsistency(obj, 1));
+    _PyObject_ASSERT(obj, PyUnicode_GET_LENGTH(obj) == length);
+    _PyObject_ASSERT(obj, PyUnicode_KIND(obj) == PyUnicode_1BYTE_KIND);
+    const Py_UCS1 *data = PyUnicode_1BYTE_DATA(obj);
+    _PyObject_ASSERT(obj, memcmp(data, str, length) == 0);
+    _PyObject_ASSERT(obj, data[length] == 0);
+}
+
+
+static void
+_PyStaticObject_CheckUnicodeCharSingleton(PyObject *obj, unsigned char ch)
+{
+    _PyStaticObject_CheckUnicode(obj, (char *)&ch, 1);
+    _PyObject_ASSERT(obj, PyUnicode_IS_ASCII(obj) == (ch <= 127));
+}
+
+
+static void
+_PyStaticObject_CheckUnicodeSingleton(PyObject *obj,
+                                      const char *str, Py_ssize_t length)
+{
+    _PyStaticObject_CheckUnicode(obj, str, length);
+    _PyObject_ASSERT(obj, PyUnicode_IS_ASCII(obj));
+}
+
+#endif  // Py_DEBUG
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* !Py_INTERNAL_GLOBAL_OBJECTS_FINI_H */

Include/internal/pycore_global_objects_fini_generated.h

@@ -3094,5 +3094,51 @@ def test_ceval_decref(self):
         self.assertEqual(lines.count("DESTROY list"), 2)
 
 
+@unittest.skipUnless(support.Py_DEBUG, 'need Py_DEBUG')
+class TestCheckSingleton(unittest.TestCase):
+    # Test that _PyStaticObjects_CheckAll() detects memory corruptions in
+    # singleton objects at Python exit.
+
+    def check(self, code):
+        code = f"""if 1:
+            import _testcapi
+            from test import support
+            support.SuppressCrashReport().__enter__()
+            {code}
+        """
+        proc = assert_python_failure("-c", code)
+        return proc.err
+
+    def test_corrupt_bytes(self):
+        stderr = self.check("_testcapi.corrupt_bytes(b'a', b'#')")
+
+        self.assertIn((b'_PyStaticObject_CheckBytesSingleton: '
+                       b'Assertion "str[0] == ch" failed'), stderr)
+        self.assertIn(b"object repr     : b'#'", stderr)
+
+    def test_corrupt_unicode(self):
+        stderr = self.check("_testcapi.corrupt_unicode('a', '#')")
+
+        self.assertIn((b'_PyStaticObject_CheckUnicode: '
+                       b'Assertion "memcmp(data, str, length) == 0" failed'), stderr)
+        self.assertIn(b"object repr     : '#'", stderr)
+
+    def test_corrupt_bool(self):
+        stderr = self.check("_testcapi.corrupt_long(True, 0)")
+
+        self.assertIn((b'_PyStaticObject_CheckLongSingleton: '
+                       b'Assertion "compact == value" failed'),
+                      stderr)
+        self.assertIn(b"object repr     : True", stderr)
+
+    def test_corrupt_long(self):
+        stderr = self.check("_testcapi.corrupt_long(5, 42)")
+
+        self.assertIn((b'_PyStaticObject_CheckLongSingleton: '
+                       b'Assertion "compact == value" failed'),
+                      stderr)
+        self.assertIn(b"object repr     : 42", stderr)
+
+
 if __name__ == "__main__":
     unittest.main()

Lib/test/test_capi/test_misc.py

@@ -1345,6 +1345,7 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/internal/pycore_getopt.h \
 		$(srcdir)/Include/internal/pycore_gil.h \
 		$(srcdir)/Include/internal/pycore_global_objects.h \
+		$(srcdir)/Include/internal/pycore_global_objects_fini.h \
 		$(srcdir)/Include/internal/pycore_global_objects_fini_generated.h \
 		$(srcdir)/Include/internal/pycore_global_strings.h \
 		$(srcdir)/Include/internal/pycore_hamt.h \

Makefile.pre.in

@@ -0,0 +1,2 @@
+In debug mode at Python exit, check if immutable singleton objects have been
+modified by mistake to detect bugs in C extensions. Patch by Victor Stinner.

Misc/NEWS.d/next/Core_and_Builtins/2026-09-15-17-04-54.gh-issue-155742.2DUW_9.rst

@@ -567,6 +567,21 @@ bytearray_overflow(PyObject *Py_UNUSED(module), PyObject *args)
 }
 
 
+// Write into an immutable bytes object to test _PyStaticObjects_CheckAll()
+static PyObject *
+corrupt_bytes(PyObject *Py_UNUSED(module), PyObject *args)
+{
+    char *bytes, *override;
+    Py_ssize_t size;
+    if (!PyArg_ParseTuple(args, "yy#", &bytes, &override, &size)) {
+        return NULL;
+    }
+
+    memcpy(bytes, override, size);
+    Py_RETURN_NONE;
+}
+
+
 static PyMethodDef test_methods[] = {
     {"bytes_resize", bytes_resize, METH_VARARGS},
     {"bytes_join", bytes_join, METH_VARARGS},
@@ -576,6 +591,7 @@ static PyMethodDef test_methods[] = {
     {"test_byteswriter_ptr", test_byteswriter_ptr, METH_NOARGS},
     {"bytes_overflow", bytes_overflow, METH_VARARGS},
     {"bytearray_overflow", bytearray_overflow, METH_VARARGS},
+    {"corrupt_bytes", corrupt_bytes, METH_VARARGS},
     {NULL},
 };
 

Modules/_testcapi/bytes.c

@@ -281,6 +281,21 @@ get_pylong_layout(PyObject *module, PyObject *Py_UNUSED(args))
 }
 
 
+// Write into an immutable int object to test _PyStaticObjects_CheckAll()
+static PyObject *
+corrupt_long(PyObject *Py_UNUSED(module), PyObject *args)
+{
+    PyObject *obj;
+    int value;
+    if (!PyArg_ParseTuple(args, "Oi", &obj, &value)) {
+        return NULL;
+    }
+
+    ((PyLongObject*)obj)->long_value.ob_digit[0] = value;
+    Py_RETURN_NONE;
+}
+
+
 static PyMethodDef test_methods[] = {
     _TESTCAPI_CALL_LONG_COMPACT_API_METHODDEF
     {"pylong_fromunicodeobject",    pylong_fromunicodeobject,   METH_VARARGS},
@@ -295,6 +310,7 @@ static PyMethodDef test_methods[] = {
     {"pylong_ispositive",           pylong_ispositive,          METH_O},
     {"pylong_isnegative",           pylong_isnegative,          METH_O},
     {"pylong_iszero",               pylong_iszero,              METH_O},
+    {"corrupt_long",                corrupt_long,               METH_VARARGS},
     {NULL},
 };
 

Modules/_testcapi/long.c

@@ -276,6 +276,25 @@ _Py_COMP_DIAG_POP
 }
 
 
+// Write into an immutable str object to test _PyStaticObjects_CheckAll()
+static PyObject *
+corrupt_unicode(PyObject *Py_UNUSED(module), PyObject *args)
+{
+    PyObject *obj, *override;
+    if (!PyArg_ParseTuple(args, "OO", &obj, &override)) {
+        return NULL;
+    }
+    assert(PyUnicode_KIND(obj) == PyUnicode_1BYTE_KIND);
+    assert(PyUnicode_KIND(override) == PyUnicode_1BYTE_KIND);
+
+    Py_UCS1 *dst = PyUnicode_1BYTE_DATA(obj);
+    Py_UCS1 *src = PyUnicode_1BYTE_DATA(override);
+    Py_ssize_t size = PyUnicode_GET_LENGTH(override);
+    memcpy(dst, src, size);
+    Py_RETURN_NONE;
+}
+
+
 // --- PyUnicodeWriter type -------------------------------------------------
 
 typedef struct {
@@ -622,6 +641,7 @@ static PyMethodDef TestMethods[] = {
     {"unicode_copycharacters",   unicode_copycharacters,         METH_VARARGS},
     {"unicode_GET_CACHED_HASH",  unicode_GET_CACHED_HASH,        METH_O},
     {"test_py_identifier",       test_py_identifier,             METH_NOARGS},
+    {"corrupt_unicode",          corrupt_unicode,                METH_VARARGS},
     {NULL},
 };
 

Modules/_testcapi/unicode.c

@@ -261,6 +261,7 @@
     <ClInclude Include="..\Include\internal\pycore_getopt.h" />
     <ClInclude Include="..\Include\internal\pycore_gil.h" />
     <ClInclude Include="..\Include\internal\pycore_global_objects.h" />
+    <ClInclude Include="..\Include\internal\pycore_global_objects_fini.h" />
     <ClInclude Include="..\Include\internal\pycore_global_objects_fini_generated.h" />
     <ClInclude Include="..\Include\internal\pycore_hamt.h" />
     <ClInclude Include="..\Include\internal\pycore_hashtable.h" />

PCbuild/pythoncore.vcxproj

@@ -702,6 +702,9 @@
     <ClInclude Include="..\Include\internal\pycore_global_objects.h">
       <Filter>Include\internal</Filter>
     </ClInclude>
+    <ClInclude Include="..\Include\internal\pycore_global_objects_fini.h">
+      <Filter>Include\internal</Filter>
+    </ClInclude>
     <ClInclude Include="..\Include\internal\pycore_global_objects_fini_generated.h">
       <Filter>Include\internal</Filter>
     </ClInclude>