djade 1.1.1

Installation

Use pip:

python -m pip install djade

Python 3.8 to 3.13 supported.

-   repo: https://github.com/adamchainz/djade-pre-commit
    rev: ""  # Replace with the latest tag on GitHub
    hooks:
    -   id: djade
        args: [--target-version, "5.1"]  # Replace with Django version

pre-commit run djade --all-files

Usage

djade is a command line tool that rewrites files in place. Pass a list of template files to format them:

$ djade --target-version 5.1 templates/**/*.html
Rewriting templates/locomotives/steam_engine.html
Rewriting templates/locomotives/diesel.html

Djade can also upgrade some old template syntax. Add the --target-version option with your Django version as <major>.<minor> to enable applicable fixers:

$ djade --target-version 5.1 templates/**/*.html
Rewriting templates/locomotives/steam_engine.html

Djade does not have any ability to recurse through directories. Use the pre-commit integration, globbing, or another technique to apply it to many files. For example, with git ls-files | xargs:

git ls-files -z -- '*.html' | xargs -0 djade

…or PowerShell’s ForEach-Object:

git ls-files -- '*.html' | %{djade $_}

Options

--target-version

Optional: the version of Django to target, in the format <major>.<minor>. If provided, Djade enables its fixers for versions up to and including the target version. See the list of available versions with djade --help.

Formatting

Djade aims to format Django template syntax in a consistent, clean way. It wants to be like Black: opinionated and free of configuration. Djade’s style is based on the rules listed in the Django contribution style guide’s template style section, plus some more.

Djade does not aim to format the host language of templates (HTML, etc.). That is a much broader scope and hard to do without semantic changes. For example, whitespace is significant in some HTML contexts, such as in <pre> tags, so even adjusting indentation can affect the meaning.

Below are the rules that Djade implements.

Rules from the Django style guide:

• Single spaces at the start and end of variables and tags:

  -{{train}}
  +{{ train }}
  
  -{%  blow whistle  %}
  +{% blow whistle %}

• Label {% endblock %} tags that aren’t on the same line as their opening {% block %} tag:

   {% block funnel %}
   ...
  -{% endblock %}
  +{% endblock funnel %}

• Sort libraries in {% load %} tags:

  -{% load coal boiler %}
  +{% load boiler coal %}

• Inside variables, no spaces around filters:

  -{{ fire | stoke }}
  +{{ fire|stoke }}

• Inside tags, single spaces between tokens:

  -{% if  locomotive  ==  'steam engine'  %}
  +{% if locomotive == 'steam engine' %}

• Unindent top-level {% block %} and {% endblock %} tags when {% extends %} is used:

  -  {% extends 'engine.html' %}
  +{% extends 'engine.html' %}
  
  -  {% block boiler %}
  +{% block boiler %}
     ...
  -  {% endblock boiler %}
  +{% endblock boiler %}

Extra rules:

• No leading empty lines:

  -
   {% extends 'engine.html' %}
   ...

• No trailing empty lines:

   ...
   {% endblock wheels %}
  -
  -

• Single spaces at the start and end of comments:

  -{#choo choo#}
  +{# choo choo #}

• No labels in {% endblock %} tags on the same line as their opening {% block %} tag:

  -{% block funnel %}...{% endblock funnel %}
  +{% block funnel %}...{% endblock %}

• Merge consecutive {% load %} tags:

  -{% load boiler %}
  -
  -{% load coal %}
  +{% load boiler coal %}

• Sort loaded items in {% load ... from .. %} tags:

-{% load steam heat from boiler %}
+{% load heat steam from boiler %}

• Unindent {% extends %} tags:

  -  {% extends 'engine.html' %}
  +{% extends 'engine.html' %}

• Exactly one blank line between top-level {% block %} and {% endblock %} tags when {% extends %} is used:

 {% extends 'engine.html' %}

-
 {% block funnel %}
   ...
 {% endblock funnel %}
+
 {% block boiler %}
   ...
 {% endblock boiler %}

Fixers

Djade applies the below fixes based on the target Django version from --target-version.

-{% if engines|length_is:1 %}
+{% if engines|length == 1 %}

-{% tracks|json_script:"" %}
+{% tracks|json_script %}

-{% load blocktrans trans from i18n %}
+{% load blocktranslate translate from i18n %}

-{% trans "Engine colours" %}
+{% translate "Engine colours" %}

-{% blocktrans with colour=engine.colour %}
+{% blocktranslate with colour=engine.colour %}
 This engine is {{ colour }}.
-{% endblocktrans %}
+{% endblocktranslate %}

-{% ifequal engine.colour 'blue' %}
+{% if engine.colour == 'blue' %}
 Thomas!
-{% endifequal %}
+{% endif %}

-{% ifnotequal engine.colour 'blue' %}
+{% if engine.colour != 'blue' %}
 Not Thomas.
-{% endifnotequal %}
+{% endif %}

-{% load staticfiles %}
+{% load static %}

-{% load admin_static %}
+{% load static %}