gh-129027: Raise DeprecationWarning for sys._clear_type_cache

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

@@ -155,3 +155,6 @@ although there is currently no date scheduled for their removal.
 
 * :meth:`zipimport.zipimporter.load_module` is deprecated:
   use :meth:`~zipimport.zipimporter.exec_module` instead.
+
+* :func:`sys._clear_type_cache` is deprecated.
+  use :func:`sys._clear_internal_caches` instead.

Doc/whatsnew/3.14.rst

@@ -661,6 +661,8 @@ 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

@@ -11,7 +11,7 @@
 import unittest
 from test import support
 from test.support import os_helper
-from test.support import force_not_colorized
+from test.support import force_not_colorized, warnings_helper
 from test.support import threading_helper
 from test.support.script_helper import (
     spawn_python, kill_python, assert_python_ok, assert_python_failure,
@@ -932,12 +932,14 @@ def test_python_asyncio_debug(self):
         self.assertIn(b'True', out)
 
     @unittest.skipUnless(sysconfig.get_config_var('Py_TRACE_REFS'), "Requires --with-trace-refs build option")
+    @warnings_helper.ignore_warnings(category=DeprecationWarning)
     def test_python_dump_refs(self):
         code = 'import sys; sys._clear_type_cache()'
         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")
+    @warnings_helper.ignore_warnings(category=DeprecationWarning)
     def test_python_dump_refs_file(self):
         with tempfile.NamedTemporaryFile() as dump_file:
             code = 'import sys; sys._clear_type_cache()'

Lib/test/test_sys.py

@@ -850,7 +850,9 @@ def test_sys_getwindowsversion_no_instantiation(self):
 
     @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

@@ -2,7 +2,10 @@
 import unittest
 import dis
 from test import support
-from test.support import import_helper, requires_specialization, requires_specialization_ft
+from test.support import (
+    import_helper, requires_specialization,
+    requires_specialization_ft, warnings_helper
+)
 try:
     from sys import _clear_type_cache
 except ImportError:
@@ -15,11 +18,13 @@
 type_assign_specific_version_unsafe = _testinternalcapi.type_assign_specific_version_unsafe
 type_assign_version = _testcapi.type_assign_version
 type_modified = _testcapi.type_modified
+ignore_deprecation = warnings_helper.ignore_warnings(category=DeprecationWarning)
 
 
 @support.cpython_only
 @unittest.skipIf(_clear_type_cache is None, "requires sys._clear_type_cache")
 class TypeCacheTests(unittest.TestCase):
+    @ignore_deprecation
     def test_tp_version_tag_unique(self):
         """tp_version_tag should be unique assuming no overflow, even after
         clearing type cache.
@@ -61,6 +66,7 @@ class C:
         self.assertNotEqual(type_get_version(C), 0)
         self.assertNotEqual(type_get_version(C), c_ver)
 
+    @ignore_deprecation
     def test_type_assign_specific_version(self):
         """meta-test for type_assign_specific_version_unsafe"""
         class C:
@@ -111,6 +117,8 @@ class HolderSub(Holder):
 
 @support.cpython_only
 class TypeCacheWithSpecializationTests(unittest.TestCase):
+
+    @ignore_deprecation
     def tearDown(self):
         _clear_type_cache()
 

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

@@ -0,0 +1,2 @@
+Raise 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

@@ -2146,6 +2146,13 @@ 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 the more general"
+                     " sys._clear_internal_caches() function instead.",
+                     1) < 0){
+        return NULL;
+    }
     PyType_ClearCache();
     Py_RETURN_NONE;
 }