dotprompt-handlebars 0.0.1.dev1__cp313-cp313-manylinux_2_25_x86_64.whl

dotprompt_handlebars-0.0.1.dev1.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: dotprompt_handlebars
+Version: 0.0.1.dev1
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Text Processing :: Markup
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Dist: strenum>=0.4.15 ; python_full_version < '3.11'
+Requires-Dist: structlog>=25.2.0
+License-File: LICENSE
+Summary: Handlebars library for Python based on handlebars-rust.
+Home-Page: https://github.com/google/dotprompt
+Author: Yesudeep Mangalapilly <yesudeep@google.com>
+Author-email: Yesudeep Mangalapilly <yesudeep@google.com>
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Source Code, https://github.com/google/dotprompt
+
+# dotprompt-handlebars
+
+**DISCLAIMER**: Project only intended to be used for dotprompt package. Support for other use cases is not guaranteed. 

dotprompt_handlebars-0.0.1.dev1.dist-info/RECORD

@@ -0,0 +1,8 @@
+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=zc3cj5SMxZ9dVRYJI3Qn_Bc5sXQD3Y87gAyGPgxCgQM,108
+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-313-x86_64-linux-gnu.so,sha256=va6pr0fcmkEQSICgRrRehPgH7hlHcpcJwGtNZbPXC3g,1499744
+dotprompt_handlebars-0.0.1.dev1.dist-info/RECORD,,

dotprompt_handlebars-0.0.1.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.8.3)
+Root-Is-Purelib: false
+Tag: cp313-cp313-manylinux_2_25_x86_64

dotprompt_handlebars-0.0.1.dev1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Google LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

handlebarrz/__init__.py

