Metadata-Version: 2.3
Name: django-despacer
Version: 0.1.3
Summary: A lightweight Django Template Language (DTL) loader that enables removing excess whitespaces.
Author: Don Parakin
Author-email: Don Parakin <don@weaddvalue.ca>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: django>=2.0
Requires-Python: >=3.4
Project-URL: Homepage, https://github.com/donparakin/django-despacer
Project-URL: Repository, https://github.com/donparakin/django-despacer.git
Project-URL: Bug Tracker, https://github.com/donparakin/django-despacer/issues
Description-Content-Type: text/markdown

# 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.

```html
<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:

```html
<div>
  
  




    Howdy, stranger!
  


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

... but with `django-despacer`:

```html
<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

```python
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](LICENSE).
