python-liquid 1.13.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

liquid/__init__.py

@@ -1,34 +1,26 @@
-try:
-    from markupsafe import Markup
-    from markupsafe import escape
-    from markupsafe import soft_str
-except ImportError:
-    from liquid.exceptions import Markup  # type: ignore
-    from liquid.exceptions import escape  # type: ignore
+from pathlib import Path
+from typing import Iterable
+from typing import Iterator
+from typing import Optional
+from typing import TextIO
+from typing import Union
 
-    soft_str = str  # type: ignore
+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 .loaders import CachingChoiceLoader
-from .loaders import CachingFileSystemLoader
-from .loaders import ChoiceLoader
-from .loaders import DictLoader
-from .loaders import FileExtensionLoader
-from .loaders import FileSystemLoader
-from .loaders import PackageLoader
-from .loaders import make_choice_loader
-from .loaders import make_file_system_loader
-
-from .context import Context
-from .context import DebugUndefined
-from .context import is_undefined
+from .context import RenderContext
 from .context import FutureContext
-from .context import StrictDefaultUndefined
-from .context import StrictUndefined
-from .context import Undefined
+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 .environment import Environment
 from .environment import Template
@@ -38,31 +30,52 @@ 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 .static_analysis import TemplateAnalysis
-from .static_analysis import ContextualTemplateAnalysis
+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__ = "1.13.0"
+__version__ = "2.0.0"
 
 __all__ = (
     "AwareBoundTemplate",
+    "BlockNode",
     "BoundTemplate",
     "CachingChoiceLoader",
+    "CachingDictLoader",
     "CachingFileSystemLoader",
+    "CachingLoaderMixin",
     "ChoiceLoader",
-    "Context",
-    "ContextualTemplateAnalysis",
+    "ConditionalBlockNode",
     "DebugUndefined",
     "DEFAULT_INNER_TAG_MAP",
     "DictLoader",
     "Environment",
     "escape",
     "Expression",
-    "FileExtensionLoader",
+    "extract_from_template",
+    "FalsyStrictUndefined",
     "FileSystemLoader",
     "future",
     "FutureAwareBoundTemplate",
@@ -72,14 +85,162 @@ __all__ = (
     "make_choice_loader",
     "make_file_system_loader",
     "Markup",
+    "MessageTuple",
     "Mode",
+    "Node",
     "PackageLoader",
+    "parse",
+    "render_async",
+    "render",
+    "RenderContext",
     "soft_str",
     "StrictDefaultUndefined",
     "StrictUndefined",
+    "Tag",
     "TagAnalysis",
     "Template",
-    "TemplateAnalysis",
     "Token",
+    "TokenStream",
+    "Translations",
     "Undefined",
 )
+
+DEFAULT_ENVIRONMENT = Environment()
+
+
+def parse(source: str) -> BoundTemplate:
+    """Parse template source text using the default environment."""
+    return DEFAULT_ENVIRONMENT.from_string(source)
+
+
+def render(source: str, **data: object) -> str:
+    """Parse and render source text using the default environment."""
+    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)
+
+
+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_
+    """
+    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 FileSystemLoader(search_path=search_path, encoding=encoding, ext=ext)
+
+
+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_
+    """
+    if cache_size > 0:
+        return CachingChoiceLoader(
+            loaders=loaders,
+            auto_reload=auto_reload,
+            namespace_key=namespace_key,
+            capacity=cache_size,
+        )
+
+    return ChoiceLoader(loaders=loaders)
+
+
+def extract_liquid(
+    fileobj: TextIO,
+    keywords: list[str],
+    comment_tags: Optional[list[str]] = None,
+    options: Optional[dict[object, object]] = None,  # noqa: ARG001
+) -> 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`.
+
+    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.
+    """
+    template = Environment(extra=True).parse(fileobj.read())
+    return extract_from_template(
+        template=template,
+        keywords=keywords,
+        comment_tags=comment_tags,
+    )

liquid/analyze_tags.py

@@ -1,20 +1,20 @@
 """Analyze template tags from tokenized source text."""
+
 from __future__ import annotations
 
 from collections import defaultdict
 from typing import TYPE_CHECKING
-from typing import Dict
+from typing import DefaultDict
 from typing import Iterable
-from typing import List
 from typing import Mapping
 from typing import Optional
-from typing import Tuple
 
-from liquid.token import TOKEN_TAG
+from .span import Span
+from .token import TOKEN_TAG
 
 if TYPE_CHECKING:
-    from liquid import Environment
-    from liquid.token import Token
+    from .environment import Environment
+    from .token import Token
 
 
 DEFAULT_INNER_TAG_MAP = {
@@ -24,15 +24,16 @@ DEFAULT_INNER_TAG_MAP = {
     "unless": ["else", "elsif"],
 }
 
+
 InnerTagMap = Mapping[str, Iterable[str]]
-TagMap = Dict[str, List[Tuple[str, int]]]
+TagMap = dict[str, list[Span]]
 
 
 class TagAnalysis:
     """The result of analyzing a template's tags with `Environment.analyze_tags()`.
 
     Each of the following properties maps tag names to a list of their locations.
-    Locations are (template_name, line_number) tuples.
+    Locations are (template_name, start_index) tuples.
 
     Note that `raw` tags are not included at all. The lexer converts them to text
     tokens before we get a chance to analyze them.
@@ -58,7 +59,7 @@ class TagAnalysis:
         *,
         env: Environment,
         name: str,
-        tokens: List[Token],
+        tokens: list[Token],
         inner_tags: Optional[InnerTagMap] = None,
     ) -> None:
         self.template_name = name
@@ -86,20 +87,20 @@ class TagAnalysis:
             self.unknown_tags,
         ) = self._audit_tags(env, tokens)
 
-    def _all_tags(self, tokens: List[Token]) -> TagMap:
+    def _all_tags(self, tokens: list[Token]) -> TagMap:
         """Map tag names to their locations, similar to `Template.analyze` etc."""
-        tags = defaultdict(list)
+        tags: DefaultDict[str, list[Span]] = defaultdict(list)
         for token in tokens:
-            if token.type == TOKEN_TAG:
-                tags[token.value].append((self.template_name, token.linenum))
+            if token.kind == TOKEN_TAG:
+                tags[token.value].append(Span(self.template_name, token.start_index))
         return dict(tags)
 
     def _audit_tags(  # noqa: PLR0912
         self,
         env: Environment,
-        tokens: List[Token],
-    ) -> Tuple[TagMap, TagMap, TagMap]:
-        block_stack: List[_BlockStackItem] = []
+        tokens: list[Token],
+    ) -> tuple[TagMap, TagMap, TagMap]:
+        block_stack: list[_BlockStackItem] = []
         unclosed_tags: TagMap = defaultdict(list)
         unexpected_tags: TagMap = defaultdict(list)
         unknown_tags: TagMap = defaultdict(list)
@@ -108,7 +109,7 @@ class TagAnalysis:
         end_tags = {
             token.value
             for token in tokens
-            if token.type == TOKEN_TAG and token.value.startswith("end")
+            if token.kind == TOKEN_TAG and token.value.startswith("end")
         }
 
         # Infer which tags are block tags. This may or may not match what the
@@ -131,7 +132,7 @@ class TagAnalysis:
         }
 
         for token in tokens:
-            if token.type != TOKEN_TAG:
+            if token.kind != TOKEN_TAG:
                 continue
 
             tag_name = token.value
@@ -143,7 +144,7 @@ class TagAnalysis:
                 if start_block_tag != tag_name[3:]:
                     # if start_block_tag.name not in inline_tags:
                     unclosed_tags[start_block_tag.name].append(
-                        (self.template_name, start_block_tag.token.linenum)
+                        Span(self.template_name, start_block_tag.token.start_index)
                     )
                 continue
 
@@ -152,18 +153,22 @@ class TagAnalysis:
                 enclosing_tags: Iterable[str] = self._inner_tags.get(tag_name, [])
                 if not enclosing_tags:
                     # Not an inner tag for any block.
-                    unknown_tags[tag_name].append((self.template_name, token.linenum))
+                    unknown_tags[tag_name].append(
+                        Span(self.template_name, token.start_index)
+                    )
                 elif not self._valid_inner_tag(
                     self._inner_tags.get(tag_name, []), block_stack
                 ):
                     # An inner tag, but not valid for any blocks currently on the stack.
                     unexpected_tags[tag_name].append(
-                        (self.template_name, token.linenum)
+                        Span(self.template_name, token.start_index)
                     )
 
         # Catch any unclosed tags.
         for block in block_stack:
-            unclosed_tags[block.name].append((self.template_name, block.token.linenum))
+            unclosed_tags[block.name].append(
+                Span(self.template_name, block.token.start_index)
+            )
 
         # Catch bad "end" tags.
         for tag_name, locations in self.all_tags.items():
@@ -184,7 +189,7 @@ class TagAnalysis:
     def _valid_inner_tag(
         self,
         tag_names: Iterable[str],
-        block_stack: List[_BlockStackItem],
+        block_stack: list[_BlockStackItem],
     ) -> bool:
         return any(tag_name in block_stack for tag_name in tag_names)