kumaraditya303 · Jul 21, 2026 · May 15, 2026 · May 20, 2026 · May 20, 2026 · May 20, 2026
diff --git a/Include/cpython/object.h b/Include/cpython/object.h
@@ -246,6 +246,8 @@ struct _typeobject {
       * This function must escape to any code that can result in
       * the GC being run, such as Py_DECREF.  */
     _Py_iteritemfunc _tp_iteritem;
+
+    void *_tp_cache;
 };
 
 #define _Py_ATTR_CACHE_UNUSED (30000)  // (see tp_versions_used)

diff --git a/Include/internal/pycore_interp_structs.h b/Include/internal/pycore_interp_structs.h
@@ -556,23 +556,6 @@ struct _types_runtime_state {
 };
 
 
-// Type attribute lookup cache: speed up attribute and method lookups,
-// see _PyType_Lookup().
-struct type_cache_entry {
-    unsigned int version;  // initialized from type->tp_version_tag
-#ifdef Py_GIL_DISABLED
-   _PySeqLock sequence;
-#endif
-    PyObject *name;        // reference to exactly a str or None
-    PyObject *value;       // borrowed reference or NULL
-};
-
-#define MCACHE_SIZE_EXP 12
-
-struct type_cache {
-    struct type_cache_entry hashtable[1 << MCACHE_SIZE_EXP];
-};
-
 typedef struct {
     PyTypeObject *type;
     int isbuiltin;
@@ -587,6 +570,10 @@ typedef struct {
        are also some diagnostic uses for the list of weakrefs,
        so we still keep it. */
     PyObject *tp_weaklist;
+    /* Per-interpreter attribute lookup cache (struct type_cache *).
+       For static builtin types the cache must be per-interpreter
+       because tp_dict and the values it stores are per-interpreter. */
+    void *_tp_cache;
 } managed_static_type_state;
 
 #define TYPE_VERSION_CACHE_SIZE (1<<12)  /* Must be a power of 2 */
@@ -597,8 +584,6 @@ struct types_state {
        where all those lower numbers are used for core static types. */
     unsigned int next_version_tag;
 
-    struct type_cache type_cache;
-
     /* Every static builtin type is initialized for each interpreter
        during its own initialization, including for the main interpreter
        during global runtime initialization.  This is done by calling

diff --git a/Include/internal/pycore_object.h b/Include/internal/pycore_object.h
@@ -291,8 +291,6 @@ _PyType_HasFeature(PyTypeObject *type, unsigned long feature) {
     return ((type->tp_flags) & feature) != 0;
 }
 
-extern void _PyType_InitCache(PyInterpreterState *interp);
-
 extern PyStatus _PyObject_InitState(PyInterpreterState *interp);
 extern void _PyObject_FiniState(PyInterpreterState *interp);
 extern bool _PyRefchain_IsTraced(PyInterpreterState *interp, PyObject *obj);

diff --git a/Include/internal/pycore_typecache.h b/Include/internal/pycore_typecache.h
@@ -0,0 +1,47 @@
+#ifndef PY_INTERNAL_TYPECACHE_H
+#define PY_INTERNAL_TYPECACHE_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef Py_BUILD_CORE
+#  error "this header requires Py_BUILD_CORE define"
+#endif
+
+#include "pycore_stackref.h"
+
+
+#define _Py_TYPECACHE_MINSIZE (1 << 3)
+#define _Py_TYPECACHE_MAXSIZE (1 << 16)
+
+struct type_cache_entry {
+    PyObject *name;     // name of the attribute or method, interned string, NULL if the entry is empty
+    PyObject *value;    // borrowed reference or NULL
+};
+
+// Per-type attribute lookup cache: speed up attribute and method lookups,
+// see _PyTypeCache_Lookup().
+struct type_cache {
+    uint32_t mask;                          // mask for indexing into hashtable, i.e. size of hashtable is mask + 1
+    uint32_t version_tag;                   // initialized from type->tp_version_tag
+    uint32_t available;                     // number of available entries in hashtable
+    uint32_t used;                          // number of used entries in hashtable
+    struct type_cache_entry hashtable[];   // hashtable entries, the total size is always power of 2 and at least _Py_TYPECACHE_MINSIZE
+};
+
+struct _PyTypeCacheLookupResult {
+    _PyStackRef value;      // value is a stack reference to the cached attribute or method, or NULL if not found
+    int cache_hit;          // 1 if the cache entry is valid and matches the type's version tag, 0 otherwise
+    uint32_t version_tag;   // version tag of the type when the value was cached
+};
+
+
+extern void _PyTypeCache_InitType(PyTypeObject *type);
+extern void _PyTypeCache_Insert(PyTypeObject *type, PyObject *name, PyObject *value);
+PyAPI_FUNC(struct _PyTypeCacheLookupResult) _PyTypeCache_Lookup(PyTypeObject *type, PyObject *name);
+PyAPI_FUNC(void) _PyTypeCache_Invalidate(PyTypeObject *type);
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* PY_INTERNAL_TYPECACHE_H */
diff --git a/Lib/test/test_free_threading/test_type.py b/Lib/test/test_free_threading/test_type.py
@@ -4,8 +4,10 @@
 from concurrent.futures import ThreadPoolExecutor
 from threading import Thread
 from unittest import TestCase
+import sys
+from test.support import import_helper, threading_helper
 
-from test.support import threading_helper
+_testinternalcapi = import_helper.import_module("_testinternalcapi")
 
 
 
@@ -84,6 +86,24 @@ def reader_func():
 
         self.run_one(writer_func, reader_func)
 
+    def test_attr_cache_mortal(self):
+        class C:
+            x = object()
+
+        class D(C):
+            pass
+
+        def writer_func():
+            for _ in range(3000):
+                C.x = object()
+
+        def reader_func():
+            for _ in range(3000):
+                C.x
+                D.x
+
+        self.run_one(writer_func, reader_func)
+
     def test___class___modification(self):
         loops = 200
 
@@ -160,6 +180,51 @@ def reader():
 
         self.run_one(writer, reader)
 
+    def test_per_type_cache_concurrent_reads(self):
+        class C:
+            pass
+
+        names = [sys.intern(f"attr_{i}") for i in range(
+            _testinternalcapi._Py_TYPECACHE_MINSIZE * 4)]
+        for name in names:
+            setattr(C, name, name)
+        # Prime the cache.
+        for name in names:
+            getattr(C, name)
+
+        lookup = _testinternalcapi.type_cache_lookup
+
+        def reader():
+            for _ in range(500):
+                for name in names:
+                    hit, value, _ = lookup(C, name)
+                    self.assertEqual(hit, 1, name)
+                    self.assertEqual(value, name)
+
+        threading_helper.run_concurrently(reader, nthreads=NTHREADS)
+
+    def test_per_type_cache_concurrent_invalidate(self):
+        class C:
+            x = "value"
+
+        # Prime the cache.
+        C.x
+        hit, value, version = _testinternalcapi.type_cache_lookup(C, "x")
+        self.assertEqual(hit, 1)
+        self.assertIs(value, "value")
+        self.assertGreater(version, 0)
+
+        def reader():
+            for _ in range(10_000):
+                self.assertIs(C.x, "value")
+
+        def invalidator():
+            for _ in range(10_000):
+                _testinternalcapi.type_cache_invalidate(C)
+
+        workers = [invalidator] + [reader] * (NTHREADS - 1)
+        threading_helper.run_concurrently(workers)
+
     def run_one(self, writer_func, reader_func):
         barrier = threading.Barrier(NTHREADS)
 

diff --git a/Lib/test/test_sys.py b/Lib/test/test_sys.py
@@ -1788,7 +1788,7 @@ def delx(self): del self.__x
         check((1,2,3), vsize('') + self.P + 3*self.P)
         # type
         # static type: PyTypeObject
-        fmt = 'P2nPI13Pl4Pn9Pn12PI2Pc'
+        fmt = 'P2nPI13Pl4Pn9Pn12PI2PcP'
         s = vsize(fmt)
         check(int, s)
         typeid = 'n' if support.Py_GIL_DISABLED else ''

@@ -1,6 +1,7 @@
 """ Tests for the internal type cache in CPython. """
 import collections.abc
 import dis
+import sys
 import unittest
 import warnings
 from test import support
@@ -281,5 +282,163 @@ def to_bool_2(instance):
         self._check_specialization(to_bool_2, H(), "TO_BOOL", should_specialize=False)
 
 
+@support.cpython_only
+class PerTypeLookupCacheTests(unittest.TestCase):
+    """Tests for the per-type lookup cache."""
+
+    type_cache_lookup = staticmethod(_testinternalcapi.type_cache_lookup)
+    type_cache_invalidate = staticmethod(_testinternalcapi.type_cache_invalidate)
+
+    def _make_type(self):
+        class C:
+            x = "x-value"
+        return C
+
+    def test_lookup_miss_on_empty_cache(self):
+        # A freshly-created type has not cached any names yet; the cache
+        # should report a miss for an arbitrary name.
+        C = self._make_type()
+        hit, value, version = self.type_cache_lookup(C, "x")
+        self.assertEqual(hit, 0)
+        self.assertIsNone(value)
+        self.assertEqual(version, 0)
+
+    def test_lookup_hit_after_access(self):
+        # Reading an attribute goes through _PyType_Lookup which
+        # caches the result. Subsequent lookups for the same name
+        # should hit the cache.
+        C = self._make_type()
+        hit, value, version = self.type_cache_lookup(C, "x")
+        self.assertEqual(hit, 0)
+        attr = C.x
+        hit, value, version = self.type_cache_lookup(C, "x")
+        self.assertEqual(hit, 1)
+        self.assertIs(value, attr)
+        self.assertNotEqual(version, 0)
+        self.assertEqual(version, type_get_version(C))
+
+    def test_lookup_caches_missing_name(self):
+        # _PyType_Lookup caches negative results too: a name that is not in
+        # the MRO should still produce a cache hit with a None value.
+        C = self._make_type()
+        with self.assertRaises(AttributeError):
+            C.does_not_exist
+        hit, value, _ = self.type_cache_lookup(C, "does_not_exist")
+        self.assertEqual(hit, 1)
+        self.assertIsNone(value)
+
+    def test_lookup_on_static_type(self):
+        # The cache for static types is stored on interpreter for isolation
+        # between subinterpreters, test that cache works for them as well.
+        self.type_cache_invalidate(int)
+        name = sys.intern("bit_length")
+        self.assertEqual(self.type_cache_lookup(int, name)[0], 0)
+        attr = getattr(int, name)
+        hit, value, _ = self.type_cache_lookup(int, name)
+        self.assertEqual(hit, 1)
+        self.assertIs(value, attr)
+
+    def test_invalidate_clears_cache(self):
+        C = self._make_type()
+        C.x  # populate cache
+        self.assertEqual(self.type_cache_lookup(C, "x")[0], 1)
+
+        self.type_cache_invalidate(C)
+        hit, value, _ = self.type_cache_lookup(C, "x")
+        self.assertEqual(hit, 0)
+        self.assertIsNone(value)
+
+    def test_setattr_invalidates_cache(self):
+        # Mutating a type's attributes must invalidate any cached entries
+        # for that type.
+        C = self._make_type()
+        C.x
+        self.assertEqual(self.type_cache_lookup(C, "x")[0], 1)
+
+        C.x = "new-value"
+        hit, _, _ = self.type_cache_lookup(C, "x")
+        self.assertEqual(hit, 0)
+
+        # The next access should re-populate the cache with the new value.
+        self.assertEqual(C.x, "new-value")
+        hit, value, _ = self.type_cache_lookup(C, "x")
+        self.assertEqual(hit, 1)
+        self.assertEqual(value, "new-value")
+
+    def test_setattr_on_subclass_preserves_base(self):
+        # Adding an attribute to a subclass changes the lookup result for
+        # the subclass, so its cache must be invalidated, but the base's
+        # cache for the same name stays valid.
+        class Base:
+            x = "base"
+        class Sub(Base):
+            pass
+
+        self.assertEqual(Sub.x, "base")
+        self.assertEqual(Base.x, "base")
+        self.assertEqual(self.type_cache_lookup(Sub, "x")[0], 1)
+        self.assertEqual(self.type_cache_lookup(Base, "x")[0], 1)
+
+        Sub.x = "sub"
+        # Sub's cache should be invalidated.
+        self.assertEqual(self.type_cache_lookup(Sub, "x")[0], 0)
+        # Base is untouched.
+        hit, value, _ = self.type_cache_lookup(Base, "x")
+        self.assertEqual(hit, 1)
+        self.assertEqual(value, "base")
+
+    def test_setattr_on_base_invalidates_subclass(self):
+        class Base:
+            x = "base"
+        class Sub(Base):
+            pass
+
+        Sub.x
+        self.assertEqual(self.type_cache_lookup(Sub, "x")[0], 1)
+
+        Base.x = "new-base"
+        # Modifying the base must invalidate the subclass cache too.
+        self.assertEqual(self.type_cache_lookup(Sub, "x")[0], 0)
+
+    def test_lookup_detects_stale_cache_version(self):
+        # The cache stores the type's tp_version_tag alongside its entries
+        # and re-checks it after locating a hit. If the type version moves
+        # forward without the cache being invalidated (the race window in
+        # lock-free invalidation), the consistency check must downgrade
+        # the hit to a miss.
+        C = self._make_type()
+        C.x  # populate cache
+        orig_version = type_get_version(C)
+        self.assertNotEqual(orig_version, 0)
+        self.assertEqual(self.type_cache_lookup(C, "x")[0], 1)
+
+        # Bump the type version directly without touching the cache slot
+        # (PyType_Modified would also invalidate, defeating the test).
+        type_assign_specific_version_unsafe(C, orig_version + 1)
+        self.assertEqual(type_get_version(C), orig_version + 1)
+
+        hit, value, _ = self.type_cache_lookup(C, "x")
+        self.assertEqual(hit, 0)
+        self.assertIsNone(value)
+
+    def test_setattr_on_unrelated_type_preserves_cache(self):
+        # Modifying one type must not invalidate a sibling's cache.
+        class A:
+            x = "a"
+        class B:
+            x = "b"
+
+        A.x
+        B.x
+        self.assertEqual(self.type_cache_lookup(A, "x")[0], 1)
+        self.assertEqual(self.type_cache_lookup(B, "x")[0], 1)
+
+        B.x = "b2"
+        # A's cache is unaffected.
+        hit, value, _ = self.type_cache_lookup(A, "x")
+        self.assertEqual(hit, 1)
+        self.assertEqual(value, "a")
+
+
 if __name__ == "__main__":
     unittest.main()
@@ -508,6 +508,7 @@ PYTHON_OBJS=	\
 		Python/thread.o \
 		Python/traceback.o \
 		Python/tracemalloc.o \
+		Python/typecache.o \
 		Python/uniqueid.o \
 		Python/getopt.o \
 		Python/pystrcmp.o \
@@ -1413,6 +1414,7 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/internal/pycore_tracemalloc.h \
 		$(srcdir)/Include/internal/pycore_tstate.h \
 		$(srcdir)/Include/internal/pycore_tuple.h \
+		$(srcdir)/Include/internal/pycore_typecache.h \
 		$(srcdir)/Include/internal/pycore_typedefs.h \
 		$(srcdir)/Include/internal/pycore_typeobject.h \
 		$(srcdir)/Include/internal/pycore_typevarobject.h \