Cache metadata-filtered class_traits()/traits() results per class

Filtering traits by metadata (e.g. class_traits(config=True)) was recomputed
from scratch on every call — the single largest cost of Application startup
(~25-30%), invoked ~45x per startup for results that are static per class
(from Application._classes_with_config_traits, KVArgParseConfigLoader.
_add_arguments, and each Configurable._load_config).

class_traits()/traits() now delegate to a shared classmethod that memoizes the
filtered dict per class and returns a .copy(), preserving the existing
"fresh dict" contract — the cached dict never escapes by reference. cls._traits
is frozen after class creation (add_traits() builds a new class rather than
mutating), so the only way a filtered result can change is a post-hoc metadata
mutation via tag()/set_metadata(); those bump a module-level generation counter
and stale cache entries (older than the current generation) are recomputed.
Only constant (non-callable, hashable) filters are cached; callable predicates
stay on the uncached path.

Measured (Python 3.11): class_traits(config=True) ~8.3us -> ~1.3us per call.

Note: the cache is invalidated by the supported post-construction metadata APIs
(tag()/set_metadata()). Mutating trait.metadata as a raw dict after the class
has already been queried is not reflected until the next generation bump; this
pattern is not used in traitlets and is vanishingly rare in practice.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaKDJ3fpGf7anQeYeBsJbk

Author: claude

tests/test_traitlets.py

@@ -937,6 +937,32 @@ class A(HasTraits):
         traits = a.traits(config_key=lambda v: True)
         self.assertEqual(traits, dict(i=A.i, f=A.f, j=A.j))
 
+    def test_traits_metadata_filter_caching(self):
+        # metadata-filtered class_traits()/traits() results are memoized per
+        # class; make sure the cache preserves the "fresh dict" contract and is
+        # invalidated when metadata is mutated after class creation.
+        class A(HasTraits):
+            i = Int().tag(config=True)
+            j = Int()
+
+        # returned dict is a fresh copy the caller may mutate freely
+        first = A.class_traits(config=True)
+        self.assertEqual(first, dict(i=A.i))
+        first["injected"] = "oops"
+        self.assertEqual(A.class_traits(config=True), dict(i=A.i))
+
+        # tagging a trait after the result was cached must be reflected
+        A.j.tag(config=True)
+        self.assertEqual(A.class_traits(config=True), dict(i=A.i, j=A.j))
+        self.assertEqual(A().traits(config=True), dict(i=A.i, j=A.j))
+
+        # a subclass has its own cache and does not pollute the parent's
+        class B(A):
+            k = Int().tag(config=True)
+
+        self.assertEqual(B.class_traits(config=True), dict(i=A.i, j=A.j, k=B.k))
+        self.assertEqual(A.class_traits(config=True), dict(i=A.i, j=A.j))
+
     def test_traits_metadata_deprecated(self):
         with expected_warnings([r"metadata should be set using the \.tag\(\) method"] * 2):
 

traitlets/traitlets.py

@@ -59,6 +59,12 @@
 
 SequenceTypes = (list, tuple, set, frozenset)
 
+# Bumped whenever trait metadata is mutated after class creation (via
+# TraitType.tag()/set_metadata()). Used to invalidate the per-class cache of
+# metadata-filtered traits kept by HasTraits._traits_matching_metadata. Kept in
+# a one-element list so it can be mutated without a module-level `global`.
+_trait_metadata_generation = [0]
+
 if t.TYPE_CHECKING:
     import pathlib
 
@@ -871,6 +877,7 @@ def set_metadata(self, key: str, value: t.Any) -> None:
         else:
             msg = "use the instance .metadata dictionary directly, like x.metadata[key] = value"
         warn("Deprecated in traitlets 4.1, " + msg, DeprecationWarning, stacklevel=2)
+        _trait_metadata_generation[0] += 1
         self.metadata[key] = value
 
     def tag(self, **metadata: t.Any) -> Self:
@@ -894,6 +901,7 @@ def tag(self, **metadata: t.Any) -> Self:
                 stacklevel=2,
             )
 
+        _trait_metadata_generation[0] += 1
         self.metadata.update(metadata)
         return self
 
