Tag

Liquid tags are defined by a pair of Protocols, liquid.Tag and liquid.Markup.

Tag has a single method, parse(), that is called by the parser and given the current token and the stateful parser instance as arguments. parse() then uses methods on liquid.Parser to process already scanned tokens, and returns a class implementing Markup.

                             Template source text
                                      │
                                      ▼
                                    Lexer
                   (Tokenizes template, including expressions)
                                      │
                                      ▼
                                    Parser
               (Steps through tokens, reads from the tag register)
                                      │
                                      ▼
                      Parser calls Tag.parse(token, parser)
                                      │
                                      ▼
                    Tag parses tokens using methods on `parser`
                              and returns `Markup`
                                      │
                                      ▼
                     Parser adds `Markup` to the active block

Tip

If built-in tokens and expressions will not do and you need to parse expression text yourself, use liquid.Parser.raw_expression(). It returns source text up to the next end tag delimiter.

At render time, Liquid calls liquid.Markup.render() whenever it needs to render a tag, at which point the tag should write output text to the provided buffer.

                            Template.render(data)
                                      │
                                      ▼
                        Markup.render(context, buffer)

Tip

It’s often convenient to implement liquid.Tag and liquid.Markup with a single class, where Tag.parse() is a static or class method. All built-in tags do this.

See built-in tags for lots of examples.

API

class liquid.Tag(*args, **kwargs)

Bases: Protocol

The interface used for parsing tokens into markup nodes.

classmethod parse(token: Token, parser: Parser) → Markup

Parse tokens or text from parser into a markup node.

class liquid.Markup(*args, **kwargs)

Bases: Protocol

The interface used for markup nodes in a template syntax tree.

All tags and the output statement must implement this interface.

property blank: bool

Return True if this node renders to an empty string or a string containing whitespace only.

This is used to suppress control flow blocks that don’t contain text or markup that contributes to the output.

block_scope() → list[Name]

Return variable names that are in scope for the duration of this node’s block.

This is used during static analysis to isolate and report global variables.

children() → list[Markup]

Returns markup nodes that are direct children of this node in the syntax tree.

This is used to traverse template syntax trees during static analysis.

expressions() → list[Expression]

Return expression owned by this node.

partials(context: RenderContext) → list[Partial]

Return meta data about partial templates rendered from this node.

async partials_async(context: RenderContext) → list[Partial]

Return meta data about partial templates rendered from this node.

render(context: RenderContext, buffer: StringBuffer) → None

Render this node to buffer using data from context.

async render_async(context: RenderContext, buffer: StringBuffer) → None

Render this node to buffer asynchronously using data from context.

property tag: str

Return the name of this tag, or the empty string if this node is not a tag.

template_scope() → list[Name]

Return variable names that this tag adds to the template scope.

property token: Token

Return a representative token for this node.

In the absence of a more specific token from an enclosed expression, this token will be used for reporting errors.

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

A base parser from which different parser behavior can be derived.

current() → Token

Return the current token without advancing the pointer.

eat(kind: TokenKind, message: str | None = None) → Token

Consume and return a token matching kind.

Parameters:
  • kind – The expected type of the next token in the stream.

  • message – An custom error message to use in the event of a syntax error.

Raises:

LiquidSyntaxError – If the current token’s kind does not match kind.

kind() → TokenKind

Return the kind of the current token without advancing the pointer.

next() → Token

Return the current token and advance the pointer.

abstractmethod parse_arguments(require_commas: bool = True) → list[Expression | KeywordArgument]

Parse positional and/or keyword arguments from the token stream.

Assumes any leading commas have been consumed by the caller, if they are allowed.

Parameters:

require_commas – When true, throw a syntax error if arguments are not separated by a comma.

abstractmethod parse_block(end: Collection[str]) → Block

Parse text and markup until reaching a named tag.

Parameters:

end – Possible tag names that terminate the block.

Returns:

block – A sequence of nodes in the template syntax tree.

abstractmethod parse_expression(precedence: Precedence = 1, *, infix: bool = False, expect_end_of_expression: bool = False) → Expression

Parse a “common” expression from the token stream.

Parameters:
  • precedence – The binding power of this sub expression.

  • infix – When true, accept infix operators when parsing the expression.

  • expect_end_of_expression – When True, raise a syntax error if we don’t finish on an expression termination token.

abstractmethod parse_filtered_expression(precedence: Precedence = 1, *, infix: bool = False) → Expression

Parse a “common” expression optionally followed by one or more filters.

Parameters:
  • precedence – The binding power of this sub expression.

  • infix – When true, accept infix operators when parsing the expression.

abstractmethod parse_identifier() → Name

Parse an identifier

Raises:

LiquidSyntaxError – If the identifier is followed by path segments.

abstractmethod parse_keyword_arguments(require_commas: bool = True) → list[KeywordArgument]

Parse zero or more keyword arguments from the token stream.

Assumes any leading commas have been consumed by the caller, if they are allowed.

Parameters:

require_commas – When true, throw a syntax error if arguments are not separated by a comma.

abstractmethod parse_line_statements() → Block

Parse newline terminated markup from the {% liquid %} tag.

abstractmethod parse_name() → Name

Parse an identifier, possibly surrounded by quotes.

Raises:

LiquidSyntaxError – If the identifier is followed by path segments.

abstractmethod parse_parameters(require_commas: bool = True) → list[Parameter]

Parse zero or more parameters from the token stream.

A parameter is a Name with an optional default expression.

Assumes any leading commas have been consumed by the caller, if they are allowed.

Parameters:

require_commas – When true, throw a syntax error if arguments are not separated by a comma.

abstractmethod parse_positional_arguments(require_commas: bool = True) → list[Expression]

Parse zero or more positional arguments from the token stream.

Assumes any leading commas have been consumed by the caller, if they are allowed.

Parameters:

require_commas – When true, throw a syntax error if arguments are not separated by a comma.

abstractmethod parse_string_literal() → StringLiteral

Parse a literal string surrounded by single or double quotes.

peek(n: int = 1) → Token

Return the token at pos+n without advancing the pointer.

peek_kind(n: int = 1) → TokenKind

Return the token kind at pos+n without advancing the pointer.

raw_expression() → str

Return source text up to but not including the next closing tag delimiter.

Calls carry_whitespace_control() and consumes the closing tag delimiter, leaving the parser ready to parse the next block.

tag(name: str) → bool

Return true if we’re at the start of a tag named name.

tags(names: Collection[str]) → str | None

Return true if we’re at the start of a tag and that tag’s name is in names.

value() → str

Return the string value associated with the current token.

class liquid.StringBuffer

An output text buffer that keeps track of its own length.

getvalue() → str

Return the contents of the buffer.

write(s: str) → None

Write s to the buffer.

type liquid.Node = str | Markup
type liquid.Block = list[Node]