niwinz / django-jinja

Simple and nonobstructive jinja2 integration with Django.
http://niwinz.github.io/django-jinja/latest/
BSD 3-Clause "New" or "Revised" License
363 stars 102 forks source link

Provide a better default template engine NAME than 'backend' #303

Closed wizpig64 closed 1 year ago

wizpig64 commented 1 year ago

This commit adds a module at django_jinja/jinja2.py that imports the Jinja2 template engine class from django_jinja/backend.py, in order to provide the import path django_jinja.jinja2.Jinja2. This is because Django uses the module's name as the template engine's default NAME, and "backend" is a poor default name for our template backend.

In thread #301, @m000 suggested a different strategy of renaming backend.py to jinja2.py, and adding a new backend.py as a shim to fix backwards compatibility, with a warning message promising it to break later. I avoided this approach because I don't want to break compatibility with existing projects at all, if I don't have to.

So at this time, I see no reason to plan the removal of support for the old import path. Instead, the examples in the docs now show the new path, and I added this explanation to the changelog:


Previously, when configuring TEMPLATES in Django's settings, NAME had to be set to avoid the template engine's name becoming "backend":

TEMPLATES = [
    {
        "NAME": "jinja2",
        "BACKEND": "django_jinja.backend.Jinja2",

If your code matches that pattern, it can now be simplified to:

TEMPLATES = [
    {
        "BACKEND": "django_jinja.jinja2.Jinja2",

There are no plans to remove support for the old backend import path, for consideration of existing projects. Also, be careful if you've set NAME to "jinja" (not "jinja2")!