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:
ProtocolThe interface used for parsing tokens into markup nodes.
- class liquid.Markup(*args, **kwargs)¶
Bases:
ProtocolThe interface used for markup nodes in a template syntax tree.
All tags and the output statement must implement this interface.
- property blank: bool¶
Return
Trueif 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.
- 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 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.
- 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.
- class liquid.StringBuffer¶
An output text buffer that keeps track of its own length.