Metadata-Version: 2.4
Name: typed-jinja-templates
Version: 0.1.2
Summary: Help with type checking of variables contexts passed into Jinja templates using only type hints
Keywords: templating,jinja,jinja2,starlette,type-checking,type-hint
Author: Martin Schorfmann
License-Expression: MIT
License-File: LICENSE.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: jinja2
Requires-Dist: starlette ; extra == 'starlette'
Maintainer: Martin Schorfmann
Requires-Python: >=3.12
Project-URL: repository, https://gitlab.com/schorfma/typed-jinja-templates
Project-URL: issues, https://gitlab.com/schorfma/typed-jinja-templates/-/issues
Provides-Extra: starlette
Description-Content-Type: text/markdown

# 🏷️ Typed Jinja Templates

> Tiny _Python_ library to help with type checking of variables contexts passed into _Jinja_ templates using only type hints

<!-- TODO: Description -->

## Installation

This project's distribution packages are published on _PyPI_: [`typed-jinja-templates` on _PyPI_](https://pypi.org/project/typed-jinja-templates/).

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:

```sh
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`

```python
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

![Type checking error showing red diagnostic underlines for the parameters "name" and "context" of TemplateResponse](examples/screenshots/Typed-Jinja-Templates_Type-Checking-Error.png)

## [License: _MIT_](./LICENSE.md)
