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

liquid/__about__.py

@@ -0,0 +1 @@
+__version__ = "3.0.0"

liquid/__init__.py

@@ -1,242 +1,216 @@
-from pathlib import Path
-from typing import Iterable
-from typing import Iterator
-from typing import Optional
-from typing import TextIO
-from typing import Union
-
-from markupsafe import Markup
-from markupsafe import escape
-from markupsafe import soft_str
-
-from .mode import Mode
-from .token import Token
-from .expression import Expression
-
-from .context import RenderContext
-from .context import FutureContext
-from .undefined import DebugUndefined
-from .undefined import is_undefined
-from .undefined import FalsyStrictUndefined
-from .undefined import StrictDefaultUndefined
-from .undefined import StrictUndefined
-from .undefined import Undefined
-
+from collections.abc import Iterator, Mapping
+from typing import Any, TextIO
+
+from ._base_tag import AbstractTag
+from ._context import RenderContext
+from ._drop import (
+    ContextHint,
+    LiquidAsyncIterable,
+    LiquidAsyncObject,
+    LiquidIterable,
+    LiquidObject,
+    LiquidPrimitive,
+)
+from ._filter import Filter, FilterContext
+from ._io import StringBuffer
+from ._lax_parser_mixin import LaxParserMixin
+from ._lexer import Lexer
+from ._lexer_extended import ExtendedLexer
+from ._lexer_legacy import LegacyLexer
+from ._loader import Loader, TemplateSource
+from ._markup import (
+    Block,
+    Expression,
+    Markup,
+    Node,
+    Partial,
+    Scope,
+    Tag,
+    render_block,
+    render_block_async,
+)
+from ._messages import (
+    MessageTuple,
+    Translations,
+    extract_from_template,
+    extract_from_templates,
+)
+from ._nothing import NOTHING
+from ._parser import Parser
+from ._parser_extended import ExtendedParser
+from ._parser_legacy import LegacyParser
+from ._resource_limits import ResourceLimits
+from ._slice import slice_range, slice_sequence
+from ._static_analysis import Segments, TemplateAnalysis
+from ._template import Template
+from .drops import (
+    AsyncIterableDrop,
+    FalsyStrictUndefined,
+    IterableDrop,
+    StrictUndefined,
+    Undefined,
+)
 from .environment import Environment
-from .environment import Template
-
-from .template import AwareBoundTemplate
-from .template import BoundTemplate
-from .template import FutureAwareBoundTemplate
-from .template import FutureBoundTemplate
-
-from .builtin import CachingDictLoader
-from .builtin import DictLoader
-from .builtin import ChoiceLoader
-from .builtin import CachingChoiceLoader
-from .builtin import CachingFileSystemLoader
-from .builtin import FileSystemLoader
-from .builtin import PackageLoader
-from .builtin import CachingLoaderMixin
-from .loader import BaseLoader
-
-from .ast import Node
-from .ast import BlockNode
-from .ast import ConditionalBlockNode
-
-from .analyze_tags import TagAnalysis
-from .analyze_tags import DEFAULT_INNER_TAG_MAP
-
-from .messages import MessageTuple
-from .messages import Translations
-from .messages import extract_from_template
-
-from .stream import TokenStream
-from .tag import Tag
-
-from . import future
-
-__version__ = "2.3.6"
+from .loaders import (
+    CachingChoiceLoader,
+    CachingDictLoader,
+    CachingFileSystemLoader,
+    CachingLoaderMixin,
+    ChoiceLoader,
+    DictLoader,
+    FileSystemLoader,
+    PackageLoader,
+)
+from .tokens import TOKEN_NAMES, Token, TokenKind, span, token_value
 
 __all__ = (
-    "AwareBoundTemplate",
-    "BlockNode",
-    "BoundTemplate",
+    "NOTHING",
+    "TOKEN_NAMES",
+    "AbstractTag",
+    "AsyncIterableDrop",
+    "Block",
     "CachingChoiceLoader",
     "CachingDictLoader",
     "CachingFileSystemLoader",
     "CachingLoaderMixin",
     "ChoiceLoader",
-    "ConditionalBlockNode",
-    "DebugUndefined",
-    "DEFAULT_INNER_TAG_MAP",
+    "ContextHint",
     "DictLoader",
     "Environment",
-    "escape",
     "Expression",
-    "extract_from_template",
+    "ExtendedLexer",
+    "ExtendedParser",
     "FalsyStrictUndefined",
     "FileSystemLoader",
-    "future",
-    "FutureAwareBoundTemplate",
-    "FutureBoundTemplate",
-    "FutureContext",
-    "is_undefined",
-    "make_choice_loader",
-    "make_file_system_loader",
+    "Filter",
+    "FilterContext",
+    "IterableDrop",
+    "LaxExtendedParser",
+    "LaxLegacyParser",
+    "LaxParserMixin",
+    "LegacyLexer",
+    "LegacyParser",
+    "Lexer",
+    "LiquidAsyncIterable",
+    "LiquidAsyncObject",
+    "LiquidIterable",
+    "LiquidObject",
+    "LiquidPrimitive",
+    "Loader",
     "Markup",
-    "MessageTuple",
-    "Mode",
     "Node",
     "PackageLoader",
-    "parse",
-    "render_async",
-    "render",
+    "Parser",
+    "Partial",
     "RenderContext",
-    "soft_str",
-    "StrictDefaultUndefined",
+    "ResourceLimits",
+    "Scope",
+    "Segments",
     "StrictUndefined",
+    "StringBuffer",
     "Tag",
-    "TagAnalysis",
     "Template",
+    "TemplateAnalysis",
+    "TemplateSource",
     "Token",
-    "TokenStream",
+    "TokenKind",
     "Translations",
     "Undefined",
+    "extract_from_templates",
+    "render_block",
+    "render_block_async",
+    "slice_range",
+    "slice_sequence",
+    "span",
+    "token_value",
 )
 
