Configuration¶
Template parsing and rendering behavior is configured using an instance of
liquid.Environment. Once configured, you’d parse templates with
liquid.Environment.parse() or liquid.Environment.get_template(), both of
which return an instance of liquid.Template.
The default environment¶
The default Liquid environment and a new instance of liquid.Environment without
any arguments is equivalent to the following.
from liquid import (
DictLoader,
Environment,
LegacyLexer,
LegacyParser,
ResourceLimits,
Undefined,
)
env = Environment(
autoescape=False,
bare_brackets=True,
conventional_operator_precedence=False,
extra=False,
globals=None,
iterable_strings=False,
loader=DictLoader({}),
parser=LegacyParser,
resource_limits=ResourceLimits(),
shorthand_indexes=False,
strict_filters=True,
tokenizer=LegacyLexer,
undefined=Undefined,
)
Extra features¶
If you’re not concerned with Shopify/liquid compatibility and want a reasonable configuration with extra tags and filters enabled, start with this.
from liquid import (
CachingFileSystemLoader,
Environment,
ExtendedLexer,
ExtendedParser,
StrictUndefined,
)
env = Environment(
autoescape=True,
conventional_operator_precedence=True,
extra=True,
iterable_strings=True,
loader=CachingFileSystemLoader("path/to/templates"),
parser=ExtendedParser,
strict_filters=True,
tokenizer=ExtendedLexer,
undefined=StrictUndefined,
)
When extra is True, the following tags and filters will be registered with the
environment.
Extra filters¶
currencydatetimedecimalgettextindexjsonmoney_with_currencymoney_without_currencymoney_without_trailing_zerosmoneyngettextnpgettextpgettextsort_numericscript_tagstylesheet_tagtunit
Tokenizers and parsers¶
Some features are enabled and disabled by choosing a combination of template tokenizer
and parser, configured with the tokenizer and parser arguments to the
liquid.Environment constructor. Built-in choices are:
LegacyLexer and LegacyParser are the defaults. Together they implement
Shopify/liquid version 5.13 syntax and semantics. It is not possible to change markup
delimiters when using LegacyLexer.
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.
Custom markup delimiters¶
You can choose alternative markup delimiters by subclassing liquid.ExtendedLexer
and defining class variables for out_start, out_end, tag_start and
tag_end. Then pass the subclass to the tokenizer argument of the
liquid.Environment constructor.
In this example we use square brackets instead of braces in all delimiters.
from liquid import Environment, ExtendedLexer
class MyTokenizer(ExtendedLexer):
comment_start: str = "[#"
comment_end: str = "#]"
out_start: str = "[["
out_end: str = "]]"
tag_start: str = "[%"
tag_end: str = "%]"
env = Environment(tokenizer=MyTokenizer)
source = """\
[% for x in y %]
* [[ x -]]
[% endfor %]
"""
print(env.render(source, {"y": [1, 2, 3]}))
# * 1
# * 2
# * 3
Lax parsing¶
Python Liquid’s 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.
Global variables¶
A template’s global variables are those added by application developers rather than
created by template authors using {% assign %} and {% capture %}.
We can pin or attach global variables to instances of liquid.Environment and/or
liquid.Template. At render time those pinned variables are combined with
variables passed to liquid.Template.render() and added to the template scope.
By default, if there’s a name conflict, globals variables attached to a template take
priority over global variables attached to the environment, and data passed to
render() takes priority over both.
from liquid import Environment
env = Environment(
globals={
"greeting": "Hello",
"name": "World",
"punctuation": "?",
}
)
template = env.parse(
"{{ greeting }}, {{ name }}{{ punctuation }}",
globals={
"punctuation": "!",
},
)
print(template.render()) # Hello, World!
print(template.render({"greeting": "Goodbye"})) # Goodbye, World!
print(template.render({"name": "Liquid", "punctuation": "."})) # Hello, Liquid.
Undefined variables¶
At render time, if a variable can not be resolved, an instance of liquid.Undefined
is used instead. Pass one of liquid.Undefined, liquid.StrictUndefined or
liquid.FalsyUndefined to the undefined argument of the liquid.Environment
constructor to control how Liquid handles undefined variables.
from liquid import Environment, StrictUndefined
env = Environment(undefined=StrictUndefined)
print(env.render("{{ nosuchthing }}"))
# liquid.exceptions.UndefinedVariableError: nosuchthing is undefined
# -> '' 1:3
# |
# 1 | {{ nosuchthing }}
# | ^^^^^^^^^^^ nosuchthing is undefined
HTML auto escape¶
When autoescape=True, all template variables are automatically escaped to produce
HTML-safe output. This protects against injection attacks by escaping characters that
could be interpreted as HTML when inserted into a page.
Autoescaping replaces the following characters with their HTML-safe equivalents:
&->&<-><>->>'->'"->"
This escaping is equivalent to applying the escape filter to every variable, unless the variable is explicitly marked as safe.
Resource limits¶
Resource limits are used to prevent template authors from consuming too much memory or
too many CPU cycles. Limits are set by passing an instance of
liquid.ResourceLimits to the resource_limits argument of the
liquid.Environment constructor.
This example is equivalent to the default resource limits.
from liquid import Environment, ResourceLimits
env = Environment(
resource_limits=ResourceLimits(
max_assign_score=None,
max_assign_score_cumulative=None,
max_render_score=None,
max_render_score_cumulative=None,
max_render_size=None,
max_context_depth=30,
max_loop_iterations=None,
max_block_depth=30,
max_expression_depth=100,
)
)
Scores are non-specific measures of usage modelled after Shopify/liquid’s resource limits. It might take some trial and error to find the best limits for your use case.
This example sets a very low max_block_depth for demonstration purposes.
from liquid import Environment, ResourceLimits
env = Environment(resource_limits=ResourceLimits(max_block_depth=3))
source = """\
{% if true %}
{% if true %}
{% if true %}
{% if true %}
{% endif %}
{% endif %}
{% endif %}
{% endif %}
"""
template = env.parse(source)
# liquid.exceptions.ResourceLimitError: maximum block depth exceeded