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_template to 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 logical and and or operators conventional precedence (and binds tighter than or) 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.LaxLegacyParser and liquid.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.1 as well as a[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.LegacyLexer and liquid.ExtendedLexer.

  • undefined – The class used to represent undefined template variables. Could be one of liquid.Undefined, liquid.StrictUndefined or liquid.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.

Type:

dict[str, Tag]

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.

Type:

dict[str, Filter]

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:
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:
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.

async render_async(source: str, data: Mapping[str, object] | None = None) → str

Parse and render source asynchronously with variables from data.

Parameters:
  • source – Template source code.

  • data – Template variables.

serialize(obj: object, context: RenderContext, span: Token) → str

Stringify obj suitable for output.

to_date(obj: object, context: RenderContext, span: Token) → dt.datetime | None

Return obj coerced to a datetime, or None on failure.

Parameters:
  • obj – The object to convert to a datetime.

  • context – The active render context.

  • span – A token suitable for use with error messages.

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.

is_up_to_date() → bool

Return False if the template has bee modified, True otherwise.

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: Lexer

A Shopify/liquid v5.12.0 compatible tokenizer with hard coded delimiters.

class liquid.ExtendedLexer(env: Environment, source: str)

Bases: Lexer

A tokenizer that accepts alternative markup delimiters.

class liquid.LegacyParser(env: Environment, source: str, template_name: str, tokens: list[Token])

Bases: Parser

A 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, LegacyParser

A legacy parser that suppresses Liquid syntax errors.

Use Template.errors() to get a list of available LiquidSyntaxError instances.

class liquid.ExtendedParser(env: Environment, source: str, template_name: str, tokens: list[Token])

Bases: LegacyParser

A parser that extends Shopify/liquid syntax with composable expressions.

class liquid.LaxExtendedParser(env: Environment, source: str, template_name: str, tokens: list[Token])

Bases: LaxParserMixin, ExtendedParser

An extended parser that suppresses Liquid syntax errors.

Use Template.errors() to get a list of available LiquidSyntaxError instances.

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.ResourceLimitError is 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.ResourceLimitError is raised.

  • max_render_score (int | None) – The maximum render score allowed per template before a liquid.ResourceLimitError is 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.ResourceLimitError is raised.

  • max_render_size (int | None) – The maximum allowed length (in code points) of the output buffer per template before a liquid.ResourceLimitError is raised.

  • max_context_depth (int) – The maximum number of times a render context can be extended or copied before a liquid.ResourceLimitError is 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.ResourceLimitError is 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.ResourceLimitError is 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.ResourceLimitError is raised. This guards against specially crafted expressions that could cause our recursive parser to hit Python’s recursion limit.