When using a custom Jinja loader, directory parameter is unnecessary but still required.

[NickColley]

In our project we're using Jinja templates like so:

from jinja2 import ChoiceLoader, PackageLoader, PrefixLoader, FileSystemLoader
from fastapi.templating import Jinja2Templates

template_loader = ChoiceLoader(
    [
        FileSystemLoader("name/web/templates"),
        PrefixLoader({"govuk_frontend_jinja": PackageLoader("govuk_frontend_jinja")}),
    ]
)

# Use a custom template loader and avoid the default directory option.
templates = Jinja2Templates(directory="null", loader=template_loader)

At the moment we use a generic "null" which is not used since in the code if you provide your own loader the default file system loader is bypassed.

starlette/starlette/templating.py

Lines 85 to 86 in 882ab69

	loader = jinja2.FileSystemLoader(directory)
	env_options.setdefault("loader", loader)

With this in mind, if a loader is passed should the directory parameter be entirely optional?

Should the API allow this?

templates = Jinja2Templates(loader=template_loader)

[euri10]

see this #1214 for the background as to why the API is what is

I agree with @alex-oleshkevich that currently the special case for loader is unsatisfactory if you want fine-grained control.

[NickColley]

I think this could also be confusing if people expect the directory to be merged with the loader or something like this. It's not clear what's happening at the moment. But seems like that thread has covered that confusion somewhat.

[Kludex]

@alex-oleshkevich wdyt?

[alex-oleshkevich]

My opinion: we need only two mutually exclusive parameters for this purpose: env: jinja2.Environment and directory: str|list[str]. The latter one is a shortcut. This covers all cases I ever faced.

I disagree with having loader and kwargs as, IMO, it is not a nice API because:

• not obvious
• mixes env-specific and class-specific parameters
• it is not clear what are kwargs about. Do they include env and class arguments or only env?

cc @Kludex

[NickColley]

I agree that the environment should be exposed since you can then do whatever you'd like and starlette doesnt have to concern itself with duplicating interfaces.

I've also ran into issues where a third party Jinja project assumed I had access to the environment, which we dont with starlette.

[alex-oleshkevich]

I made a PR to demonstrate the changes we discussed - #2159

[Kludex]

I've suggested to first deprecate it: #2159 (comment)

Then on v1 we can remove it.

[alex-oleshkevich]

The solution is merged. We can close this issue.

[NickColley]

Thank you for your work on this much appreciated