djade 1.0.0

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/eggs/*.html
Rewriting templates/eggs/dodo.html
Rewriting templates/eggs/ostrich.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/eggs/*.html
Rewriting templates/eggs/quail.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:

  -{{egg}}
  +{{ egg }}
  
  -{%  crack egg  %}
  +{% crack egg %}

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

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

• Sort libraries in {% load %} tags:

  -{% load omelette frittata %}
  +{% load friattata omelette %}

• Inside variables, no spaces around filters:

  -{{ egg | crack }}
  +{{ egg|crack }}

• Inside tags, single spaces between tokens:

  -{% if  breakfast  ==  'scrambled eggs'  %}
  +{% if breakfast == 'scrambled eggs' %}

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

  -  {% extends 'egg.html' %}
  +{% extends 'egg.html' %}
  
  -  {% block yolk %}
  +{% block yolk %}
       ...
  -  {% endblock yolk %}
  +{% endblock yolk %}

Extra rules:

• No leading empty lines:

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

• No trailing empty lines:

   ...
   {% endblock content %}
  -
  -

• Single spaces at the start and end of comments:

  -{#egg#}
  +{# egg #}

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

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

• Merge consecutive {% load %} tags:

  -{% load omelette %}
  -
  -{% load frittata %}
  +{% load frittata omelette %}

• Unindent {% extends %} tags:

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

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

 {% extends 'egg.html' %}

-
 {% block yolk %}
   ...
 {% endblock yolk %}
+
 {% block white %}
   ...
 {% endblock white %}

Fixers

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

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

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

-{% trans "Egg types" %}
+{% translate "Egg types" %}

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

-{% ifequal egg.colour 'golden' %}
+{% if egg.colour == 'golden' %}
 golden
-{% endifequal %}
+{% endif %}

-{% ifnotequal egg.colour 'silver' %}
+{% if egg.colour != 'silver' %}
 not silver
-{% endifnotequal %}
+{% endif %}

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

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