typed-jinja-templates 0.1.2

Help with type checking of variables contexts passed into Jinja templates using only type hints

🏷️ Typed Jinja Templates

Tiny Python library to help with type checking of variables contexts passed into Jinja templates using only type hints

Installation

This project's distribution packages are published on PyPI: typed-jinja-templates on PyPI.

While it can be installed using pip install typed-jinja-templates, it is only useful as a dependency in a project context.

Therefore, add typed-jinja-templates as a dependency to an existing project.

For uv-managed projects use:

uv add typed-jinja-templates

Usage

Just add one of the parametrized type hints that this library provides to variables with instances of the original types:

• Type Jinja2Templates from starlette as TypedJinjaTemplates[TemplateName, ModelType]
• Type Environment from jinja2 as TypedJinjaEnvironment[TemplateName, ModelType]
• Type Template from jinja2 as TypedJinjaTemplate[TemplateName, ModelType]

Insert a typing.Literal string type for TemplateName to constrain to the expected template name or template names for type checking. Insert a typing.TypedDict sub class for ModelType to constrain the template context to a dict conforming to the schema provided for type checking.

Example for TypedJinjaTemplates

from typing import Literal, NotRequired, TypedDict

from starlette.requests import Request
from starlette.responses import HTMLResponse
from starlette.templating import Jinja2Templates

from typed_jinja_templates import TypedJinjaTemplates

TEMPLATES = Jinja2Templates("...")  # Contains "hello.jinja.html"


class GreetingContext(TypedDict):
    greeting: NotRequired[str]
    greetee: str
    capitalize: NotRequired[Literal[True]]


# @APP.get("/hello", ...)
def get_hello(request: Request) -> HTMLResponse:
    templates: TypedJinjaTemplates[
        Literal["hello.jinja.html"],  # --> Constrains template name
        GreetingContext,  # --> Constrains template context
    ] = TEMPLATES  # type: ignore[assignment]

    return templates.TemplateResponse(
        request=request,
        name="hello.jinja.html",
        context={
            "greetee": "World",
            "capitalize": True,
        },
    )


# @APP.get("/hello", ...)
def get_hello_with_error(request: Request) -> HTMLResponse:
    templates: TypedJinjaTemplates[
        Literal["hello.jinja.html"],  # --> Constrains template name
        GreetingContext,  # --> Constrains template context
    ] = TEMPLATES  # type: ignore[assignment]

    return templates.TemplateResponse(
        request=request,
        name="hell.jinja.html",  # --> Shows error mypy(arg-type)!
        context={  # --> Shows error mypy(arg-type)!
            "greetee": 42,
            "capitalize": True,
        },
    )

Screenshot of Type Checking Errors

License: MIT