python-liquid

• Fixed PackageLoader. It now rejects fully qualified template names that could escape the package directory.
• Fixed the first and last filters when the Liquid.Environment class variable string_first_and_last is True. Setting the string_first_and_last option to True would correctly tell the .first and .last special properties to treat strings as sequences, but the same behavior was not implemented for equivalent filters. Now | first and | last behave the same as .first and .last. See #213.

Fixes

• Fixed an issue with excessively large integer values given to offset in {% for %} and {% tablerow %} tags. Previously we would get a ValueError in somme cases. Now we clamp offset to the length of the target iterable. See #209.

• Fixed an issue with excessively large range literals ((1..10)). We now limit the minimum and maximum values allowed in range literal expressions to between -1024 and 1024.

• Fixed an issue with FileSystemLoader where it would raise an OSError if given a very long file name when testing a path for existence.

Features

• Added the block_nesting_limit class variable to liquid.Environment for handling excessive markup block nesting in Liquid templates. Previously we would get a RecursionError at render time if Python's recursion limit was reached. Now we raise a BlockNestingError (a subclass of ResourceLimitError) at parse time if block_nesting_limit is reached.

  The default block_nesting_limit is 30. That's a maximum depth of 30 blocks per template source string or file.

  See #208.

Fixes

• Fixed a bug in the built-in FileSystemLoader where a ValueError would be raised at render time if the target file name is empty or, in some cases, contains only path punctuation and the loader is configured with a default file extension. Now a TemplateNotFoundError is raised instead. See #203.
• Fixed an issue with the built-in FileSystemLoader where a ValueError would be raised at render time if the configured default file extension is not a valid suffix. Now we raise a ValueError at FileSystemLoader construction time if the ext argument is not a valid suffix.
• Fixed a bug with the {% cycle %} tag. Previously, if given a cycle group name without any other arguments, a ZeroDivisionError exception would be raised at render time. Now we raise a LiquidSyntaxError (we don't have a TagArgumentError) at parse time. See #202.
• Fixed a bug where we'd get an AssertionError at render time when resolving variables using bracket syntax for the root segment and that segment evaluates to a non-string value. Now such uses of bracketed path syntax will be resolved to the configured Undefined type. See #206.

Fixed {% case %} tags with no associated {% when %} or {% else %} tags, and no closing {% endcase %} tag. Previously a template such as {% case x %} would cause the parser to hang in an infinite loop.

• Fixed FileSystemLoader and CachingFileSystemLoader to reject absolute paths.
• Added the reject_symlinks keyword argument to FileSystemLoader and CachingFileSystemLoader. When True, symlinks pointing to files outside the search path will be rejected. reject_symlinks defaults to False.
• Added the squish filter. {{ x | squish }} is equivalent to {{ x | strip | split | join }}. See #195.
• Added BoundTemplate.comments() and BoundTemplate.docs() for statically retrieving {% comment %}, {% # inline comment %} and {% doc %} nodes.
• Added an experimental {% snippet %} tag. Shopify/liquid released then quickly removed {% snippet %}. We're calling it "experimental" and keeping it disabled by default, pending more activity from Shopify/liquid. See #191 and #193.
• Improved static analysis of partial templates. Previously we would visit a partial template only once, regardless of how many times it is rendered with {% render %}. Now we visit partial templates once for each distinct set of arguments passed to {% render %}, potentially reporting "global" variables that we'd previously missed.
• Changed the string_filter decorator to coerce None to an empty string instead of "None". This is what Shopify/liquid does with nil.to_s.

Features

• Added the escapejs filter for escaping characters for use in JavaScript string literals. Whereas the standard escape filter replaces &, <, >, ' and " with their equivalent HTML escape sequence, escapejs replaces control characters and potentially dangerous symbols with their corresponding Unicode escape sequences.

Docs

• Improved documentation for HTML auto escaping and the escape filter.

• Fixed static analysis of filters in ternary expressions. See #180.
• Fixed static analysis of macro blocks. Previously args and kwargs were considered "global". See #181.
• Fixed looping over non-iterable objects with the {% for %} tag. We were raising a LiquidTypeError when we should have been defaulting to an empty iterable, as Shopify/liquid does.

Fixes

• Fixed bad imports from typing_extensions.

This is a major release with several breaking changes. As well as API changes listed below, we:

• Drop support for Python version 3.7 and 3.8.
• Promote rendering behavior from liquid.future.Environment to be the default, so as to improve Shopify/liquid compatibility by default.
• Fix variable/identifier/path parsing described in issue #39.
• Improve Liquid syntax error messages and exposes source index, line numbers and column numbers through methods on Liquid exceptions. See #53.
• Change comment tag parsing to better match Shopify/Liquid. See #133.
• Remove BoundTemplate.analyze_with_context(). Shout if you need contextual analysis and we'll restore this feature.
• Remove the cache_size argument to liquid.Environment and liquid.Template. Template caching is now handled by template loaders.
• Remove the expression_cache_size argument to liquid.Environment and liquid.Template. Environment-level expression caching is no longer available as it does not play nicely with detailed error messages. If you need to cache parsing of Liquid expressions, it is now recommended to implement a cache per tag, where it makes sense to do so for your use case.
• Make markupsafe>=3 a dependency. Previously markupsafe was an optional dependency. Version 3 of markupsafe brings some subtle changes to the replace, replace_first and replace_last filters when they receive a "safe" string wrapped in Markup().
• Add new filters reject, has, find and find_index.
• Add the new doc tag.

API changes

Also see the migration guide.

Miscellaneous

• Added liquid.parse(source), liquid.render(source, **data) and liquid.render_async(source, **data). These are shorthand functions that use liquid.DEFAULT_ENVIRONMENT.
• Renamed liquid.Environment.parse to liquid.Environment._parse, which returns a list of nodes, not a template.
• Aliased liquid.Environment.from_string as liquid.Environment.parse.
• Added liquid.Environment.render(source, **data) and liquid.Environment.render_async(source, **data). These are convenience methods equivalent to liquid.Environment.from_string(source).render(**data).
• Renamed liquid.Context to liquid.RenderContext.
• Change the liquid.RenderContext constructor (previously liquid.Context) to require an instance of BoundTemplate as its only positional argument instead of an instance of Environment. All other arguments are now keyword only.
• Renamed liquid.exceptions.Error to liquid.exceptions.LiquidError.
• Renamed liquid.exceptions.TemplateNotFound to liquid.exceptions.TemplateNotFoundError.
• Renamed liquid.exceptions.NoSuchFilterFunc to liquid.exceptions.UnknownFilterError.

Template loaders

• Changed BaseLoader.get_source and BaseLoader.get_source_async to accept and optional context keyword argument and arbitrary keyword arguments as "load context".
• Removed BaseLoader.get_source_with_args and BaseLoader.get_source_with_context, and their async equivalents. BaseLoader.get_source now accepts optional context and load context arguments.
• Changed TemplateSource (a named tuple) to be (text, name, uptodate, matter). It used to be (source, filename, uptodate, matter)

Builtin expressions

• Removed liquid.expression.*. Now built-in expressions live in liquid.builtin.expressions.
• Renamed Identifier to Path.
• Removed IdentifierPathElement. Path segments are now list[str | int | Path]].
• Removed constant versions of True, False, Nil, Empty and Blank. Each of these primitive expressions now require a token, so they can't be constant.

Tag expression parsing

• Changed liquid.token.Token to be a named tuple of (kind, value, index, source). It used to be (linenum, type, value).
• Removed legacy expression parsing functions. If you're importing anything from liquid.parse for your custom tags, you'll need to use functions/methods from liquid.builtin.expressions instead.
• Removed liquid.parse.expect() and liquid.parse.expect_peek() in favour of TokenStream.expect() and TokenStream.expect_peek().
• Removed liquid.expressions.TokenStream. Now there's only one TokenStream class, liquid.stream.TokenStream, reexported as liquid.TokenStream.
• All tokens are now named tuples. Previously functions in liquid.expressions would generate and use plain tuples internally.
• Added the TOKEN_RANGE_LITERAL token kind. The opening parenthesis of a range expression will use this kind to differentiate logical grouping parentheses from range expressions.
• Split tokens with kind TOKEN_OUTPUT in to two tokens, TOKEN_OUTPUT and TOKEN_EXPRESSION. Previously the value associated with TOKEN_OUTPUT would be the expression, now the expression follows in the next token, just like TOKEN_TAG.

Here's a summary mapping from old expression parsing functions to the recommended new parsing functions/methods.

Old	New
tokenize_common_expression(str, linenum)	liquid.builtin.expressions.tokenize(source, parent_token)
*.tokenize(source, linenum)	liquid.builtin.expressions.tokenize(source, parent_token)
parse_common_expression(stream)	liquid.builtin.expressions.parse_primitive(env, stream)
parse_keyword_arguments(expr, linenum)	liquid.builtin.expressions.KeywordArgument.parse(env, stream)
parse_identifier(stream)	liquid.builtin.expressions.Path.parse(env, stream)
parse_unchained_identifier(stream)	liquid.builtin.expressions.parse_identifier(env, stream)
parse_string_or_identifier	liquid.builtin.expressions.parse_string_or_path(env, stream)
parse_unchained_identifier	liquid.builtin.expressions.parse_name(env, stream)
parse_boolean	liquid.builtin.expressions.parse_primitive(env, stream)
parse_nil	liquid.builtin.expressions.parse_primitive(env, stream)
parse_empty	liquid.builtin.expressions.parse_primitive(env, stream)
parse_blank	liquid.builtin.expressions.parse_primitive(env, stream)
parse_string_literal	liquid.builtin.expressions.parse_primitive(env, stream)
parse_integer_literal	liquid.builtin.expressions.parse_primitive(env, stream)
parse_float_literal	liquid.builtin.expressions.parse_primitive(env, stream)
Environment.parse_boolean_expression	liquid.builtin.expressions.BooleanExpression.parse(env, stream)
Environment.parse_filtered_expression	liquid.builtin.expressions.FilteredExpression.parse(env, stream)
Environment.parse_loop_expression	liquid.builtin.expressions.LoopExpression.parse(env, stream)

Features

• Added a shorthand_indexes class variable to liquid.Environment. When shorthand_indexes is set to True (default is False), array indexes in variable paths need not be surrounded by square brackets. See #165.

Fixes

• Fixed {% case %} / {% when %} behavior. When using liquid.future.Environment, we now render any number of {% else %} blocks and allow {% when %} tags to appear after {% else %} tags. The default Environment continues to raise a LiquidSyntaxError in such cases.
• Fixed line numbers in some error messages. When parsing some Liquid expressions, we were always getting a line number of 1 in the event of a syntax error. See issue #162.

Changed

• Changed {% break %} and {% continue %} tag handling when they appear inside a {% tablerow %} tag. Now, when using liquid.future.Environment, interrupts follow Shopify/Liquid behavior introduced in #1818. Python Liquid's default environment is unchanged.

Fixes

• Fixed handling of {% else %} tags that include text between else and the closing tag delimiter (%}). Previously we were treating such text as part of the {% else %} block. Now the default behavior is to raise a LiquidSyntaxError. When using liquid.future.Environment, we follow Shopify/Liquid behavior of silently ignoring {% else %} tag expressions, even in strict mode. See #150.
• liquid.future.Environment now silently ignores superfluous {% else %} and {% elsif %} blocks. The default environment continues to raise a LiquidSyntaxError if {% else %} or {% elsif %} appear after the first {% else %} tag. See #151.

