Mark BirdLoader as deprecated (#153)

Author: joshuadavidthomas

CHANGELOG.md

@@ -32,6 +32,7 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 ### Deprecated
 
 - The built-in asset serving view (`asset_view`) is deprecated and will be removed in the next minor version (v0.14.0). Use `BirdAssetFinder` with Django's staticfiles app.
+- The `BirdLoader` template loader is deprecated and will be removed in a future version. If you have enabled manual configuration by setting `ENABLE_AUTO_CONFIG=False`, please remove `django_bird.loader.BirdLoader` from your `TEMPLATES` setting.
 
 ### Removed
 

docs/configuration.md

@@ -70,7 +70,6 @@ If you would like to disable this behavior and perform the setup manually, setti
 When `ENABLE_AUTO_CONFIG` is set to `False`, you need to manually configure the following:
 
 1. Add django-bird's template tags to Django's built-ins.
-2. Include django-bird's loader in your template loaders, ensuring it comes before Django's default filesystem and app directories loaders.
 
 The complete setup in your settings file should look like this:
 
@@ -95,22 +94,12 @@ TEMPLATES = [
             "builtins": [
                 "django_bird.templatetags.django_bird",
             ],
-            "loaders": [
-                (
-                    "django.template.loaders.cached.Loader",
-                    [
-                        "django_bird.loader.BirdLoader",
-                        "django.template.loaders.filesystem.Loader",
-                        "django.template.loaders.app_directories.Loader",
-                    ],
-                ),
-            ],
         },
     }
 ]
 ```
 
-This configuration ensures that django-bird's templatetags are available globally and that its loader is used to compile bird component templates before the standard Django loaders.
+This configuration ensures that django-bird's templatetags are available globally.
 
 ## `ENABLE_BIRD_ATTRS`
 

src/django_bird/conf.py

@@ -17,7 +17,6 @@
 
 DJANGO_BIRD_BUILTINS = "django_bird.templatetags.django_bird"
 DJANGO_BIRD_FINDER = "django_bird.staticfiles.BirdAssetFinder"
-DJANGO_BIRD_LOADER = "django_bird.loader.BirdLoader"
 
 
 @dataclass
@@ -70,33 +69,13 @@ def configure_templates(self) -> None:
 
         options = template_config.setdefault("OPTIONS", {})
 
-        self.configure_loaders(options)
         self.configure_builtins(options)
 
         # Force re-evaluation of settings.TEMPLATES because EngineHandler caches it.
         with suppress(AttributeError):
             del django.template.engines.templates
             django.template.engines._engines = {}  # type: ignore[attr-defined]
 
-    def configure_loaders(self, options: dict[str, Any]) -> None:
-        loaders = options.setdefault("loaders", [])
-
-        # find the inner-most loaders, which is an iterable of only strings
-        while not all(isinstance(loader, str) for loader in loaders):
-            for loader in loaders:
-                # if we've found a list or tuple, we aren't yet in the inner-most loaders
-                if isinstance(loader, list | tuple):
-                    # reassign `loaders` variable to force the while loop restart
-                    loaders = loader
-
-        # if django-bird's loader is the first, we good
-        loaders_already_configured = (
-            len(loaders) > 0 and DJANGO_BIRD_LOADER == loaders[0]
-        )
-
-        if not loaders_already_configured:
-            loaders.insert(0, DJANGO_BIRD_LOADER)
-
     def configure_builtins(self, options: dict[str, Any]) -> None:
         builtins = options.setdefault("builtins", [])
 

src/django_bird/loader.py

@@ -1,16 +1,18 @@
 from __future__ import annotations
 
-from django.template.base import Origin
+import warnings
+
 from django.template.engine import Engine
 from django.template.loaders.filesystem import Loader as FileSystemLoader
 
-from ._typing import override
-
 
 class BirdLoader(FileSystemLoader):
     def __init__(self, engine: Engine):
+        warnings.warn(
+            "BirdLoader is deprecated and will be removed in a future version. "
+            "Please remove 'django_bird.loader.BirdLoader' from your TEMPLATES setting "
+            "in settings.py and use Django's built-in 'django.template.loaders.filesystem.Loader' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         super().__init__(engine)
-
-    @override
-    def get_contents(self, origin: Origin) -> str:
-        return super().get_contents(origin)

tests/conftest.py

@@ -48,7 +48,6 @@ def pytest_configure(config):
                     "django_bird.templatetags.django_bird",
                 ],
                 "loaders": [
-                    "django_bird.loader.BirdLoader",
                     "django.template.loaders.filesystem.Loader",
                     "django.template.loaders.app_directories.Loader",
                 ],
@@ -127,7 +126,6 @@ def _create_template(template_file: Path) -> DjangoTemplate:
         engine = Engine(
             builtins=["django_bird.templatetags.django_bird"],
             dirs=[str(template_file.parent)],
-            loaders=["django_bird.loader.BirdLoader"],
         )
         template = engine.get_template(template_file.name)
         backend = DjangoTemplates(