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

liquid/{utils/lru_cache.py → _lru_cache.py}

@@ -1,20 +1,12 @@
 """An LRU cache with a mapping interface implemented using an ordered dict."""
 
 from collections import OrderedDict
+from collections.abc import Iterator
 from threading import Lock
-from typing import Generic
-from typing import Iterator
-from typing import Optional
-from typing import TypeVar
-from typing import Union
 from typing import overload
 
-_KT = TypeVar("_KT")
-_VT = TypeVar("_VT")
-_T = TypeVar("_T")
 
-
-class LRUCache(Generic[_KT, _VT]):
+class LRUCache[KT, VT]:
     """An LRU cache with a mapping interface."""
 
     def __init__(self, capacity: int):
@@ -22,14 +14,14 @@ class LRUCache(Generic[_KT, _VT]):
             raise ValueError("cache capacity must be greater than zero")
 
         self.capacity = capacity
-        self._cache: OrderedDict[_KT, _VT] = OrderedDict()
+        self._cache: OrderedDict[KT, VT] = OrderedDict()
 
-    def __getitem__(self, key: _KT) -> _VT:
+    def __getitem__(self, key: KT) -> VT:
         value = self._cache[key]  # This will raise a KeyError if key is not cached
         self._cache.move_to_end(key)
         return value
 
-    def __setitem__(self, key: _KT, value: _VT) -> None:
+    def __setitem__(self, key: KT, value: VT) -> None:
         try:
             self._cache.move_to_end(key)
         except KeyError:
@@ -38,74 +30,74 @@ class LRUCache(Generic[_KT, _VT]):
 
         self._cache[key] = value
 
-    def __delitem__(self, key: _KT) -> None:
+    def __delitem__(self, key: KT) -> None:
         del self._cache[key]
 
     def __len__(self) -> int:
         return len(self._cache)
 
-    def __iter__(self) -> Iterator[_KT]:
+    def __iter__(self) -> Iterator[KT]:
         return reversed(self._cache)
 
-    def __contains__(self, key: _KT) -> bool:
+    def __contains__(self, key: KT) -> bool:
         return key in self._cache
 
     @overload
-    def get(self, key: _KT) -> Optional[_VT]: ...
+    def get(self, key: KT) -> VT | None: ...
     @overload
-    def get(self, key: _KT, default: _VT) -> _VT: ...
+    def get(self, key: KT, default: VT) -> VT: ...
     @overload
-    def get(self, key: _KT, default: _T) -> Union[_VT, _T]: ...
-    def get(self, key: _KT, default: object = None) -> object:
+    def get[T](self, key: KT, default: T) -> VT | T: ...
+    def get(self, key: KT, default: object = None) -> object:
         """Return the cached value for _key_ if _key_ is in the cache, else default."""
         try:
             return self[key]
         except KeyError:
             return default
 
-    def keys(self) -> Iterator[_KT]:
+    def keys(self) -> Iterator[KT]:
         """Return an iterator over this cache's keys."""
         return reversed(self._cache.keys())
 
-    def values(self) -> Iterator[_VT]:
+    def values(self) -> Iterator[VT]:
         """Return an iterator over this cache's values."""
         return reversed(self._cache.values())
 
-    def items(self) -> Iterator[tuple[_KT, _VT]]:
+    def items(self) -> Iterator[tuple[KT, VT]]:
         """Return an iterator over this cache's key/value pairs."""
         return reversed(self._cache.items())
 
 
-class ThreadSafeLRUCache(LRUCache[_KT, _VT]):
+class ThreadSafeLRUCache[KT, VT](LRUCache[KT, VT]):
     """A thread safe LRU cache."""
 
     def __init__(self, capacity: int):
         super().__init__(capacity)
         self._lock = Lock()
 
-    def __getitem__(self, key: _KT) -> _VT:
+    def __getitem__(self, key: KT) -> VT:
         with self._lock:
             return super().__getitem__(key)
 
-    def __setitem__(self, key: _KT, value: _VT) -> None:
+    def __setitem__(self, key: KT, value: VT) -> None:
         with self._lock:
             return super().__setitem__(key, value)
 
-    def __delitem__(self, key: _KT) -> None:
+    def __delitem__(self, key: KT) -> None:
         with self._lock:
             return super().__delitem__(key)
 
-    def __contains__(self, key: _KT) -> bool:
+    def __contains__(self, key: KT) -> bool:
         with self._lock:
             return super().__contains__(key)
 
     @overload
