Template processor for Django

• PyPI
• GitHub
• Full documentation
• Creator & Maintainer: Fabian Binz

Adds pre- and post-processing hooks to your Django project. While this package does not provide any functionality itself, it is configurable to add your own pre- and post-processing hooks.

Installation

• Install the package via pip:

  pip install django-template-processors

  or via pipenv:

  pipenv install django-template-processors

• Add module to INSTALLED_APPS within the main django settings.py:

  INSTALLED_APPS = (
      ...
      'template_processors',
  )

• Extend the TEMPLATE_PRE_PROCESSORS and TEMPLATE_POST_PROCESSORS settings with your own processors:

  TEMPLATE_PRE_PROCESSORS = [
      'my_app.processors.my_pre_processor',
  ]
  
  TEMPLATE_POST_PROCESSORS = [
      'my_app.processors.my_post_processor',
  ]

• Adjust the template loaders to use the new template processors. As an example, the following configuration assumse that you had the built-in filesystem and app_directories loaders configured. You need to wrap each loader with the template_processors.loader.Loader class:

  TEMPLATES = [
      {
          'BACKEND': 'django.template.backends.django.DjangoTemplates',
          ...,
          'OPTIONS': {
              ...,
              'loaders': [
                  (
                      'template_processors.loader.Loader',
                      'django.template.loaders.filesystem.Loader',
                  ),
                  (
                      'template_processors.loader.Loader',
                      'django.template.loaders.app_directories.Loader',
                  ),
              ],
          },
      },
  ]

Usage

Configure pre- and post-processing hooks in your settings.py:

TEMPLATE_PRE_PROCESSORS = [
    'my_app.processors.my_pre_processor',
]

TEMPLATE_POST_PROCESSORS = [
    'my_app.processors.my_post_processor',
]

Pre-processors are called before the template is rendered with the string contents of the template. Post-processors are called after the template is rendered with the full TemplateResponse object.

Note that the post-processing only works, if the view returns a TemplateResponse object, i.e. not if the view returns using djangos render function.

Contribute

Setup package for development

• Create a Python virtualenv and activate it
• Install "pip-tools" with pip install -U pip-tools
• Compile the requirements with pip-compile --extra dev, -o requirements.txt pyproject.toml --resolver=backtracking
• Sync the dependencies with your virtualenv with pip-sync

Add functionality

• Create a new branch for your feature
• Change the dependency in your requirements.txt to a local (editable) one that points to your local file system: -e /Users/workspace/django-template-processors or via pip pip install -e /Users/workspace/django-template-processors
• Ensure the code passes the tests
• Create a pull request

Run tests

• Run tests

  pytest --ds settings tests
  

• Check coverage

  coverage run -m pytest --ds settings tests
  coverage report -m
  

Git hooks (via pre-commit)

We use pre-push hooks to ensure that only linted code reaches our remote repository and pipelines aren't triggered in vain.

To enable the configured pre-push hooks, you need to install pre-commit and run once:

pre-commit install -t pre-push -t pre-commit --install-hooks

This will permanently install the git hooks for both, frontend and backend, in your local .git/hooks folder. The hooks are configured in the .pre-commit-config.yaml.

You can check whether hooks work as intended using the run command:

pre-commit run [hook-id] [options]

Example: run single hook

pre-commit run ruff --all-files --hook-stage push

Example: run all hooks of pre-push stage

pre-commit run --all-files --hook-stage push

Update documentation

• To build the documentation run: sphinx-build docs/ docs/_build/html/.
• Open docs/_build/html/index.html to see the documentation.

Translation files

If you have added custom text, make sure to wrap it in _() where _ is gettext_lazy (from django.utils.translation import gettext_lazy as _).

How to create translation file:

• Navigate to django-template-processors
• python manage.py makemessages -l de
• Have a look at the new/changed files within django-template-processors/locale

How to compile translation files:

• Navigate to django-template-processors
• python manage.py compilemessages
• Have a look at the new/changed files within django-template-processors/locale

Publish to ReadTheDocs.io

• Fetch the latest changes in GitHub mirror and push them
• Trigger new build at ReadTheDocs.io (follow instructions in admin panel at RTD) if the GitHub webhook is not yet set up.

Publish to PyPi

• Update documentation about new/changed functionality

• Update the Changelog

• Increment version in main __init__.py

• Create pull request / merge to master

• This project uses the flit package to publish to PyPI. Thus publishing should be as easy as running:

  flit publish
  

  To publish to TestPyPI use the following ensure that you have set up your .pypirc as shown here and use the following command:

  flit publish --repository testpypi
  

Maintenance

Please note that this package supports the ambient-package-update. So you don't have to worry about the maintenance of this package. All important configuration and setup files are being rendered by this updater. It works similar to well-known updaters like pyupgrade or django-upgrade.

To run an update, refer to the documentation page of the "ambient-package-update".