feat(jinja): migrate litestar.contrib.jinja to litestar.plugins.jinja (#4762)

cofin · xronocode · web-flow · commit 60d87d2a81d0 · 2026-05-13T22:25:02.000Z
Moves the Jinja2 template engine integration from `litestar.contrib.jinja` to `litestar.plugins.jinja`, and removes the contrib path on `main`. A follow-up PR onto `v2` will add a deprecation shim, giving 2.x users a migration window. Same shape as the OTel split (#4691 + #4759) and the repository split (#4735 + #4758). Implementation reference: PR #4752 by @xronocode. Every commit carries a co-author trailer. Salvages the contrib tests into `tests/unit/test_plugins/test_jinja.py`, migrates every internal call site (csrf middleware, flash, template suite, htmx examples), and adds `docs/reference/plugins/jinja.rst`. Closes #4716. Co-authored-by: xronocode <myevdokimov@gmail.com>
diff --git a/docs/conf.py b/docs/conf.py
@@ -191,7 +191,7 @@
     (PY_CLASS, "litestar.background_tasks.P"),
     (PY_CLASS, "P.args"),
     (PY_CLASS, "P.kwargs"),
-    (PY_CLASS, "litestar.contrib.jinja.P"),
+    (PY_CLASS, "litestar.plugins.jinja.P"),
     (PY_CLASS, "litestar.plugins.mako.P"),
     (PY_CLASS, "MiniJinjaTemplate"),
     (PY_CLASS, "litestar.plugins.minijinja.MiniJinjaTemplate"),
diff --git a/docs/examples/plugins/flash_messages/jinja.py b/docs/examples/plugins/flash_messages/jinja.py
@@ -1,7 +1,7 @@
 from litestar import Litestar
-from litestar.contrib.jinja import JinjaTemplateEngine
 from litestar.middleware.session.server_side import ServerSideSessionConfig
 from litestar.plugins.flash import FlashConfig, FlashPlugin
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.template.config import TemplateConfig
 
 template_config = TemplateConfig(engine=JinjaTemplateEngine, directory="templates")
diff --git a/docs/examples/plugins/flash_messages/usage.py b/docs/examples/plugins/flash_messages/usage.py
@@ -1,7 +1,7 @@
 from litestar import Litestar, Request, get
-from litestar.contrib.jinja import JinjaTemplateEngine
 from litestar.middleware.session.server_side import ServerSideSessionConfig
 from litestar.plugins.flash import FlashConfig, FlashPlugin, flash
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.response import Template
 from litestar.template.config import TemplateConfig
 
diff --git a/docs/examples/templating/engine_instance_jinja.py b/docs/examples/templating/engine_instance_jinja.py
@@ -1,4 +1,4 @@
-from litestar.contrib.jinja import JinjaTemplateEngine
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.template.config import TemplateConfig
 
 template_config = TemplateConfig(engine=JinjaTemplateEngine, directory="templates")
diff --git a/docs/examples/templating/returning_templates_jinja.py b/docs/examples/templating/returning_templates_jinja.py
@@ -1,7 +1,7 @@
 from pathlib import Path
 
 from litestar import Litestar, get
-from litestar.contrib.jinja import JinjaTemplateEngine
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.response import Template
 from litestar.template.config import TemplateConfig
 
diff --git a/docs/examples/templating/template_engine_jinja.py b/docs/examples/templating/template_engine_jinja.py
@@ -1,7 +1,7 @@
 from pathlib import Path
 
 from litestar import Litestar
-from litestar.contrib.jinja import JinjaTemplateEngine
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.template.config import TemplateConfig
 
 app = Litestar(
diff --git a/docs/examples/templating/template_functions_jinja.py b/docs/examples/templating/template_functions_jinja.py
@@ -2,7 +2,7 @@
 from typing import Any
 
 from litestar import Litestar, get
-from litestar.contrib.jinja import JinjaTemplateEngine
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.response import Template
 from litestar.template.config import TemplateConfig
 
diff --git a/docs/migration/flask.rst b/docs/migration/flask.rst
@@ -320,7 +320,7 @@ In addition to Jinja, Litestar supports `Mako <https://www.makotemplates.org/>`_
         .. code-block:: python
 
             from litestar import Litestar, get
-            from litestar.contrib.jinja import JinjaTemplateEngine
+            from litestar.plugins.jinja import JinjaTemplateEngine
             from litestar.response import Template
             from litestar.template.config import TemplateConfig
 
diff --git a/docs/reference/contrib/index.rst b/docs/reference/contrib/index.rst
@@ -1,7 +1,2 @@
 contrib
 =======
-
-.. toctree::
-    :maxdepth: 1
-
-    jinja
diff --git a/docs/reference/contrib/jinja.rst b/docs/reference/contrib/jinja.rst
diff --git a/docs/reference/plugins/index.rst b/docs/reference/plugins/index.rst
@@ -12,6 +12,7 @@ plugins
     attrs
     flash_messages
     htmx
+    jinja
     mako
     minijinja
     opentelemetry
diff --git a/docs/reference/plugins/jinja.rst b/docs/reference/plugins/jinja.rst
@@ -0,0 +1,6 @@
+=====
+jinja
+=====
+
+.. automodule:: litestar.plugins.jinja
+    :members:
diff --git a/docs/usage/htmx.rst b/docs/usage/htmx.rst
@@ -21,7 +21,7 @@ It can be installed via the ``litestar[htmx]`` package extra.
     from litestar.plugins.htmx import HTMXPlugin
     from litestar import Litestar
 
-    from litestar.contrib.jinja import JinjaTemplateEngine
+    from litestar.plugins.jinja import JinjaTemplateEngine
     from litestar.template.config import TemplateConfig
 
     from pathlib import Path
@@ -51,7 +51,7 @@ HTMX client.  You can configure this globally by using the ``HTMXPlugin`` or by
     from litestar import get, Litestar
     from litestar.response import Template
 
-    from litestar.contrib.jinja import JinjaTemplateEngine
+    from litestar.plugins.jinja import JinjaTemplateEngine
     from litestar.template.config import TemplateConfig
 
     from pathlib import Path
diff --git a/docs/usage/templating.rst b/docs/usage/templating.rst
@@ -80,7 +80,7 @@ The above example will create a jinja Environment instance, but you can also pas
 
 
     from litestar import Litestar
-    from litestar.contrib.jinja import JinjaTemplateEngine
+    from litestar.plugins.jinja import JinjaTemplateEngine
     from litestar.template import TemplateConfig
     from jinja2 import Environment, DictLoader
 
diff --git a/litestar/plugins/jinja.py b/litestar/plugins/jinja.py
@@ -1,4 +1,4 @@
-from __future__ import annotations
+"""Jinja2 template engine integration for Litestar."""
 
 from collections.abc import Mapping
 from typing import TYPE_CHECKING, Any, TypeVar
@@ -35,8 +35,8 @@ class JinjaTemplateEngine(TemplateEngineProtocol["JinjaTemplate", Mapping[str, A
 
     def __init__(
         self,
-        directory: Path | list[Path] | None = None,
-        engine_instance: Environment | None = None,
+        directory: "Path | list[Path] | None" = None,
+        engine_instance: "Environment | None" = None,
     ) -> None:
         """Jinja-based TemplateEngine.
 
@@ -55,7 +55,7 @@ def __init__(
         self.register_template_callable(key="csrf_token", template_callable=csrf_token)
         self.register_template_callable(key="url_for", template_callable=url_for)
 
-    def get_template(self, template_name: str) -> JinjaTemplate:
+    def get_template(self, template_name: str) -> "JinjaTemplate":
         """Retrieve a template by matching its name (dotted path) with files in the directory or directories provided.
 
         Args:
@@ -100,7 +100,7 @@ def render_string(self, template_string: str, context: Mapping[str, Any]) -> str
         return template.render(context)
 
     @classmethod
-    def from_environment(cls, jinja_environment: Environment) -> JinjaTemplateEngine:
+    def from_environment(cls, jinja_environment: "Environment") -> "JinjaTemplateEngine":
         """Create a JinjaTemplateEngine from an existing jinja Environment instance.
 
         Args:
diff --git a/tests/unit/test_middleware/test_csrf_middleware.py b/tests/unit/test_middleware/test_csrf_middleware.py
@@ -8,10 +8,10 @@
 
 from litestar import MediaType, WebSocket, delete, get, patch, post, put, websocket
 from litestar.config.csrf import CSRFConfig
-from litestar.contrib.jinja import JinjaTemplateEngine
 from litestar.enums import RequestEncodingType
 from litestar.handlers import HTTPRouteHandler
 from litestar.params import Body
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.plugins.mako import MakoTemplateEngine
 from litestar.response.template import Template
 from litestar.status_codes import HTTP_200_OK, HTTP_201_CREATED, HTTP_403_FORBIDDEN
diff --git a/tests/unit/test_plugins/test_flash.py b/tests/unit/test_plugins/test_flash.py
@@ -6,11 +6,11 @@
 import pytest
 
 from litestar import Litestar, Request, get, post
-from litestar.contrib.jinja import JinjaTemplateEngine
 from litestar.exceptions import ImproperlyConfiguredException
 from litestar.middleware.rate_limit import RateLimitConfig
 from litestar.middleware.session.server_side import ServerSideSessionConfig
 from litestar.plugins.flash import FlashConfig, FlashPlugin, flash
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.plugins.mako import MakoTemplateEngine
 from litestar.plugins.minijinja import MiniJinjaTemplateEngine
 from litestar.response import Redirect, Template
diff --git a/tests/unit/test_plugins/test_jinja.py b/tests/unit/test_plugins/test_jinja.py
@@ -0,0 +1,91 @@
+"""Functional tests for litestar.plugins.jinja."""
+
+from pathlib import Path
+
+import pytest
+from jinja2 import DictLoader, Environment
+
+from litestar.exceptions import ImproperlyConfiguredException, TemplateNotFoundException
+from litestar.plugins.jinja import JinjaTemplateEngine
+
+
+def test_init_with_directory(tmp_path: Path) -> None:
+    template_dir = tmp_path / "templates"
+    template_dir.mkdir()
+    (template_dir / "hello.html").write_text("Hello {{ name }}!")
+
+    engine = JinjaTemplateEngine(directory=template_dir)
+    assert isinstance(engine.engine, Environment)
+
+
+def test_init_with_directory_list(tmp_path: Path) -> None:
+    first = tmp_path / "first"
+    second = tmp_path / "second"
+    first.mkdir()
+    second.mkdir()
+
+    engine = JinjaTemplateEngine(directory=[first, second])
+    assert isinstance(engine.engine, Environment)
+
+
+def test_init_with_engine_instance() -> None:
+    env = Environment(loader=DictLoader({"hello.html": "Hi {{ name }}"}), autoescape=True)
+    engine = JinjaTemplateEngine(engine_instance=env)
+    assert engine.engine is env
+
+
+def test_init_raises_when_both_directory_and_engine_instance(tmp_path: Path) -> None:
+    env = Environment(loader=DictLoader({}))
+    with pytest.raises(ImproperlyConfiguredException):
+        JinjaTemplateEngine(directory=tmp_path, engine_instance=env)
+
+
+def test_from_environment_classmethod() -> None:
+    env = Environment(loader=DictLoader({}), autoescape=True)
+    engine = JinjaTemplateEngine.from_environment(env)
+    assert isinstance(engine, JinjaTemplateEngine)
+    assert engine.engine is env
+
+
+def test_get_template_returns_template(tmp_path: Path) -> None:
+    template_dir = tmp_path / "templates"
+    template_dir.mkdir()
+    (template_dir / "hello.html").write_text("Hello {{ name }}!")
+
+    engine = JinjaTemplateEngine(directory=template_dir)
+    template = engine.get_template("hello.html")
+    assert template.render({"name": "World"}) == "Hello World!"
+
+
+def test_get_template_raises_when_missing(tmp_path: Path) -> None:
+    template_dir = tmp_path / "templates"
+    template_dir.mkdir()
+    engine = JinjaTemplateEngine(directory=template_dir)
+    with pytest.raises(TemplateNotFoundException):
+        engine.get_template("missing.html")
+
+
+def test_render_string() -> None:
+    env = Environment(loader=DictLoader({}), autoescape=True)
+    engine = JinjaTemplateEngine(engine_instance=env)
+    rendered = engine.render_string("Hello {{ name }}!", {"name": "World"})
+    assert rendered == "Hello World!"
+
+
+def test_register_template_callable_adds_to_globals() -> None:
+    env = Environment(loader=DictLoader({}), autoescape=True)
+    engine = JinjaTemplateEngine(engine_instance=env)
+
+    def shout(_context: object, value: str) -> str:
+        return value.upper()
+
+    engine.register_template_callable(key="shout", template_callable=shout)
+    assert "shout" in engine.engine.globals
+
+
+def test_csrf_token_and_url_for_registered_by_default(tmp_path: Path) -> None:
+    template_dir = tmp_path / "templates"
+    template_dir.mkdir()
+    engine = JinjaTemplateEngine(directory=template_dir)
+    assert "csrf_token" in engine.engine.globals
+    assert "url_for" in engine.engine.globals
diff --git a/tests/unit/test_response/test_response_to_asgi_response.py b/tests/unit/test_response/test_response_to_asgi_response.py
@@ -11,8 +11,8 @@
 
 from litestar import Litestar, MediaType, Request, Response, get
 from litestar.background_tasks import BackgroundTask
-from litestar.contrib.jinja import JinjaTemplateEngine
 from litestar.datastructures import Cookie, ResponseHeader
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.response import ServerSentEvent
 from litestar.response.base import ASGIResponse
 from litestar.response.file import ASGIFileResponse, File
diff --git a/tests/unit/test_template/test_built_in.py b/tests/unit/test_template/test_built_in.py
@@ -9,7 +9,7 @@
 from mako.lookup import TemplateLookup  # type: ignore[import-untyped]
 
 from litestar import get
-from litestar.contrib.jinja import JinjaTemplateEngine
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.plugins.mako import MakoTemplateEngine
 from litestar.plugins.minijinja import MiniJinjaTemplateEngine
 from litestar.response.template import Template
diff --git a/tests/unit/test_template/test_builtin_functions.py b/tests/unit/test_template/test_builtin_functions.py
@@ -5,7 +5,7 @@
 import pytest
 
 from litestar import get
-from litestar.contrib.jinja import JinjaTemplateEngine
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.plugins.mako import MakoTemplateEngine
 from litestar.plugins.minijinja import MiniJinjaTemplateEngine
 from litestar.response.template import Template
diff --git a/tests/unit/test_template/test_config.py b/tests/unit/test_template/test_config.py
@@ -1,6 +1,6 @@
 from typing import TYPE_CHECKING
 
-from litestar.contrib.jinja import JinjaTemplateEngine
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.template.config import TemplateConfig
 
 if TYPE_CHECKING:
diff --git a/tests/unit/test_template/test_context.py b/tests/unit/test_template/test_context.py
@@ -4,7 +4,7 @@
 import pytest
 
 from litestar import MediaType, get
-from litestar.contrib.jinja import JinjaTemplateEngine
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.plugins.mako import MakoTemplateEngine
 from litestar.plugins.minijinja import MiniJinjaTemplateEngine
 from litestar.response.template import Template
diff --git a/tests/unit/test_template/test_csrf_token.py b/tests/unit/test_template/test_csrf_token.py
@@ -6,8 +6,8 @@
 
 from litestar import MediaType, get
 from litestar.config.csrf import CSRFConfig
-from litestar.contrib.jinja import JinjaTemplateEngine
 from litestar.middleware.csrf import generate_csrf_token
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.plugins.mako import MakoTemplateEngine
 from litestar.plugins.minijinja import MiniJinjaTemplateEngine
 from litestar.response.template import Template
diff --git a/tests/unit/test_template/test_template.py b/tests/unit/test_template/test_template.py
@@ -9,8 +9,8 @@
 import pytest
 
 from litestar import Litestar, MediaType, get
-from litestar.contrib.jinja import JinjaTemplateEngine
 from litestar.exceptions import ImproperlyConfiguredException
+from litestar.plugins.jinja import JinjaTemplateEngine
 from litestar.plugins.mako import MakoTemplateEngine
 from litestar.plugins.minijinja import MiniJinjaTemplateEngine
 from litestar.response.template import Template

-Original file line number
+Diff line change
@@ @@ -1,7 +1,2 @@ @@
 contrib
 =======
+-
 -.. toctree::
 -    :maxdepth: 1
+-
 -    jinja