-    def get(self, key: _KT) -> Optional[_VT]: ...
+    def get(self, key: KT) -> VT | None: ...
     @overload
-    def get(self, key: _KT, default: _VT) -> _VT: ...
+    def get(self, key: KT, default: VT) -> VT: ...
     @overload
-    def get(self, key: _KT, default: _T) -> Union[_VT, _T]: ...
-    def get(self, key: _KT, default: object = None) -> object:
+    def get[T](self, key: KT, default: T) -> VT | T: ...
+    def get(self, key: KT, default: object = None) -> object:
         """Return the cached value for _key_ if _key_ is in the cache, else default."""
         # NOTE: self.__getitem__ is already acquiring the lock.
         try:
@@ -113,17 +105,17 @@ class ThreadSafeLRUCache(LRUCache[_KT, _VT]):
         except KeyError:
             return default
 
-    def keys(self) -> Iterator[_KT]:
+    def keys(self) -> Iterator[KT]:
         """Return an iterator over this cache's keys."""
         with self._lock:
             return super().keys()
 
-    def values(self) -> Iterator[_VT]:
+    def values(self) -> Iterator[VT]:
         """Return an iterator over this cache's values."""
         with self._lock:
             return super().values()
 
-    def items(self) -> Iterator[tuple[_KT, _VT]]:
+    def items(self) -> Iterator[tuple[KT, VT]]:
         """Return an iterator over this cache's key/value pairs."""
         with self._lock:
-            return super().items()
+            return super().items()

