Skip to main content

Getting Started

Python Liquid is a Python engine for Liquid, the safe, customer-facing template language for flexible web apps.

This page gets you started using Liquid with Python. See Introduction to Liquid, the filter reference and the tag reference to learn about writing Liquid templates.

Install​

Install Python Liquid from PyPi:

python -m pip install -U python-liquid

Or conda-forge:

conda install -c conda-forge python-liquid

Render​

Render a template string by creating a Template and calling its render() method.

from liquid import Template

template = Template("Hello, {{ you }}!")
print(template.render(you="World"))  # Hello, World!
print(template.render(you="Liquid"))  # Hello, Liquid!

Keyword arguments passed to render() are available as variables for templates to use in Liquid expressions.

from liquid import Template

template = Template(
    "{% for person in people %}"
    "Hello, {{ person.name }}!\n"
    "{% endfor %}"
)

data = {
    "people": [
        {"name": "John"},
        {"name": "Sally"},
    ]
}

print(template.render(**data))
# Hello, John!
# Hello, Sally!

Configure​

Configure template parsing and rendering behavior with extra arguments to Template. The following example renders a template in strict mode and will raise an exception whenever an undefined variable is used. See liquid.Template for all available options.

from liquid import Template
from liquid import Mode
from liquid import StrictUndefined

template = Template(
    "Hello, {{ you }}!",
    tolerance=Mode.STRICT,
    undefined=StrictUndefined,
)

result = template.render(you="World")
tip

Keep reading to see how to configure an environment once, then load and render templates from it.

Environment​

While Template can be convenient, more often than not an application will want to configure a single Environment, then load and render templates from it. This is usually more efficient than using Template directly.

All templates rendered from an Environment will share the environment's configuration. See liquid.Environment for all available options. Notice that Environment accepts a loader argument, whereas Template does not.

from liquid import Environment
from liquid import Mode
from liquid import StrictUndefined
from liquid import FileSystemLoader

env = Environment(
    tolerance=Mode.STRICT,
    undefined=StrictUndefined,
    loader=FileSystemLoader("./templates/"),
)

template = env.from_string("Hello, {{ you }}!")
result = template.render(you="World")