Allow attr values to be HTML

Author: schloerke

htmltools/_core.py

@@ -97,7 +97,7 @@ class MetadataNode:
 
 TagT = TypeVar("TagT", bound="Tag")
 
-TagAttrValue = Union[str, float, bool, None]
+TagAttrValue = Union[str, float, bool, "HTML", None]
 """
 Types that can be passed in as attributes to `Tag` functions. These values will be
 converted to strings before being stored as tag attributes.
@@ -225,7 +225,7 @@ class Tagifiable(Protocol):
     returns a `TagList`, the children of the `TagList` must also be tagified.
     """
 
-    def tagify(self) -> "TagList | Tag | MetadataNode | str": ...
+    def tagify(self) -> "TagList | Tag | MetadataNode | str | HTML": ...
 
 
 @runtime_checkable
@@ -486,7 +486,7 @@ def _repr_html_(self) -> str:
 # =============================================================================
 # TagAttrDict class
 # =============================================================================
-class TagAttrDict(Dict[str, str]):
+class TagAttrDict(Dict[str, "str | HTML"]):
     """
     A dictionary-like object that can be used to store attributes for a tag. All
     attribute values will be stored as strings.
@@ -521,7 +521,7 @@ def update(  # type: ignore[reportIncompatibleMethodOverride] # TODO-future: fix
         if kwargs:
             args = args + (kwargs,)
 
-        attrz: dict[str, str] = {}
+        attrz: dict[str, str | HTML] = {}
         for arg in args:
             for k, v in arg.items():
                 val = self._normalize_attr_value(v)
@@ -544,12 +544,14 @@ def _normalize_attr_name(x: str) -> str:
         return x.replace("_", "-")
 
     @staticmethod
-    def _normalize_attr_value(x: TagAttrValue) -> str | None:
+    def _normalize_attr_value(x: TagAttrValue) -> str | HTML | None:
         if x is None or x is False:
             return None
         if x is True:
             return ""
-        if isinstance(x, str):
+        # Return both str and HTML objects as is.
+        # HTML objects will handle value escaping when added to other values
+        if isinstance(x, (str, HTML)):
             return x
         if isinstance(x, (int, float)):  # pyright: ignore[reportUnnecessaryIsInstance]
             return str(x)
@@ -671,7 +673,7 @@ def __enter__(self) -> None:
         sys.displayhook = wrap_displayhook_handler(
             # self.append takes a TagChild, but the wrapper expects a function that
             # takes a object.
-            self.append  # pyright: ignore[reportArgumentType,reportGeneralTypeIssues]
+            self.append  # pyright: ignore[reportArgumentType]
         )
 
     def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
@@ -840,7 +842,8 @@ def get_html_string(self, indent: int = 0, eol: str = "\n") -> str:
 
         # Write attributes
         for key, val in self.attrs.items():
-            val = html_escape(val, attr=True)
+            if not isinstance(val, HTML):
+                val = html_escape(val, attr=True)
             html_ += f' {key}="{val}"'
 
         # Dependencies are ignored in the HTML output
@@ -1383,7 +1386,6 @@ def __radd__(self, other: object) -> HTML:
         # Case: `str + HTML()`
         return HTML(html_escape(str(other)) + self.as_string())
 
-
     def __repr__(self) -> str:
         return self.as_string()
 
@@ -1923,7 +1925,7 @@ def _tag_show(
             import IPython  # pyright: ignore[reportUnknownVariableType]
 
             ipy = (  # pyright: ignore[reportUnknownVariableType]
-                IPython.get_ipython()  # pyright: ignore[reportUnknownMemberType, reportPrivateImportUsage]
+                IPython.get_ipython()  # pyright: ignore[reportUnknownMemberType, reportPrivateImportUsage, reportAttributeAccessIssue]
             )
             renderer = "ipython" if ipy else "browser"
         except ImportError:

tests/test_tags.py

@@ -108,6 +108,25 @@ def test_basic_tag_api():
     x4.add_style("color: blue;", prepend=True)
     assert x4.attrs["style"] == "color: blue; color: red; color: green;"
 
+    x5 = div()
+    x5.add_style("color: &purple;")
+    assert isinstance(x5.attrs["style"], str)
+    assert x5.attrs["style"] == "color: &purple;"
+    x5.add_style(HTML("color: &green;"))
+    assert isinstance(x5.attrs["style"], HTML)
+    assert x5.attrs["style"] == HTML("color: &purple; color: &green;")
+
+    x6 = div()
+    x6.add_style("color: &red;")
+    assert isinstance(x6.attrs["style"], str)
+    assert x6.attrs["style"] == "color: &red;"
+    x6.add_style(HTML("color: &green;"), prepend=True)
+    assert isinstance(x6.attrs["style"], HTML)
+    assert x6.attrs["style"] == HTML("color: &green; color: &red;")
+    assert isinstance(x6.attrs["style"], HTML)
+    x6.add_style(HTML("color: &blue;"))
+    assert x6.attrs["style"] == HTML("color: &green; color: &red; color: &blue;")
+
 
 def test_tag_list_dict():
     # Dictionaries allowed at top level
@@ -542,14 +561,8 @@ def test_tag_escaping():
     # Attributes are HTML escaped
     expect_html(div("text", class_="<a&b>"), '<div class="&lt;a&amp;b&gt;">text</div>')
     expect_html(div("text", class_="'ab'"), '<div class="&apos;ab&apos;">text</div>')
-    # Sending in HTML causes an error
-    with pytest.raises(TypeError):
-        div(
-            "text",
-            class_=HTML(
-                "<a&b>"
-            ),  # pyright: ignore[reportArgumentType,reportGeneralTypeIssues]
-        )
+    # Attributes support `HTML()` values
+    expect_html(div("text", class_=HTML("<a&b>")), '<div class="<a&b>">text</div>')
 
     # script and style tags are not escaped
     assert str(tags.script("a && b > 3")) == "<script>a && b > 3</script>"
@@ -654,7 +667,7 @@ def _walk_mutate(x: TagNode, fn: Callable[[TagNode], TagNode]) -> TagNode:
             x.children[i] = _walk_mutate(child, fn)
     elif isinstance(x, list):
         for i, child in enumerate(x):
-            x[i] = _walk_mutate(child, fn)
+            x[i] = _walk_mutate(child, fn)  # pyright: ignore[reportArgumentType]
     return x