@@ -0,0 +1,544 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Python wrapper for the Handlebars templating language using handlebars-rust.
+
+It supports most Handlebars functionality including template registration,
+rendering, partials, block helpers, custom helpers, subexpressions, inline
+partials, and various configuration options.
+
+## Features:
+
+- Block helpers with inverse sections (`else` blocks)
+- Built-in helpers (`each`, `if`, `unless`, `with`, `lookup`, `log`)
+- Context navigation (`this`, `../parent`, `@root`)
+- Custom helper functions
+- Development mode for automatic template reloading
+- HTML escaping options and customization
+- Partial templates and blocks
+- Strict mode for missing fields
+- Subexpressions and parameter literals
+- Template registration (strings, files, directories)
+- Whitespace control with `~` operator
+
+## Example
+
+```python
+# Using the Template class.
+from handlebarrz import Template
+
+template = Template()
+template.register_template('hello', 'Hello {{name}}!')
+result = template.render('hello', {'name': 'World'})
+# result = "Hello World!"
+
+# Using the Handlebars alias.
+from handlebarrz import Handlebars
+
+handlebars = Handlebars()
+handlebars.register_template('greeting', 'Hello {{name}}!')
+result = handlebars.render('greeting', {'name': 'World'})  # "Hello World!"
+
+
+# Using custom helpers.
+def format_name(params, hash, ctx):
+    name = params[0]
+    return name.upper() if hash.get('uppercase') else name
+
+
+handlebars.register_helper('format', format_name)
+handlebars.register_template(
+    'formatted', 'Hello {{format name uppercase=true}}!'
+)
+result = handlebars.render('formatted', {'name': 'World'})  # "Hello WORLD!"
+```
+"""
+
+import json
+import sys  # noqa
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+if sys.version_info < (3, 11):  # noqa
+    from strenum import StrEnum  # noqa
+else:  # noqa
+    from enum import StrEnum  # noqa
+
+from ._native import (
+    HandlebarrzTemplate,
+    html_escape,
+    no_escape,
+)
+
+logger = structlog.get_logger(__name__)
+
+
+HelperFn = Callable[[list[Any], dict[str, Any], dict[str, Any]], str]
+NativeHelperFn = Callable[[str, str, str], str]
+
+
+class EscapeFunction(StrEnum):
+    """Enumeration of built-in escape functions for Handlebars templates.
+
+    These constants define how content is escaped when rendered in templates.
+    By default, Handlebars escapes HTML entities in variables to prevent XSS
+    attacks, but this behavior can be customized:
+
+    | Character | HTML Entity |
+    |-----------|-------------|
+    | `&`       | `&amp;`     |
+    | `<`       | `&lt;`      |
+    | `>`       | `&gt;`      |
+    | `"`       | `&quot;`    |
+    | `'`       | `&#x27;`    |
+
+    Attributes:
+        HTML_ESCAPE: Escapes HTML entities (default)
+        NO_ESCAPE: Passes content through without any escaping
+    """
+
+    HTML_ESCAPE = 'html_escape'
+    NO_ESCAPE = 'no_escape'
+
+
+class Template:
+    """A Handlebars template engine that can register and render templates.
+
+    This class wraps the Rust implementation of Handlebars and provides a
+    Pythonic interface for template registration, rendering, and configuration.
+    The following language features are supported:
+
+    * Block Expressions: `{{#block}}...{{/block}}`
+    * Block Helpers: `{{#helper}}...{{else}}...{{/helper}}`
+    * Comments: `{{! comment }}`
+    * Expressions: `{{var}}`, `{{{var}}}`, `{{&var}}`
+    * Helpers: `{{helper param1 param2 key=value}}`
+    * Literals: `{{helper "string" 123 true null undefined}}`
+    * Partials: `{{> partial}}`
+    * Path Navigation: `{{../parent}}`, `{{this}}`, `{{@root}}`
+    * Subexpressions: `{{helper (subhelper param) param2}}`
+    * Whitespace Control: `{{~helper}}` or `{{helper~}}`
+
+    Attributes:
+        strict_mode: Whether to raise errors for missing fields in templates.
+        dev_mode: Whether to enable development mode features for
+            auto-reloading.
+    """
+
+    def __init__(
+        self,
+        escape_fn: EscapeFunction = EscapeFunction.HTML_ESCAPE,
+        strict_mode: bool = False,
+        dev_mode: bool = False,
+    ) -> None:
+        """Create a new Handlebars template engine.
+
+        Args:
+            escape_fn: The escape function to use for HTML escaping.
+            strict_mode: Whether to raise errors for missing fields in templates.
+            dev_mode: Whether to enable development mode features for
+                auto-reloading.
+        """
+        self._template: HandlebarrzTemplate = HandlebarrzTemplate()
+        self._template.set_escape_fn(escape_fn)
+        self._template.set_strict_mode(strict_mode)
+        self._template.set_dev_mode(dev_mode)
+
+    @property
+    def strict_mode(self) -> bool:
+        """Whether the strict mode setting is enabled.
+
+        Returns:
+            Whether the strict mode setting is enabled.
+        """
+        return self._template.get_strict_mode()
+
+    @strict_mode.setter
+    def strict_mode(self, enabled: bool) -> None:
+        """Set strict mode.
+
+        This turns typos, missing field access, and undefined variables into
+        errors.
+
+        Args:
+            enabled: Whether strict mode should be enable.
+        """
+        self._template.set_strict_mode(enabled)
+        logger.debug({'event': 'strict_mode_changed', 'enabled': enabled})
+
+    @property
+    def dev_mode(self) -> bool:
+        """Whether dev mode has been enabled.
+
+        Returns:
+            Whether dev mode has been enabled.
+        """
+        return self._template.get_dev_mode()
+
+    @dev_mode.setter
+    def dev_mode(self, enabled: bool) -> None:
+        """Set development mode for this template engine.
+
+        In dev mode, templates are automatically reloaded from file when
+        modified. This is useful during development to see changes without
+        restarting the application.
+
+        Args:
+            enabled: Whether to enable development mode
+        """
+        self._template.set_dev_mode(enabled)
+        logger.debug({'event': 'dev_mode_changed', 'enabled': enabled})
+
+    def set_escape_function(self, escape_fn: EscapeFunction) -> None:
+        """Set the escape function used for HTML escaping.
+
+        Controls how variable values are escaped when rendered with the
+        `{{var}}` syntax (triple stache `{{{var}}}` and ampersand `{{&var}}`
+        will still be rendered unescaped).
+
+        Args:
+            escape_fn: The escape function to use, one of the values from
+                EscapeFunction
+
+        Raises:
+            ValueError: If the escape function is not recognized
+        """
+        try:
+            self._template.set_escape_fn(escape_fn)
+            logger.debug({
+                'event': 'escape_function_changed',
+                'function': escape_fn,
+            })
+        except ValueError as e:
+            logger.error({'event': 'escape_function_error', 'error': str(e)})
+            raise
+
+    def register_template(self, name: str, template_string: str) -> None:
+        """Register a template with the given name.
+
+        Templates are parsed and validated at registration time, which allows
+        for early detection of syntax errors. Registered templates can be
+        rendered multiple times with different contexts without reparsing.
+
+        Args:
+            name: The name to register the template under
+            template_string: The template string to register
+
+        Raises:
+            ValueError: If there is a syntax error in the template
+        """
+        try:
+            self._template.register_template(name, template_string)
+            logger.debug({'event': 'template_registered', 'name': name})
+        except ValueError as e:
+            logger.error({
+                'event': 'template_registration_error',
+                'name': name,
+                'error': str(e),
+            })
+            raise
+
+    def register_partial(self, name: str, template_string: str) -> None:
+        """Register a partial with the given name.
+
+        Partials are templates that can be included in other templates using the
+        `{{> partial_name}}` syntax. They can receive the current context or a
+        custom context.
+
+        Args:
+            name: The name to register the partial under
+            template_string: The partial template string
+
+        Raises:
+            ValueError: If there is a syntax error in the template
+        """
+        try:
+            self._template.register_partial(name, template_string)
+            logger.debug({'event': 'partial_registered', 'name': name})
+        except ValueError as e:
+            logger.error({
+                'event': 'partial_registration_error',
+                'name': name,
+                'error': str(e),
+            })
+            raise
+
+    def register_template_file(self, name: str, file_path: str | Path) -> None:
+        """Register a template from a file.
+
+        Reads the template from the specified file and registers it under the
+        given name. In development mode, the template will be automatically
+        reloaded when the file changes.
+
+        Args:
+            name: The name to register the template under
+            file_path: Path to the template file
+
+        Raises:
+            FileNotFoundError: If the template file does not exist
+            ValueError: If there is a syntax error in the template
+        """
+        file_path_str = str(file_path)
+        try:
+            self._template.register_template_file(name, file_path_str)
+            logger.debug({
+                'event': 'template_file_registered',
+                'name': name,
+                'path': file_path_str,
+            })
+        except (FileNotFoundError, ValueError) as e:
+            logger.error({
+                'event': 'template_file_registration_error',
+                'name': name,
+                'path': file_path_str,
+                'error': str(e),
+            })
+            raise
+
+    def register_templates_directory(self, dir_path: str | Path, extension: str = '.hbs') -> None:
+        """Register all templates in a directory.
+
+        Recursively finds all files with the specified extension in the
+        directory and registers them as templates. The template name will be the
+        file path relative to the directory, without the extension.
+
+        Args:
+            dir_path: Path to the directory containing templates
+            extension: File extension for templates, defaults to ".hbs"
+
+        Raises:
+            FileNotFoundError: If the directory does not exist
+            ValueError: If there is a syntax error in any template
+        """
+        dir_path_str = str(dir_path)
+        try:
+            self._template.register_templates_directory(dir_path_str, extension)
+            logger.debug({
+                'event': 'templates_directory_registered',
+                'path': dir_path_str,
+                'extension': extension,
+            })
+        except (FileNotFoundError, ValueError) as e:
+            logger.error({
+                'event': 'templates_directory_registration_error',
+                'path': dir_path_str,
+                'extension': extension,
+                'error': str(e),
+            })
+            raise
+
+    def register_helper(
+        self,
+        name: str,
+        helper_fn: HelperFn,
+    ) -> None:
+        """Register a helper function.
+
+        Helpers extend the templating engine with custom functionality. They can
+        be called from templates using the `{{helper_name arg1 arg2 key=value}}`
+        syntax.
+
+        The helper function should take three parameters:
+        - params: List of positional parameters passed to the helper
+        - hash: Dictionary of named parameters (hash) passed to the helper
+        - context: Dictionary containing the current context
+
+        It should return a string that will be inserted into the template.
+
+        Examples:
+            ```python
+            # A helper that formats a date
+            def format_date(params, hash, ctx):
+                date_obj = params[0]
+                format_str = hash.get('format', '%Y-%m-%d')
+                return date_obj.strftime(format_str)
+
+
+            template.register_helper('formatDate', format_date)
+
+            # Usage in template:
+            # {{formatDate date format="%-d %B %Y"}}
+            ```
+
+        Args:
+            name: The name to register the helper under
+            helper_fn: The helper function
+        """
+        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})
+        except Exception as e:
+            logger.error({
+                'event': 'helper_registration_error',
+                'name': name,
+                'error': str(e),
+            })
+            raise
+
+    def has_template(self, name: str) -> bool:
+        """Determines whether the template with teh given name exists.
+
+        Args:
+            name: Name of the template.
+
+        Returns:
+            Whether the template exists.
+        """
+        return self._template.has_template(name)
+
+    def unregister_template(self, name: str) -> None:
+        """Unregister a template with the given name.
+
+        Removes the template from the registry if it exists.
+
+        Args:
+            name: The name of the template to unregister.
+        """
+        self._template.unregister_template(name)
+        logger.debug({'event': 'template_unregistered', 'name': name})
+
+    def render(self, name: str, data: dict[str, Any]) -> str:
+        """Render a template with the given data.
+
+        Renders a previously registered template using the provided data
+        context. The data is converted to JSON before being passed to the
+        template engine.
+
+        Args:
+            name: The name of the template to render
+            data: The data to render the template with
+
+        Returns:
+            str: The rendered template string
+
+        Raises:
+            ValueError: If the template does not exist or there is a rendering
+                error.
+        """
+        try:
+            result = self._template.render(name, json.dumps(data))
+            logger.debug({'event': 'template_rendered', 'name': name})
+            return result
+        except ValueError as e:
+            logger.error({
+                'event': 'template_rendering_error',
+                'name': name,
+                'error': str(e),
+            })
+            raise
+
+    def render_template(self, template_string: str, data: dict[str, Any]) -> str:
+        """Render a template string directly without registering it.
+
+        Parses and renders the template string in one step. This is useful for
+        one-off template rendering, but for templates that will be rendered
+        multiple times, it's more efficient to register them first.
+
+        Args:
+            template_string: The template string to render
+            data: The data to render the template with
+
+        Returns:
+            Rendered template string.
+
+        Raises:
+            ValueError: If there is a syntax error in the template or a
+                rendering error.
+        """
+        try:
+            result = self._template.render_template(template_string, json.dumps(data))
+            logger.debug({'event': 'template_string_rendered'})
+            return result
+        except ValueError as e:
+            logger.error({
+                'event': 'template_string_rendering_error',
+                'error': str(e),
+            })
+            raise
+
+    def register_extra_helpers(self) -> None:
+        """Registers extra helper functions.
+
+        - `ifEquals`
+        - `unlessEquals`
+        - `json`
+
+        These helpers are not registered by default and must be registered
+        explicitly if needed.
+        """
+        try:
+            self._template.register_extra_helpers()
+            logger.debug({'event': 'extra_helpers_registered'})
+        except Exception as e:
+            logger.error({
+                'event': 'extra_helpers_registration_error',
+                'error': str(e),
+            })
+            raise
+
+
+def create_helper(
+    fn: HelperFn,
+) -> NativeHelperFn:
+    """Create a helper function compatible with the Rust interface.
+
+    This function adapts a Python function with typed parameters to the format
+    expected by the Rust bindings. It handles the serialization and
+    deserialization of JSON data between Rust and Python.
+
+    Helper functions in Handlebars can be used for various purposes:
+
+    - Conditional rendering with custom logic.
+    - Formatting data (dates, numbers, strings).
+    - Generating HTML or other output formats.
+    - Implementing custom block helpers.
+    - Transforming data (sorting, filtering, mapping).
+
+    Args:
+        fn: A function taking of type HelperFn (params, hash, context).
+
+    Returns:
+        Function compatible with the Rust interface.
+    """
+
+    def wrapper(params_json: str, hash_json: str, ctx_json: str) -> str:
+        params = json.loads(params_json)
+        hash = json.loads(hash_json)
+        ctx = json.loads(ctx_json)
+
+        result = fn(params, hash, ctx)
+        return result
+
+    return wrapper
+
+
+# Alias Template as Handlebars.  This is done because the JS implementation
+# calls its template class `Handlebars` so mostly for familiarity.
+Handlebars = Template
+
+
+__all__ = [
+    'EscapeFunction',
+    'Handlebars',
+    'Template',
+    'create_helper',
+    'html_escape',
+    'no_escape',
+]

handlebarrz/_native.pyi

@@ -0,0 +1,58 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Stub type annotations for native Handlebars."""
+
+from collections.abc import Callable
+
+def html_escape(text: str) -> str: ...
+def no_escape(text: str) -> str: ...
+
+class HandlebarrzTemplate:
+    """Stub type annotations for native Handlebars."""
+
+    def __init__(self) -> None: ...
+
+    # Strict mode.
+    def get_strict_mode(self) -> bool: ...
+    def set_strict_mode(self, enabled: bool) -> None: ...
+
+    # Dev mode.
+    def get_dev_mode(self) -> bool: ...
+    def set_dev_mode(self, enabled: bool) -> None: ...
+
+    # Escape function.
+    def set_escape_fn(self, escape_fn: str) -> None: ...
+
+    # Template registration.
+    def register_template(self, name: str, template_string: str) -> None: ...
+    def register_partial(self, name: str, template_string: str) -> None: ...
+    def register_template_file(self, name: str, file_path_str: str) -> None: ...
+    def register_templates_directory(self, dir_path_str: str, extension: str) -> None: ...
+
+    # Helper registration.
+    def register_helper(self, name: str, helper_fn: Callable[[str], str]) -> None: ...
+
+    # Template management.
+    def has_template(self, name: str) -> bool: ...
+    def unregister_template(self, name: str) -> None: ...
+
+    # Rendering.
+    def render(self, name: str, data_json: str) -> str: ...
+    def render_template(self, template_str: str, data_json: str) -> str: ...
+
+    # Extra helper registration.
+    def register_extra_helpers(self) -> None: ...