Concerns with new "libraries" template functionality

[Yo-Yo Ma]

I was reading through the 1.9 release notes when I came across the new OPTIONS['libraries'] feature.

Relevant links:

  - https://docs.djangoproject.com/en/dev/releases/1.9/#template-tag-modules-are-imported-when-templates-are-configured
  - https://docs.djangoproject.com/en/dev/releases/1.9/#templates
  - https://docs.djangoproject.com/en/dev/topics/templates/#module-django.template.backends.django

tl;dr

This new functionality trades convention for configuration, in a problematic way, for little gain.

If OPTIONS['libraries'] was made to mean: "only these libraries can be used in templates", there would be no problem. If it does in fact mean this, please disregard the following points and view this as a documentation update request.

Long version:

My concern is that we're now offering a way to explicitly register template libraries in OPTIONS['libraries'], which:

    1) allows you to {% load some_key_from_that_dict %}
    2) causes the modules to be loaded upon application start (and presumably `check`)

Unless I missed something, this functionality is lacking / concerning because of the following reasons:

    1) 'libraries' will not be the *only* libraries allowed to be used in your templates, which removes the "explicit" nature (there isn't much explicit about a setting that is only additive)
    2) Due to #2, you can still run into module load time errors via {% load something_not_registered %}
    3) Environment-specific settings module (e.g., local_settings.py) can now cause unexpected runtime errors due to renaming tag libraries (vs simply using the module name)
    4) 'libraries' will not be automatically built-in ('builtins' does that)

#4 is only mentioned because when you consider #1, #2 and #3 there is suddenly no additional value added by this "libraries" option, unless it also acted as add_to_builtins.

If the goal of this feature is to add application start time checks for template libraries, the right (and consistent) way to handle this would be to follow suit with admin.py, models.py, tests.py, etc., and add `templatetags` packages to application checks. If the goal of this feature is to provide a way to control the name used in {% load ... %} (very small value added, IMHO), then this should be the only thing it does, so that devs don't rely on the feature for something more.

If I'm understanding this new feature correctly, the elevator pitch becomes:

You can now use OPTIONS['libraries'] to have Django check for import errors on *some* of your template libraries, the ones you remember to add there. The side effect is that {% load some_name_that_isnt_a_module_name %} will confuse devs. Also, your devs can continue to use {% load by_module_name_not_libraries_key %} and ignore your settings completely, or even worse, if they have local template settings due to local file system differences, they will have to remember to copy new libraries in each time they're added / changed.

[Yo-Yo Ma]

CORRECTION:

| Due to #2, you can still run...

Should be:

| Due to #1, you can still run...

[Aymeric Augustin]

Hello,

The situation is nowhere near as complicated as you make it sound.

1) Builtins: many applications or projects relied on the private `add_to_builtins` API in order not to have to {% load %} commonly used libraries in every template. The new “builtins” option provides a public API for this purpose.

2) Libraries: it can be inconvenient to create an application just for registering a library. Also that doesn’t make sense when using the template engine outside of Django, which is possible since I refactored it as a library. The new “libraires” option provides an alternative for these use cases. The current convention remains to allow pluggable apps to provide template tags (and for backwards-compatibility).

See https://code.djangoproject.com/ticket/17085 and https://github.com/django/django/commit/655f52491505932ef04264de2bce21a03f3a7cd0 for details.

You’re saying that this change “trades convention for configuration, in a problematic way”. But it only adds options and doesn’t remove anything; nothing is being traded.

I suspect that you’re confused about the ability to “{% load some_key_from_that_dict %}”. Libraries registered in the libraries option must be loaded exactly as if they had been registered with @library.register.

If you think the docs could be clarified, patch welcome!

-- 

Aymeric.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.
To post to this group, send email to django-d...@googlegroups.com.
Visit this group at http://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/2bfe1c14-c4a7-4fc9-a9f7-b77a4f7d35ce%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Yo-Yo Ma]

Hi Aymeric,

Pardon my misunderstand of the new functionality, and thanks for the explanation. The ability to use template libraries outside of installed apps alone is a great addition. Thanks for your hard work on this.