jinja2-embedded 0.1.5

How to use

Two changes are necessary. First, change PackageLoader to EmbeddedPackageLoader:

from jinja2 import Environment, PackageLoader
from jinja2_embedded import EmbeddedPackageLoader

# before
env = Environment(
    loader=PackageLoader('my_package', 'templates'),
    autoescape=True,
    ...
)

# after
env = Environment(
    loader=EmbeddedPackageLoader('my_package.templates'),
    autoescape=True, # default False, but FastAPI uses True as default
    extensions=[],
)

# with FastAPI
from fastapi.templating import Jinja2Templates
templates = Jinja2Templates(env=env)

Second, declare the templates directory as a module by adding a __init__.py file:

my_package
├── __init__.py
├── main.py
└── templates
    ├── __init__.py # required
    ├── bar
    │   ├── __init__.py # not required
    │   └── test.html.jinja2
    ├── foo
    │   └── test.html
    └── test.html

The subdirectories inside the templates directory can be declared as modules (here my_package.templates.bar), but this is not required. The EmbeddedPackageLoader works with either or mixed configuration.

How it works

The EmbeddedPackageLoader will first try to locate the template with the ResourceReader from my_package.templates. From our example above, the ResourceReader is able to see:

>>> from importlib.util import find_spec
>>> package = 'my_package.templates'
>>> loader = find_spec(package).loader
>>> resource_reader = loader.get_resource_reader(package)
>>> contents = resource_reader.contents()
>>> print(list(contents))
['foo/test.html', 'test.html']

So we can use the provided resource_reader to read either of those files:

>>> with resource_reader.open_resource('foo/test.html') as file:
...    content = file.read()
>>> print(content.decode('utf-8'))
FOO

Since, bar is declared as module (directory contains a __init__.py file), we need to use the ResourceReader of the respective module:

>>> resource_reader = loader.get_resource_reader('my_package.templates.bar')
>>> contents = resource_reader.contents()
>>> print(list(contents))
['test.html.jinja2']

The EmbeddedPackageLoader will first try to find the resource in the ResourceReader of the main package and then fallback to the ResourceReader of the submodule (if it is declared as such).

Development

Install uv, then run uv sync --all-extras. This creates a venv with all necessary dependencies. Run pytest to run all tests.

To run the tests in a embedded Python version created with PyOxidizer, run pyoxidizer run in the root directory. After the executable has been build, the tests will run automatically.

This repository used ruff to enforce style standards. The formatting is automatically done for you via pre-commit. Install pre-commit with pre-commit install.