Add feature

Author: davepeck

README.md

@@ -228,7 +228,14 @@ page = html(t"<div>My widget: {SafeWidget()}</div>")
 # <div>My widget: <button>Custom Widget</button></div>
 ```
 
-TODO: support explicitly marking content as `unsafe` with a format specifier, too.
+You can also explicitly mark a string as "unsafe" using the `:unsafe` format specifier. This forces the string to be escaped, even if it would normally be treated as safe:
+
+```python
+from html_tstring import html, Markup
+trusted_html = Markup("<strong>This is safe HTML</strong>")
+page = html(t"<div>{trusted_html:unsafe}</div>")
+# <div>&lt;strong&gt;This is safe HTML&lt;/strong&gt;</div>
+```
 
 ### Template Composition
 

html_tstring/processor.py

@@ -12,6 +12,12 @@
 from .parser import parse_html
 from .utils import format_interpolation as base_format_interpolation
 
+
+@t.runtime_checkable
+class HasHTMLDunder(t.Protocol):
+    def __html__(self) -> str: ...
+
+
 # --------------------------------------------------------------------------
 # Value formatting
 # --------------------------------------------------------------------------
@@ -292,6 +298,8 @@ def _node_from_value(value: object) -> Node:
         case Iterable():
             children = [_node_from_value(v) for v in value]
             return Fragment(children=children)
+        case HasHTMLDunder():
+            return Text(Markup(value.__html__()))
         case _:
             return Text(str(value))
 
@@ -319,6 +327,8 @@ def _invoke_component(
             return html(result)
         case str():
             return Text(result)
+        case HasHTMLDunder():
+            return Text(Markup(result.__html__()))
         case _:
             raise TypeError(
                 f"Component callable must return a Node, Template, or str; "

html_tstring/processor_test.py

@@ -134,15 +134,15 @@ def test_conversions():
 # --------------------------------------------------------------------------
 
 
-def test_raw_html_injection_with_helper():
+def test_raw_html_injection_with_markupsafe():
     raw_content = Markup("<strong>I am bold</strong>")
     node = html(t"<div>{raw_content}</div>")
     assert node == Element("div", children=[Text(text=raw_content)])
     assert str(node) == "<div><strong>I am bold</strong></div>"
 
 
 def test_raw_html_injection_with_dunder_html_protocol():
-    class SafeContent(str):
+    class SafeContent:
         def __init__(self, text):
             self._text = text
 
@@ -153,7 +153,12 @@ def __html__(self):
     content = SafeContent("emphasized")
     node = html(t"<p>Here is some {content}.</p>")
     assert node == Element(
-        "p", children=[Text("Here is some "), Text(content), Text(".")]
+        "p",
+        children=[
+            Text("Here is some "),
+            Text(Markup("<em>emphasized</em>")),
+            Text("."),
+        ],
     )
     assert str(node) == "<p>Here is some <em>emphasized</em>.</p>"
 
@@ -172,6 +177,20 @@ def test_raw_html_injection_with_format_spec():
     assert str(node) == "<p>This is <u>underlined</u> text.</p>"
 
 
+def test_raw_html_injection_with_markupsafe_unsafe_format_spec():
+    supposedly_safe = Markup("<i>italic</i>")
+    node = html(t"<p>This is {supposedly_safe:unsafe} text.</p>")
+    assert node == Element(
+        "p",
+        children=[
+            Text("This is "),
+            Text(supposedly_safe),
+            Text(" text."),
+        ],
+    )
+    assert str(node) == "<p>This is &lt;i&gt;italic&lt;/i&gt; text.</p>"
+
+
 # --------------------------------------------------------------------------
 # Conditional rendering and control flow
 # --------------------------------------------------------------------------