dotprompt-handlebars 0.0.1.dev1__cp312-cp312-manylinux_2_33_aarch64.whl → 0.1.1__cp312-cp312-manylinux_2_33_aarch64.whl

{dotprompt_handlebars-0.0.1.dev1.dist-info → dotprompt_handlebars-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotprompt_handlebars
-Version: 0.0.1.dev1
+Version: 0.1.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10

dotprompt_handlebars-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+dotprompt_handlebars-0.1.1.dist-info/METADATA,sha256=xetUj3NI052dvFAy1UXVOA0dFWKFtDsj2Mdg28kiruA,1169
+dotprompt_handlebars-0.1.1.dist-info/WHEEL,sha256=AB65alw64Me6t53a6SXTkmn8HmlUtkGRrmAow8OqOnM,109
+dotprompt_handlebars-0.1.1.dist-info/licenses/LICENSE,sha256=bsvE5_qSn_2LH2G-haMvT_AoIeINhX6fvzZTlyq2xJY,11340
+handlebarrz/_native.pyi,sha256=dfLbPXf2DYH-lxurBEUWk6hChe96uVQ2Ss3kOT4kPDw,2386
+handlebarrz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+handlebarrz/__init__.py,sha256=_wK1CTsv3NmXcQ20Jl1wvn_z19QNsHbGurMuXZcAjTI,23127
+handlebarrz/_native.cpython-312-aarch64-linux-gnu.so,sha256=s8_z_yQOjYda4wyRFzFQ4m_DhsbL-qFIuxke9DgHymE,1535104
+dotprompt_handlebars-0.1.1.dist-info/RECORD,,

handlebarrz/__init__.py

@@ -67,11 +67,14 @@ result = handlebars.render('formatted', {'name': 'World'})  # "Hello WORLD!"
 ```
 """
 
+from __future__ import annotations
+
 import json
+import re
 import sys  # noqa
 from collections.abc import Callable
 from pathlib import Path
-from typing import Any
+from typing import Any, TypedDict
 
 import structlog
 
@@ -81,6 +84,7 @@ else:  # noqa
     from enum import StrEnum  # noqa
 
 from ._native import (
+    HandlebarrzHelperOptions,
     HandlebarrzTemplate,
     html_escape,
     no_escape,
@@ -89,8 +93,23 @@ from ._native import (
 logger = structlog.get_logger(__name__)
 
 
-HelperFn = Callable[[list[Any], dict[str, Any], dict[str, Any]], str]
-NativeHelperFn = Callable[[str, str, str], str]
+HelperFn = Callable[[list[Any], 'HelperOptions'], str]
+NativeHelperFn = Callable[[str, HandlebarrzHelperOptions], str]
+Context = dict[str, Any]
+
+
+class RuntimeOptions(TypedDict):
+    """Options for the runtime of a Handlebars template.
+
+    These options are used to configure the runtime behavior of a Handlebars
+    template. They can be passed to the compiled template function to customize
+    the rendering process.
+    """
+
+    data: dict[str, Any] | None
+
+
+CompiledRenderer = Callable[[Context, RuntimeOptions | None], str]
 
 
 class EscapeFunction(StrEnum):
@@ -159,6 +178,7 @@ class Template:
         self._template.set_escape_fn(escape_fn)
         self._template.set_strict_mode(strict_mode)
         self._template.set_dev_mode(dev_mode)
+        self._known_partials: set[str] = set()
 
     @property
     def strict_mode(self) -> bool:
@@ -226,7 +246,7 @@ class Template:
                 'function': escape_fn,
             })
         except ValueError as e:
-            logger.error({'event': 'escape_function_error', 'error': str(e)})
+            logger.exception({'event': 'escape_function_error', 'error': str(e)})
             raise
 
     def register_template(self, name: str, template_string: str) -> None:
@@ -247,7 +267,7 @@ class Template:
             self._template.register_template(name, template_string)
             logger.debug({'event': 'template_registered', 'name': name})
         except ValueError as e:
-            logger.error({
+            logger.exception({
                 'event': 'template_registration_error',
                 'name': name,
                 'error': str(e),
@@ -270,15 +290,27 @@ class Template:
         """
         try:
             self._template.register_partial(name, template_string)
+            self._known_partials.add(name)
             logger.debug({'event': 'partial_registered', 'name': name})
-        except ValueError as e:
-            logger.error({
+        except Exception as e:
+            logger.exception({
                 'event': 'partial_registration_error',
                 'name': name,
                 'error': str(e),
             })
             raise
 
+    def has_partial(self, name: str) -> bool:
+        """Check if a partial is registered.
+
+        Args:
+            name: The name of the partial to check.
+
+        Returns:
+            True if the partial is registered, False otherwise.
+        """
+        return name in self._known_partials
+
     def register_template_file(self, name: str, file_path: str | Path) -> None:
         """Register a template from a file.
 
@@ -303,7 +335,7 @@ class Template:
                 'path': file_path_str,
             })
         except (FileNotFoundError, ValueError) as e:
-            logger.error({
+            logger.exception({
                 'event': 'template_file_registration_error',
                 'name': name,
                 'path': file_path_str,
@@ -335,7 +367,7 @@ class Template:
                 'extension': extension,
             })
         except (FileNotFoundError, ValueError) as e:
-            logger.error({
+            logger.exception({
                 'event': 'templates_directory_registration_error',
                 'path': dir_path_str,
                 'extension': extension,
@@ -383,9 +415,9 @@ class Template:
         try:
             # TODO: Fix this type error.
             self._template.register_helper(name, create_helper(helper_fn))  # type: ignore[arg-type]
-            logger.debug({'event': 'helper_registered', 'name': name})
+            # logger.debug({'event': 'helper_registered', 'name': name})
         except Exception as e:
-            logger.error({
+            logger.exception({
                 'event': 'helper_registration_error',
                 'name': name,
                 'error': str(e),
@@ -414,7 +446,7 @@ class Template:
         self._template.unregister_template(name)
         logger.debug({'event': 'template_unregistered', 'name': name})
 
-    def render(self, name: str, data: dict[str, Any]) -> str:
+    def render(self, name: str, data: dict[str, Any], options: RuntimeOptions | None = None) -> str:
         """Render a template with the given data.
 
         Renders a previously registered template using the provided data
@@ -424,6 +456,7 @@ class Template:
         Args:
             name: The name of the template to render
             data: The data to render the template with
+            options: Additional options for the template.
 
         Returns:
             str: The rendered template string
@@ -432,19 +465,21 @@ class Template:
             ValueError: If the template does not exist or there is a rendering
                 error.
         """
+        # TODO: options is currently ignored; need to add support for it.
+
         try:
             result = self._template.render(name, json.dumps(data))
             logger.debug({'event': 'template_rendered', 'name': name})
             return result
         except ValueError as e:
-            logger.error({
+            logger.exception({
                 'event': 'template_rendering_error',
                 'name': name,
                 'error': str(e),
             })
             raise
 
-    def render_template(self, template_string: str, data: dict[str, Any]) -> str:
+    def render_template(self, template_string: str, data: dict[str, Any], options: RuntimeOptions | None = None) -> str:
         """Render a template string directly without registering it.
 
         Parses and renders the template string in one step. This is useful for
@@ -454,6 +489,7 @@ class Template:
         Args:
             template_string: The template string to render
             data: The data to render the template with
+            options: Additional options for the template.
 
         Returns:
             Rendered template string.
@@ -463,16 +499,79 @@ class Template:
                 rendering error.
         """
         try:
+            # Merging runtime data with the data dictionary.
+            runtime_data = (options.get('data') if options is not None else {}) or {}
+            for k, v in runtime_data.items():
+                data[k] = v
+
+            # TODO: get rid of this once the Rust library has a local variables
+            # support.
+
+            # Local variables support workaround:
+            # Context: Handlebars Rust implementation currently doesn't support
+            # local variables (e.g. {{@my_variable}}), so instead we are
+            # dynamically replacing those with global variables
+            # (e.g. {{my_variable}}) to make things work.
+            # This is of course not an ideal solution, and it comes with some
+            # overhead, but so far we weren't able to detect a use case where
+            # this could be a blocker (but time will tell).
+            matches = re.findall(r'{{@.*?}}', template_string)
+            for m in set(matches):
+                key = m.strip('{}@').split('.')[0]
+                if key in runtime_data:
+                    template_string = template_string.replace(m, m.replace('@', ''))
+
+            # Render the template.
             result = self._template.render_template(template_string, json.dumps(data))
             logger.debug({'event': 'template_string_rendered'})
             return result
         except ValueError as e:
-            logger.error({
+            logger.exception({
                 'event': 'template_string_rendering_error',
                 'error': str(e),
             })
             raise
 
+    def compile(self, template_string: str) -> CompiledRenderer:
+        """Compile a template string into a reusable function.
+
+        This method provides an interface similar to Handlebars.js's `compile`.
+        It takes a template string and returns a function that can be called
+        with different data contexts to render the template.
+
+        Note: Unlike the JS version which can bake options into the compiled
+        template, this implementation returns a function that uses the current
+        configuration (strict mode, escape function, registered helpers, etc.)
+        of the `Template` instance at the time the returned function is called.
+
+        Args:
+            template_string: The Handlebars template string to compile.
+
+        Returns:
+            A callable function that takes a data dictionary and some runtime
+            options and returns the rendered string.
+
+        Raises:
+            ValueError: If there is a syntax error during the initial parse
+            check performed by render_template (depending on Rust implementation
+            details).  Rendering errors will occur when the returned function is
+            called.
+        """
+
+        def compiled(context: Context, options: RuntimeOptions | None = None) -> str:
+            """Compiled template function.
+
+            Args:
+                context: The data to render the template with.
+                options: Additional options for the template.
+
+            Returns:
+                The rendered template string.
+            """
+            return self.render_template(template_string, context, options)
+
+        return compiled
+
     def register_extra_helpers(self) -> None:
         """Registers extra helper functions.
 
@@ -487,13 +586,45 @@ class Template:
             self._template.register_extra_helpers()
             logger.debug({'event': 'extra_helpers_registered'})
         except Exception as e:
-            logger.error({
+            logger.exception({
                 'event': 'extra_helpers_registration_error',
                 'error': str(e),
             })
             raise
 
 
+class HelperOptions:
+    """Handlebars helper options."""
+
+    def __init__(self, options: HandlebarrzHelperOptions) -> None:
+        self._options: HandlebarrzHelperOptions = options
+
+    def context(self) -> dict[str, Any]:
+        """Get a representation of a context."""
+        context_json = self._options.context_json()
+        return json.loads(context_json) or {}
+
+    def hash_value(self, key: str) -> Any:
+        """Get a hash value for the given key (resolved within the context).
+
+        Args:
+            key: The key corresponding for the hash required.
+
+        Returns:
+            The hash value.
+        """
+        hash_value_json = self._options.hash_value_json(key)
+        return json.loads(hash_value_json) if hash_value_json else ''
+
+    def fn(self) -> str:
+        """Renders a default inner template (if the helper is a block helper)."""
+        return self._options.template()
+
+    def inverse(self) -> str:
+        """Renders the template of the else branch (if any)."""
+        return self._options.inverse()
+
+
 def create_helper(
     fn: HelperFn,
 ) -> NativeHelperFn:
@@ -518,12 +649,9 @@ def create_helper(
         Function compatible with the Rust interface.
     """
 
-    def wrapper(params_json: str, hash_json: str, ctx_json: str) -> str:
+    def wrapper(params_json: str, options: HandlebarrzHelperOptions) -> str:
         params = json.loads(params_json)
-        hash = json.loads(hash_json)
-        ctx = json.loads(ctx_json)
-
-        result = fn(params, hash, ctx)
+        result = fn(params, HelperOptions(options))
         return result
 
     return wrapper

handlebarrz/_native.pyi

@@ -17,10 +17,20 @@
 """Stub type annotations for native Handlebars."""
 
 from collections.abc import Callable
+from typing import Any
 
 def html_escape(text: str) -> str: ...
 def no_escape(text: str) -> str: ...
 
+class HandlebarrzHelperOptions:
+    """Stub type annotations for native Handlebars helper options."""
+
+    def __init__(self) -> None: ...
+    def context_json(self) -> str: ...
+    def hash_value_json(self, key: str) -> str: ...
+    def template(self) -> str: ...
+    def inverse(self) -> str: ...
+
 class HandlebarrzTemplate:
     """Stub type annotations for native Handlebars."""
 

dotprompt_handlebars-0.0.1.dev1.dist-info/RECORD

@@ -1,8 +0,0 @@
-dotprompt_handlebars-0.0.1.dev1.dist-info/METADATA,sha256=9_xBpQnwIVm71CTHLHmtbtuCE--s2vPbFOXSwzTs6_E,1174
-dotprompt_handlebars-0.0.1.dev1.dist-info/WHEEL,sha256=AB65alw64Me6t53a6SXTkmn8HmlUtkGRrmAow8OqOnM,109
-dotprompt_handlebars-0.0.1.dev1.dist-info/licenses/LICENSE,sha256=bsvE5_qSn_2LH2G-haMvT_AoIeINhX6fvzZTlyq2xJY,11340
-handlebarrz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-handlebarrz/__init__.py,sha256=pxIV7rtRAfnOlv6q3oPiNT1Srs2KR3CYrWtVAksDCKw,18124
-handlebarrz/_native.pyi,sha256=GhUc2bN9WHgl4OKBRLMjvPi4mg7FzVrXBsMpgajsiVo,2063
-handlebarrz/_native.cpython-312-aarch64-linux-gnu.so,sha256=sk3nPZ0hKrfnJ4R1-cKoxDwjOOSrOjuURxTS45AVKH4,1523752
-dotprompt_handlebars-0.0.1.dev1.dist-info/RECORD,,