Basic¶
- liquid.parse(source: str, *, name: str = '', globals: Mapping[str, Any] | None = None) Template¶
Parse template source code source using the default Liquid environment.
- Parameters:
source – Template source code.
name – A name for the template that will appear in error messages.
globals – Variables to pin to the resulting template.
- liquid.render(source: str, data: Mapping[str, Any] | None = None) str¶
Parse and render source with variables from data using the default environment.
- Parameters:
source – Template source code.
data – Template variables.
- async liquid.render_async(source: str, data: Mapping[str, Any] | None = None) str¶
Parse and render source asynchronously with variables from data using the default environment.
- Parameters:
source – Template source code.
data – Template variables.
- liquid.extract_liquid(fileobj: TextIO, keywords: list[str], comment_tags: list[str] | None = None, options: Mapping[str, Any] | None = None) Iterator[MessageTuple]¶
A babel compatible translation message extraction method for Liquid templates.
See https://babel.pocoo.org/en/latest/messages.html
Keywords are the names of Liquid filters or tags operating on translatable strings. For a filter to contribute to message extraction, it must also appear as a child of a FilteredExpression and be a TranslatableFilter. Similarly, tags must produce a node that is a TranslatableTag.
Where a Liquid comment contains a prefix in comment_tags, the comment will be attached to the translatable filter or tag immediately following the comment. Python Liquid’s non-standard shorthand comments are not supported.
Use
extract_from_templateto extract messages from an existing template bound to an existing environment.
- liquid.extract_from_templates(*templates: Template, keywords: dict[str, Any] | None = None, comment_tags: list[str] | None = None, strip_comment_tags: bool = False) Catalog¶
Extract messages from one or more templates.
This function returns a single babel.messages.Catalog containing messages from all the given templates.
- Parameters:
templates – Templates to extract messages from.
keywords – A Babel compatible mapping of translatable “function” names to argument specs. The included translation filters and tag transform their messages into typical *gettext format, regardless of their names.
comment_tags – A list of translator tags to search for and include in extracted messages.
strip_comment_tags – If True, remove comment tags from collected message comments.
- class liquid.Environment(*, autoescape: bool = False, bare_brackets: bool = True, conventional_operator_precedence: bool = False, extra: bool = False, globals: Mapping[str, object] | None=None, iterable_strings: bool = False, loader: Loader | None = None, parser: type[Parser] = <class 'liquid._parser_legacy.LegacyParser'>, resource_limits: ResourceLimits | None = None, shorthand_indexes: bool = False, strict_filters: bool = True, tokenizer: type[Lexer] = <class 'liquid._lexer_legacy.LegacyLexer'>, undefined: type[Undefined] = <class 'liquid.drops.undefined.Undefined'>)¶
Liquid template parsing and rendering configuration.
- Parameters:
autoescape – When
True, apply HTML-escaping to variables before writing them to the output buffer.bare_brackets – When
True, allow variables to start with a bracketed segment [var].conventional_operator_precedence – When
True, give logicalandandoroperators conventional precedence (andbinds tighter thanor) instead of legacy Liquid’s right-associative behavior.extra – Enable all built-in, non-standard tags and filters.
globals – A mapping of variables that will be attached to the Liquid environment. These variables will be available to all templates rendered from the environment.
iterable_strings – When
True, allow strings to be iterated with the{% for %}tag.loader – A template loader used by get_template, the {% render %} tag and any other tags that need to load templates.
parser – The parser to use. Built-in parsers are
liquid.LegacyParser,liquid.ExtendedParser,liquid.LaxLegacyParserandliquid.LaxExtendedParser.resource_limits – Limits used during template parsing an rendering to prevent malicious template authors from consuming to much memory or too many CPU cycles.
shorthand_indexes – When
True, allow dotted indexes in variable paths.a.1as well asa[1].strict_filters – When
True, raise an exception if a filter is unknown or is given unacceptable arguments. Otherwise silently ignore the filter invocation.tokenizer – The tokenizer to use. Built-in tokenizers are
liquid.LegacyLexerandliquid.ExtendedLexer.undefined – The class used to represent undefined template variables. Could be one of
liquid.Undefined,liquid.StrictUndefinedorliquid.FalsyUndefined.
- tags¶
A mapping of tag names to tag implementations. It’s OK to update this dictionary after instantiating an environment, or override setup_tags_and_filters.
- filters¶
A mapping of filter names to filter implementations. It’s OK to update this dictionary after instantiating an environment, or override setup_tags_and_filters.
- get_template(name: str, *, globals: Mapping[str, object] | None = None, context: RenderContext | None = None, **kwargs: object) Template¶
Load and parse the template identified by name using the configured loader.
- Parameters:
name – The template’s name or identifier. The template loader is responsible for interpreting name. It could be the name of a file on the file system or the value in a field in a database.
globals – A mapping of variables that will be attached to the resulting template.
context – The current render context, if one is available.
kwargs – Arbitrary arguments passed to the template loader that can be used to narrow the template search space.
- Raises:
LiquidSyntaxError – If the template source text contains invalid Liquid markup.
TemplateNotFoundError – If name is not known to the configured template loader.
- async get_template_async(name: str, *, globals: Mapping[str, object] | None = None, context: RenderContext | None = None, **kwargs: object) Template¶
Load and parse the template identified by name using the configured loader.
- Parameters:
name – The template’s name or identifier. The template loader is responsible for interpreting name. It could be the name of a file on the file system or the value in a field in a database.
globals – A mapping of variables that will be attached to the resulting template.
context – The current render context, if one is available.
kwargs – Arbitrary arguments passed to the template loader that can be used to narrow the template search space.
- Raises:
LiquidSyntaxError – If the template source text contains invalid Liquid markup.
TemplateNotFoundError – If name is not known to the configured template loader.
- parse(source: str, *, name: str = '', path: str | None = None, globals: Mapping[str, object] | None = None, matter: Mapping[str, object] | None = None, up_to_date: Callable[[], bool | Awaitable[bool]] | None = None) Template¶
Parse source as a Liquid template.
- Parameters:
source – Liquid template source code.
name – An optional name for the template. This name will appear in exception messages.
path – An optional path to name, if source represents a file or other resource with a path.
globals – A mapping of variables that will be attached to the resulting template.
matter – A mapping of variables associated with source. This could be front matter or meta data read from a database, for example.
up_to_date – A function use by the resulting template to determine if it needs to be loaded again after consulting a template cache.
- render(source: str, data: Mapping[str, object] | None = None) str¶
Parse and render source with variables from data
- Parameters:
source – Template source code.
data – Template variables.
- class liquid.Template(env: Environment, source: str, name: str, nodes: Block, *, path: str | None = None, globals: Mapping[str, object] | None, matter: Mapping[str, object] | None, up_to_date: Callable[[], bool | Awaitable[bool]] | None = None)¶
A compiled template ready to be rendered.
- analyze(*, include_partials: bool = True) TemplateAnalysis¶
Statically analyze this template and any included/rendered templates.
- Parameters:
include_partials – If
True, we will try to load partial templates and analyze those templates too.
- async analyze_async(*, include_partials: bool = True) TemplateAnalysis¶
An async version of analyze.
- comments() list[CommentTag | InlineCommentTag | TemplateComment]¶
Return a list of comment tag nodes found in this template.
Instances of CommentNode and InlineCommentNode have token and text properties. Use [node.text for node in template.comments()] to get a list of comment strings.
Note that this method does not try to load included or rendered templates.
- docs() list[DocTag]¶
Return a list of doc tag nodes found in this template.
Instances of DocNode have token and text properties. Use [node.text for node in template.docs()] to get a list of doc strings.
- errors() list[ErrorNode | ErrorExpr]¶
Return a list of error nodes found in this template.
Error nodes are inserted by lax parsers via
Environment.parser. Strict parsers raise errors before a template can be created.
- filter_names(*, include_partials: bool = True) list[str]¶
Return a list of filter names used in this template.
- async filter_names_async(*, include_partials: bool = True) list[str]¶
Return a list of filter names used in this template.
- global_variable_paths(*, include_partials: bool = True) list[str]¶
Return a list of variables used in this template including all path segments.
Excludes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct paths for variables in this template.
- async global_variable_paths_async(*, include_partials: bool = True) list[str]¶
Return a list of variables used in this template including all path segments.
Excludes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct paths for variables in this template.
- global_variable_segments(*, include_partials: bool = True) list[Segments]¶
Return a list of variables used in this template, each as a list of segments.
Excludes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct paths for variables in this template.
- async global_variable_segments_async(*, include_partials: bool = True) list[Segments]¶
Return a list of variables used in this template, each as a list of segments.
Excludes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct paths for variables in this template.
- global_variables(*, include_partials: bool = True) list[str]¶
Return a list of variables used in this template without path segments.
Excludes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct root segments for variables in this template.
- async global_variables_async(*, include_partials: bool = True) list[str]¶
Return a list of variables used in this template without path segments.
Excludes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct root segments for variables in this template.
- async is_up_to_date_async() bool¶
An async version of is_up_to_date.
If template.up_to_date is a coroutine, it wil be awaited. Otherwise it will be called just like is_up_to_date
- line_col(token: Token) tuple[int, int]¶
Return the line and column number of token in this template.
- render(data: Mapping[str, object] | None = None) str¶
Render this template with variables from data.
- async render_async(data: Mapping[str, object] | None = None) str¶
Render this template asynchronously with variables from data.
- render_with_errors(data: Mapping[str, object] | None = None) tuple[str, list[DetailedLiquidError]]¶
Render this template with error capture and rendering.
- Returns:
Rendered text and a list of
liquid.exceptions.DetailedLiquidError.
- async render_with_errors_async(data: Mapping[str, object] | None = None) tuple[str, list[DetailedLiquidError]]¶
Render this template asynchronously with error capture and rendering.
- Returns:
Rendered text and a list of
liquid.exceptions.DetailedLiquidError.
- tag_names(*, include_partials: bool = True) list[str]¶
Return a list of tag names used in this template.
- async tag_names_async(*, include_partials: bool = True) list[str]¶
Return a list of tag names used in this template.
- variable_paths(*, include_partials: bool = True) list[str]¶
Return a list of variables used in this template including all path segments.
Includes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.See also [global_variable_paths][liquid.BoundTemplate.global_variable_paths].
- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct paths for variables in this template.
- async variable_paths_async(*, include_partials: bool = True) list[str]¶
Return a list of variables used in this template including all path segments.
Includes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.See also [global_variable_paths][liquid.BoundTemplate.global_variable_paths].
- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct paths for variables in this template.
- variable_segments(*, include_partials: bool = True) list[Segments]¶
Return a list of variables used in this template, each as a list of segments.
Includes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.See [global_variable_segments][liquid.BoundTemplate.global_variable_segments].
- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct paths for variables in this template.
- async variable_segments_async(*, include_partials: bool = True) list[Segments]¶
Return a list of variables used in this template, each as a list of segments.
Includes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.See [global_variable_segments][liquid.BoundTemplate.global_variable_segments].
- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct paths for variables in this template.
- variables(*, include_partials: bool = True) list[str]¶
Return a list of variables used in this template without path segments.
Includes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.See also [global_variables][liquid.BoundTemplate.global_variables].
- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct root segments for variables in this template.
- async variables_async(*, include_partials: bool = True) list[str]¶
Return a list of variables used in this template without path segments.
Includes variables that are _local_ to the template, like those crated with
{% assign %}and{% capture %}.See also [global_variables][liquid.BoundTemplate.global_variables].
- Parameters:
include_partials (If
True, will try to load and find variables in) – included/rendered templates too.Returns – A list of distinct root segments for variables in this template.
- class liquid.LegacyLexer(env: Environment, source: str)¶
Bases:
LexerA Shopify/liquid v5.12.0 compatible tokenizer with hard coded delimiters.
- class liquid.ExtendedLexer(env: Environment, source: str)¶
Bases:
LexerA tokenizer that accepts alternative markup delimiters.
- class liquid.LegacyParser(env: Environment, source: str, template_name: str, tokens: list[Token])¶
Bases:
ParserA single pass template parser compatible with Shopify/liquid v5.12.0.
- class liquid.LaxLegacyParser(env: Environment, source: str, template_name: str, tokens: list[Token])¶
Bases:
LaxParserMixin,LegacyParserA legacy parser that suppresses Liquid syntax errors.
Use
Template.errors()to get a list of availableLiquidSyntaxErrorinstances.
- class liquid.ExtendedParser(env: Environment, source: str, template_name: str, tokens: list[Token])¶
Bases:
LegacyParserA parser that extends Shopify/liquid syntax with composable expressions.
- class liquid.LaxExtendedParser(env: Environment, source: str, template_name: str, tokens: list[Token])¶
Bases:
LaxParserMixin,ExtendedParserAn extended parser that suppresses Liquid syntax errors.
Use
Template.errors()to get a list of availableLiquidSyntaxErrorinstances.
- class liquid.ResourceLimits(*, max_assign_score: int | None = None, max_assign_score_cumulative: int | None = None, max_render_score: int | None = None, max_render_score_cumulative: int | None = None, max_render_size: int | None = None, max_context_depth: int = 30, max_loop_iterations: int | None = None, max_block_depth: int = 30, max_expression_depth: int = 100)¶
- Parameters:
max_assign_score (int | None) – The maximum assign score allowed per template before a
liquid.ResourceLimitErroris raised.max_assign_score_cumulative (int | None) – The maximum combined assign score allowed for a template and all its descendant partial templates before a
liquid.ResourceLimitErroris raised.max_render_score (int | None) – The maximum render score allowed per template before a
liquid.ResourceLimitErroris raised.max_render_score_cumulative (int | None) – The maximum combined render score allowed for a template and all its descendant partial templates before a
liquid.ResourceLimitErroris raised.max_render_size (int | None) – The maximum allowed length (in code points) of the output buffer per template before a
liquid.ResourceLimitErroris raised.max_context_depth (int) – The maximum number of times a render context can be extended or copied before a
liquid.ResourceLimitErroris raised. This helps us guard against circular{% render %}and{% include %}tags.max_loop_iterations (int | None) – The maximum number of loop iterations allowed before a
liquid.ResourceLimitErroris raised, taking into account nested loops that could span multiple partial templates.max_block_depth (int) – The maximum block nesting depth allowed before a
liquid.ResourceLimitErroris raised. This guards against specially crafted templates that could hit Python’s recursion limit during the parsing phase.max_expression_depth (int) – The maximum expression nesting depth allowed before a
liquid.ResourceLimitErroris raised. This guards against specially crafted expressions that could cause our recursive parser to hit Python’s recursion limit.