Django template style guide extensions

Django Internals
1

In this thread, we implemented a style guide in Django’s contribution guide, thanks to @rcheley .

I recently created a formatter tool, Djade, that follows that guide plus a bit more. Based on this experience, I propose the following changes to the template style guide.

  1. One {% load %} tag per line, alphabetically sorted. @nessita pinged on the previous thread about this, and the djade issue has broad support.

  2. Prefer {% load ... from ... %} syntax over {% load ... %}. This is equivalent to PEP 8's recommendation to prefer from … import …overfrom … import *`. @ericholscher reminded me of this syntax when reporting an issue in Djade. It’s clearer, safer, and I can see why Read the Docs prefers it.

  3. In templates using {% extends %}, one line between top-level tags, except between comments and the following tag, and {% load %} tags:

    {# Tank engine base #}
{% extends 'engine.html' %}

{# load some stuff #}
{% load translate from i18n %}
{% load static from static %}

{% block boiler %}
...
{% endblock boiler %}

  4. Single spaces at the start and end of comments: {# comment #}. The style guide currently describes this style for tags and variables - comments were just missed.

2

I’m not a fan of 1 and 2. Both of these feel like overreach TBH

No problem with 3 and 4 though.

1 Like
3

Definitely not a fan of #2. (Thinking of all the {% load static %} and {% load crispy_forms_tags %} directives across all my templates.)

4

I’m a fan of #1, opposite of a fan for #2, and +1 for #3 and #4.

For #2, I just learned today that the load ... from ... syntax is possible! However, I don’t agree with Eric’s comparison to the Python import syntax. I think it’s a bit of a stretch, as Python modules can contain many items that might be shadowed by local definitions, which can lead to namespace pollution and complicate/pollute imports for others.

In the case of Django templates, I don’t believe this concern applies in the same way. Additionally, changing every single load directive in thousands of projects seems more tedious than beneficial (I have never seen a project using load ... from ... so far!). Because of this, I’m -1 to #2.

5

I very seldom have merge conflicts in the {% load %} line in templates, so I slightly prefer the load tag to contain all used template tag libraries, but either choice wouldn’t cause me to remove djade from my projects. That being said, I like alphabetic sorting a lot.

I basically never use {% load ... from ... %} and I fully agree with @nessita 's reasoning there. The only time something like this was necessary I instead wrote my own template library registering the offending tag under a different name.

Definitely agree with 3. and 4.

6

I agree with Carlton.

I also roughly never had conflicts bit adding the new querystring tag might do so for some users.

7

I am a big fun of #1 and use it heavily on all production sites.
I prefer that way because of search where that specific template tag is used and refactor it in case I rename module to another name and I search thought problem like {% load {MODULENMAE} %}
Also, for my it is visually better to distinguish which template tags I load in that template.

8

For 2, I will add the extra argument that often I struggle to figure out if a loaded template library is actually used at all without looking through several files. Having {% load ... from ... %} would help me know when I can remove the load entirely if I’ve stopped using the tags in there. I don’t always remember where every tag and filter comes from.