python-liquid 2.3.6__py3-none-any.whl → 3.0.0__py3-none-any.whl

liquid/static_analysis.py

@@ -1,443 +0,0 @@
-"""Analyze variable, tag and filter usage by traversing a template's syntax tree."""
-
-from __future__ import annotations
-
-import re
-from collections import defaultdict
-from dataclasses import dataclass
-from dataclasses import field
-from typing import TYPE_CHECKING
-from typing import Iterable
-from typing import Optional
-from typing import Union
-
-from .ast import BlockNode
-from .ast import ConditionalBlockNode
-from .ast import PartialScope
-from .builtin.expressions import FilteredExpression
-from .builtin.expressions import Path
-from .builtin.expressions import TernaryFilteredExpression
-from .builtin.tags.case_tag import MultiExpressionBlockNode
-from .context import RenderContext
-from .span import Span
-from .token import TOKEN_TAG
-
-if TYPE_CHECKING:
-    from .ast import Node
-    from .expression import Expression
-    from .template import BoundTemplate
-
-
-RE_PROPERTY = re.compile(r"[\u0080-\uFFFFa-zA-Z_][\u0080-\uFFFFa-zA-Z0-9_-]*")
-Segments = list[Union[int, str, "Segments"]]
-
-
-@dataclass(frozen=True)
-class Variable:
-    """A variable as sequence of segments that make up its path and its location.
-
-    Variables with the same segments compare equal, regardless of span.
-    """
-
-    segments: Segments
-    """The variable's segments."""
-
-    span: Span = field(hash=False, compare=False)
-    """The variable's location."""
-
-    def __str__(self) -> str:
-        return self._segments_str(self.segments)
-
-    def _segments_str(self, segments: Segments) -> str:
-        it = iter(segments)
-        buf = [str(next(it))]
-
-        for segment in it:
-            if isinstance(segment, list):
-                buf.append(f"[{self._segments_str(segment)}]")
-            elif isinstance(segment, str):
-                if RE_PROPERTY.fullmatch(segment):
-                    buf.append(f".{segment}")
-                else:
-                    buf.append(f"[{segment!r}]")
-            else:
-                buf.append(f"[{segment}]")
-        return "".join(buf)
-
-    def __hash__(self) -> int:
-        return hash(str(self))
-
-
-class _StaticScope:
-    def __init__(self, globals: set[str]) -> None:  # noqa: A002
-        self.stack = [globals]
-
-    def __contains__(self, key: str) -> bool:
-        return any(key in scope for scope in self.stack)
-
-    def push(self, scope: set[str]) -> _StaticScope:
-        self.stack.append(scope)
-        return self
-
-    def pop(self) -> set[str]:
-        return self.stack.pop()
-
-    def add(self, name: str) -> None:
-        """Add a name to the root/template scope."""
-        self.stack[0].add(name)
-
-
-class _VariableMap:
-    def __init__(self) -> None:
-        self._data: dict[str, list[Variable]] = {}
-
-    def __getitem__(self, var: Variable) -> list[Variable]:
-        k = str(var.segments[0])
-        if k not in self._data:
-            self._data[k] = []
-        return self._data[k]
-
-    def add(self, var: Variable) -> None:
-        self[var].append(var)
-
-    def as_dict(self) -> dict[str, list[Variable]]:
-        return self._data
-
-
-@dataclass(frozen=True)
-class TemplateAnalysis:
-    """The result of analyzing a template using `Template.analyze()`.
-
-    Args:
-        variables: All referenced variables, whether they are in scope or not.
-            Including references to names such as `forloop` from the `for` tag.
-        locals: Template variables that are added to the template local
-            scope, whether they are subsequently used or not.
-        globals: Template variables that, on the given line number and
-            "file", are out of scope or are assumed to be "global". That is, expected to
-            be included by the application developer rather than a template author.
-        filters: All filters found during static analysis.
-        tags: All tags found during static analysis.
-    """
-
-    variables: dict[str, list[Variable]]
-    globals: dict[str, list[Variable]]
-    locals: dict[str, list[Variable]]
-    filters: dict[str, list[Span]]
-    tags: dict[str, list[Span]]
-
-
-def analyze(template: BoundTemplate, *, include_partials: bool) -> TemplateAnalysis:
-    """Report variable, filters and tags used in the given template.
-
-    This is used by `BoundTemplate.analyze`.
-    """
-    variables = _VariableMap()
-    globals = _VariableMap()  # noqa: A001
-    locals = _VariableMap()  # noqa: A001
-
-    filters: defaultdict[str, list[Span]] = defaultdict(list)
-    tags: defaultdict[str, list[Span]] = defaultdict(list)
-
-    template_scope: set[str] = set()
-    root_scope = _StaticScope(template_scope)
-    static_context = RenderContext(template)
-
-    # Names of partial templates that have already been analyzed.
-    # Keys are hashes of partial template name and its arguments. If we've
-    # visited a template before but ith different arguments, later visits
-    # only record global variables so as not to double count locals, filters
-    # and tags.
-    seen: defaultdict[str, set[Optional[int]]] = defaultdict(set)
-
-    def _visit(
-        node: Node,
-        template_name: str,
-        scope: _StaticScope,
-        *,
-        just_globals: bool = False,
-    ) -> None:
-        if template_name and not just_globals:
-            seen[template_name].add(None)
-
-        # Update tags from node.token
-        if (
-            not just_globals
-            and not isinstance(
-                node, (BlockNode, ConditionalBlockNode, MultiExpressionBlockNode)
-            )
-            and node.token.kind == TOKEN_TAG
-        ):
-            tags[node.token.value].append(Span(template_name, node.token.start_index))
-
-        # Update variables from node.expressions()
-        for expr in node.expressions():
-            _analyze_variables(
-                expr,
-                template_name,
-                scope,
-                globals,
-                _VariableMap() if just_globals else variables,
-            )
-
-            if not just_globals:
-                # Update filters from expr
-                for name, span in _extract_filters(expr, template_name):
-                    filters[name].append(span)
-
-        # Update the template scope from node.template_scope()
-        for ident in node.template_scope():
-            scope.add(ident)
-            locals.add(
-                Variable(
-                    segments=[ident],
-                    span=Span(template_name, ident.token.start_index),
-                )
-            )
-
-        if partial := node.partial_scope():
-            partial_name = (
-                partial.name
-                if isinstance(partial.name, str)
-                else str(partial.name.evaluate(static_context))
-            )
-
-            # If we've seen this partial before but with different arguments,
-            # we might want to visit it again but only capture globals.
-            _just_globals = partial_name in seen
-            if partial.key in seen[partial_name]:
-                # We've visited this partial template before with the same
-                # arguments.
-                return
-
-            seen[partial_name].add(partial.key)
-            partial_name = partial_name or template_name
-
-            partial_scope = (
-                _StaticScope(set(partial.in_scope))
-                if partial.scope == PartialScope.ISOLATED
-                else root_scope.push(set(partial.in_scope))
-            )
-
-            for child in node.children(
-                static_context, include_partials=include_partials
-            ):
-                _visit(
-                    child,
-                    partial_name,
-                    partial_scope,
-                    just_globals=just_globals or _just_globals,
-                )
-
-            partial_scope.pop()
-        else:
-            scope.push(set(node.block_scope()))
-            for child in node.children(
-                static_context, include_partials=include_partials
-            ):
-                _visit(child, template_name, scope, just_globals=just_globals)
-            scope.pop()
-
-    for node in template.nodes:
-        _visit(node, template.name, root_scope)
-
-    return TemplateAnalysis(
-        variables=variables.as_dict(),
-        globals=globals.as_dict(),
-        locals=locals.as_dict(),
-        filters=dict(filters),
-        tags=dict(tags),
-    )
-
-
-async def analyze_async(
-    template: BoundTemplate, *, include_partials: bool
-) -> TemplateAnalysis:
-    """Report variable, filters and tags used in the given template.
-
-    This is used by `BoundTemplate.analyze_async`.
-    """
-    variables = _VariableMap()
-    globals = _VariableMap()  # noqa: A001
-    locals = _VariableMap()  # noqa: A001
-
-    filters: defaultdict[str, list[Span]] = defaultdict(list)
-    tags: defaultdict[str, list[Span]] = defaultdict(list)
-
-    template_scope: set[str] = set()
-    root_scope = _StaticScope(template_scope)
-    static_context = RenderContext(template)
-
-    # Names of partial templates that have already been analyzed.
-    seen: defaultdict[str, set[Optional[int]]] = defaultdict(set)
-
-    async def _visit(
-        node: Node,
-        template_name: str,
-        scope: _StaticScope,
-        *,
-        just_globals: bool = False,
-    ) -> None:
-        if template_name and not just_globals:
-            seen[template_name].add(None)
-
-        # Update tags from node.token
-        if (
-            not just_globals
-            and not isinstance(
-                node, (BlockNode, ConditionalBlockNode, MultiExpressionBlockNode)
-            )
-            and node.token.kind == TOKEN_TAG
-        ):
-            tags[node.token.value].append(Span(template_name, node.token.start_index))
-
-        # Update variables from node.expressions()
-        for expr in node.expressions():
-            _analyze_variables(
-                expr,
-                template_name,
-                scope,
-                globals,
-                _VariableMap() if just_globals else variables,
-            )
-
-            if not just_globals:
-                # Update filters from expr
-                for name, span in _extract_filters(expr, template_name):
-                    filters[name].append(span)
-
-        # Update the template scope from node.template_scope()
-        for ident in node.template_scope():
-            scope.add(ident)
-            locals.add(
-                Variable(
-                    segments=[ident],
-                    span=Span(template_name, ident.token.start_index),
-                )
-            )
-
-        if partial := node.partial_scope():
-            partial_name = (
-                partial.name
-                if isinstance(partial.name, str)
-                else str(partial.name.evaluate(static_context))
-            )
-
-            # If we've seen this partial before but with different arguments,
-            # we might want to visit it again but only capture globals.
-            _just_globals = partial_name in seen
-            if partial.key in seen[partial_name]:
-                # We've visited this partial template before with the same
-                # arguments.
-                return
-
-            seen[partial_name].add(partial.key)
-            partial_name = partial_name or template_name
-
-            partial_scope = (
-                _StaticScope(set(partial.in_scope))
-                if partial.scope == PartialScope.ISOLATED
-                else root_scope.push(set(partial.in_scope))
-            )
-
-            for child in await node.children_async(
-                static_context, include_partials=include_partials
-            ):
-                await _visit(
-                    child,
-                    partial_name,
-                    partial_scope,
-                    just_globals=just_globals or _just_globals,
-                )
-
-            partial_scope.pop()
-        else:
-            scope.push(set(node.block_scope()))
-            for child in await node.children_async(
-                static_context, include_partials=include_partials
-            ):
-                await _visit(child, template_name, scope, just_globals=just_globals)
-            scope.pop()
-
-    for node in template.nodes:
-        await _visit(node, template.name, root_scope)
-
-    return TemplateAnalysis(
-        variables=variables.as_dict(),
-        globals=globals.as_dict(),
-        locals=locals.as_dict(),
-        filters=dict(filters),
-        tags=dict(tags),
-    )
-
-
-def _extract_filters(
-    expression: Expression, template_name: str
-) -> Iterable[tuple[str, Span]]:
-    if isinstance(expression, TernaryFilteredExpression):
-        yield from _extract_filters(expression.left, template_name)
-
-        if expression.filters:
-            yield from (
-                (f.name, Span(template_name, f.token.start_index))
-                for f in expression.filters
-            )
-
-        if expression.tail_filters:
-            yield from (
-                (f.name, Span(template_name, f.token.start_index))
-                for f in expression.tail_filters
-            )
-
-    if isinstance(expression, FilteredExpression) and expression.filters:
-        yield from (
-            (f.name, Span(template_name, f.token.start_index))
-            for f in expression.filters
-        )
-
-    for expr in expression.children():
-        yield from _extract_filters(expr, template_name)
-
-
-def _analyze_variables(
-    expression: Expression,
-    template_name: str,
-    scope: _StaticScope,
-    globals: _VariableMap,  # noqa: A002
-    variables: _VariableMap,
-) -> None:
-    if isinstance(expression, Path):
-        var = Variable(
-            segments=_segments(expression, template_name),
-            span=Span(template_name, expression.token.start_index),
-        )
-
-        # NOTE: We're updating globals and variables here so we can manage scope while
-        # traversing the expression. This is for the benefit of lambda expressions that
-        # add names to the scope of their children.
-        variables.add(var)
-
-        root = str(var.segments[0])
-        if root not in scope:
-            globals.add(var)
-
-    if child_scope := expression.scope():
-        scope.push(set(child_scope))
-        for expr in expression.children():
-            _analyze_variables(expr, template_name, scope, globals, variables)
-        scope.pop()
-    else:
-        for expr in expression.children():
-            _analyze_variables(expr, template_name, scope, globals, variables)
-
-
-def _segments(path: Path, template_name: str) -> Segments:
-    segments: Segments = []
-
-    for segment in path.path:
-        if isinstance(segment, Path):
-            segments.append(_segments(segment, template_name))
-        else:
-            segments.append(segment)
-
-    return segments

