django-despacer

A lightweight loader for the Django Template Language (DTL) that enables removing excess whitespace by using delimiters like {#- and -#}. It's lightweight because it adds just two regular expressions at template loading time and nothing to request handling time.

This package is intended as a demonstration of this feature. I'm hoping this feature will eventually be included in Django's core code, at which time this package will no longer be needed.

About

I'm a frugal pragmatic perfectionist (with deadlines).

As a perfectionist, I'm horrified by the HTML generated by DTL: so many empty lines and bits of text floating in space. Being pragmatic, I accept that perfect whitespace control that generates perfectly indented HTML is unrealistic; so I'll settle for merely better looking HTML. Being frugal, I won't repeatedly pay a price for it but I'm willing to pay just once (at template load time).

So, I created django-despacer, a Python package which meets these criteria.

Features:

• At request handling time, it does nothing (no overhead added).
• At template loading time, just two regular expressions are run to alter templates before they're passed to the template compiler.
  • When DEBUG is False (production), whitespace is removed as indicated by despacing indicators ({#-, -#}, {{-, -}}, {%-, -%}) that you add where you desire.
  • When DEBUG is True (development), only the despacing indicator - is removed. Whitespace is not removed so that DTL compiler error messages have the correct line numbers.
• Just two regular expressions are added. It's lightweight.
• My favourite feature: I can now add lots of comments (comments are a good thing), {#- yada yada -#}, without adding lots of blank lines to the HTML generated.

Function

Below ··· represents one or more consecutive space, tab, and new line characters.

• When DEBUG is False (prod), when a DTL template is loaded:
  • ···{#-, -#}··· are replace with {#, #} respectively.
  • ···{%-, -%}··· are replace with {%, %} respectively.
  • ···{{-, -}}··· are replace with {{, }} respectively.
  • thereby removing blank lines and floating text in the generated HTML.
• When DEBUG is True (dev), when a DTL template is loaded:
  • ··· is not removed; only the -. Why? The line numbers of the original DTL source code must match the line numbers in the compiler's input to have correct line numbers in any error messages. That's important in development.
  • {#-, -#} are replace with {#, #} respectively.
  • {%-, -%} are replace with {%, %} respectively.
  • {{-, -}} are replace with {{, }} respectively.

Usage

In my DTL templates I usually:

• Despace before and after comments {#- yada yada -#}. I can now have many lines of comments without having many empty lines in my generated HTML!
• Despace before but not after tags like {%- if ... %}. This omits the empty line but still has a new-line after. See if below.
• Despace before and after when I want to squeeze things down more. See <button> below where I want a one-liner.

<div>
  {#- I can now add lots of comments to my template -#}
  {#- ... without adding a ton of empty lines! -#}
  {#- the {%- on the `if` below removes empty lines -#}
  {#- I added for readability -#}

  {%- if not user.is_authenticated %}
    Howdy, stranger!
  {%- else %}
    Welcome back, {{ user.name }}.
  {%- endif -%}

  <button>
    {#- Despacing before and after collapses <button> down to a one liner -#}
    {%- translate "Save and Publish" -%}
    {#- Isn't it just great to be able to add lots of comments! -#}
  </button>
</div>

Without django-despacer (and without the -), the HTML would look like:

<div>
  
  




    Howdy, stranger!
  


  <button>
    
    Save and Publish
    
  </button>
</div>

... but with django-despacer:

<div>
    Howdy, stranger!
  <button>Save and Publish</button>
</div>

Installation

• Requirements:

  • Python >= 3.4
  • Django >= 2.0

• Install the package: uv add django-despacer (or for old-schoolers pip install django-despacer)

• Configure Django settings to use the template loader provided

TEMPLATES = [
  {
    # ...
    "OPTIONS": {
      # ...
      "loaders": [
        (
          "django.template.loaders.cached.Loader",
          [
            (
              "django_despacer.DespacingLoader",
              [
                "django.template.loaders.filesystem.Loader",
                "django.template.loaders.app_directories.Loader",
              ]
            )
          ],
        ),
      ]
    },
  },
]

• Since you are defining "loaders" explicitly, you must specify them all, especially "django.template.loaders.cached.Loader".
• Apologies for the ugly configuration. If Django adopts this feature into core, you'll just need to remove the loader.

License

This project is licensed under the MIT License.