Merge pull request #191 from jg-rp/snippet

Implement the `snippet` tag

Author: jg-rp

CHANGES.md

@@ -1,5 +1,10 @@
 # Python Liquid Change Log
 
+## Version 2.2.0 (unreleased)
+
+- Added the `{% snippet %}` tag.
+- 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.
+
 ## Version 2.1.0
 
 **Features**

docs/tag_reference.md

@@ -540,10 +540,86 @@ Additional keyword arguments given to the `render` tag will be added to the rend
 {% render "partial_template" greeting: "Hello", num: 3, skip: 2 %}
 ```
 
-## tablerow
+## snippet
+
+**_New in version 2.2.0_**
+
+```plain
+{% snippet <identifier> %}
+  <liquid markup>
+{% endsnippet %}
+```
+
+A snippet is a reusable block of Liquid markup. Traditionally we'd save a snippet to a file and include it in a template with the `{% render %}` tag.
+
+```liquid
+{% render  "some_snippet" %}
+```
 
-<!-- md:version 0.1.0 -->
-<!-- md:shopify -->
+With the `{% snippet %}` tag we can define blocks for reuse inside a single template, potentially reducing the number of snippet files we need.
+
+```liquid
+{% snippet div %}
+  <div>
+    {{ content }}
+  </div>
+{% endsnippet %}
+```
+
+Defining a snippet does not render it. We use `{% render snippet_name %}` to render a snippet, where `snippet_name` is the name of your snippet without quotes (file-based snippet names must be quoted).
+
+```liquid
+{% snippet div %}
+  <div>
+    {{ content }}
+  </div>
+{% endsnippet %}
+
+{% render div, content: "Some content" %}
+{% render div, content: "Other content" %}
+```
+
+```html title="output"
+<div>Some content</div>
+
+<div>Other content</div>
+```
+
+Inline snippets share the same namespace as variables defined with `{% assign %}` and `{% capture %}`, so be wary of accidentally overwriting snippets with non-snippet data.
+
+```liquid
+{% snippet foo %}Hello{% endsnippet %}
+{% foo = 42 %}
+{% render foo %} {% # error %}
+```
+
+Snippets can be nested and follow the same scoping rules as file-based snippets.
+
+```liquid
+{% snippet a %}
+  b
+  {% snippet c %}
+    d
+  {% endsnippet %}
+  {% render c %}
+{% endsnippet %}
+
+{% render a %}
+{% render c %} {% # error, c is out of scope %}
+```
+
+Snippet blocks are bound to their names late. You can conditionally define multiple snippets with the same name and pick one at render time.
+
+```liquid
+{% if x %}
+  {% snippet a %}b{% endsnippet %}
+{% else %}
+  {% snippet a %}c{% endsnippet %}
+{% endif %}
+{% render a %}
+```
+
+## tablerow
 
 ```plain
 {% tablerow <identifier> in <expression>

liquid/__init__.py

@@ -56,7 +56,7 @@
 
 from . import future
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 
 __all__ = (
     "AwareBoundTemplate",

liquid/ast.py

@@ -9,7 +9,9 @@
 from typing import TYPE_CHECKING
 from typing import Collection
 from typing import Iterable
+from typing import Optional
 from typing import TextIO
+from typing import Union
 
 from .exceptions import DisabledTagError
 from .output import NullIO
@@ -104,7 +106,7 @@ def block_scope(self) -> Iterable[Identifier]:
         """Return variables this node adds to the node's block scope."""
         return []
 
-    def partial_scope(self) -> Partial | None:
+    def partial_scope(self) -> Optional[Partial]:
         """Return information about a partial template loaded by this node."""
         return None
 
@@ -121,19 +123,30 @@ class Partial:
     """Partial template meta data.
 
     Args:
-        name: An expression resolving to the name associated with the partial template.
+        name: The name of the partial or an expression resolving to the name
+            associated with the partial template.
         scope: The kind of scope the partial template should have when loaded.
         in_scope: Names that will be added to the partial template scope.
+        key: A hash of the partial template name and any arguments the partial
+            template will be rendered with that might affect its scope. If a
+            key is provided, static analysis helpers will visit a partial
+            template once for each distinct key.
     """
 
-    __slots__ = ("name", "scope", "in_scope")
+    __slots__ = ("name", "scope", "in_scope", "key")
 
     def __init__(
-        self, name: Expression, scope: PartialScope, in_scope: Iterable[Identifier]
+        self,
+        name: Union[Expression, str],
+        scope: PartialScope,
+        in_scope: Iterable[Identifier],
+        *,
+        key: Optional[int] = None,
     ) -> None:
         self.name = name
         self.scope = scope
         self.in_scope = in_scope
+        self.key = key
 
 
 class IllegalNode(Node):

liquid/builtin/__init__.py

@@ -90,6 +90,7 @@
 from .tags import inline_comment_tag
 from .tags import liquid_tag
 from .tags import render_tag
+from .tags import snippet
 from .tags import tablerow_tag
 from .tags import unless_tag
 
@@ -133,6 +134,7 @@ def register(env: Environment) -> None:  # noqa: PLR0915
     env.add_tag(ifchanged_tag.IfChangedTag)
     env.add_tag(inline_comment_tag.InlineCommentTag)
     env.add_tag(doc_tag.DocTag)
+    env.add_tag(snippet.SnippetTag)
 
     env.add_filter("abs", abs_)
     env.add_filter("at_most", at_most)

liquid/builtin/tags/doc_tag.py

@@ -50,7 +50,7 @@ def parse(self, stream: TokenStream) -> DocNode:
 
         # This only happens if the doc tag is malformed
         token = stream.eat(TOKEN_TAG)
-        text = []
+        text: list[str] = []
 
         if stream.current.kind == TOKEN_EXPRESSION:
             raise LiquidSyntaxError("unexpected expression", token=stream.current)

liquid/builtin/tags/render_tag.py

@@ -7,6 +7,7 @@
 from typing import Iterable
 from typing import Optional
 from typing import TextIO
+from typing import Union
 
 from liquid.ast import Node
 from liquid.ast import Partial
@@ -21,11 +22,12 @@
 from liquid.builtin.expressions import parse_primitive
 from liquid.builtin.tags.for_tag import ForLoop
 from liquid.builtin.tags.include_tag import TAG_INCLUDE
+from liquid.exceptions import LiquidSyntaxError
 from liquid.exceptions import TemplateNotFoundError
 from liquid.tag import Tag
+from liquid.template import BoundTemplate
 from liquid.token import TOKEN_AS
 from liquid.token import TOKEN_FOR
-from liquid.token import TOKEN_STRING
 from liquid.token import TOKEN_TAG
 from liquid.token import TOKEN_WITH
 from liquid.token import TOKEN_WORD
@@ -50,7 +52,8 @@ class RenderNode(Node):
     def __init__(
         self,
         token: Token,
-        name: StringLiteral,
+        name: Union[StringLiteral, Identifier],
+        *,
         var: Optional[Expression] = None,
         loop: bool = False,
         alias: Optional[Identifier] = None,
@@ -77,14 +80,26 @@ def __str__(self) -> str:
 
     def render_to_output(self, context: RenderContext, buffer: TextIO) -> int:
         """Render the node to the output buffer."""
-        try:
-            template = context.env.get_template(
-                self.name.value, context=context, tag=self.tag
+        if isinstance(self.name, Identifier):
+            # We're expecting an inline snippet.
+            template: Optional[BoundTemplate] = context.resolve(
+                self.name, token=self.token, default=None
             )
-        except TemplateNotFoundError as err:
-            err.token = self.name.token
-            err.template_name = context.template.full_name()
-            raise
+            if not isinstance(template, BoundTemplate):
+                raise TemplateNotFoundError(
+                    self.name,
+                    filename=context.template.full_name(),
+                    token=self.name.token,
+                )
+        else:
+            try:
+                template = context.env.get_template(
+                    self.name.value, context=context, tag=self.tag
+                )
+            except TemplateNotFoundError as err:
+                err.token = self.name.token
+                err.template_name = context.template.full_name()
+                raise
 
         # Evaluate keyword arguments once. Unlike 'include', 'render' can not
         # mutate variables in the outer scope, so there's no need to re-evaluate
@@ -145,14 +160,26 @@ async def render_to_output_async(
         self, context: RenderContext, buffer: TextIO
     ) -> int:
         """Render the node to the output buffer."""
-        try:
-            template = await context.env.get_template_async(
-                self.name.value, context=context, tag=self.tag
+        if isinstance(self.name, Identifier):
+            # We're expecting an inline snippet.
+            template: Optional[BoundTemplate] = context.resolve(
+                self.name, token=self.token, default=None
             )
-        except TemplateNotFoundError as err:
-            err.token = self.name.token
-            err.template_name = context.template.full_name()
-            raise
+            if not isinstance(template, BoundTemplate):
+                raise TemplateNotFoundError(
+                    self.name,
+                    filename=context.template.full_name(),
+                    token=self.name.token,
+                )
+        else:
+            try:
+                template = await context.env.get_template_async(
+                    self.name.value, context=context, tag=self.tag
+                )
+            except TemplateNotFoundError as err:
+                err.token = self.name.token
+                err.template_name = context.template.full_name()
+                raise
 
         # Evaluate keyword arguments once. Unlike 'include', 'render' can not
         # mutate variables in the outer scope, so there's no need to re-evaluate
@@ -215,7 +242,15 @@ def children(
         self, static_context: RenderContext, *, include_partials: bool = True
     ) -> Iterable[Node]:
         """Return this node's children."""
-        if include_partials:
+        if isinstance(self.name, Identifier):
+            # We're expecting an inline snippet.
+            # Always visit inline snippets, even if include_partials is False.
+            template: Optional[BoundTemplate] = static_context.resolve(
+                self.name, token=self.token, default=None
+            )
+            if template:
+                yield from template.nodes
+        elif include_partials:
             name = self.name.evaluate(static_context)
             try:
                 template = static_context.env.get_template(
@@ -231,7 +266,14 @@ async def children_async(
         self, static_context: RenderContext, *, include_partials: bool = True
     ) -> Iterable[Node]:
         """Return this node's children."""
-        if include_partials:
+        if isinstance(self.name, Identifier):
+            # We're expecting an inline snippet.
+            template: Optional[BoundTemplate] = static_context.resolve(
+                self.name, token=self.token, default=None
+            )
+            if template:
+                return template.nodes
+        elif include_partials:
             name = await self.name.evaluate_async(static_context)
             try:
                 template = await static_context.env.get_template_async(
@@ -246,12 +288,11 @@ async def children_async(
 
     def expressions(self) -> Iterable[Expression]:
         """Return this node's expressions."""
-        yield self.name
         if self.var:
             yield self.var
         yield from (arg.value for arg in self.args)
 
-    def partial_scope(self) -> Partial | None:
+    def partial_scope(self) -> Optional[Partial]:
         """Return information about a partial template loaded by this node."""
         scope: list[Identifier] = [
             Identifier(arg.name, token=arg.token) for arg in self.args
@@ -267,7 +308,17 @@ def partial_scope(self) -> Partial | None:
                     )
                 )
 
-        return Partial(name=self.name, scope=PartialScope.ISOLATED, in_scope=scope)
+        partial_name = self.name.value if isinstance(self.name, StringLiteral) else ""
+        partial_key = hash((partial_name, *[arg.name for arg in self.args]))
+
+        # Static analysis will use the parent template name if Partial.name is
+        # empty. Which is what we want for inline snippets.
+        return Partial(
+            name=partial_name,
+            scope=PartialScope.ISOLATED,
+            in_scope=scope,
+            key=partial_key,
+        )
 
 
 BIND_TAGS = frozenset((TOKEN_WITH, TOKEN_FOR))
@@ -284,12 +335,18 @@ def parse(self, stream: TokenStream) -> Node:
         """Parse tokens from _stream_ into an AST node."""
         token = stream.eat(TOKEN_TAG)
         tokens = stream.into_inner(tag=token, eat=False)
-
-        # Need a string. 'render' does not accept identifiers that resolve to a string.
-        # This is the name of the template to be included.
-        tokens.expect(TOKEN_STRING)
-        name = parse_primitive(self.env, tokens)
-        assert isinstance(name, StringLiteral)
+        name: Union[Expression, Identifier] = parse_primitive(self.env, tokens)
+
+        if isinstance(name, Path):
+            head = name.head()
+            if len(name.path) != 1 or not isinstance(head, str):
+                raise LiquidSyntaxError(
+                    "expected an identifier, found a path",
+                    token=name.token,
+                )
+            name = Identifier(head, token=name.token)
+        elif not isinstance(name, StringLiteral):
+            raise LiquidSyntaxError("expected a string or identifier", token=name.token)
 
         alias: Optional[Identifier] = None
         var: Optional[Path] = None
@@ -311,4 +368,4 @@ def parse(self, stream: TokenStream) -> Node:
 
         # Zero or more keyword arguments
         args = KeywordArgument.parse(self.env, tokens)
-        return self.node_class(token, name, var, loop, alias, args)
+        return self.node_class(token, name, var=var, loop=loop, alias=alias, args=args)