Provide a better default template engine NAME than 'backend'

Author: wizpig64

CHANGES.adoc

@@ -8,6 +8,30 @@ Unreleased
 - Drop Python 3.6 and 3.7 support, now require >=3.8.
 - Add Django 4.1 and 4.2 support.
 - Add Python 3.11 support.
+- Provide a better default template engine NAME than 'backend' (#303):
+
+Previously, when configuring `TEMPLATES` in Django's settings,
+`NAME` had to be set to avoid the template engine's name becoming `"backend"`:
+
+[source,python]
+----
+TEMPLATES = [
+    {
+        "NAME": "jinja2",
+        "BACKEND": "django_jinja.backend.Jinja2",
+----
+
+If your code matches that pattern, it can now be simplified to:
+
+[source,python]
+----
+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"`)!
 
 
 Version 2.10.2

django_jinja/jinja2.py

@@ -0,0 +1,9 @@
+"""
+This import enables the import path of the django-jinja template backend
+to have a sane default NAME in your TEMPLATES setting.
+See: https://github.com/niwinz/django-jinja/pull/303
+"""
+
+from .backend import Jinja2
+
+__all__ = ["Jinja2"]

django_jinja/management/commands/makemessages.py

@@ -67,10 +67,11 @@ def add_arguments(self, parser):
 
     def _get_default_jinja_template_engine(self):
         # dev's note: i would love to have this easy default: --jinja2-engine-name=jinja2
-        # but as currently implemented, django-jinja's engine's name defaults to 'backend'.
+        # but due to historical reasons, django-jinja's engine's name can default to either `jinja2` or 'backend'.
         # see: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-TEMPLATES-NAME
-        # for now, the default engine will be the first one exactly matching our backend's path.
-        return [e for e in engines.templates.values() if e["BACKEND"] == "django_jinja.backend.Jinja2"][0]
+        # the default engine will be the first one exactly matching either of the new or old import paths.
+        supported_import_paths = ["django_jinja.backend.Jinja2", "django_jinja.jinja2.Jinja2"]
+        return [e for e in engines.templates.values() if e["BACKEND"] in supported_import_paths][0]
 
     def handle(self, *args, **options):
         old_endblock_re = trans_real.endblock_re

doc/content.adoc

@@ -117,8 +117,7 @@ Followed by the basic template engine configuration:
 ----
 TEMPLATES = [
     {
-        "NAME": "jinja2",
-        "BACKEND": "django_jinja.backend.Jinja2",
+        "BACKEND": "django_jinja.jinja2.Jinja2",
         "DIRS": [],
         "APP_DIRS": True,
         "OPTIONS": {}
@@ -139,12 +138,6 @@ django-jinja backend, take care of the template engines order, because the
 django-jinja backend by default uses the same directory for the templates as
 the django template engine. If you put the django engine first every jinja
 template will be found by the django engine.
-
-Also, keep in mind that the automatically inferred `NAME` for the django-jinja
-backend will be `backend`. For this, you probably want to manually set the `NAME`
-setting to something more meaningful (e.g. `jinja2`), which you can later use
-when you need to specify a template engine by name
-(e.g. `render_to_string("myapp/template.jinja", context, using="jinja2")`).
 ====
 
 To read more on the logic of the `DIRS` and `APP_DIRS` settings,
@@ -338,6 +331,21 @@ from django_jinja.builtins import DEFAULT_EXTENSIONS
 
 ----
 
+=== Setting the template engine name
+
+Keep in mind that the automatically inferred `NAME` for any template backend
+link:https://docs.djangoproject.com/en/dev/ref/settings/#std-setting-TEMPLATES-NAME[will depend on the backend's import path].
+This name is used when you need to specify a template engine by name
+(e.g. `render_to_string("myapp/template.jinja", context, using="jinja2")`).
+
+In previous versions of django-jinja, the backend's import path was `django_jinja.backend.Jinja2`,
+providing the unhelpful default engine name, `"backend"`.
+
+Now, the import path `django_jinja.jinja2.Jinja2` can be used,
+which provides a more meaningful engine name, `"jinja2"`.
+
+The old import path is still available for compatability with existing Django projects.
+
 
 === Gettext Style
 
@@ -363,8 +371,7 @@ This is a complete configuration example with django-jinja's defaults:
 ----
 TEMPLATES = [
     {
-        "NAME": "jinja2",
-        "BACKEND": "django_jinja.backend.Jinja2",
+        "BACKEND": "django_jinja.jinja2.Jinja2",
         "APP_DIRS": True,
         "OPTIONS": {
             "match_extension": ".jinja",

testing/settings.py

@@ -61,8 +61,7 @@
 
 TEMPLATES = [
     {
-        "BACKEND": "django_jinja.backend.Jinja2",
-        "NAME": "jinja2",
+        "BACKEND": "django_jinja.jinja2.Jinja2",
         "APP_DIRS": True,
         "OPTIONS": {
             "debug": True,