python-liquid 1.10.2__tar.gz → 1.12.0__tar.gz

{python_liquid-1.10.2 → python_liquid-1.12.0}/PKG-INFO

@@ -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 → python_liquid-1.12.0}/README.md

@@ -2,8 +2,8 @@
 
 <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">
@@ -29,6 +29,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 → python_liquid-1.12.0}/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",

python_liquid-1.12.0/liquid/builtin/loaders/__init__.py

@@ -0,0 +1,133 @@
+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
+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)

{python_liquid-1.10.2 → python_liquid-1.12.0}/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

python_liquid-1.12.0/liquid/builtin/loaders/caching_file_system_loader.py

@@ -0,0 +1,75 @@
+"""A file system loader that caches parsed templates in memory."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from typing import Iterable
+from typing import Union
+
+from .file_system_loader import FileExtensionLoader
+from .mixins import CachingLoaderMixin
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from liquid import Context
+
+    from .base_loader import TemplateSource
+
+# ruff: noqa: D102
+
+
+class CachingFileSystemLoader(CachingLoaderMixin, FileExtensionLoader):
+    """A file system loader that caches parsed templates in memory.
+
+    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.
+    """
+
+    def __init__(
+        self,
+        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,
+    ):
+        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,
+        )
+
+    def get_source_with_context(
+        self, context: Context, template_name: str, **kwargs: str
+    ) -> TemplateSource:
+        # In this case, our cache key and real file name are the same.
+        name = self.cache_key_with_context(template_name, context, **kwargs)
+        return self.get_source(context.env, name)
+
+    async def get_source_with_context_async(
+        self, context: Context, template_name: str, **kwargs: str
+    ) -> TemplateSource:
+        # In this case, our cache key and real file name are the same.
+        name = self.cache_key_with_context(template_name, context, **kwargs)
+        return await self.get_source_async(context.env, name)

python_liquid-1.12.0/liquid/builtin/loaders/choice_loader.py

@@ -0,0 +1,143 @@
+"""A template loader that delegates to other template loaders."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from typing import List
+
+from liquid.exceptions import TemplateNotFound
+
+from .base_loader import BaseLoader
+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.
+
+    Args:
+        loaders: A list of loaders implementing `liquid.loaders.BaseLoader`.
+    """
+
+    def __init__(self, loaders: List[BaseLoader]):
+        super().__init__()
+        self.loaders = loaders
+
+    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)
+            except TemplateNotFound:
+                pass
+
+        raise TemplateNotFound(template_name)
+
+    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)
+            except TemplateNotFound:
+                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)