+
 DEFAULT_ENVIRONMENT = Environment()
 
 
-def parse(source: str) -> BoundTemplate:
-    """Parse template source text using the default environment."""
-    return DEFAULT_ENVIRONMENT.from_string(source)
+def parse(
+    source: str,
+    *,
+    name: str = "",
+    globals: Mapping[str, Any] | None = None,
+) -> Template:
+    """Parse template source code `source` using the default Liquid environment.
+
+    Parameters
+    ----------
+    source
+        Template source code.
+    name
+        A name for the template that will appear in error messages.
+    globals
+        Variables to pin to the resulting template.
+    """
+    return DEFAULT_ENVIRONMENT.parse(source, name=name, globals=globals)
 
 
-def render(source: str, **data: object) -> str:
-    """Parse and render source text using the default environment."""
-    return DEFAULT_ENVIRONMENT.render(source, **data)
+def render(source: str, data: Mapping[str, Any] | None = None) -> str:
+    """Parse and render `source` with variables from `data` using the default environment.
 
+    Parameters
+    ----------
+    source
+        Template source code.
+    data
+        Template variables.
+    """
+    return DEFAULT_ENVIRONMENT.render(source, data)
 
-async def render_async(source: str, **data: object) -> str:
-    """Parse and render source text using the default environment."""
-    return await DEFAULT_ENVIRONMENT.render_async(source, **data)
 
+async def render_async(source: str, data: Mapping[str, Any] | None = None) -> str:
+    """Parse and render `source` asynchronously with variables from `data` using the
+    default environment.
 
-def make_file_system_loader(
-    search_path: Union[str, Path, Iterable[Union[str, Path]]],
-    *,
-    encoding: str = "utf-8",
-    ext: str = ".liquid",
-    auto_reload: bool = True,
-    namespace_key: str = "",
-    cache_size: int = 300,
-) -> BaseLoader:
-    """A _file system_ template loader factory.
-
-    Returns one of `CachingFileSystemLoader` or `FileSystemLoader` depending in
-    the given arguments.
-
-    A `CachingFileSystemLoader` is returned if _cache_size_ is greater than 0.
-    Otherwise a `FileExtensionLoader` is returned if _ext_ is not empty.
-    If _ext_ is empty, a `FileSystemLoader` is returned.
-
-    _auto_reload_ and _namespace_key_ are ignored if _cache_key_ is less than 1.
-
-    Args:
-        search_path: One or more paths to search.
-        encoding: Open template files with the given encoding.
-        ext: A default file extension. Should include a leading period.
-        auto_reload: If `True`, automatically reload a cached template if it has been
-            updated.
-        namespace_key: The name of a global render context variable or loader keyword
-            argument that resolves to the current loader "namespace" or "scope".
-
-            If you're developing a multi-user application, a good namespace might be
-            `uid`, where `uid` is a unique identifier for a user and templates are
-            arranged in folders named for each `uid` inside the search path.
-        cache_size: The maximum number of templates to hold in the cache before removing
-            the least recently used template.
-
-    _New in version 1.12.0_
+    Parameters
+    ----------
+    source
+        Template source code.
+    data
+        Template variables.
     """
-    if cache_size > 0:
-        return CachingFileSystemLoader(
-            search_path=search_path,
-            encoding=encoding,
-            ext=ext,
-            auto_reload=auto_reload,
-            namespace_key=namespace_key,
-            capacity=cache_size,
-        )
+    return await DEFAULT_ENVIRONMENT.render_async(source, data)
 
-    return FileSystemLoader(search_path=search_path, encoding=encoding, ext=ext)
 
+class LaxLegacyParser(LaxParserMixin, LegacyParser):
+    """A legacy parser that suppresses Liquid syntax errors.
 