liquid/_markup.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal, Protocol
+
+from .exceptions import DetailedLiquidError, DisabledTagError, ResourceLimitError
+
+if TYPE_CHECKING:
+    from ._context import RenderContext
+    from ._io import StringBuffer
+    from ._parser import Parser
+    from ._template import Template
+    from .expressions import Name
+    from .tokens import Token
+
+type Node = str | Markup
+"""A node in a template syntax tree."""
+
+type Block = list[Node]
+"""A sequence of template syntax tree nodes."""
+
+
+class Markup(Protocol):
+    """The interface used for *markup nodes* in a template syntax tree.
+
+    All tags and the output statement must implement this interface.
+    """
+
+    @property
+    def blank(self) -> bool:
+        """Return ``True`` if this node renders to an empty string or a string containing
+        whitespace only.
+
+        This is used to suppress control flow blocks that don't contain text or markup
+        that contributes to the output.
+        """
+        ...
+
+    @property
+    def token(self) -> Token:
+        """Return a representative token for this node.
+
+        In the absence of a more specific token from an enclosed expression, this token
+        will be used for reporting errors.
+        """
+        ...
+
+    @property
+    def tag(self) -> str:
+        """Return the name of this tag, or the empty string if this node is not a tag."""
+        ...
+
+    def render(self, context: RenderContext, buffer: StringBuffer) -> None:
+        """Render this node to `buffer` using data from `context`."""
+        ...
+
+    async def render_async(self, context: RenderContext, buffer: StringBuffer) -> None:
+        """Render this node to `buffer` asynchronously using data from `context`."""
+        ...
+
+    def children(self) -> list[Markup]:
+        """Returns markup nodes that are direct children of this node in the syntax tree.
+
+        This is used to traverse template syntax trees during static analysis.
+        """
+        ...
+
+    def expressions(self) -> list[Expression]:
+        """Return expression owned by this node."""
+        ...
+
+    def block_scope(self) -> list[Name]:
+        """Return variable names that are in scope for the duration of this node's block.
+
+        This is used during static analysis to isolate and report global variables.
+        """
+        ...
+
+    def template_scope(self) -> list[Name]:
+        """Return variable names that this tag adds to the template scope."""
+        ...
+
+    def partials(self, context: RenderContext) -> list[Partial]:
+        """Return meta data about partial templates rendered from this node."""
+        ...
+
+    async def partials_async(self, context: RenderContext) -> list[Partial]:
+        """Return meta data about partial templates rendered from this node."""
+        ...
+
+
+class Tag(Protocol):
+    """The interface used for parsing tokens into markup nodes."""
+
+    @classmethod
+    def parse(cls, token: Token, parser: Parser) -> Markup:
+        """Parse tokens or text from `parser` into a markup node."""
+        ...
+
+
+class Expression(Protocol):
+    @property
+    def token(self) -> Token:
+        """Return a representative token for this expression.
+
+        It could be the expression's first token or the token for this expression's
+        operator, for example.
+        """
+        ...
+
+    @property
+    def span(self) -> Token:
+        """Return a token spanning the entire expression."""
+        ...
+
+    def evaluate(self, context: RenderContext) -> object:
+        """Evaluate this expression using data from `context`."""
+        ...
+
+    async def evaluate_async(self, context: RenderContext) -> object:
+        """Evaluate this expression asynchronously using data from `context`."""
+        ...
+
+    def children(self) -> list[Expression]:
+        """Return this expressions direct child expressions."""
+        ...
+
+
+type Scope = Literal[1, 2, 3]
+
+SCOPE_SHARED: Literal[1] = 1
+SCOPE_ISOLATED: Literal[2] = 2
+SCOPE_INHERITED: Literal[3] = 3
+
+
+class Partial:
+    def __init__(
+        self,
+        *,
+        template: Template,
+        scope: Scope,
+        in_scope: list[Name],
+        key: int,
+    ) -> None:
+        self.template = template
+        self.scope = scope
+        self.in_scope = in_scope
+        self.key = key
+
+
+def render_block(block: Block, context: RenderContext, buffer: StringBuffer) -> None:
+    if context.limits.max_render_score or context.limits.max_render_score_cumulative:
+        context.render_score += len(block)
+        context.render_score_cumulative += len(block)
+
+        if (
+            context.limits.max_render_score
+            and context.render_score > context.limits.max_render_score
+        ) or (
+            context.limits.max_render_score_cumulative
+            and context.render_score_cumulative
+            > context.limits.max_render_score_cumulative
+        ):
+            raise ResourceLimitError("memory limits reached")
+
+    for node in block:
+        if isinstance(node, str):
+            buffer.write(node)
+
+        else:
+            if context.disabled_tags and node.tag in context.disabled_tags:
+                raise DisabledTagError(
+                    f"{node.tag!r} is not allowed in this context",
+                    token=node.token,
+                    source=context.template.source,
+                    name=context.template.name,
+                )
+
+            try:
+                node.render(context, buffer)
+            except DetailedLiquidError as err:
+                if context.capture_errors:
+                    buffer.write(f"\n{err}\n")
+                    context.errors.append(err)
+                else:
+                    raise
+
+            if context.interrupts:
+                if context.interrupts[-1] == "stop":
+                    context.interrupts.pop()
+                break
+
+        if (
+            context.limits.max_render_size
+            and len(buffer) > context.limits.max_render_size
+        ):
+            raise ResourceLimitError("memory limits exceeded")
+
+
+async def render_block_async(
+    block: Block, context: RenderContext, buffer: StringBuffer
+) -> None:
+    if context.limits.max_render_score or context.limits.max_render_score_cumulative:
+        context.render_score += len(block)
+        context.render_score_cumulative += len(block)
+
+        if (
+            context.limits.max_render_score
+            and context.render_score > context.limits.max_render_score
+        ) or (
+            context.limits.max_render_score_cumulative
+            and context.render_score_cumulative
+            > context.limits.max_render_score_cumulative
+        ):
+            raise ResourceLimitError("memory limits reached")
+
+    for node in block:
+        if isinstance(node, str):
+            buffer.write(node)
+
+        else:
+            if context.disabled_tags and node.tag in context.disabled_tags:
+                raise DisabledTagError(
+                    f"{node.tag!r} is not allowed in this context",
+                    token=node.token,
+                    source=context.template.source,
+                    name=context.template.name,
+                )
+
+            try:
+                await node.render_async(context, buffer)
+            except DetailedLiquidError as err:
+                if context.capture_errors:
+                    buffer.write(f"\n{err}\n")
+                    context.errors.append(err)
+                else:
+                    raise
+
+        if context.interrupts:
+            if context.interrupts[-1] == "stop":
+                context.interrupts.pop()
+            break
+
+        if (
+            context.limits.max_render_size
+            and len(buffer) > context.limits.max_render_size
+        ):
+            raise ResourceLimitError("memory limits exceeded")
+
+
+def is_blank_block(block: Block) -> bool:
+    return all(
+        node.isspace() if isinstance(node, str) else node.blank for node in block
+    )