liquid/stream.py

@@ -1,148 +0,0 @@
-"""Step through a sequence of tokens."""
-
-from __future__ import annotations
-
-from typing import Iterator
-from typing import Optional
-
-from .builtin.expressions import tokenize
-from .exceptions import LiquidSyntaxError
-from .token import TOKEN_EOF
-from .token import TOKEN_EXPRESSION
-from .token import Token
-from .token import reverse_operators
-
-
-class TokenStream:
-    """Step through a sequence of tokens."""
-
-    eof = Token(TOKEN_EOF, TOKEN_EOF, -1, "")
-
-    def __init__(self, tokens: Iterator[Token], block_depth_carry: int = 0):
-        self.tokens = list(tokens)
-        self.pos = 0
-        self.block_depth = block_depth_carry
-
-    def __next__(self) -> Token:
-        return self.next_token()
-
-    def next(self) -> Token:
-        """Return the next token and advance the iterator."""
-        try:
-            token = self.tokens[self.pos]
-            self.pos += 1
-            return token
-        except IndexError:
-            return self.eof
-
-    def next_token(self) -> Token:
-        """Return the next token and advance the iterator."""
-        try:
-            token = self.tokens[self.pos]
-            self.pos += 1
-            return token
-        except IndexError:
-            return self.eof
-
-    @property
-    def current(self) -> Token:
-        """Return the token at the head of the stream without advancing."""
-        try:
-            return self.tokens[self.pos]
-        except IndexError:
-            return self.eof
-
-    @property
-    def peek(self) -> Token:
-        """Look at the next token."""
-        try:
-            return self.tokens[self.pos + 1]
-        except IndexError:
-            return self.eof
-
-    def _expect(self, tok: Token, typ: str, value: Optional[str] = None) -> Token:
-        if tok.kind != typ or (value is not None and tok.value != value):
-            _typ = self._operator(tok.kind)
-            _expected_typ = self._operator(typ)
-            if value is not None:
-                msg = f"expected {_expected_typ} {value}, found {_typ}"
-            else:
-                msg = f"expected {_expected_typ}, found {_typ}"
-            raise LiquidSyntaxError(msg, token=tok)
-        return tok
-
-    def expect(self, typ: str, value: Optional[str] = None) -> Token:
-        """Check the current token in the stream matches the given type and value.
-
-        Returns the current token if its type matches _typ_.
-        Raises a `LiquidSyntaxError` if it doesn't.
-        """
-        return self._expect(self.current, typ, value)
-
-    def expect_peek(self, typ: str, value: Optional[str] = None) -> Token:
-        """Check the next token in the stream matches the given type and value.
-
-        Returns the next token if its type matches _typ_.
-        Raises a `LiquidSyntaxError` it doesn't.
-        """
-        return self._expect(self.peek, typ, value)
-
-    def eat(self, typ: str) -> Token:
-        """Consume and return the next token.
-
-        If the type of the next token is equal to _typ_, raise an exceptions.
-
-        This is equivalent to `stream.expect(typ)` followed by `next(stream)`.
-        """
-        tok = self.current
-        if tok.kind != typ:
-            msg = f"expected {self._operator(typ)}, found {self._operator(tok.kind)}"
-            raise LiquidSyntaxError(msg, token=tok)
-        return next(self)
-
-    def eat_one_of(self, *typ: str) -> Token:
-        """Consume and return the next token.
-
-        If the type of the next token is equal to _typ_, raise an exceptions.
-
-        This is equivalent to `stream.expect(typ)` followed by `next(stream)`.
-        """
-        tok = self.current
-        if tok.kind not in typ:
-            msg = f"expected one of {typ!r}, found {self._operator(tok.kind)}"
-            raise LiquidSyntaxError(msg, token=tok)
-        return next(self)
-
-    def into_inner(
-        self, *, tag: Optional[Token] = None, eat: bool = True
-    ) -> TokenStream:
-        """Return a stream of tokens for the current expression token.
-
-        If the current token is not an expression, a `LiquidSyntaxError` is
-        raised.
-
-        If _tag_ is given, it will be used to add context information to the
-        syntax error, should one be raised.
-
-        If _eat_ is true (the default), the current token is consumed.
-        """
-        token = self.current
-        if token.kind != TOKEN_EXPRESSION:
-            raise LiquidSyntaxError("missing expression", token=tag or token)
-
-        if eat:
-            next(self)
-        return TokenStream(tokenize(token.value, parent_token=token))
-
-    def expect_eos(self) -> None:
-        """Raise a syntax error if we're not at the end of the stream."""
-        if self.current.kind != TOKEN_EOF:
-            raise LiquidSyntaxError(
-                f"unexpected token {self.current.kind}", token=self.current
-            )
-
-    def _operator(self, kind: str) -> str:
-        try:
-            return repr(reverse_operators[kind])
-        except KeyError:
-            return kind