-def make_choice_loader(
-    loaders: list[BaseLoader],
-    *,
-    auto_reload: bool = True,
-    namespace_key: str = "",
-    cache_size: int = 300,
-) -> BaseLoader:
-    """A _choice loader_ factory.
-
-    Returns one of `CachingChoiceLoader` or `ChoiceLoader` depending on the
-    given arguments.
-
-    A `CachingChoiceLoader` is returned if _cache_size_ > 0, otherwise a
-    `ChoiceLoader` is returned.
-
-    _auto_reload_ and _namespace_key_ are ignored if _cache_key_ is less than 1.
-
-    Args:
-        loaders: A list of loaders implementing `liquid.loaders.BaseLoader`.
-        auto_reload: If `True`, automatically reload a cached template if it
-            has been updated.
-        namespace_key: The name of a global render context variable or loader
-            keyword argument that resolves to the current loader "namespace" or
-            "scope".
-        cache_size: The maximum number of templates to hold in the cache before
-            removing the least recently used template.
-
-    _New in version 1.12.0_
+    Use ``Template.errors()`` to get a list of available ``LiquidSyntaxError`` instances.
     """
-    if cache_size > 0:
-        return CachingChoiceLoader(
-            loaders=loaders,
-            auto_reload=auto_reload,
-            namespace_key=namespace_key,
-            capacity=cache_size,
-        )
 
