Environment

liquid2.Environment

Template parsing and rendering configuration.

An Environment is where you might register custom tags and filters, or store global context variables that should be included with every template.

PARAMETER	DESCRIPTION
loader	A template loader from which template source text will be read when calling get_template or when rendering with the built-in {% include %} and {% render %}, among others. If None, the environment will be configured with an empty DictLoader. TYPE: BaseLoader | None DEFAULT: None
globals	An optional mapping of template variables that will be added to the render context of all templates rendered from the environment. TYPE: Mapping[str, object] | None DEFAULT: None
auto_escape	If True, automatically escape HTML text upon output, unless the text is explicitly marked as "safe". TYPE: bool DEFAULT: False
undefined	The Undefined type used to represent template variables that don't exist. TYPE: Type[Undefined] DEFAULT: Undefined
default_trim	The automatic whitespace stripping mode to use. This mode can then be overridden by template authors per Liquid tag using whitespace control symbols (-, +, ~). TYPE: WhitespaceControl DEFAULT: PLUS
validate_filter_arguments	If True, class-based filters that define a validate() method will have their arguments validated as each template is parsed. TYPE: bool DEFAULT: True

context_depth_limit class-attribute

context_depth_limit: int = 30

Maximum number of times a render context can be extended or wrapped before raising a ContextDepthError.

default_trim instance-attribute

default_trim: WhitespaceControl = (
    PLUS if default_trim == DEFAULT else default_trim
)

The default whitespace trimming mode.

filters instance-attribute

filters: dict[str, Callable[..., Any]] = {}

The environment's filter register, mapping filter names to callables.

lexer_class class-attribute instance-attribute

lexer_class = Lexer

The lexer class to use when scanning template source text.

local_namespace_limit class-attribute

local_namespace_limit: int | None = None

Maximum number of bytes (according to sys.getsizeof) allowed in a template's local namespace before a LocalNamespaceLimitError is raised. We only count the size of the namespaces values, not the size of keys/names.

loop_iteration_limit class-attribute

loop_iteration_limit: int | None = None

Maximum number of loop iterations allowed before a LoopIterationLimitError is raised.

output_stream_limit class-attribute

output_stream_limit: int | None = None

Maximum number of bytes that can be written to a template's output stream before raising an OutputStreamLimitError.

shorthand_indexes class-attribute instance-attribute

shorthand_indexes: bool = False

If True, array indexes can be separated by dots without enclosing square brackets. The default is False.

suppress_blank_control_flow_blocks class-attribute instance-attribute

suppress_blank_control_flow_blocks: bool = True

If True (the default), indicates that blocks rendering to whitespace only will not be output.

tags instance-attribute

tags: dict[str, Tag] = {}

The environment's tag register, mapping tag names to instances of Tag.

template_class class-attribute instance-attribute

template_class = Template

The template class to use after parsing source text.

from_string

from_string(
    source: str,
    *,
    name: str = "",
    path: str | Path | None = None,
    globals: Mapping[str, object] | None = None,
    overlay_data: Mapping[str, object] | None = None
) -> Template

Create a template from a string.

get_template

get_template(
    name: str,
    *,
    globals: Mapping[str, object] | None = None,
    context: RenderContext | None = None,
    **kwargs: object
) -> Template

Load and parse a template using the configured loader.

PARAMETER	DESCRIPTION
name	The template's name. The loader is responsible for interpreting the name. It could be the name of a file or some other identifier. TYPE: str
globals	A mapping of render context variables attached to the resulting template. TYPE: Mapping[str, object] | None DEFAULT: None
context	An optional render context that can be used to narrow the template source search space. TYPE: RenderContext | None DEFAULT: None
kwargs	Arbitrary arguments that can be used to narrow the template source search space. TYPE: object DEFAULT: {}

RAISES	DESCRIPTION
TemplateNotFound	If a template with the given name can not be found.

get_template_async async

get_template_async(
    name: str,
    *,
    globals: Mapping[str, object] | None = None,
    context: RenderContext | None = None,
    **kwargs: object
) -> Template

An async version of get_template().

make_globals

make_globals(
    globals: Mapping[str, object] | None = None,
) -> dict[str, object]

Combine environment globals with template globals.

parse

parse(source: str) -> list[Node]

Compile template source text and return an abstract syntax tree.

setup_tags_and_filters

setup_tags_and_filters() -> None

Add tags and filters to this environment.

This is called once when initializing an environment. Override this method in your custom environments.

tokenize

tokenize(source: str) -> list[TokenT]

Scan Liquid template source and return a list of Markup objects.

trim

trim(
    text: str,
    left_trim: WhitespaceControl,
    right_trim: WhitespaceControl,
) -> str

Return text after applying whitespace control.