Fixes

• Fixed a bug with the LRU cache. We now raise a ValueError at construction time if a caching template loader is given a cache size less than 1. Previously, in such cases, an IndexError would have been raised when attempting to write to the cache. See #148.

Features

• Added make_choice_loader(), a factory function that returns a ChoiceLoader or CachingChoiceLoader depending on its arguments. (docs, source)
• Added make_file_system_loader(), a factory function that returns a FileSystemLoader, FileExtensionLoader or CachingFileSystemLoader depending on its arguments. (docs, source)

Fixes

• Fixed comparing strings with <, <=, > and >= in boolean expressions ({% if %} and {% unless %}). Previously we were raising a LiquidTypeError, now we return the result of comparing two string by their lexicographical order. See #141.

Features

• Added CachingChoiceLoader, a template loader that chooses between a list of template loaders and caches parsed templates in memory. (docs, source)
• Added PackageLoader, a template loader that reads templates from Python packages. (docs, source)

Dependencies

• Python Liquid now depends on importlib-resources >= 5.10. This is that backport of importlib.resources from Python's standard library. We use it in PackageLoader.

Fixes

• Added an additional implementation of the split filter, which resolves some compatibility issues between Python Liquid's and the reference implementation. Previously, when given an empty string to split or when the string and the delimiter were equal, we used Python's str.split() behavior of producing one or two element lists containing empty strings. We now match Shopify/Liquid in returning an empty list for such cases. The new split filter will be enabled by default when using liquid.future.Environment, and can optionally be registered with liquid.Environment for those that don't mind the behavioral change. See #135.

