feat(inner content): allow passing content as a function, as a custom parser (#13)

* feat(inner content): allow passing content as a function, as a custom parser

* fix(render): add raw content helper function

* bump version to 0.4.0

* docs: about the new raw content feature

Author: DavidVujic

README.md

@@ -106,6 +106,21 @@ The HTML equivalent is:
 <script async src="js/script.js"></script>
 ```
 
+### Adding unescaped content
+This is useful when rendering HTML entities like `&copy;`.
+
+``` python
+from python_hiccup.html import raw
+
+data = ["div", raw("&copy; this should <strong>not</strong> be escaped!")]
+```
+
+The HTML output:
+
+``` html
+<div>&copy; this should <strong>not</strong> be escaped!</div>
+```
+
 ## Resources
 - [PyScript and python-hiccup example](https://pyscript.com/@davidvujic/pyscript-jokes-with-a-hiccup/latest?files=main.py) - PyScript Jokes with a Hiccup
 - [Hiccup](https://github.com/weavejester/hiccup) - the original implementation, for Clojure.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-hiccup"
-version = "0.3.4"
+version = "0.4.0"
 description = "Python Hiccup is a library for representing HTML using plain Python data structures"
 authors = [{name = "David Vujic"}]
 readme = "README.md"

src/python_hiccup/html/__init__.py

@@ -1,5 +1,5 @@
 """Render data into HTML."""
 
-from python_hiccup.html.core import render
+from python_hiccup.html.core import raw, render
 
-__all__ = ["render"]
+__all__ = ["raw", "render"]

src/python_hiccup/html/core.py

@@ -2,7 +2,7 @@
 
 import html
 import operator
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from functools import reduce
 
 from python_hiccup.transform import CONTENT_TAG, transform
@@ -60,12 +60,16 @@ def _is_content(element: str) -> bool:
     return element == CONTENT_TAG
 
 
+def _is_raw(content: str | Callable) -> bool:
+    return callable(content) and content.__name__ == "raw_content"
+
+
 def _to_html(tag: Mapping, parent: str = "") -> list:
     element = next(iter(tag.keys()))
     child = next(iter(tag.values()))
 
     if _is_content(element):
-        return [_escape(str(child), parent)]
+        return child() if _is_raw(child) else [_escape(str(child), parent)]
 
     attributes = reduce(_to_attributes, tag.get("attributes", []), "")
     bool_attributes = reduce(_to_bool_attributes, tag.get("boolean_attributes", []), "")
@@ -96,3 +100,12 @@ def render(data: Sequence) -> str:
     transformed_html: list = reduce(operator.iadd, matrix, [])
 
     return "".join(transformed_html)
+
+
+def raw(content: str | float) -> Callable:
+    """Content that should not be escaped when rendering HTML elements."""
+
+    def raw_content() -> str | float:
+        return content
+
+    return raw_content

src/python_hiccup/transform/core.py

@@ -1,11 +1,11 @@
 """Transform a sequence of tag data into groups."""
 
 from collections import defaultdict
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from collections.abc import Set as AbstractSet
 from functools import reduce
 
-Item = str | AbstractSet | Mapping | Sequence
+Item = str | AbstractSet | Mapping | Sequence | Callable
 
 ATTRIBUTES = "attributes"
 BOOLEAN_ATTRIBUTES = "boolean_attributes"

test/test_render_html.py

@@ -1,6 +1,6 @@
 """Unit tests for the python_hiccup.html.render function."""
 
-from python_hiccup.html import render
+from python_hiccup.html import raw, render
 
 
 def test_returns_a_string() -> None:
@@ -142,3 +142,11 @@ def test_order_of_items() -> None:
     data = ["h1", "some ", ["span.pys", "<py>"]]
 
     assert render(data) == '<h1>some <span class="pys">&lt;py&gt;</span></h1>'
+
+
+def test_content_as_function() -> None:
+    """Allow defining content as a callable function, as a custom parser."""
+    content = "&copy; this <strong>should</strong> not be escaped!"
+
+    assert render(["div", raw("&copy;")]) == "<div>&copy;</div>"
+    assert render(["div", raw(content)]) == f"<div>{content}</div>"