Version 2 API Changes

[jg-rp]

This is a list of API changes planned for Python Liquid version 2.0. Work has not yet begun on version 2.0. Suggestions are welcome.

• Replace the env: Environment argument to liquid.Context with template: BoundTemplate. The current environment can be accessed through the template object.
• Force all arguments except template to the liquid.Context constructor to be keyword only arguments.
• Rename liquid.Context to liquid.RenderContext to differentiate it from LoadContext and any other "contexts" that crop up.
• Rename VariableCaptureContext to CaptureRenderContext.
• Make MarkupSafe a required dependency, even if HTML auto escaping is disabled.
• Change liquid.token.Token from (linenum, type, value) to (kind, value, index, source, source_name), where type has been renamed to kind, index is the index of the start of the token in source (template source text), and source_name is the name associated with the source text. This is done in the name of better error reporting, especially when reporting errors from included, rendered or extended templates.
• Change the base exception, liquid.exceptions.Error, to require a token (as described above) argument instead of optional linenum and filename.
• Change the liquid.ast.Node constructor to require a token: Token argument. At the moment it is just a convention.
• Remove template caching from liquid.Environment. Instead, all template caches should be implemented in template loaders, or mixed in to simpler template loaders.
• Consolidate get_template, get_template_with_context and their async versions in to get_template with an optional context argument.
• Change common and built-in expression parsing functions to be grouped into expression parsing classes that have a reference to the active environment. This is so we can tweak parsing behaviour depending on options set on the environment.
• Move most Environment constructor arguments to class attributes. Environment customisation would be achieved by subclassing.

2024/01/30

• Add abstract method list_templates() to BaseLoader.

2024/10/06

• children() is now a required method of ast.Node and expression.Expression.

[jg-rp]

Python liquid2 (separate repository) has been released. It incorporates many of the API changes discussed here. See the migration guide's API changes section.

Some of these API changes can still be applied to this project, but we'll take a more conservative approach than that seen in Python Liquid2.