• Fixed unexpected errors from the date filter when it's given an invalid format string. Previously we were raising a liquid.exceptions.Error in response to a ValueError from strftime. We now raise a FilterArgumentError with its __cause__ set to the ValueError.

• Fixed handling of "%s" date filter format strings. We now fall back to a string representation of datetime.timestamp() for platforms that don't support %s. Note that this is for "%s" exactly. We don't handle the more general case of %s appearing in a longer format string.

Features

• Optionally disable automatic suppression of whitespace only blocks with the Environment class attribute render_whitespace_only_blocks. (docs).
• All built-in and included "extra" tags now have a node_class class attribute specifying the Node type the tag contributes to a templates AST. This is done for easier customization through Tag and Node subclassing.

Fixes

• Fixed async loading of templates with the {% extends %} tag. Previously templates were being loaded synchronously, even when using render_async(). See #124.
• Fixed handling of recursive {% extends %} tags during async static analysis. See #125.

Fixes

• Removed is_up_to_date from liquid.BoundTemplate.__repr__. It was causing RuntimeWarnings with Python 3.11 when using an async template loader. Specifically warnings about coroutines that were never awaited.
• Fixed the map filter. If given a nested array-like input, it now flattens it automatically. See #119.
• Fixed the behavior of the liquid tag when other liquid tags appear within it. See #123.

