fix(py/handlebarrz): helpers support in handlebarrz (#291)

* feat: python: Fix helpers support in Handlebars

ISSUE: #284

CHANGELOG:
[x] implement a render context helper Python wrapper
[x] modify helpers to be aligned with the new HelperFn interface

* feat: python: Fix helpers support in Handlebars

ISSUE: #284

CHANGELOG:
[x] implement a render context helper Python wrapper
[x] modify helpers to be aligned with the new HelperFn interface

* feat: python: Fix helper interface across relevant tests

* Fix Rust lint warning

* Change HandlebarrzHelper visibility in the helper wrapper.

* Fix format warnings

* Fix ruff preview warnings

* Remove debug statements.

* Address PR review comments.

Author: r8zr

python/dotpromptz/src/dotpromptz/helpers.py

@@ -39,16 +39,15 @@
 import json
 from typing import Any
 
-from handlebarrz import Handlebars, HelperFn
+from handlebarrz import Handlebars, HelperFn, HelperOptions
 
 
-def json_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any]) -> str:
+def json_helper(params: list[Any], options: HelperOptions) -> str:
     """Convert a value to a JSON string.
 
     Args:
         params: List of values to convert to JSON
-        hash_args: Hash arguments including formatting options.
-        ctx: Current context options.
+        options: Handlebars helper options.
 
     Returns:
         JSON string representation of the value.
@@ -57,21 +56,22 @@ def json_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any
         return ''
 
     obj = params[0]
-    indent = hash_args.get('indent', 0)
-
+    indent = options.hash_value('indent') or 0
     try:
         if isinstance(indent, str):
             indent = int(indent)
     except (ValueError, TypeError):
         indent = 0
 
     try:
+        if indent == 0:
+            return json.dumps(obj, separators=(',', ':'))
         return json.dumps(obj, indent=indent)
     except (TypeError, ValueError):
         return '{}'
 
 
-def role_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any]) -> str:
+def role_helper(params: list[Any], options: HelperOptions) -> str:
     """Create a dotprompt role marker.
 
     Example:
@@ -81,8 +81,7 @@ def role_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any
 
     Args:
         params: List of values.
-        hash_args: Hash arguments.
-        ctx: Current context options.
+        options: Handlebars helper options.
 
     Returns:
         Role marker of the form `<<<dotprompt:role:...>>>`.
@@ -94,7 +93,7 @@ def role_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any
     return f'<<<dotprompt:role:{role_name}>>>'
 
 
-def history_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any]) -> str:
+def history_helper(params: list[Any], options: HelperOptions) -> str:
     """Create a dotprompt history marker.
 
     Example:
@@ -104,16 +103,15 @@ def history_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str,
 
     Args:
         params: List of values.
-        hash_args: Hash arguments including formatting options.
-        ctx: Current context options.
+        options: Handlebars helper options.
 
     Returns:
         History marker of the form `<<<dotprompt:history>>>`.
     """
     return '<<<dotprompt:history>>>'
 
 
-def section_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any]) -> str:
+def section_helper(params: list[Any], options: HelperOptions) -> str:
     """Create a dotprompt section marker.
 
     Example:
@@ -123,8 +121,7 @@ def section_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str,
 
     Args:
         params: List of values.
-        hash_args: Hash arguments including formatting options.
-        ctx: Current context options.
+        options: Handlebars helper options.
 
     Returns:
         Section marker of the form `<<<dotprompt:section ...>>>`.
@@ -136,7 +133,7 @@ def section_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str,
     return f'<<<dotprompt:section {section_name}>>>'
 
 
-def media_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any]) -> str:
+def media_helper(params: list[Any], options: HelperOptions) -> str:
     """Create a dotprompt media marker.
 
     Example:
@@ -146,24 +143,23 @@ def media_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, An
 
     Args:
         params: List of values.
