gh-129027: Raise DeprecationWarning for sys._clear_type_cache (#129043)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Doc/deprecations/pending-removal-in-future.rst

@@ -153,3 +153,6 @@ although there is currently no date scheduled for their removal.
   :class:`~xml.etree.ElementTree.Element` is deprecated. In a future release it
   will always return ``True``. Prefer explicit ``len(elem)`` or
   ``elem is not None`` tests instead.
+
+* :func:`sys._clear_type_cache` is deprecated:
+  use :func:`sys._clear_internal_caches` instead.

Doc/whatsnew/3.14.rst

@@ -1246,6 +1246,9 @@ sys
 * On FreeBSD, :data:`sys.platform` doesn't contain the major version anymore.
   It is always ``'freebsd'``, instead of ``'freebsd13'`` or ``'freebsd14'``.
 
+* Raise :exc:`DeprecationWarning` for :func:`sys._clear_type_cache`. This
+  function was deprecated in Python 3.13 but it didn't raise a runtime warning.
+
 
 sys.monitoring
 --------------

Lib/test/test_cmd_line.py

@@ -9,6 +9,7 @@ import sysconfig
 import tempfile
 import textwrap
 import unittest
+import warnings
 from test import support
 from test.support import os_helper
 from test.support import force_not_colorized
@@ -936,14 +937,20 @@ class CmdLineTest(unittest.TestCase):
     @unittest.skipUnless(sysconfig.get_config_var('Py_TRACE_REFS'), "Requires --with-trace-refs build option")
     def test_python_dump_refs(self):
         code = 'import sys; sys._clear_type_cache()'
-        rc, out, err = assert_python_ok('-c', code, PYTHONDUMPREFS='1')
+        # TODO: Remove warnings context manager once sys._clear_type_cache is removed
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            rc, out, err = assert_python_ok('-c', code, PYTHONDUMPREFS='1')
         self.assertEqual(rc, 0)
 
     @unittest.skipUnless(sysconfig.get_config_var('Py_TRACE_REFS'), "Requires --with-trace-refs build option")
     def test_python_dump_refs_file(self):
         with tempfile.NamedTemporaryFile() as dump_file:
             code = 'import sys; sys._clear_type_cache()'
-            rc, out, err = assert_python_ok('-c', code, PYTHONDUMPREFSFILE=dump_file.name)
+            # TODO: Remove warnings context manager once sys._clear_type_cache is removed
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", DeprecationWarning)
+                rc, out, err = assert_python_ok('-c', code, PYTHONDUMPREFSFILE=dump_file.name)
             self.assertEqual(rc, 0)
             with open(dump_file.name, 'r') as file:
                 contents = file.read()

Lib/test/test_sys.py

@@ -891,7 +891,9 @@ class SysModuleTest(unittest.TestCase):
 
     @test.support.cpython_only
     def test_clear_type_cache(self):
-        sys._clear_type_cache()
+        with self.assertWarnsRegex(DeprecationWarning,
+                                   r"sys\._clear_type_cache\(\) is deprecated.*"):
+            sys._clear_type_cache()
 
     @force_not_colorized
     @support.requires_subprocess()

Lib/test/test_type_cache.py

@@ -1,6 +1,7 @@
 """ Tests for the internal type cache in CPython. """
-import unittest
 import dis
+import unittest
+import warnings
 from test import support
 from test.support import import_helper, requires_specialization, requires_specialization_ft
 try:
@@ -16,6 +17,10 @@ type_assign_specific_version_unsafe = _testinternalcapi.type_assign_specific_ver
 type_assign_version = _testcapi.type_assign_version
 type_modified = _testcapi.type_modified
 
+def clear_type_cache():
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        _clear_type_cache()
 
 @support.cpython_only
 @unittest.skipIf(_clear_type_cache is None, "requires sys._clear_type_cache")
@@ -38,7 +43,7 @@ class TypeCacheTests(unittest.TestCase):
         append_result = all_version_tags.append
         assertNotEqual = self.assertNotEqual
         for _ in range(30):
-            _clear_type_cache()
+            clear_type_cache()
             X = type('Y', (), {})
             X.x = 1
             X.x
@@ -78,7 +83,7 @@ class TypeCacheTests(unittest.TestCase):
         new_version = type_get_version(C)
         self.assertEqual(new_version, orig_version + 5)
 
-        _clear_type_cache()
+        clear_type_cache()
 
     def test_per_class_limit(self):
         class C:
@@ -112,7 +117,7 @@ class TypeCacheTests(unittest.TestCase):
 @support.cpython_only
 class TypeCacheWithSpecializationTests(unittest.TestCase):
     def tearDown(self):
-        _clear_type_cache()
+        clear_type_cache()
 
     def _assign_valid_version_or_skip(self, type_):
         type_modified(type_)

Misc/NEWS.d/next/Library/2025-01-21-11-48-19.gh-issue-129027.w0vxzZ.rst

@@ -0,0 +1,2 @@
+Raise :exc:`DeprecationWarning` for :func:`sys._clear_type_cache`. This function was deprecated in Python 3.13
+but it didn't raise a runtime warning.

Python/sysmodule.c

@@ -2208,6 +2208,14 @@ static PyObject *
 sys__clear_type_cache_impl(PyObject *module)
 /*[clinic end generated code: output=20e48ca54a6f6971 input=127f3e04a8d9b555]*/
 {
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "sys._clear_type_cache() is deprecated and"
+                     " scheduled for removal in a future version."
+                     " Use sys._clear_internal_caches() instead.",
+                     1) < 0)
+    {
+        return NULL;
+    }
     PyType_ClearCache();
     Py_RETURN_NONE;
 }