Features

• Added the sum filter, which will return the sum of all numeric values in its input sequence. (docs, source).
• Added Environment.setup_tags_and_filters() for easier tag and filter registration when subclassing Environment. See #122.

Fixes

• Fixed a bug where a class-based filter defining filter_async and setting with_context or with_environment to True would not be awaited. See #117.

Build

• Fixed some package build issues since moving to hatch. Both version 1.9.0 and 1.9.1 inadvertently included .mypy_cache folders, making the distribution files significantly larger.

Fixes

• Force the "wheel" build target to include py.typed.
• Restore liquid.__version__.

Fixes

• Changed FileSystemLoader so that loaded templates can be pickled. See #107.
• Fixed the liquid.Environment template cache. Now, when given a cache_size of 0, the cache is disabled. See #108.

Features

• Added context-aware template loader bootstrapping methods. See #109.
• Added support for async class-based filters. See #115.
• Added CachingFileSystemLoader, a template loader that handles its own cache rather than relying on the Environment template cache, which can't handle context-aware loaders. See #116.

See CHANGELOG.

See CHANGELOG.

See CHANGELOG.

Fixes

• Fixed static template analysis fails with {% break %} and {% continue %}. See #89.

See CHANGELOG.

Fixes

• Fixed case and when tag expression parsing. when expressions no longer fail when presented with a string containing a comma. Handling of comma and or separated "sub-expressions" is now consistent with the reference implementation. See #86.

Feature release. See CHANGELOG.

Bug fix release. See CHANGELOG.

Bug fixes and test against Python 3.11. See CHANGELOG.

Bug fix release. See CHANGELOG.

Fixes

• Keep comment text for later static analysis when parsing {% comment %} block tags. See https://github.com/jg-rp/liquid/issues/70.
• Guard against DoS by very large str to int conversion. We honour environment variable PYTHONINTMAXSTRDIGITS, or use LIQUIDINTMAXSTRDIGITS if you want to set Liquid's max digits independently. The default is 4300. See https://github.com/python/cpython/issues/95778

Bug fixes. See CHANGELOG.

Fixes

• Fixed a potential memory leak from using functools.lru_cache on a class method. See #63.
• Fixed a bug with the default filter. Liquid zero should not be equal to False. The default filter now returns 0 if its left value is zero. Before it would have return its default value. See #62.
• Fixed a bug where boolean expressions would consider Liquid 0 and false to be equal and 0 to be falsy. Python Liquid is now consistent with the reference implementation when comparing integers to booleans. See #65.