liquid/_messages.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    NamedTuple,
+    Protocol,
+    TypeGuard,
+)
+
+from babel.messages import Catalog
+
+from . import expressions
+from .tags import CommentTag, InlineCommentTag, TemplateComment
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+    from ._markup import Expression, Markup
+    from ._template import Template
+    from .environment import Environment
+
+
+DEFAULT_KEYWORDS: dict[str, Any] = {
+    "t": None,
+    "trans": None,
+    "translate": None,
+    "gettext": None,
+    "ngettext": (1, 2),
+    "pgettext": ((1, "c"), 2),
+    "npgettext": ((1, "c"), 2, 3),
+}
+
+DEFAULT_COMMENT_TAGS = [
+    "Translators:",
+]
+
+
+class Translations(Protocol):
+    """Message catalog interface.
+
+    An object implementing this protocol is expected to be available in a render context.
+
+    Could be a ``GNUTranslations`` instance from the ``gettext`` module, a Babel
+    ``Translations`` object, or any object implementing ``gettext``, ``ngettext``,
+    ``pgettext`` and ``npgettext`` methods.
+    """
+
+    def gettext(self, message: str) -> str:
+        """Lookup the message in the catalog."""
+        ...
+
+    def ngettext(self, singular: str, plural: str, n: int) -> str:
+        """Do plural-forms message lookup."""
+        ...
+
+    def pgettext(self, context: str, message: str) -> str:
+        """Lookup the context and message in the catalog."""
+        ...
+
+    def npgettext(self, context: str, singular: str, plural: str, n: int) -> str:
+        """Do plural-forms context and message lookup."""
+        ...
+
+
+type MESSAGES = (
+    str
+    | tuple[str, ...]
+    | tuple[tuple[str, str], str]
+    | tuple[tuple[str, str], str, str]
+)
+
+type SPEC = (
+    tuple[int, ...] | tuple[tuple[int, str], int] | tuple[tuple[int, str], int, int]
+)
+
+
+class MessageTuple(NamedTuple):
+    """The tuple expected to be returned from babel extraction methods."""
+
+    lineno: int
+    funcname: str
+    message: MESSAGES
+    comments: list[str]
+
+
+class MessageText(NamedTuple):
+    """Partial message tuple returned from translatable tags."""
+
+    lineno: int
+    funcname: str
+    message: MESSAGES
+
+
+class TranslatableTag(Protocol):
+    def messages(self, template: Template) -> Iterable[MessageText]:
+        """Generate a sequence of translation messages."""
+        ...
+
+    def children(self) -> list[Markup]: ...
+
+
+def translatable_tag(node: Markup) -> TypeGuard[TranslatableTag]:
+    return hasattr(node, "messages")
+
+
+class TranslatableFilter(Protocol):
+    def message(
+        self,
+        left: Expression,
+        filter_: expressions.Filtered,
+        lineno: int,
+    ) -> MessageText | None:
+        """Return a translation message."""
+
+
+def translatable_filter(node: object) -> TypeGuard[TranslatableFilter]:
+    return hasattr(node, "message")
+
+
+def extract_from_templates(
+    *templates: Template,
+    keywords: dict[str, Any] | None = None,
+    comment_tags: list[str] | None = None,
+    strip_comment_tags: bool = False,
+) -> Catalog:
+    """Extract messages from one or more templates.
+
+    This function returns a single `babel.messages.Catalog` containing messages from all
+    the given templates.
+
+    Parameters
+    ----------
+    templates
+        Templates to extract messages from.
+    keywords
+        A Babel compatible mapping of translatable "function" names to argument specs.
+        The included translation filters and tag transform their messages into typical
+        \\*gettext format, regardless of their names.
+    comment_tags
+        A list of translator tags to search for and include in extracted messages.
+    strip_comment_tags
+        If `True`, remove comment tags from collected message comments.
+    """
+    keywords = keywords or DEFAULT_KEYWORDS
+    comment_tags = comment_tags or DEFAULT_COMMENT_TAGS
+    catalog = Catalog()
+    for template in templates:
+        for lineno, funcname, messages, comments in extract_from_template(
+            template, keywords, comment_tags
+        ):
+            # A partial re-implementation of Babel's messages.extract function.
+            # See https://github.com/python-babel/babel/blob/master/babel/messages/extract.py#L262
+            spec: SPEC = keywords[funcname] or (1,)
+            if not isinstance(messages, (list, tuple)):
+                messages = (messages,)
+            if not messages:
+                continue
+            if len(spec) != len(messages):
+                continue
+
+            # Assumes context is the first item in the spec
+            if isinstance(spec[0], tuple):
+                # context aware message
+                context = messages[spec[0][0] - 1][0]
+                message = [messages[i - 1] for i in spec[1:]]
+            else:
+                context = None
+                message = [messages[i - 1] for i in spec if isinstance(i, int)]
+
+            if not message[0]:
+                # Empty message
+                continue
+
+            if strip_comment_tags:
+                comments = _strip_comment_tags(comments, comment_tags)
+
+            # Use the template's path if it has one
+            template_name = template.name
+            if isinstance(template.path, Path):
+                template_name = str(template.path.joinpath(template_name))
+            elif isinstance(template.path, str):
+                template_name = os.path.join(template.path, template_name)
+
+            catalog.add(
+                message[0] if len(message) == 1 else message,  # type: ignore
+                "",
+                [(template_name, lineno)],
+                auto_comments=comments,
+                context=context,
+            )
+
+    return catalog
+
+
+def extract_from_template(
+    template: Template,
+    keywords: list[str] | dict[str, Any] | None = None,
+    comment_tags: list[str] | None = None,
+) -> Iterator[MessageTuple]:
+    """Extract translation messages from a Liquid template."""
+    comment_tags_ = comment_tags or DEFAULT_COMMENT_TAGS
+    comments_: list[tuple[int, str]] = []
+    keywords_ = keywords or DEFAULT_KEYWORDS
+
+    def visit_expression(expr: Expression, lineno: int) -> Iterator[MessageTuple]:
+        if isinstance(expr, expressions.Filtered):
+            for _lineno, funcname, message in _extract_from_filters(
+                template.env, expr, lineno, keywords_
+            ):
+                if comments_ and comments_[-1][0] < lineno - 1:
+                    comments_.clear()
+
+                yield MessageTuple(
+                    lineno=_lineno,
+                    funcname=funcname,
+                    message=message,
+                    comments=[text for _, text in comments_],
+                )
+                comments_.clear()
+
+        for expression in expr.children():
+            yield from visit_expression(expression, lineno)
+
+    def visit(node: Markup) -> Iterator[MessageTuple]:
+        lineno, _ = template.line_col(node.token)
+        if (
+            isinstance(node, (CommentTag, InlineCommentTag, TemplateComment))
+            and node.text
+        ):
+            comment_text = node.text.strip()
+
+            for comment_tag in comment_tags_:
+                if comment_text.startswith(comment_tag):
+                    # Our multi-line comments are wrapped in a tag, so we're
+                    # only ever going to have one comment text object to deal
+                    # with.
+                    comments_.clear()
+                    comments_.append((lineno, comment_text))
+                    break
+
+        elif translatable_tag(node):
+            for lineno, funcname, message in node.messages(template):
+                if comments_ and comments_[-1][0] < lineno - 1:
+                    comments_.clear()
+
+                yield MessageTuple(
+                    lineno=lineno,
+                    funcname=funcname,
+                    message=message,
+                    comments=[text for _, text in comments_],
+                )
+                comments_.clear()
+
+        for child in node.children():
+            for expr in child.expressions():
+                yield from visit_expression(expr, template.line_col(expr.token)[0])
+            yield from visit(child)
+
+    for node in template.nodes:
+        if not isinstance(node, str):
+            for expr in node.expressions():
+                yield from visit_expression(expr, template.line_col(expr.token)[0])
+            yield from visit(node)
+
+
+def _extract_from_filters(
+    environment: Environment,
+    expression: expressions.Filtered,
+    lineno: int,
+    keywords: list[str] | dict[str, Any],
+) -> Iterable[MessageText]:
+    if expression.name.value in keywords:
+        filter_callable = environment.filters.get(expression.name.value)
+        if translatable_filter(filter_callable):
+            msg = filter_callable.message(expression.left, expression, lineno)
+            if msg:
+                yield msg
+
+
+def _strip_comment_tags(comments: list[str], tags: list[str]) -> list[str]:
+    """Similar to Babel's messages.extract._strip_comment_tags."""
+
+    def _strip(line: str) -> str:
+        for tag in tags:
+            if line.startswith(tag):
+                return line[len(tag) :].strip()
+        return line
+
+    return [_strip(comment) for comment in comments]

liquid/_missing.py

@@ -0,0 +1,3 @@
+from ._nothing import NOTHING
+
+MISSING = NOTHING