python-liquid 1.10.2__py3-none-any.whl → 1.12.0__py3-none-any.whl

liquid/__init__.py

@@ -12,11 +12,15 @@ 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
@@ -42,11 +46,12 @@ from .static_analysis import ContextualTemplateAnalysis
 
 from . import future
 
-__version__ = "1.10.2"
+__version__ = "1.12.0"
 
 __all__ = (
     "AwareBoundTemplate",
     "BoundTemplate",
+    "CachingChoiceLoader",
     "CachingFileSystemLoader",
     "ChoiceLoader",
     "Context",
@@ -64,8 +69,11 @@ __all__ = (
     "FutureBoundTemplate",
     "FutureContext",
     "is_undefined",
+    "make_choice_loader",
+    "make_file_system_loader",
     "Markup",
     "Mode",
+    "PackageLoader",
     "soft_str",
     "StrictDefaultUndefined",
     "StrictUndefined",

liquid/builtin/loaders/__init__.py

@@ -1,9 +1,15 @@
+from pathlib import Path
+from typing import Iterable
+from typing import List
+from typing import Union
+
 from .base_loader import BaseLoader
 from .base_loader import DictLoader
 from .base_loader import TemplateNamespace
 from .base_loader import TemplateSource
 from .base_loader import UpToDate
 
+from .choice_loader import CachingChoiceLoader
 from .choice_loader import ChoiceLoader
 
 from .file_system_loader import FileExtensionLoader
@@ -11,14 +17,117 @@ from .file_system_loader import FileSystemLoader
 
 from .caching_file_system_loader import CachingFileSystemLoader
 
+from .package_loader import PackageLoader
+
 __all__ = (
     "BaseLoader",
+    "CachingChoiceLoader",
     "CachingFileSystemLoader",
     "ChoiceLoader",
     "DictLoader",
     "FileExtensionLoader",
     "FileSystemLoader",
+    "make_choice_loader",
+    "make_file_system_loader",
+    "PackageLoader",
     "TemplateNamespace",
     "TemplateSource",
     "UpToDate",
 )
+
+
+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`, `FileExtensionLoader` 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,
+            cache_size=cache_size,
+        )
+
+    if ext:
+        return FileExtensionLoader(
+            search_path=search_path,
+            encoding=encoding,
+            ext=ext,
+        )
+
+    return FileSystemLoader(search_path=search_path, encoding=encoding)
+
+
+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,
+            cache_size=cache_size,
+        )
+
+    return ChoiceLoader(loaders=loaders)

liquid/builtin/loaders/base_loader.py

@@ -129,11 +129,12 @@ class BaseLoader(ABC):  # noqa: B024
         name: str,
         globals: TemplateNamespace = None,  # noqa: A002
     ) -> BoundTemplate:
-        """Load and parse a template.
+        """Find and parse template source code.
 
-        Used internally by `Environment` to load a template source. Delegates to
-        `get_source`. A custom loaders would typically implement `get_source` rather
-        than overriding `load`.
+        This is used internally by `liquid.Environment` to load template
+        source text. `load()` delegates to `BaseLoader.get_source()`. Custom
+        loaders would typically implement `get_source()` rather than overriding
+        `load()`.
         """
         try:
             source, filename, uptodate, matter = self.get_source(env, name)
@@ -156,7 +157,7 @@ class BaseLoader(ABC):  # noqa: B024
         name: str,
         globals: TemplateNamespace = None,  # noqa: A002
     ) -> BoundTemplate:
-        """An async version of `load`."""
+        """An async version of `load()`."""
         try:
             template_source = await self.get_source_async(env, name)
             source, filename, uptodate, matter = template_source

liquid/builtin/loaders/caching_file_system_loader.py

@@ -1,32 +1,24 @@
 """A file system loader that caches parsed templates in memory."""
 from __future__ import annotations
 
-from functools import partial
 from typing import TYPE_CHECKING
-from typing import Awaitable
-from typing import Callable
 from typing import Iterable
-from typing import Mapping
 from typing import Union
 
-from liquid.utils import LRUCache
-
 from .file_system_loader import FileExtensionLoader
+from .mixins import CachingLoaderMixin
 
 if TYPE_CHECKING:
     from pathlib import Path
 
-    from liquid import BoundTemplate
     from liquid import Context
-    from liquid import Environment
 
-    from .base_loader import TemplateNamespace
     from .base_loader import TemplateSource
 
-# ruff: noqa: D102 D101
+# ruff: noqa: D102
 
 
-class CachingFileSystemLoader(FileExtensionLoader):
+class CachingFileSystemLoader(CachingLoaderMixin, FileExtensionLoader):
     """A file system loader that caches parsed templates in memory.
 
     Args:
@@ -45,8 +37,6 @@ class CachingFileSystemLoader(FileExtensionLoader):
             the least recently used template.
     """
 
-    caching_loader = True
-
     def __init__(
         self,
         search_path: Union[str, Path, Iterable[Union[str, Path]]],
@@ -58,160 +48,17 @@ class CachingFileSystemLoader(FileExtensionLoader):
         cache_size: int = 300,
     ):
         super().__init__(
+            auto_reload=auto_reload,
+            namespace_key=namespace_key,
+            cache_size=cache_size,
+        )
+
+        FileExtensionLoader.__init__(
+            self,
             search_path=search_path,
             encoding=encoding,
             ext=ext,
         )
-        self.auto_reload = auto_reload
-        self.cache = LRUCache(capacity=cache_size)
-        self.namespace_key = namespace_key
-
-    def load(
-        self,
-        env: Environment,
-        name: str,
-        globals: TemplateNamespace = None,  # noqa: A002
-    ) -> BoundTemplate:
-        return self.check_cache(
-            env,
-            name,
-            globals,
-            partial(super().load, env, name, globals),
-        )
-
-    async def load_async(
-        self,
-        env: Environment,
-        name: str,
-        globals: TemplateNamespace = None,  # noqa: A002
-    ) -> BoundTemplate:
-        return await self.check_cache_async(
-            env,
-            name,
-            globals,
-            partial(super().load_async, env, name, globals),
-        )
-
-    def load_with_args(
-        self,
-        env: Environment,
-        name: str,
-        globals: TemplateNamespace = None,  # noqa: A002
-        **kwargs: object,
-    ) -> BoundTemplate:
-        cache_key = self.cache_key(name, kwargs)
-        return self.check_cache(
-            env,
-            cache_key,
-            globals,
-            partial(super().load_with_args, env, cache_key, globals, **kwargs),
-        )
-
-    async def load_with_args_async(
-        self,
-        env: Environment,
-        name: str,
-        globals: TemplateNamespace = None,  # noqa: A002
-        **kwargs: object,
-    ) -> BoundTemplate:
-        cache_key = self.cache_key(name, kwargs)
-        return await self.check_cache_async(
-            env,
-            cache_key,
-            globals,
-            partial(super().load_with_args_async, env, cache_key, globals, **kwargs),
-        )
-
-    def load_with_context(
-        self, context: Context, name: str, **kwargs: str
-    ) -> BoundTemplate:
-        cache_key = self.cache_key_with_context(name, context, **kwargs)
-        return self.check_cache(
-            context.env,
-            cache_key,
-            context.globals,
-            partial(super().load_with_context, context=context, name=name, **kwargs),
-        )
-
-    async def load_with_context_async(
-        self, context: Context, name: str, **kwargs: str
-    ) -> BoundTemplate:
-        cache_key = self.cache_key_with_context(name, context, **kwargs)
-        return await self.check_cache_async(
-            context.env,
-            cache_key,
-            context.globals,
-            partial(super().load_with_context_async, context, name, **kwargs),
-        )
-
-    def check_cache(
-        self,
-        env: Environment,  # noqa: ARG002
-        cache_key: str,
-        globals: TemplateNamespace,  # noqa: A002
-        load_func: Callable[[], BoundTemplate],
-    ) -> BoundTemplate:
-        try:
-            cached_template: BoundTemplate = self.cache[cache_key]
-        except KeyError:
-            template = load_func()
-            self.cache[cache_key] = template
-            return template
-
-        if self.auto_reload and not cached_template.is_up_to_date:
-            template = load_func()
-            self.cache[cache_key] = template
-            return template
-
-        if globals:
-            cached_template.globals.update(globals)
-        return cached_template
-
-    async def check_cache_async(
-        self,
-        env: Environment,  # noqa: ARG002
-        cache_key: str,
-        globals: TemplateNamespace,  # noqa: A002
-        load_func: Callable[[], Awaitable[BoundTemplate]],
-    ) -> BoundTemplate:
-        try:
-            cached_template: BoundTemplate = self.cache[cache_key]
-        except KeyError:
-            template = await load_func()
-            self.cache[cache_key] = template
-            return template
-
-        if self.auto_reload and not await cached_template.is_up_to_date_async():
-            template = await load_func()
-            self.cache[cache_key] = template
-            return template
-
-        if globals:
-            cached_template.globals.update(globals)
-        return cached_template
-
-    def cache_key(self, name: str, args: Mapping[str, object]) -> str:
-        if not self.namespace_key:
-            return name
-
-        try:
-            return f"{args[self.namespace_key]}/{name}"
-        except KeyError:
-            return name
-
-    def cache_key_with_context(
-        self,
-        name: str,
-        context: Context,
-        **kwargs: str,  # noqa: ARG002
-    ) -> str:
-        if not self.namespace_key:
-            return name
-
-        try:
-            return f"{context.globals[self.namespace_key]}/{name}"
-        except KeyError:
-            return name
 
     def get_source_with_context(
         self, context: Context, template_name: str, **kwargs: str

liquid/builtin/loaders/choice_loader.py

@@ -7,11 +7,14 @@ from typing import List
 from liquid.exceptions import TemplateNotFound
 
 from .base_loader import BaseLoader
-from .base_loader import TemplateSource
+from .mixins import CachingLoaderMixin
 
 if TYPE_CHECKING:
+    from liquid import Context
     from liquid import Environment
 
+    from .base_loader import TemplateSource
+
 
 class ChoiceLoader(BaseLoader):
     """A template loader that will try each of a list of loaders in turn.
@@ -24,9 +27,8 @@ class ChoiceLoader(BaseLoader):
         super().__init__()
         self.loaders = loaders
 
-    def get_source(  # noqa: D102
-        self, env: Environment, template_name: str
-    ) -> TemplateSource:
+    def get_source(self, env: Environment, template_name: str) -> TemplateSource:
+        """Get source code for a template from one of the configured loaders."""
         for loader in self.loaders:
             try:
                 return loader.get_source(env, template_name)
@@ -35,11 +37,12 @@ class ChoiceLoader(BaseLoader):
 
         raise TemplateNotFound(template_name)
 
-    async def get_source_async(  # noqa: D102
+    async def get_source_async(
         self,
         env: Environment,
         template_name: str,
     ) -> TemplateSource:
+        """An async version of `get_source`."""
         for loader in self.loaders:
             try:
                 return await loader.get_source_async(env, template_name)
@@ -47,3 +50,94 @@ class ChoiceLoader(BaseLoader):
                 pass
 
         raise TemplateNotFound(template_name)
+
+    def get_source_with_args(
+        self,
+        env: Environment,
+        template_name: str,
+        **kwargs: object,
+    ) -> TemplateSource:
+        """Get source code for a template from one of the configured loaders."""
+        for loader in self.loaders:
+            try:
+                return loader.get_source_with_args(env, template_name, **kwargs)
+            except TemplateNotFound:
+                pass
+
+        # TODO: include arguments in TemplateNotFound exception.
+        raise TemplateNotFound(template_name)
+
+    async def get_source_with_args_async(
+        self,
+        env: Environment,
+        template_name: str,
+        **kwargs: object,
+    ) -> TemplateSource:
+        """An async version of `get_source_with_args`."""
+        for loader in self.loaders:
+            try:
+                return await loader.get_source_with_args_async(
+                    env, template_name, **kwargs
+                )
+            except TemplateNotFound:
+                pass
+
+        raise TemplateNotFound(template_name)
+
+    def get_source_with_context(
+        self, context: Context, template_name: str, **kwargs: str
+    ) -> TemplateSource:
+        """Get source code for a template from one of the configured loaders."""
+        for loader in self.loaders:
+            try:
+                return loader.get_source_with_context(context, template_name, **kwargs)
+            except TemplateNotFound:
+                pass
+
+        raise TemplateNotFound(template_name)
+
+    async def get_source_with_context_async(
+        self, context: Context, template_name: str, **kwargs: str
+    ) -> TemplateSource:
+        """Get source code for a template from one of the configured loaders."""
+        for loader in self.loaders:
+            try:
+                return await loader.get_source_with_context_async(
+                    context, template_name, **kwargs
+                )
+            except TemplateNotFound:
+                pass
+
+        raise TemplateNotFound(template_name)
+
+
+class CachingChoiceLoader(CachingLoaderMixin, ChoiceLoader):
+    """A `ChoiceLoader` that caches parsed templates in memory.
+
+    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.11.0._
+    """
+
+    def __init__(
+        self,
+        loaders: List[BaseLoader],
+        *,
+        auto_reload: bool = True,
+        namespace_key: str = "",
+        cache_size: int = 300,
+    ):
+        super().__init__(
+            auto_reload=auto_reload,
+            namespace_key=namespace_key,
+            cache_size=cache_size,
+        )
+
+        ChoiceLoader.__init__(self, loaders)

liquid/builtin/loaders/mixins.py

@@ -0,0 +1,240 @@
+"""Mixin classes that can be used to add common functions to a template loader."""
+from __future__ import annotations
+
+from abc import ABC
+from functools import partial
+from typing import TYPE_CHECKING
+from typing import Awaitable
+from typing import Callable
+from typing import Mapping
+
+from typing_extensions import Protocol
+
+from liquid.utils import LRUCache
+
+if TYPE_CHECKING:
+    from liquid import BoundTemplate
+    from liquid import Context
+    from liquid import Environment
+
+    from .base_loader import TemplateNamespace
+
+# ruff: noqa: D102
+
+# ignoring "safe-super" type errors due to https://github.com/python/mypy/issues/14757
+
+
+class _CachingLoaderProtocol(Protocol):
+    def load(
+        self,
+        env: Environment,
+        name: str,
+        globals: TemplateNamespace = None,  # noqa: A002
+    ) -> BoundTemplate:
+        ...
+
+    async def load_async(
+        self,
+        env: Environment,
+        name: str,
+        globals: TemplateNamespace = None,  # noqa: A002
+    ) -> BoundTemplate:
+        ...
+
+    def load_with_args(
+        self,
+        env: Environment,
+        name: str,
+        globals: TemplateNamespace = None,  # noqa: A002
+        **kwargs: object,
+    ) -> BoundTemplate:
+        ...
+
+    async def load_with_args_async(
+        self,
+        env: Environment,
+        name: str,
+        globals: TemplateNamespace = None,  # noqa: A002
+        **kwargs: object,
+    ) -> BoundTemplate:
+        ...
+
+    def load_with_context(
+        self,
+        context: Context,
+        name: str,
+        **kwargs: str,
+    ) -> BoundTemplate:
+        ...
+
+    async def load_with_context_async(
+        self,
+        context: Context,
+        name: str,
+        **kwargs: str,
+    ) -> BoundTemplate:
+        ...
+
+
+class CachingLoaderMixin(ABC, _CachingLoaderProtocol):
+    """A mixin class that adds caching to a template loader."""
+
+    caching_loader = True
+
+    def __init__(
+        self,
+        *,
+        auto_reload: bool = True,
+        namespace_key: str = "",
+        cache_size: int = 300,
+    ):
+        self.auto_reload = auto_reload
+        self.cache = LRUCache(capacity=cache_size)
+        self.namespace_key = namespace_key
+
+    def _check_cache(
+        self,
+        env: Environment,  # noqa: ARG002
+        cache_key: str,
+        globals: TemplateNamespace,  # noqa: A002
+        load_func: Callable[[], BoundTemplate],
+    ) -> BoundTemplate:
+        try:
+            cached_template: BoundTemplate = self.cache[cache_key]
+        except KeyError:
+            template = load_func()
+            self.cache[cache_key] = template
+            return template
+
+        if self.auto_reload and not cached_template.is_up_to_date:
+            template = load_func()
+            self.cache[cache_key] = template
+            return template
+
+        if globals:
+            cached_template.globals.update(globals)
+        return cached_template
+
+    async def _check_cache_async(
+        self,
+        env: Environment,  # noqa: ARG002
+        cache_key: str,
+        globals: TemplateNamespace,  # noqa: A002
+        load_func: Callable[[], Awaitable[BoundTemplate]],
+    ) -> BoundTemplate:
+        try:
+            cached_template: BoundTemplate = self.cache[cache_key]
+        except KeyError:
+            template = await load_func()
+            self.cache[cache_key] = template
+            return template
+
+        if self.auto_reload and not await cached_template.is_up_to_date_async():
+            template = await load_func()
+            self.cache[cache_key] = template
+            return template
+
+        if globals:
+            cached_template.globals.update(globals)
+        return cached_template
+
+    def load(
+        self,
+        env: Environment,
+        name: str,
+        globals: TemplateNamespace = None,  # noqa: A002
+    ) -> BoundTemplate:
+        return self._check_cache(
+            env,
+            name,
+            globals,
+            partial(super().load, env, name, globals),  # type: ignore
+        )
+
+    async def load_async(
+        self,
+        env: Environment,
+        name: str,
+        globals: TemplateNamespace = None,  # noqa: A002
+    ) -> BoundTemplate:
+        return await self._check_cache_async(
+            env,
+            name,
+            globals,
+            partial(super().load_async, env, name, globals),  # type: ignore
+        )
+
+    def load_with_args(
+        self,
+        env: Environment,
+        name: str,
+        globals: TemplateNamespace = None,  # noqa: A002
+        **kwargs: object,
+    ) -> BoundTemplate:
+        cache_key = self.cache_key(name, kwargs)
+        return self._check_cache(
+            env,
+            cache_key,
+            globals,
+            partial(super().load_with_args, env, cache_key, globals, **kwargs),  # type: ignore
+        )
+
+    async def load_with_args_async(
+        self,
+        env: Environment,
+        name: str,
+        globals: TemplateNamespace = None,  # noqa: A002
+        **kwargs: object,
+    ) -> BoundTemplate:
+        cache_key = self.cache_key(name, kwargs)
+        return await self._check_cache_async(
+            env,
+            cache_key,
+            globals,
+            partial(super().load_with_args_async, env, cache_key, globals, **kwargs),  # type: ignore
+        )
+
+    def load_with_context(
+        self, context: Context, name: str, **kwargs: str
+    ) -> BoundTemplate:
+        cache_key = self.cache_key_with_context(name, context, **kwargs)
+        return self._check_cache(
+            context.env,
+            cache_key,
+            context.globals,
+            partial(super().load_with_context, context=context, name=name, **kwargs),  # type: ignore
+        )
+
+    async def load_with_context_async(
+        self, context: Context, name: str, **kwargs: str
+    ) -> BoundTemplate:
+        cache_key = self.cache_key_with_context(name, context, **kwargs)
+        return await self._check_cache_async(
+            context.env,
+            cache_key,
+            context.globals,
+            partial(super().load_with_context_async, context, name, **kwargs),  # type: ignore
+        )
+
+    def cache_key(self, name: str, args: Mapping[str, object]) -> str:
+        if not self.namespace_key:
+            return name
+
+        try:
+            return f"{args[self.namespace_key]}/{name}"
+        except KeyError:
+            return name
+
+    def cache_key_with_context(
+        self,
+        name: str,
+        context: Context,
+        **kwargs: str,  # noqa: ARG002
+    ) -> str:
+        if not self.namespace_key:
+            return name
+
+        try:
+            return f"{context.globals[self.namespace_key]}/{name}"
+        except KeyError:
+            return name

liquid/builtin/loaders/package_loader.py

@@ -0,0 +1,108 @@
+"""A template loader that reads templates from Python packages."""
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import Iterable
+from typing import Union
+
+from importlib_resources import files
+
+from liquid.exceptions import TemplateNotFound
+
+from .base_loader import BaseLoader
+from .base_loader import TemplateSource
+
+if TYPE_CHECKING:
+    from types import ModuleType
+
+    from importlib_resources.abc import Traversable
+
+    from liquid import Environment
+
+
+class PackageLoader(BaseLoader):
+    """A template loader that reads templates from Python packages.
+
+    Args:
+        package: Import name of a package containing Liquid templates.
+        package_path: One or more directories in the package containing Liquid
+            templates.
+        encoding: Encoding of template files.
+        ext: A default file extension to use if one is not provided. Should
+            include a leading period.
+
+    _New in version 1.11.0._
+    """
+
+    def __init__(
+        self,
+        package: Union[str, ModuleType],
+        *,
+        package_path: Union[str, Iterable[str]] = "templates",
+        encoding: str = "utf-8",
+        ext: str = ".liquid",
+    ) -> None:
+        if isinstance(package_path, str):
+            self.paths = [files(package).joinpath(package_path)]
+        else:
+            _package = files(package)
+            self.paths = [_package.joinpath(path) for path in package_path]
+
+        self.encoding = encoding
+        self.ext = ext
+
+    def _resolve_path(self, template_name: str) -> Traversable:
+        template_path = Path(template_name)
+
+        # Don't build a path that escapes package/package_path.
+        # Does ".." appear in template_name?
+        if os.path.pardir in template_path.parts:
+            raise TemplateNotFound(template_name)
+
+        # Add suffix self.ext if template name does not have a suffix.
+        if not template_path.suffix:
+            template_path = template_path.with_suffix(self.ext)
+
+        for path in self.paths:
+            source_path = path.joinpath(template_path)
+            if source_path.is_file():
+                # MyPy seems to think source_path has `Any` type :(
+                return source_path  # type: ignore
+
+        raise TemplateNotFound(template_name)
+
+    def get_source(  # noqa: D102
+        self,
+        _: Environment,
+        template_name: str,
+    ) -> TemplateSource:
+        source_path = self._resolve_path(template_name)
+        return TemplateSource(
+            source=source_path.read_text(self.encoding),
+            filename=str(source_path),
+            uptodate=None,
+        )
+
+    async def get_source_async(  # noqa: D102
+        self, _: Environment, template_name: str
+    ) -> TemplateSource:
+        loop = asyncio.get_running_loop()
+
+        source_path = await loop.run_in_executor(
+            None,
+            self._resolve_path,
+            template_name,
+        )
+
+        source_text = await loop.run_in_executor(
+            None,
+            source_path.read_text,
+            self.encoding,
+        )
+
+        return TemplateSource(
+            source=source_text, filename=str(source_path), uptodate=None
+        )

liquid/exceptions.py

@@ -235,3 +235,7 @@ class Markup(str):
         raise Error(
             "autoescape requires Markupsafe to be installed"
         )  # pragma: no cover
+
+
+class CacheCapacityValueError(ValueError):
+    """An exception raised when the LRU cache is given a zero or negative capacity."""

liquid/expression.py

@@ -16,6 +16,7 @@ from typing import Iterable
 from typing import Iterator
 from typing import List
 from typing import Mapping
+from typing import NoReturn
 from typing import Optional
 from typing import Tuple
 from typing import TypeVar
@@ -29,6 +30,7 @@ from liquid.exceptions import FilterValueError
 from liquid.exceptions import LiquidTypeError
 from liquid.exceptions import NoSuchFilterFunc
 from liquid.limits import to_int
+from liquid.undefined import Undefined
 
 # ruff: noqa: D102 D101
 
@@ -1079,7 +1081,7 @@ def eval_number_expression(left: Number, operator: str, right: Number) -> bool:
 
 
 def _is_py_falsy_number(obj: object) -> bool:
-    # Liquid 0, 0.0, 0b0, 0X0, 0o0 and Decimal("0") are not falsy.
+    # Liquid 0, 0.0, and Decimal("0") are not falsy.
     return not isinstance(obj, bool) and isinstance(obj, (int, float, Decimal))
 
 
@@ -1090,67 +1092,86 @@ def is_truthy(obj: Any) -> bool:
     return _is_py_falsy_number(obj) or obj not in (False, None)
 
 
-def compare_bool(left: Any, operator: str, right: Any) -> bool:
-    """Compare an object to a boolean value."""
-    if (isinstance(left, bool) and _is_py_falsy_number(right)) or (
-        isinstance(right, bool) and _is_py_falsy_number(left)
-    ):
-        if operator in ("==", "<", ">", "<=", ">="):
-            return False
-        if operator in ("!=", "<>"):
-            return True
-        raise LiquidTypeError(
-            f"unknown operator: {type(left)} {operator} {type(right)}"
-        )
-
-    if operator == "==":
-        return bool(left == right)
-    if operator in ("!=", "<>"):
-        return bool(left != right)
-    if operator in ("<", ">", "<=", ">="):
-        return False
-
-    raise LiquidTypeError(f"unknown operator: {type(left)} {operator} {type(right)}")
-
-
-def compare(left: Any, operator: str, right: Any) -> bool:  # noqa: PLR0911, PLR0912
-    """Return the result of a comparison operation between two objects."""
-    if operator == "and":
+def compare(left: object, op: str, right: object) -> bool:  # noqa: PLR0911, PLR0912
+    """Compare _left_ with _right_ according to Liquid semantics."""
+    if op == "and":
         return is_truthy(left) and is_truthy(right)
-    if operator == "or":
+    if op == "or":
         return is_truthy(left) or is_truthy(right)
 
     if hasattr(left, "__liquid__"):
         left = left.__liquid__()
+
     if hasattr(right, "__liquid__"):
         right = right.__liquid__()
 
-    if isinstance(right, (Empty, Blank)):
-        left, right = right, left
-
-    if isinstance(left, bool) or isinstance(right, bool):
-        return compare_bool(left, operator, right)
+    def _type_error(_left: object, _right: object) -> NoReturn:
+        if type(_left) != type(_right):
+            raise LiquidTypeError(f"invalid operator for types '{_left} {op} {_right}'")
 
-    if operator == "==":
-        return bool(left == right)
-    if operator in ("!=", "<>"):
-        return bool(left != right)
+        raise LiquidTypeError(f"unknown operator: {type(_left)} {op} {type(_right)}")
 
-    if operator == "contains":
+    if op == "==":
+        return _eq(left, right)
+    if op == "!=":
+        return not _eq(left, right)
+    if op == "<>":
+        return not _eq(left, right)
+    if op == "<":
+        try:
+            return _lt(left, right)
+        except TypeError:
+            _type_error(left, right)
+    if op == ">":
+        try:
+            return _lt(right, left)
+        except TypeError:
+            _type_error(right, left)
+    if op == ">=":
+        try:
+            return _lt(right, left) or _eq(left, right)
+        except TypeError:
+            _type_error(right, left)
+    if op == "<=":
+        try:
+            return _lt(left, right) or _eq(left, right)
+        except TypeError:
+            _type_error(left, right)
+    if op == "contains":
         if isinstance(left, str):
             return str(right) in left
         if isinstance(left, (list, dict)):
             return right in left
+        if isinstance(left, Undefined):
+            return False
 
-    if None in (left, right):
-        return False
+    return _type_error(left, right)
 
-    if type(left) in (int, float) and type(right) in (int, float):
-        return eval_number_expression(left, operator, right)
 
-    if type(left) != type(right):
-        raise LiquidTypeError(
-            f"invalid operator for types '{str(left)} {operator} {str(right)}'"
-        )
+def _eq(left: object, right: object) -> bool:
+    if isinstance(right, (Empty, Blank)):
+        left, right = right, left
+
+    # Remember 1 == True and 0 == False in Python
+    if isinstance(right, bool):
+        left, right = right, left
+
+    if isinstance(left, bool):
+        return isinstance(right, bool) and left == right
+
+    return left == right
+
+
+def _lt(left: object, right: object) -> bool:
+    if isinstance(left, str) and isinstance(right, str):
+        return left < right
+
+    if isinstance(left, bool) or isinstance(right, bool):
+        return False
+
+    if isinstance(left, (int, float, Decimal)) and isinstance(
+        right, (int, float, Decimal)
+    ):
+        return left < right
 
-    raise LiquidTypeError(f"unknown operator: {type(left)} {operator} {type(right)}")
+    raise TypeError

liquid/golden/if_tag.py

@@ -219,4 +219,52 @@ cases = [
         expect="false",
         error=True,
     ),
+    Case(
+        description="string is less than string",
+        template="{% if 'abc' < 'acb' %}true{% else %}false{% endif %}",
+        globals={},
+        expect="true",
+    ),
+    Case(
+        description="string is not less than string",
+        template="{% if 'bbb' < 'aaa' %}true{% else %}false{% endif %}",
+        globals={},
+        expect="false",
+    ),
+    Case(
+        description="string is less than or equal to string",
+        template="{% if 'abc' <= 'acb' %}true{% else %}false{% endif %}",
+        globals={},
+        expect="true",
+    ),
+    Case(
+        description="string is not less than or equal to string",
+        template="{% if 'bbb' <= 'aaa' %}true{% else %}false{% endif %}",
+        globals={},
+        expect="false",
+    ),
+    Case(
+        description="string is greater than string",
+        template="{% if 'abc' > 'acb' %}true{% else %}false{% endif %}",
+        globals={},
+        expect="false",
+    ),
+    Case(
+        description="string is not greater than string",
+        template="{% if 'bbb' > 'aaa' %}true{% else %}false{% endif %}",
+        globals={},
+        expect="true",
+    ),
+    Case(
+        description="string is greater than or equal to string",
+        template="{% if 'abc' >= 'acb' %}true{% else %}false{% endif %}",
+        globals={},
+        expect="false",
+    ),
+    Case(
+        description="string is not greater than or equal to string",
+        template="{% if 'bbb' >= 'aaa' %}true{% else %}false{% endif %}",
+        globals={},
+        expect="true",
+    ),
 ]

liquid/loaders.py

@@ -1,21 +1,29 @@
 """Built-in loaders."""
 from .builtin.loaders import BaseLoader
+from .builtin.loaders import CachingChoiceLoader
 from .builtin.loaders import CachingFileSystemLoader
 from .builtin.loaders import ChoiceLoader
 from .builtin.loaders import DictLoader
 from .builtin.loaders import FileExtensionLoader
 from .builtin.loaders import FileSystemLoader
+from .builtin.loaders import PackageLoader
 from .builtin.loaders import TemplateNamespace
 from .builtin.loaders import TemplateSource
 from .builtin.loaders import UpToDate
+from .builtin.loaders import make_choice_loader
+from .builtin.loaders import make_file_system_loader
 
 __all__ = (
     "BaseLoader",
+    "CachingChoiceLoader",
     "CachingFileSystemLoader",
     "ChoiceLoader",
     "DictLoader",
     "FileExtensionLoader",
     "FileSystemLoader",
+    "make_choice_loader",
+    "make_file_system_loader",
+    "PackageLoader",
     "TemplateNamespace",
     "TemplateSource",
     "UpToDate",

liquid/utils/cache.py

@@ -36,6 +36,8 @@ from collections import abc
 from collections import deque
 from threading import Lock
 
+from liquid.exceptions import CacheCapacityValueError
+
 
 class LRUCache(abc.MutableMapping):
     """A simple LRU Cache implementation."""
@@ -45,6 +47,9 @@ class LRUCache(abc.MutableMapping):
     # won't do any harm.
 
     def __init__(self, capacity: int):
+        if capacity < 1:
+            raise CacheCapacityValueError("cache size must be greater than 1")
+
         self.capacity = capacity
         self._mapping = {}
         self._queue = deque()

{python_liquid-1.10.2.dist-info → python_liquid-1.12.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-liquid
-Version: 1.10.2
+Version: 1.12.0
 Summary: A Python engine for the Liquid template language.
 Project-URL: Change Log, https://github.com/jg-rp/liquid/blob/main/CHANGES.md
 Project-URL: Documentation, https://jg-rp.github.io/liquid/
@@ -19,9 +19,11 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.7
+Requires-Dist: importlib-resources>=5.10.0
 Requires-Dist: python-dateutil>=2.8.1
 Requires-Dist: typing-extensions>=4.2.0
 Provides-Extra: autoescape
@@ -32,8 +34,8 @@ Description-Content-Type: text/markdown
 
 <p align="center">
 A Python engine for <a href="https://shopify.github.io/liquid/">Liquid</a>, the safe customer-facing template language for flexible web apps.
+<br>We follow <a href="https://github.com/Shopify/liquid">Shopify/Liquid</a> closely and test against the <a href="https://github.com/jg-rp/golden-liquid">Golden Liquid</a> test suite.
 </p>
-
 <p align="center">
   <a href="https://github.com/jg-rp/liquid/blob/main/LICENSE">
     <img src="https://img.shields.io/pypi/l/python-liquid.svg?style=flat-square" alt="License">
@@ -59,6 +61,10 @@ A Python engine for <a href="https://shopify.github.io/liquid/">Liquid</a>, the
   <a href="https://github.com/jg-rp/liquid/actions/workflows/coverage.yaml">
     <img src="https://img.shields.io/github/actions/workflow/status/jg-rp/liquid/coverage.yaml?branch=main&label=coverage&style=flat-square" alt="Coverage">
   </a>
+  <br>
+  <a href="https://pypi.org/project/python-liquid/">
+    <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/python-liquid?style=flat-square">
+  </a>
 </p>
 
 ---

{python_liquid-1.10.2.dist-info → python_liquid-1.12.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
-liquid/__init__.py,sha256=UaDLh_elcxm5c7mDFqlyuG1l06SMw7f0s-4MVDtdhY0,1907
+liquid/__init__.py,sha256=0nYsF01jFXyXrxYCLnglEp0H4H7fHG7_tyh91X4td5o,2173
 liquid/analyze_tags.py,sha256=PKMBk4lFWNwkfuMY9ulou6QeSq676IgQmC88JqfeO0k,7503
 liquid/ast.py,sha256=zawW4ryxo_0ExGKpMYUifbtD7F5SlmlMrDJvCVTfWCM,8313
 liquid/chain_map.py,sha256=nxkw3wwF6ddlGarIuL7Ii2elm4dU80LySgdQx1oift0,1517
 liquid/context.py,sha256=cHn0IYhtOM3xlujn1M0fY0KO9WMS8sMNj9AWjTxicZg,26261
 liquid/environment.py,sha256=9PhcexMoKW30pmFzfo8so7pZhweO_WCk6SRQp0w-jdo,30780
-liquid/exceptions.py,sha256=7Rd7FOj6CntEv1EtV8xKH2caQgBbETq9Bimok51lvqg,6559
-liquid/expression.py,sha256=MU2QtquzqRMzAUiLZtW1xpTPvbckr8eGlTFaMtte59k,34912
+liquid/exceptions.py,sha256=gbqQcwJmChp6FCGQdxTWo0mstQtAqmp3-MkUT-evlFI,6691
+liquid/expression.py,sha256=NwI8ZIbfqY8HejYZJiNTRCdu_KvEkPtDD9_PIepsmsk,35252
 liquid/filter.py,sha256=AOBC4cU4eLLiiUvLfb9L0zZvR38ln0BSKqlIy41AUd4,6315
 liquid/lex.py,sha256=pizKyPdIqRNT6TN5NolRhBI3oBpTyoYwJS_DCyyQhg8,15137
 liquid/limits.py,sha256=N3InvvDMg9lTVc6vUhKftV206Oz8D3Pmg_a_jZtgyro,1675
-liquid/loaders.py,sha256=xMBHI5PEgGkP-326BrTcjnKZKhq3KNldtmJyjAXzVpI,639
+liquid/loaders.py,sha256=aXh-hiDyYV6gaBEWRkUORawkhJ4hbBwXP8Sbv9c4j7c,937
 liquid/mode.py,sha256=nYm-oYRkcZk1j-pmYPXMBqfQMMfYYB13SHI2OWHHFr0,207
 liquid/output.py,sha256=QEL_dg4Opb63W0pv1P-4IpUX36uAtuJf9sKxZbVLGxk,773
 liquid/parse.py,sha256=50BT569pjW1sYAofiJ2SVzZgzKlma9lKPStF7EPfE1w,27131
@@ -33,11 +33,13 @@ liquid/builtin/filters/extra.py,sha256=7_8mUD6DlNLBti-TVCeqzI2NpCmua_OJrwYa5re6c
 liquid/builtin/filters/math.py,sha256=ZEzeX5Rw9gTTtIEnR951MXl_1Fv9j2ntfM9EDzmSYlU,3804
 liquid/builtin/filters/misc.py,sha256=z4DXSqidAqZ0F3W5Kr__mebAghDmzYzGr4BzE5-tsFY,3436
 liquid/builtin/filters/string.py,sha256=GJMl2nFcygAz73snVsud4lX0Gk0VhwGbhldeX558SSo,9964
-liquid/builtin/loaders/__init__.py,sha256=L9EcC-gJua6aO5Mbw9RXJmxJly7dAayLnMUX9_kHPhM,613
-liquid/builtin/loaders/base_loader.py,sha256=2549s2rP8IsLY25-L5AJklkSW_EEAno2Vm-CdCyi2Qk,9447
-liquid/builtin/loaders/caching_file_system_loader.py,sha256=50lCTRxaIdF7TocyCBdOp1VMPm1c3aH70gUNwQSj6X4,7261
-liquid/builtin/loaders/choice_loader.py,sha256=LJcC1xOZZdDAv4mkkh4FXWHvlxrepihJUrZTg5ZNfxU,1353
+liquid/builtin/loaders/__init__.py,sha256=9B7KAc-HoNd-pUNwJ-Syzr_8JsBD2S7feYwulUWtrtk,4309
+liquid/builtin/loaders/base_loader.py,sha256=ks_tfzx1t0Dg2gW0Ewr-jHn4KKd5oUWXdREh_n2zHEY,9509
+liquid/builtin/loaders/caching_file_system_loader.py,sha256=3_rGFWv2A3caYmGiaXqjJF-kqEFnU5oZj9R95y1Qc3w,2681
+liquid/builtin/loaders/choice_loader.py,sha256=89rXKA6LR66BqA5ZQEOM9JwRIjPdLUtb3_DyJel8C4I,4566
 liquid/builtin/loaders/file_system_loader.py,sha256=z6nSZih0fDn5aUCWaPlBMqKgAPaGj2NxyZOPHCfTVrg,4396
+liquid/builtin/loaders/mixins.py,sha256=lIlKcjhekb8aoSCuGjJR7mquNP9VjxKUaMu86ONcOSg,6668
+liquid/builtin/loaders/package_loader.py,sha256=xqkl1neXhEPlfjGUlcRzHi3OUpFH4Ht596WOKt04MSw,3234
 liquid/builtin/tags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 liquid/builtin/tags/assign_tag.py,sha256=0TujfsRE8N8hSjuVpmNQ0HQmmMUbFY89K_mnK2ogdfw,2554
 liquid/builtin/tags/capture_tag.py,sha256=m9Mo7bxarA-Xq_nsrc70aUZJXRVr3WBvoKmCXepy6wk,3136
@@ -122,7 +124,7 @@ liquid/golden/first_filter.py,sha256=BzyMgvUVZYqDp-qGIXDlncbocXmO4zpnz2gxKCejOfU
 liquid/golden/floor_filter.py,sha256=hL7aonQiADdMhvIYRi5NY90MV4GjTSPEVk3ju3xudGQ,1474
 liquid/golden/for_tag.py,sha256=FGUwzLQef_ibBwSszddA-DIMNAesSfyO6CC8TuqYbHE,20459
 liquid/golden/identifiers.py,sha256=XyGUFaMHdvW_q13JrloLaY8AwhSFGIpM78YHeqkeOUc,7364
-liquid/golden/if_tag.py,sha256=amdJsivN-EmXXnrfEazNXTuikWcepYAh-Db2e4KYVoc,6629
+liquid/golden/if_tag.py,sha256=YmdlIHVGRYZq0lbqFqZtnt8gieZfbr5jh9S-m6TiGkU,8177
 liquid/golden/ifchanged_tag.py,sha256=I048sTPf6p4XHy-RQs6rTVrFkZR1YW9juQxBw7l3i2g,1375
 liquid/golden/illegal.py,sha256=AyJIrNKf435NXT51KBqXlYTYP1t9WUia4e5Zg6iqY8Y,777
 liquid/golden/include_tag.py,sha256=ukzCYwIm9SFA4ZOU7QML2JYB_WB_sF1JnWpNii5aIhk,6842
@@ -174,11 +176,11 @@ liquid/golden/url_encode_filter.py,sha256=pT6u0Ib44AgIKeHUdNGgpRZNjZzFwRwkvhjY8w
 liquid/golden/where_filter.py,sha256=8myDb6AUCMU3qgBihU8-O-MehzeLEXUsXe7q9XGVckg,3858
 liquid/golden/whitespace_control.py,sha256=uAcIIuE1DFWRQhP3fQmI0S3LumMGlIfvWQMIqbxbWMw,7809
 liquid/utils/__init__.py,sha256=X8Dc_jIJKRCccurGqHGqin8IJswNUta-cV9XoRANmEQ,230
-liquid/utils/cache.py,sha256=VOYltMBLU0FKOEX71EPrG7ZSIBeRkIZL93pfI3R5kQE,6297
+liquid/utils/cache.py,sha256=9fgOrkocCSSQNHNjXmeh0EssK6ZfFmF6pB-0asogSLc,6457
 liquid/utils/cache.pyi,sha256=4Vgtz5vk9IDPnD43AOnby1kWEJJgGH3fsHgQ-B7qa4M,543
 liquid/utils/html.py,sha256=47ACnJLEMSRkDgqDLBujmT091pk0EjoapmlZxkzz3D8,1755
 liquid/utils/text.py,sha256=1SwDECNMaqnnZ05je_AZZgxqzZd6U-mvq5jNU3W1-Qk,841
-python_liquid-1.10.2.dist-info/METADATA,sha256=VNMKyq_n78_TVXvP838aP9VzU_zPPOyDWpT2nOVVu0Y,7478
-python_liquid-1.10.2.dist-info/WHEEL,sha256=rKV0FgtKSxe-Q3jTBlmgn27qdhTm0_K1YKwPwAPskZ0,87
-python_liquid-1.10.2.dist-info/licenses/LICENSE,sha256=yAFURzud5ERNHt1rZIPnTLJ92ep7q8y5yG9g5DUMR_E,1075
-python_liquid-1.10.2.dist-info/RECORD,,
+python_liquid-1.12.0.dist-info/METADATA,sha256=z32jYN1wGgKeuwpN8lzbgd1Ck3furve1KTkBD7FARPE,7925
+python_liquid-1.12.0.dist-info/WHEEL,sha256=TJPnKdtrSue7xZ_AVGkp9YXcvDrobsjBds1du3Nx6dc,87
+python_liquid-1.12.0.dist-info/licenses/LICENSE,sha256=yAFURzud5ERNHt1rZIPnTLJ92ep7q8y5yG9g5DUMR_E,1075
+python_liquid-1.12.0.dist-info/RECORD,,

{python_liquid-1.10.2.dist-info → python_liquid-1.12.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.20.0
+Generator: hatchling 1.21.1
 Root-Is-Purelib: true
 Tag: py3-none-any