Hot fix

• Fixed a bug with the StrictDefaultFilter. It was failing to be strict when accessed by some filter decorators and helpers. Now the default filter will immediately return its default value if its left value defines a force_liquid_default property and that property is truthy. See #62.

Feature release. Resource limits.

Features

• Allow render context customization by subclassing Context and BoundTemplate.
• Contextual template analysis with BoundTemplate.analyze_with_context(). Complementing static template analysis, released in version 1.2.0, contextual template analysis performs a template render, capturing information about template variable usage as it goes. (docs)

• Add typing-extensions dependency.

Features

• New inline comment tag {% # .. %}. See Shopify Liquid PR #1498
• Template static analysis. BoundTemplate.analyze() and BoundTemplate.analyze_async() traverse a template's abstract syntax tree and report template variable usage. Static tree traversal (without rendering or evaluating expressions) is supported by the new, optional children() methods of liquid.expression.Expression and liquid.ast.Node. (docs)

Fixes

• Fixed a bug where the lexer would incorrectly calculate an expression's line number if there were one or more newlines between a tag name and it's expression. Most notable with liquid tags where it is common to put a newline immediately after "liquid".
• More robust syntax error handling when parsing Liquid expression filters. The refactored expression lexers from version 1.1.3 failed to account for some classes of syntax error.

• Fixed a bug where double pipe characters (||) in a filtered expression would cause an IndexError. A LiquidSyntaxError is now raised in such cases, including the line number of the offending error.
• Changed Environment.fromString to catch unexpected parsing errors. A Liquid Error will now be raised with a message of "unexpected liquid parsing error" and its __cause__ set to the offending exception.

• Fixed a bug where the where filter would incorrectly ignore an explicit false given as the target value. See #51.

• Prioritise object properties and keys named size, first and last over the special built-in properties of the same names. See #46.
• Fixed a bug with the uniq filter. It no longer raises an exception when given a key argument and a sequence containing objects that don't have that key/property. See #47.
• The strip_html filter now removes style and script tag blocks in their entirety, including everything in between. See #45.
• Added remove_last and replace_last filters.

• Lazy forloop helper variables. Don't calculate index, rindex etc. unless accessed.
• Implemented forloop.name, as per the reference implementation. forloop.name is the concatenation of the loop variable identifier and the target iterable identifier, or a string representation of a range literal, separated by a hyphen.
• Fixed a bug with the divided_by filter. Given a float value and integer argument, it was incorrectly doing integer division.
• Simplified tablerowloop and tablerow HTML generation.

• Refactored expression lexers. New, subtly different, tag expression tokenizers are now in liquid.expressions. Built-in tags use these lexers indirectly via new specialized expression parsers. Older expression lexers and parsers will be maintained until at least Python Liquid version 2.0 for those that use them in custom tags. See #42.
• Specialized expression parsers. Each of the three built-in expression types now have a dedicated parser defined in liquid.expressions, whereas before all expression parsing went through liquid.parse.ExpressionParser.parse_expression(). Built-in tags now use these new parsers. The more general parser will be maintained until at least Python Liquid Version 2.0. See #42.
• liquid.parse.Parser.parse_block() now accepts any container as its end argument. Benchmarks show that using a frozenset for end instead of a tuple gives a small performance improvement.
• Fixed an incompatibility with the reference implementation where Python Liquid would not recognize identifiers with a trailing question mark. This seems to be a common idiom in Ruby to indicate something returns a Boolean value.
• Added get_source_with_context() and get_source_with_context_async() to liquid.loaders.BaseLoader. Custom loaders can now use the active render context to dynamically modify their search space when used from include or render, or any custom tag using Context.get_template_with_context(). Context.get_template_with_context() also accepts arbitrary keyword arguments that are passed along to get_source_with_context(). The build-in include and render tags add a tag argument with their tag name, so custom loaders can modify their search space depending on which tag was used. See the Custom Loaders documentation for examples.

• Fixed a bug where a for loop's limit would be incorrect when using offset: continue multiple times (three or more for tags looping over the same sequence). See #41.

• Fixed a bug where blocks that contain whitespace only were being suppressed when the whitespace was explicitly output. Automatic whitespace suppression now only occurs in if, unlesss and for blocks that don't contain an output statement or echo tag, even if the output itself is whitespace. See #38.
• Fixed a bug where the behavior of the special .first and .last properties did not match that of the first and last filters. Now, if given a string, .first and .last will return an undefined, and the first and last filters will return None. See #34.

• Added new comment syntax. Disabled by default, enable shorthand comments with the template_comments argument to liquid.Template or liquid.Environment. When True, anything between {# and #} will be considered a comment.
• New expression cache. Distinct from the existing template cache, optionally cache common Liquid expression types (conditions, loops and filtered expressions) to avoid lexing and parsing the same expression multiple times.
• Fixed a bug where, in some cases, forloop.length would be incorrect when using offsset: continue in a loop expression.

• Explicit re-export
• Changed Context._tag_namespace to Context.tag_namespace.

• Fixed manifest error.

• Added py.typed

Version bump. First stable release.

The following behavioral changes are the result of feedback gained from exporting Python Liquid's "golden" test cases, and running them against Ruby Liquid (the reference implementation). Both Python Liquid version 0.11.0 and Ruby Liquid version 5.1.0 pass all tests currently defined in liquid/golden/.

• Added support for comma separated when expressions. See #31.
• The built-in join, concat, where, uniq and compact filters now use the new sequence_filter decorator. sequence_filter coerces filter left values to array-like objects. sequence_filter will also flatten nested array-like objects, just like the reference implementation.
• The built-in first, last and map filters now operate on any array-like objects. Previously they were limited to lists and tuples. Strings still don't work.
• The built-in uniq and compact filters now accept an optional argument. If an argument is provided, it should be the name of a property and the left value should be a sequence of objects.
• The size filter now returns a default of 0 if its left value does not have a __len__ method.
• The replace and replace_first filters now treat undefined arguments as an empty string.
• The slice filter now works on lists, tuples and ranges, as well as strings.
• Fixed a bug where the math_filter decorator would cast strings representations of negative integers to a float rather than an int.
• Added golden test cases for all filters.

• Range literals can now be assigned, compared and passed as arguments to include or render tags. They can also be filtered as if they were an array.
• Range literals will accept a float value for start and/or stop values. If a float is given for start or stop, it will be cast to an integer.
• Fixed a bug where the token stream would return the wrong token when peeking immediately after a push.

• Changed named counter (increment and decrement) scoping. Unless a named counter is shadowed by an assign or capture, the counter will be in scope for all subsequent Liquid expressions.
• Changed {% increment %} to be a post-increment operation. {% decrement %} remains a pre-decrement operation.
• Added forloop.parentloop. Access parent forloop objects from nested loops.

• Fixed a bug where arguments to Template() where not being passed to the implicit environment properly (again).
• Fixed a bug where some errors from the sort and map filters were being ignored. Those filters can now raise a FilterError.
• Removed depreciated class-based filters.

• Removed @abstractmethod from liquid.loaders.BaseLoader.get_source. Custom loaders are now free to implement either get_source or get_source_async or both. The BaseLoader implementation of get_source simply raises a NotImplementedError.
• liquid.loaders.TemplateSource.uptodate (as returned by get_source and get_source_async) can now be a coroutine function. This means async loaders can check a template's source for changes asynchronously.
• Added the cache_size argument to Environment and Template for controlling the capacity of the default template cache.
• Easier subclassing of liquid.parser.ExpressionParser with END_EXPRESSION.

Version bump. Last release before removing depreciated class-based filters.

Change log: https://github.com/jg-rp/liquid/blob/main/CHANGES.rst

• Recursive use of the "render" tag now raises a ContextDepthError if MAX_CONTEXT_DEPTH is exceeded. This is now consistent with recursive "include".
• Drops (custom classes in a render context) can now mimic primitive Liquid values when used as array indexes or hash keys, or in conditional expressions (including case/when and unless). If defined, the result of calling a drop's __liquid__ method will be used in those scenarios.
• Added base64_encode, base64_decode, base64_url_safe_encode and base64_url_safe_decode filters.
• Added asynchronous template loading and rendering. When Template.render_async is awaited, render and include tags will load templates asynchronously. Custom loaders should implement get_source_async.
• Added support for asynchronous drops. If a class implements __getitem_async__, which is assumed to be an async version of __getitem__, it will be awaited instead of calling __getitem__.