A Python template engine for the Liquid markup language.
Project description
A Python implementation of Liquid. A non evaling templating language suitable for end users.
Installing
Install and update using pip:
$ python -m pip install -U python-liquidQuick Start
Please see Shopify’s documentation for template syntax and a reference of available tags and filters.
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!"Keyword arguments passed to render are added to the render context, and are available as variables for templates to use in Liquid expressions.
Loading Templates
If you want to use the built-in include or render tags, you’ll need to create an Environment, with a template Loader, then load and render templates from that environment.
This example assumes a folder called templates exists in the current working directory, and that the template file index.html exists within it.
from liquid import Environment
from liquid import FileSystemLoader
env = Environment(loader=FileSystemLoader("templates/"))
template = env.get_template("index.html")
print(template.render(some="variable", other="thing"))You can create templates from strings using an Environment too. This is often more efficient than using Template directly.
from liquid import Environment
env = Environment()
template = env.from_string("""
<html>
{% for i in (1..3) %}
<p>hello {{ some }} {{ i }}</p>
{% endfor %}
</html>
""")
print(template.render(some="thing"))Render Context
Among other things, a render context includes namespaces for global variables passed down from the Environment and local variables assigned with the built-in {% assign %} or {% capture %} tags.
The Environment constructor accepts globals, a dictionary of variables made available to all templates rendered from that environment.
from liquid import Environment
env = Environment(globals={"site_name": "Google"})
template = env.from_string("""
<html>
<h1>{{ site_name }}</h1>
{% for i in (1..3) %}
<p>hello {{ some }} {{ i }}</p>
{% endfor %}
</html>
""")
print(template.render(some="thing"))As does Template, Environment.get_template and Environment.from_string, where the dictionary of variables is added to the resulting render context each time you call render.
from liquid import Environment
env = Environment()
template = env.get_template("index.html", globals={"page": "home"})
print(template.render(some="thing"))Strictness
Templates are parsed and rendered in strict mode by default. Where syntax and render-time type errors raise an exception as soon as possible. You can change the error tolerance mode with the tolerance argument to the Environment or Template constructor.
Available modes are Mode.STRICT, Mode.WARN and Mode.LAX.
from liquid import Environment, FileSystemLoader, Mode
env = Environment(
loader=FileSystemLoader("templates/"),
tolerance=Mode.LAX,
)By default, references to undefined variables are silently ignored. In strict variables mode, any operation on an undefined variable will raise an UndefinedError.
from liquid import Environment, StrictUndefined
env = Environment(
loader=FileSystemLoader("templates/"),
undefined=StrictUndefined,
)HTML Auto Escape
As of version 0.7.4, Python Liquid offers HTML auto-escaping. Where context variables are automatically escaped on output. Install optional dependencies for auto-escaping using the autoescape extra.
$ python -m pip install -U python-liquid[autoescape]Auto-escaping is disabled by default. Enable it by setting the Environment or Template autoescape argument to True.
>>> from liquid import Environment
>>> env = Environment(autoescape=True)
>>> template = env.from_string("<p>Hello, {{ you }}</p>")
>>> template.render(you='</p><script>alert("XSS!");</script>')
'<p>Hello, </p><script>alert("XSS!");</script></p>'Mark a string as “safe” by making it Markup.
>>> from liquid import Environment, Markup
>>> env = Environment(autoescape=True)
>>> template = env.from_string("<p>Hello, {{ you }}</p>")
>>> template.render(you=Markup("<em>World!</em>"))
'<p>Hello, <em>World!</em></p>'Alternatively use the non-standard safe filter.
>>> from liquid import Environment
>>> env = Environment(autoescape=True)
>>> template = env.from_string("<p>Hello, {{ you | safe }}</p>")
>>> template.render(you="<em>World!</em>")
'<p>Hello, <em>World!</em></p>'Async Support
Python Liquid supports loading and rendering templates asynchronously. When Template.render_async is awaited, render and include tags will load templates asynchronously. Custom loaders should implement get_source_async.
import asyncio
from liquid import Environment, FileSystemLoader
env = Environment(loader=FileSystemLoader("templates/"))
async def coro():
template = await env.get_template_async("index.html")
return await template.render_async(you="World")
result = asyncio.run(coro())Custom “drops” can implement __getitem_async__. If an instance of a drop that implements __getitem_async__ appears in a render_async context, __getitem_async__ will be awaited instead of calling __getitem__.
Most likely used for lazy loading objects from a database, an async drop would look something like this.
class SomeAsyncDrop(abc.Mapping):
def __init__(self, val):
self.key = "foo"
self.val = val
def __len__(self):
return 1
def __iter__(self):
return iter([self.key])
def __getitem__(self, k):
# Blocking IO here
time.sleep(0.5)
# ...
async def __getitem_async__(self, k):
# Do async IO here.
asyncio.sleep(0.5)
# ...Compatibility
We strive to be 100% compatible with the reference implementation of Liquid, written in Ruby. That is, given an equivalent render context, a template rendered with Python Liquid should produce the same output as when rendered with Ruby Liquid.
Python Liquid faithfully reproduces the following tags.
assign
capture
case/when
comment
cycle
decrement
echo
for/break/continue
ifchanged
if/elsif/else
include
increment
liquid
raw
render
tablerow
unless
Known Issues
Please help by raising an issue if you notice an incompatibility.
Error handling. Python Liquid might not handle syntax or type errors in the same way as the reference implementation. We might fail earlier or later, and will almost certainly produce a different error message.
The built-in date filter uses dateutil for parsing strings to datetimes, and strftime for formatting. There are likely to be some inconsistencies between this and the reference implementation’s equivalent parsing and formatting of dates and times.
Benchmark
You can run the benchmark using make benchmark (or python -O performance.py if you don’t have make) from the root of the source tree. On my ropey desktop computer with a Ryzen 5 1500X, we get the following results.
Best of 5 rounds with 100 iterations per round and 60 ops per iteration (6000 ops per round).
lex template (not expressions): 1.3s (4727.35 ops/s, 78.79 i/s)
lex and parse: 6.4s (942.15 ops/s, 15.70 i/s)
render: 1.7s (3443.62 ops/s, 57.39 i/s)
lex, parse and render: 8.2s (733.30 ops/s, 12.22 i/s)And PyPy3.7 gives us a decent increase in performance.
Best of 5 rounds with 100 iterations per round and 60 ops per iteration (6000 ops per round).
lex template (not expressions): 0.58s (10421.14 ops/s, 173.69 i/s)
lex and parse: 2.9s (2036.33 ops/s, 33.94 i/s)
render: 1.1s (5644.80 ops/s, 94.08 i/s)
lex, parse and render: 4.2s (1439.43 ops/s, 23.99 i/s)On the same machine, running rake benchmark:run from the root of the reference implementation source tree gives us these results.
/usr/bin/ruby ./performance/benchmark.rb lax
Running benchmark for 10 seconds (with 5 seconds warmup).
Warming up --------------------------------------
parse: 3.000 i/100ms
render: 8.000 i/100ms
parse & render: 2.000 i/100ms
Calculating -------------------------------------
parse: 39.072 (± 0.0%) i/s - 393.000 in 10.058789s
render: 86.995 (± 1.1%) i/s - 872.000 in 10.024951s
parse & render: 26.139 (± 0.0%) i/s - 262.000 in 10.023365sI’ve tried to match the benchmark workload to that of the reference implementation, so that we might compare results directly. The workload is meant to be representative of Shopify’s use case, although I wouldn’t be surprised if their usage has changed subtly since the benchmark fixture was designed.
Custom Filters
Add a custom template filter to an Environment by calling its add_filter method. A filter can be any callable that accepts at least one argument (the result of the left hand side of a filtered expression), and returns a string or object with a __str__ method.
Here’s a simple example of adding str.endswith as a filter function.
from liquid import Environment, FileSystemLoader
env = Environment(loader=FileSystemLoader("templates/"))
env.add_filter("endswith", str.endswith)And use it like this.
{% assign foo = "foobar" | endswith: "bar" %}
{% if foo %}
<!-- do something -->
{% endif %}Decorate filter functions with with_context or with_environment to have the active context or environment passed as a keyword arguments.
from liquid.filter import with_context
from liquid.filter import string_filter
@string_filter
@with_context
def link_to_tag(label, tag, *, context):
handle = context.resolve("handle", default="")
return (
f'<a title="Show tag {tag}" href="/collections/{handle}/{tag}">{label}</a>'
)And register it wherever you create your environment.
from liquid import Environment, FileSystemLoader
from myfilters import link_to_tag
env = Environment(loader=FileSystemLoader("templates/"))
env.add_filter("link_to_tag", link_to_tag)In a template, you could then use the link_to_tag filter like this.
{% if tags %}
<dl class="navbar">
<dt>Tags</dt>
{% for tag in collection.tags %}
<dd>{{ tag | link_to_tag: tag }}</dd>
{% endfor %}
</dl>
{% endif %}All built-in filters are implemented in this way, so have a look in liquid/builtin/filters/ for many more examples.
Note that old style, class-based filters are depreciated and will be removed in Liquid 0.9. You can still implement custom filters as callable classes, but Liquid will not include any abstract base classes for filters or legacy filter “helpers”.
Custom Loaders
Write a custom loader class by inheriting from liquid.loaders.BaseLoader and implementing its get_source method. Here we implement DictLoader, a loader that uses a dictionary of strings instead of the file system for loading templates.
from liquid.loaders import BaseLoader
from liquid.loaders import TemplateSource
from liquid.exceptions import TemplateNotFound
class DictLoader(BaseLoader):
def __init__(self, templates: Mapping[str, str]):
self.templates = templates
def get_source(self, _: Env, template_name: str) -> TemplateSource:
try:
source = self.templates[template_name]
except KeyError as err:
raise TemplateNotFound(template_name) from err
return TemplateSource(source, template_name, None)TemplateSource is a named tuple containing the template source as a string, its name and an optional uptodate callable. If uptodate is not None it should be a callable that returns False if the template needs to be loaded again, or True otherwise.
You could then use DictLoader like this.
from liquid import Environment
from liquid.loaders import DictLoader
snippets = {
"greeting": "Hello {{ user.name }}",
"row": """
<div class="row"'
<div class="col">
{{ row_content }}
</div>
</div>
""",
}
env = Environment(loader=DictLoader(snippets))
template = env.from_string("""
<html>
{% include 'greeting' %}
{% for i in (1..3) %}
{% include 'row' with i as row_content %}
{% endfor %}
</html>
""")
print(template.render(user={"name": "Brian"}))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 or python -m unittest.
Check test coverage with make coverage and open htmlcov/index.html in your browser.
Check your changes have not adversely affected performance with make benchmark.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file python-liquid-0.7.7.tar.gz.
File metadata
- Download URL: python-liquid-0.7.7.tar.gz
- Upload date:
- Size: 159.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.8.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 54d33f8d3951ce2380a11ed9846f13a2e2febb239b84e1eb393804a8dc3d5ea7 |
|
| MD5 | d6e85959ddb81574056b6ec2a4dffd25 |
|
| BLAKE2b-256 | ba94f5acf1aa8f6d928ffb1d3faf71f0288a2137af4c1d093580c927a0417faf |
File details
Details for the file python_liquid-0.7.7-py3-none-any.whl.
File metadata
- Download URL: python_liquid-0.7.7-py3-none-any.whl
- Upload date:
- Size: 83.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.8.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 4c1b31a0c53356b0e30529a97aa9ed26ca96a6d1f994555b1c1c27654b4b5f8e |
|
| MD5 | dd6d8c6d695c4d9b41c525fb041c7213 |
|
| BLAKE2b-256 | e5471bc41f411c683e2490690e5f0769374dab22d8f145a8c82ec29465d5e1b8 |