-        hash_args: Hash arguments including formatting options.
-        ctx: Current context options.
+        options: Handlebars helper options.
 
     Returns:
         Media marker of the form `<<<dotprompt:media:url ...>>>`).
     """
-    url = hash_args.get('url', '')
+    url = options.hash_value('url')
     if not url:
         return ''
 
-    content_type = hash_args.get('contentType', '')
+    content_type = options.hash_value('contentType')
     if content_type:
         return f'<<<dotprompt:media:url {url} {content_type}>>>'
     else:
         return f'<<<dotprompt:media:url {url}>>>'
 
 
-def if_equals_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any]) -> str:
+def if_equals_helper(params: list[Any], options: HelperOptions) -> str:
     """Compares two values and returns appropriate content.
 
     Example:
@@ -176,8 +172,7 @@ def if_equals_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str
         ```
     Args:
         params: List containing the two values to compare.
-        hash_args: Hash arguments.
-        ctx: Current context options.
+        options: Handlebars helper options.
 
     Returns:
         Rendered content based on equality check.
@@ -186,17 +181,10 @@ def if_equals_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str
         return ''
 
     a, b = params[0], params[1]
-    fn = ctx.get('fn')
-    if a == b and fn is not None:
-        return str(fn(ctx))
-    else:
-        inverse = ctx.get('inverse')
-        if inverse is not None:
-            return str(inverse(ctx))
-    return ''
+    return options.fn() if a == b else options.inverse()
 
 
-def unless_equals_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any]) -> str:
+def unless_equals_helper(params: list[Any], options: HelperOptions) -> str:
     """Compares two values and returns appropriate content.
 
     Example:
@@ -209,8 +197,7 @@ def unless_equals_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict
         ```
     Args:
         params: List containing the two values to compare.
-        hash_args: Hash arguments.
-        ctx: Current context options.
+        options: Handlebars helper options.
 
     Returns:
         Rendered content based on inequality check.
@@ -219,14 +206,7 @@ def unless_equals_helper(params: list[Any], hash_args: dict[str, Any], ctx: dict
         return ''
 
     a, b = params[0], params[1]
-    fn = ctx.get('fn')
-    if a != b and fn is not None:
-        return str(fn(ctx))
-    else:
-        inverse = ctx.get('inverse')
-        if inverse is not None:
-            return str(inverse(ctx))
-    return ''
+    return options.fn() if a != b else options.inverse()
 
 
 BUILTIN_HELPERS: dict[str, HelperFn] = {

python/dotpromptz/tests/dotpromptz/dotprompt_test.py

@@ -40,7 +40,7 @@
 
 from dotpromptz.dotprompt import Dotprompt, _identify_partials
 from dotpromptz.typing import ModelConfigT, ParsedPrompt, PromptMetadata, ToolDefinition
-from handlebarrz import HelperFn
+from handlebarrz import HelperFn, HelperOptions
 
 
 @pytest.fixture
@@ -79,7 +79,8 @@ def test_init_default(mock_handlebars: Mock) -> None:
 def test_init_with_options(mock_handlebars: Mock) -> None:
     """Test initializing Dotprompt with custom options."""
 
-    def helper_fn(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any]) -> str:
+    def helper_fn(params: list[Any], options: HelperOptions) -> str:
+        """Test helper."""
         return 'test_helper'
 
     helpers: dict[str, HelperFn] = {'helper1': helper_fn}
@@ -98,7 +99,8 @@ def test_define_helper(mock_handlebars: Mock) -> None:
     """Test defining a helper function."""
 
     # This should match the signature of HelperFn.
-    def helper_fn(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any]) -> str:
+    def helper_fn(params: list[Any], options: HelperOptions) -> str:
+        """Test helper."""
         return 'test_helper'
 
     dotprompt = Dotprompt()
@@ -168,7 +170,8 @@ def test_chainable_interface(mock_handlebars: Mock) -> None:
         inputSchema={'type': 'object'},
     )
 
-    def helper_fn(params: list[Any], hash_args: dict[str, Any], ctx: dict[str, Any]) -> str:
+    def helper_fn(params: list[Any], options: HelperOptions) -> str:
+        """Test helper."""
         return 'helper1'
 
     result = dotprompt.define_helper('helper1', helper_fn).define_partial('partial1', 'content').define_tool(tool_def)