liquid/stringify.py

@@ -1,31 +0,0 @@
-"""Stringify a Python object ready for output in a Liquid template."""
-from typing import Any
-
-from liquid import Markup
-from liquid import escape
-from liquid import soft_str
-
-
-def to_liquid_string(val: Any, autoescape: bool) -> str:
-    """Stringify a Python object ready for output in a Liquid template."""
-    if isinstance(val, str) or (autoescape and hasattr(val, "__html__")):
-        pass
-    elif isinstance(val, bool):
-        val = str(val).lower()
-    elif val is None:
-        val = ""
-    elif isinstance(val, list):
-        if autoescape:
-            val = Markup("").join(soft_str(itm) for itm in val)
-        else:
-            val = "".join(soft_str(itm) for itm in val)
-    elif isinstance(val, range):
-        val = f"{val.start}..{val.stop - 1}"
-    else:
-        val = str(val)
-
-    if autoescape:
-        val = escape(val)
-
-    assert isinstance(val, str)
-    return val

liquid/tag.py

@@ -1,47 +0,0 @@
-"""Liquid tag base class."""
-
-from __future__ import annotations
-
-from abc import ABC
-from abc import abstractmethod
-from typing import TYPE_CHECKING
-
-from .ast import IllegalNode
-from .ast import Node
-from .exceptions import LiquidError
-from .parser import eat_block
-
-if TYPE_CHECKING:
-    from .environment import Environment
-    from .stream import TokenStream
-
-
-class Tag(ABC):
-    """Base class for all built-in and custom template tags."""
-
-    block = True
-    name = ""
-    end = ""
-
-    def __init__(self, env: Environment):
-        self.env = env
-
-    def get_node(self, stream: TokenStream) -> Node:
-        """Wraps `Tag.parse`, possibly returning an `IllegalNode`."""
-        try:
-            return self.parse(stream)
-        except LiquidError as err:
-            token = stream.current
-            if not err.token:
-                err.token = token
-
-            self.env.error(err)
-
-            if self.block and hasattr(self, "end"):
-                eat_block(stream, (self.end,))
-
-            return IllegalNode(token)
-
-    @abstractmethod
-    def parse(self, stream: TokenStream) -> Node:
-        """Return a parse tree node by parsing tokens from the given stream."""