django-liquid 0.1.1

A Django template backend for Liquid.

A Django template backend for Liquid. Render Liquid templates in your Django apps.

Installing

Install and update using pip:

$ python -m pip install -U django-liquid

Quick Start

If you’re already familiar with configuring Django for Jinja2, Liquid works in almost exactly the same way. Just with less options. Simply set BACKEND to django_liquid.liquid.Liquid.

Add configuration for the Liquid template engine to your Django project’s settings.py file. Starting with the default TEMPLATE configuration after running django-admin startproject mysite, basic Liquid configuration would look like this.

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
    {
        'BACKEND': 'django_liquid.liquid.Liquid',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {},
    },
]

When APP_DIRS is True, Liquid engines look for templates in the liquid subdirectory of installed applications.

OPTIONS are passed to the liquid.Environment constructor. The default Environment is configured as follows.

• autoescape: True

• loader: a FileSystemLoader configured for DIRS and APP_DIRS

• undefined: DebugUndefined if settings.DEBUG else Undefined

Render Liquid templates from your app views just like any other Django template backend.

from django.shortcuts import render

def index(request):
    context = {"greeting": "hello"}
    return render(request, 'myapp/index.liquid', context)

If you’ve got multiple template engines configured, like in the example above, Django will use the first engine and template it finds matching the given template name. You can force Django to use a specific template engine with the using argument.

from django.shortcuts import render

def index(request):
    context = {"greeting": "hello"}
    return render(request, 'myapp/index.html', context, using='liquid')

Environment Factory

You can configure your liquid.Environment with additional tags or filters by setting the environment template backend option to the name of an Environment factory function. Lets say you want to register the json filter from python-liquid-extra. If the following is saved as myproject/liquid.py

from liquid import Environment
from liquid_extra import filters

def environment(**options):
    env = Environment(**options)
    env.add_filter("json", filters.JSON())
    # Register more filters or tags here.
    return env

Then tell the django template backend to use your environment factory function like this.

# settings.py
TEMPLATES = [
    {
        'BACKEND': 'django_liquid.liquid.Liquid',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
          'environment': 'myproject.liquid.environment'
        },
    },
]

Contributing

• Install development dependencies with Pipenv

• Python Liquid fully embraces type hints and static type checking. I like to use the Pylance extension for Visual Studio Code, which includes Pyright for static type checking.

• Format code using black.

• Write tests using unittest.TestCase.

• Run tests with make test.

• Check test coverage with make coverage and open htmlcov/index.html in your browser.