add component registry for caching lookups (#63)

* add component registry for caching lookups

* add cachetools dep directly

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* rename library-wide registry instance to components

* update changelog

* add cachetools typeshed stubs

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* be more specific on exception

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: joshuadavidthomas

CHANGELOG.md

@@ -18,9 +18,15 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+### Added
+
+- Added component caching with LRU (Least Recently Used) strategy via global `components` registry.
+  - `cachetools>=5.5.0` is now a dependency of the library to support this new cache strategy
+
 ### Changed
 
 - **Internal**: Flattened package structure by moving files from `components/` subdirectory to root level. No public API changes.
+- **Internal**: `BirdNode` now uses cached components instead of creating new ones each time.
 
 ## [0.4.0]
 

pyproject.toml

@@ -31,7 +31,8 @@ docs = [
 types = [
   "django-stubs>=5.1.0",
   "django-stubs-ext>=5.1.0",
-  "mypy>=1.11.2"
+  "mypy>=1.11.2",
+  "types-cachetools>=5.5.0.20240820"
 ]
 
 [project]
@@ -56,6 +57,7 @@ classifiers = [
   "Programming Language :: Python :: Implementation :: CPython"
 ]
 dependencies = [
+  "cachetools>=5.5.0",
   "django>=4.2"
 ]
 description = "High-flying components for perfectionists with deadlines"

src/django_bird/components.py

@@ -1,17 +1,14 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
 from typing import Any
 
+from cachetools import LRUCache
 from django.template.backends.django import Template
 from django.template.loader import select_template
 
 from .templates import get_template_names
 
-if TYPE_CHECKING:
-    pass
-
 
 @dataclass(frozen=True, slots=True)
 class Component:
@@ -30,3 +27,23 @@ def from_name(cls, name: str):
         template_names = get_template_names(name)
         template = select_template(template_names)
         return cls(name=name, template=template)
+
+
+class Registry:
+    def __init__(self, maxsize: int = 100):
+        self._cache: LRUCache[str, Component] = LRUCache(maxsize=maxsize)
+
+    def get_component(self, name: str) -> Component:
+        try:
+            return self._cache[name]
+        except KeyError:
+            component = Component.from_name(name)
+            self._cache[name] = component
+            return component
+
+    def clear(self) -> None:
+        """Clear the component cache. Mainly useful for testing."""
+        self._cache.clear()
+
+
+components = Registry()

src/django_bird/templatetags/tags/bird.py

@@ -12,6 +12,7 @@
 from django_bird._typing import TagBits
 from django_bird._typing import override
 from django_bird.components import Component
+from django_bird.components import components
 from django_bird.params import Params
 from django_bird.slots import DEFAULT_SLOT
 from django_bird.slots import Slots
@@ -59,7 +60,7 @@ def __init__(self, name: str, params: Params, nodelist: NodeList | None) -> None
     @override
     def render(self, context: Context) -> str:
         component_name = self.get_component_name(context)
-        component = Component.from_name(component_name)
+        component = components.get_component(component_name)
         component_context = self.get_component_context_data(component, context)
         return component.render(component_context)
 

tests/conftest.py

@@ -72,7 +72,7 @@ def override_templates_settings(base_dir):
 def create_bird_dir(base_dir):
     def func(name):
         bird_template_dir = base_dir / name
-        bird_template_dir.mkdir()
+        bird_template_dir.mkdir(exist_ok=True)
         return bird_template_dir
 
     return func
@@ -118,3 +118,12 @@ def func(text):
         return text.strip()
 
     return func
+
+
+@pytest.fixture(autouse=True)
+def clear_registry():
+    from django_bird.components import components
+
+    components.clear()
+    yield
+    components.clear()

tests/test_components.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import pytest
+from django.template.backends.django import Template
+from django.template.exceptions import TemplateDoesNotExist
+
+from django_bird.components import Component
+from django_bird.components import Registry
+
+
+class TestComponent:
+    def test_from_name(self, create_bird_template):
+        create_bird_template("button", "<button>Click me</button>")
+
+        comp = Component.from_name("button")
+
+        assert comp.name == "button"
+        assert isinstance(comp.template, Template)
+        assert comp.render({}) == "<button>Click me</button>"
+
+
+class TestRegistry:
+    @pytest.fixture
+    def registry(self):
+        return Registry(maxsize=2)
+
+    def test_get_component_caches(self, registry, create_bird_template):
+        create_bird_template(name="button", content="<button>Click me</button>")
+
+        component1 = registry.get_component("button")
+        component2 = registry.get_component("button")
+
+        assert component1 is component2
+
+    def test_lru_cache_behavior(self, registry, create_bird_template):
+        create_bird_template(name="button1", content="1")
+        create_bird_template(name="button2", content="2")
+        create_bird_template(name="button3", content="3")
+
+        button1 = registry.get_component("button1")
+        button2 = registry.get_component("button2")
+        button3 = registry.get_component("button3")
+
+        new_button1 = registry.get_component("button1")
+        assert new_button1 is not button1
+
+        cached_button2 = registry.get_component("button2")
+        assert cached_button2.name == button2.name
+        assert cached_button2.render({}) == button2.render({})
+
+        cached_button3 = registry.get_component("button3")
+        assert cached_button3.name == button3.name
+        assert cached_button3.render({}) == button3.render({})
+
+    def test_component_not_found(self, registry):
+        with pytest.raises(TemplateDoesNotExist):
+            registry.get_component("nonexistent")