-    return ChoiceLoader(loaders=loaders)
+
+class LaxExtendedParser(LaxParserMixin, ExtendedParser):
+    """An extended parser that suppresses Liquid syntax errors.
+
+    Use ``Template.errors()`` to get a list of available ``LiquidSyntaxError`` instances.
+    """
 
 
 def extract_liquid(
     fileobj: TextIO,
     keywords: list[str],
-    comment_tags: Optional[list[str]] = None,
-    options: Optional[dict[object, object]] = None,  # noqa: ARG001
+    comment_tags: list[str] | None = None,
+    options: Mapping[str, Any] | None = None,
 ) -> Iterator[MessageTuple]:
     """A babel compatible translation message extraction method for Liquid templates.
 
     See https://babel.pocoo.org/en/latest/messages.html
 
-    Keywords are the names of Liquid filters or tags operating on translatable
-    strings. For a filter to contribute to message extraction, it must also
-    appear as a child of a `FilteredExpression` and be a `TranslatableFilter`.
-    Similarly, tags must produce a node that is a `TranslatableTag`.
+    Keywords are the names of Liquid filters or tags operating on translatable strings.
+    For a filter to contribute to message extraction, it must also appear as a child of
+    a `FilteredExpression` and be a `TranslatableFilter`. Similarly, tags must produce a
+    node that is a `TranslatableTag`.
 
-    Where a Liquid comment contains a prefix in `comment_tags`, the comment
-    will be attached to the translatable filter or tag immediately following
-    the comment. Python Liquid's non-standard shorthand comments are not
-    supported.
+    Where a Liquid comment contains a prefix in `comment_tags`, the comment will be
+    attached to the translatable filter or tag immediately following the comment. Python
+    Liquid's non-standard shorthand comments are not supported.
 
-    Options are arguments passed to the `liquid.Template` constructor with the
-    contents of `fileobj` as the template's source. Use `extract_from_template`
-    to extract messages from an existing template bound to an existing
-    environment.
+    Use ``extract_from_template`` to extract messages from an existing template bound to
+    an existing environment.
     """
     template = Environment(extra=True).parse(fileobj.read())
     return extract_from_template(

liquid/_base_tag.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._context import RenderContext
+    from ._io import StringBuffer
+    from ._markup import Expression, Markup, Partial
+    from ._parser import Parser
+    from .expressions import Name
+    from .tokens import Token
+
+
+class AbstractTag(ABC):
+    """An abstract class for implementing custom tags.
+
+    It is not necessary to inherit from `AbstractTag` when implementing custom tags, but
+    it can be convenient if you're not interested in methods supporting static template
+    analysis, saving you from writing several empty methods.
+
+    Internally we use the `Markup` and `Tag` protocols, without a required base class.
+    """
+
+    @classmethod
+    @abstractmethod
+    def parse(cls, token: Token, parser: Parser) -> Markup:
+        """Parse tokens or text from `parser` into a markup node."""
+
+    @abstractmethod
+    def render(self, context: RenderContext, buffer: StringBuffer) -> None:
+        """Render this node to `buffer` using data from `context`."""
+
+    @abstractmethod
+    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.
+        """
+        return []
+
+    def expressions(self) -> list[Expression]:
+        """Return expression owned by this node."""
+        return []
+
+    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.
+        """
+        return []
+
+    def template_scope(self) -> list[Name]:
+        """Return variable names that this tag adds to the template scope."""
+        return []
+
+    def partials(self, context: RenderContext) -> list[Partial]:
+        """Return meta data about partial templates rendered from this node."""
+        return []
+
+    async def partials_async(self, context: RenderContext) -> list[Partial]:
+        """Return meta data about partial templates rendered from this node."""
+        return []

liquid/{utils/chain_map.py → _chain_map.py}

@@ -3,26 +3,29 @@
 Based on "A greatly simplified read-only version of Chainmap" by Raymond Hettinger.
 https://code.activestate.com/recipes/305268/
 """
+
 from collections import deque
+from collections.abc import Iterator, Mapping
 from itertools import chain
-from typing import Any
-from typing import Iterator
-from typing import Mapping
+
+from ._missing import MISSING
 
 
 class ReadOnlyChainMap(Mapping[str, object]):
-    """Combine multiple mappings for sequential lookup."""
+    """Combine multiple mappings for sequential lookup.
+
+    This chain map never raises a KeyError. It returns the MISSING sentinel
+    if a key does not exist in the chain.
+    """
 
     def __init__(self, *maps: Mapping[str, object]):
         self._maps = deque(maps)
 
     def __getitem__(self, key: str) -> object:
         for mapping in self._maps:
-            try:
+            if key in mapping:
                 return mapping[key]
-            except KeyError:
-                pass
-        raise KeyError(key)
+        return MISSING
 
     def __iter__(self) -> Iterator[str]:
         return chain(*self._maps)
@@ -30,21 +33,17 @@ class ReadOnlyChainMap(Mapping[str, object]):
     def __len__(self) -> int:
         return sum(len(_map) for _map in self._maps)
 
+    def __contains__(self, key: object) -> bool:
+        return any(key in mapping for mapping in self._maps)
+
     def size(self) -> int:
-        """Return the number of maps in the chain."""
         return len(self._maps)
 
-    def get(self, key: str, default: object = None) -> object:
-        """Return the value for key if key is in the dictionary, else default."""
-        try:
-            return self[key]
-        except KeyError:
-            return default
+    def get(self, key: str, default: object = MISSING) -> object:
+        return self[key]
 
-    def push(self, namespace: Mapping[Any, Any]) -> None:
-        """Add a mapping to the front of the chain map."""
+    def push(self, namespace: Mapping[str, object]) -> None:
         self._maps.appendleft(namespace)
 
-    def pop(self) -> Mapping[Any, Any]:
-        """Remove a mapping from the front of the chain map."""
+    def pop(self) -> Mapping[str, object]:
         return self._maps.popleft()