@@ -1030,6 +1038,8 @@ def setup_class(cls: MetaHasTraits, classdict: dict[str, t.Any]) -> list[tuple[s
         # also looking at base classes
         cls._all_trait_default_generators = {}
         cls._traits = {}
+        # per-class cache for metadata-filtered class_traits()/traits() results
+        cls._traits_metadata_cache: dict[t.Any, tuple[int, dict[str, t.Any]]] = {}
         cls._static_immutable_initial_values = {}
 
         # Reuse the members collected by the parent metaclass rather than
@@ -1339,6 +1349,7 @@ class HasTraits(HasDescriptors, metaclass=MetaHasTraits):
     _trait_validators: dict[str | Sentinel, t.Any]
     _cross_validation_lock: bool
     _traits: dict[str, t.Any]
+    _traits_metadata_cache: dict[t.Any, tuple[int, dict[str, TraitType[t.Any, t.Any]]]]
     _all_trait_default_generators: dict[str, t.Any]
 
     def setup_instance(self, /, *args: t.Any, **kwargs: t.Any) -> None:
@@ -1802,21 +1813,64 @@ def class_traits(cls: type[HasTraits], **metadata: t.Any) -> dict[str, TraitType
         the output.  If a metadata key doesn't exist, None will be passed
         to the function.
         """
-        traits = cls._traits.copy()
-
         if len(metadata) == 0:
-            return traits
+            return cls._traits.copy()
+
+        # Return a copy so callers can freely mutate the result; the underlying
+        # (cached) dict must not escape by reference.
+        return cls._traits_matching_metadata(metadata).copy()
 
-        result = {}
-        for name, trait in traits.items():
-            for meta_name, meta_eval in metadata.items():
-                if not callable(meta_eval):
-                    meta_eval = _SimpleTest(meta_eval)
+    @classmethod
+    def _traits_matching_metadata(
+        cls: type[HasTraits], metadata: dict[str, t.Any]
+    ) -> dict[str, TraitType[t.Any, t.Any]]:
+        """Return the subset of ``cls._traits`` matching a metadata filter.
+
+        The result is shared, not copied — callers (``class_traits``/``traits``)
+        are responsible for copying before returning it to user code.
+
+        For filters whose values are all non-callable and hashable (the hot
+        path, e.g. ``config=True``), the result is memoized per class. Because
+        ``cls._traits`` is frozen after class creation, the only way the answer
+        can change is a post-hoc metadata mutation via ``tag()``/``set_metadata()``,
+        which bump ``_trait_metadata_generation``; cache entries older than the
+        current generation are recomputed.
+        """
+        # Build a cache key only for constant (non-callable) filters; callable
+        # predicates are the cold path and are never cached.
+        key: t.Any = None
+        if not any(callable(v) for v in metadata.values()):
+            try:
+                key = tuple(sorted(metadata.items()))
+                hash(key)  # ensure the values are hashable before use as a key
+            except TypeError:
+                key = None
+
+        generation = _trait_metadata_generation[0]
+        cache: dict[t.Any, tuple[int, dict[str, TraitType[t.Any, t.Any]]]] | None = (
+            cls.__dict__.get("_traits_metadata_cache")
+        )
+        if key is not None and cache is not None:
+            entry = cache.get(key)
+            if entry is not None and entry[0] == generation:
+                return entry[1]
+
+        # Normalize the metadata filters once, rather than rebuilding a
+        # _SimpleTest for every trait on every call.
+        checks = [
+            (meta_name, meta_eval if callable(meta_eval) else _SimpleTest(meta_eval))
+            for meta_name, meta_eval in metadata.items()
+        ]
+        result: dict[str, TraitType[t.Any, t.Any]] = {}
+        for name, trait in cls._traits.items():
+            for meta_name, meta_eval in checks:
                 if not meta_eval(trait.metadata.get(meta_name, None)):
                     break
             else:
                 result[name] = trait
 
+        if key is not None and cache is not None:
+            cache[key] = (generation, result)
         return result
 
     @classmethod
@@ -1935,22 +1989,12 @@ def traits(self, **metadata: t.Any) -> dict[str, TraitType[t.Any, t.Any]]:
         the output.  If a metadata key doesn't exist, None will be passed
         to the function.
         """
-        traits = self._traits.copy()
-
         if len(metadata) == 0:
-            return traits
-
-        result = {}
-        for name, trait in traits.items():
-            for meta_name, meta_eval in metadata.items():
-                if not callable(meta_eval):
-                    meta_eval = _SimpleTest(meta_eval)
-                if not meta_eval(trait.metadata.get(meta_name, None)):
-                    break
-            else:
-                result[name] = trait
+            return self._traits.copy()
 
-        return result
+        # Delegates to the (cached) class-level implementation; self._traits is
+        # always type(self)._traits. Return a copy so callers can mutate freely.
+        return type(self)._traits_matching_metadata(metadata).copy()
 
     def trait_metadata(self, traitname: str, key: str, default: t.Any = None) -> t.Any:
         """Get metadata values for trait by key."""