Migration guide¶
This is the documentation for Python Liquid version 3 (GitHub). Archived documentation for versions 1 and 2 can be found here and here, respectively.
In version 3, Python Liquid improves template parsing performance, adds a few opt-in template language features and makes several breaking API changes.
Python versions and dependencies¶
The minimum supported Python version is now 3.12. Anyone still using Python version 3.9, 3.10 or 3.11 will not be able to use Python Liquid version 3.
We’ve added tzdata as a dependency and removed the pytz dependency in favour of
Python’s built-in zoneinfo module.
New template language features¶
Extended syntax¶
Some new template language features are available when Liquid is
configured with an ExtendedLexer
and/or an ExtendedParser.
The extended lexer:
Adds hash-style comments (
{# .. #}).Adds proper string literal parsing without interfering with markup delimiters (
{{ "this is a delimiter '}}'" }}).Allows custom markup delimiters.
The extended parser:
Adds a logical
notoperator and parentheses for grouping terms.Adds Python-style ternary expressions (
a if b else c).Adds arithmetic operators (
+,-,*,/and%).Allows
=as well as:between names and values in named tag and filter arguments.Allows logical
andandorin all tags and the output statement, with short circuit, last value semantics.Allows filter application (
|) in all tags and the output statement with a well-defined precedence that plays nicely with parentheses.
Those last two points are important. With the extended parser, expressions are composable and all operators are available in every expression.
See Extended expressions for examples.
Self¶
We’ve added the self keyword and an option to disable bare brackets, as found in
Shopify/liquid in version 5.13 (See Shopify/liquid #2060).
This is most likely in preparation for future array literal syntax, which is yet to be implemented in Ruby or Python Liquid.
New template engine features¶
Drops¶
The Drop interface (developer defined types for templates) has been redesigned to:
Give drop methods access to context data and environment config at render time.
Support lazy and/or async iteration with the
{% for %}tag.Consolidate and give fine-grained control of coercion to Liquid primitive types.
See Drop.
Lax parsing¶
The new lax parsers, liquid.LaxLegacyParser and liquid.LaxExtendedParser,
suppress syntax errors and attempt to continue parsing template source text. In some cases
an earlier error can lead to confusing or misleading error messages later on.
After parsing with a lax parser, a list of errors can be retrieved using
liquid.Template.errors().
from liquid import Environment, LaxLegacyParser
env = Environment(parser=LaxLegacyParser)
# Typo in the `if` expression.
template = env.parse(
"{% if a =! b %}TRUE{% else %}FALSE{% endif %}",
name="some_template",
)
for error in template.errors():
print(error)
unknown or missing operator
-> 'some_template' 1:8
|
1 | {% if a =! b %}TRUE{% else %}FALSE{% endif %}
| ^ unknown or missing operator
This can be useful for discovering multiple errors in one go, but it’s usually best to keep template parsing an rendering as strict as possible so errors don’t go unnoticed.
Error capture and rendering¶
A list of (potentially many) render time exceptions can now be retrieved using
liquid.Template.render_with_errors(). It returns a (rendered string, error list)
tuple, with error messages written to the output string at the point they occurred.
API changes¶
Template(source)can no longer be used to parse a template from a string. Useliquid.parse()orliquid.Environment.parse()instead.Removed
Environment.from_string(). Useliquid.parse()orliquid.Environment.parse()instead.Changed
liquid.render(),liquid.Environment.render()andliquid.Template.render()to accept data as a dict (or any mapping) instead of keyword arguments.Renamed class
BoundTemplatetoliquid.Template.Removed
liquid.Environmentclass variables in favour of constructor arguments.Renamed several
liquid.Environmentconstructor arguments.Removed
Environment.add_tag()andEnvironment.add_filter(). Update dictionariesliquid.Environment.tagsandliquid.Environment.filtersdirectly instead.Removed
DebugUndefined. Useliquid.Template.render_with_errors()instead.Removed
StrictDefaultUndefined. UseFalsyStrictUndefinedinstead.Renamed
BaseLoadertoliquid.Loader.__html__is no longer used to serialize a drop to an HTML safe string. Useliquid.LiquidPrimitive.__liquid__()with the"output"hint instead.
Drops¶
Drops (developer defined types for templates) are no longer tied to Python’s
collections.abc.Mapping interface. They are now defined by protocols with
__liquid_<...>__ methods. It’s still OK to add custom Mapping
objects to render context data, but they are just mappings.
Whereas before you’d implement __getitem__(self, key) and possibly
__getitem_async__(self, key), now you’d implement the liquid.LiquidObject
protocol and the liquid.LiquidAsyncObject protocol.
See Liquid data model and built-in drops for examples.
Filters¶
We no longer use decorators to coerce filter inputs to acceptable types. Nor do we use decorators to indicate that a filter accepts the active render context or environment.
Instead we define filters as callables. They can be functions or classes with a
__call__ method.
- type liquid.Filter = Callable[[Concatenate[FilterContext, object, ...]], object]
The first argument is always an instance of liquid.FilterContext, which has
access to the render context and active environment.
The second argument is the result of evaluating the left hand side of the filter expression, and remaining arguments are defined by the filter.
Instances of FilterContext also have convenient methods for coercing objects to
primitive types, and methods for testing objects for Liquid truthiness and nullish-ness.
See Filter and built-in filters for examples.