Export is_tag_node(), is_tag_child() and consolidate_attrs()

Author: schloerke

CHANGELOG.md

@@ -23,6 +23,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Exported `ReprHtml` protocol class. If an object has a `_repr_html_` method, then it is of instance `ReprHtml`. (#86)
 
+* Exported `is_tag_node()` and `is_tag_child()` functions that utilize `typing.TypeIs` to narrow `TagNode` and `TagChild` type variables, respectively. (#86)
+
+* Exported `consolidate_attrs(*args, **kwargs)` function. This function will combine the `TagAttrs` (supplied in `*args`) with `TagAttrValues` (supplied in `**kwargs`) into a single `TagAttrs` object. In addition, it will also return all `*args` that are not dictionary as a list of unaltered `TagChild` objects. (#86)
+* This function takes a list of `TagAttrs` and returns a single `TagAttrs` object. (#86)
+
 ### Bug fixes
 
 * Fixed an issue with `HTMLTextDocument()` returning extracted `HTMLDependency()`s in a non-determistic order. (#95)

htmltools/__init__.py

@@ -19,7 +19,10 @@
     Tagifiable,
     TagList,
     TagNode,
+    consolidate_attrs,
     head_content,
+    is_tag_child,
+    is_tag_node,
     wrap_displayhook_handler,
 )
 from ._util import css, html_escape
@@ -61,7 +64,10 @@
     "TagList",
     "TagNode",
     "ReprHtml",
+    "consolidate_attrs",
     "head_content",
+    "is_tag_child",
+    "is_tag_node",
     "wrap_displayhook_handler",
     "css",
     "html_escape",

htmltools/_core.py

@@ -26,6 +26,7 @@
     TypeVar,
     Union,
     cast,
+    overload,
 )
 
 # Even though TypedDict is available in Python 3.8, because it's used with NotRequired,
@@ -36,6 +37,11 @@
 else:
     from typing_extensions import Never, NotRequired, TypedDict
 
+if sys.version_info >= (3, 13):
+    from typing import TypeIs
+else:
+    from typing_extensions import TypeIs
+
 from typing import Literal, Protocol, SupportsIndex, runtime_checkable
 
 from packaging.version import Version
@@ -63,7 +69,10 @@
     "TagNode",
     "TagFunction",
     "Tagifiable",
+    "consolidate_attrs",
     "head_content",
+    "is_tag_child",
+    "is_tag_node",
     "wrap_displayhook_handler",
 )
 
@@ -100,13 +109,23 @@ class MetadataNode:
 unnamed arguments to Tag functions like `div()`.
 """
 
-TagNode = Union["Tagifiable", "Tag", MetadataNode, "ReprHtml", str]
+# NOTE: If this type is updated, please update `is_tag_node()`
+TagNode = Union[
+    "Tagifiable",
+    # "Tag", # Tag is Tagifiable, do not include here
+    # "TagList", # TagList is Tagifiable, do not include here
+    MetadataNode,
+    "ReprHtml",
+    str,
+    "HTML",
+]
 """
 Types of objects that can be a node in a `Tag` tree. Equivalently, these are the valid
 elements of a `TagList`. Note that this type represents the internal structure of items
 in a `TagList`; the user-facing type is `TagChild`.
 """
 
+# NOTE: If this type is updated, please update `is_tag_child()`
 TagChild = Union[
     TagNode,
     "TagList",
@@ -120,13 +139,85 @@ class MetadataNode:
 will be flattened and normalized to `TagNode` objects.
 """
 
+
 # These two types existed in htmltools 0.14.0 and earlier. They are here so that
 # existing versions of Shiny will be able to load, but users of those existing packages
 # will see type errors, which should encourage them to upgrade Shiny.
 TagChildArg = Never
 TagAttrArg = Never
 
 
+# # No use yet, so keeping code commented for now
+# TagNodeT = TypeVar("TagNodeT", bound=TagNode)
+# """
+# Type variable for `TagNode`.
+# """
+
+TagChildT = TypeVar("TagChildT", bound=TagChild)
+"""
+Type variable for `TagChild`.
+"""
+
+
+def is_tag_node(x: object) -> TypeIs[TagNode]:
+    """
+    Check if an object is a `TagNode`.
+
+    Note: The type hint is `TypeIs[TagNode]` to allow for type checking of the
+    return value. (`TypeIs` is imported from `typing_extensions` for Python < 3.13.)
+
+    Parameters
+    ----------
+    x
+        Object to check.
+
+    Returns
+    -------
+    :
+        `True` if the object is a `TagNode`, `False` otherwise.
+    """
+    # Note: Tag and TagList are both Tagifiable
+    return isinstance(x, (Tagifiable, MetadataNode, ReprHtml, str, HTML))
+
+
+def is_tag_child(x: object) -> TypeIs[TagChild]:
+    """
+    Check if an object is a `TagChild`.
+
+    Note: The type hint is `TypeIs[TagChild]` to allow for type checking of the
+    return value. (`TypeIs` is imported from `typing_extensions` for Python < 3.13.)
+
+    Parameters
+    ----------
+    x
+        Object to check.
+
+    Returns
+    -------
+    :
+        `True` if the object is a `TagChild`, `False` otherwise.
+    """
+
+    if is_tag_node(x):
+        return True
+    if x is None:
+        return True
+    if isinstance(
+        x,
+        (
+            # TagNode, # Handled above
+            TagList,
+            float,
+            # None, # Handled above
+            Sequence,
+        ),
+    ):
+        return True
+
+    # Could not determine the type
+    return False
+
+
 @runtime_checkable
 class Tagifiable(Protocol):
     """
@@ -1744,6 +1835,61 @@ def head_content(*args: TagChild) -> HTMLDependency:
     return HTMLDependency(name=name, version="0.0", head=head)
 
 
+# If no children are provided, it will not be able to infer the type of `TagChildT`.
+# Using `TagChild`, even though the list will be empty.
+@overload
+def consolidate_attrs(
+    *args: TagAttrs,
+    **kwargs: TagAttrValue,
+) -> tuple[TagAttrs, list[TagChild]]: ...
+
+
+# Same as original definition
+@overload
+def consolidate_attrs(
+    *args: TagChildT | TagAttrs,
+    **kwargs: TagAttrValue,
+) -> tuple[TagAttrs, list[TagChildT]]: ...
+
+
+def consolidate_attrs(
+    *args: TagChildT | TagAttrs,
+    **kwargs: TagAttrValue,
+) -> tuple[TagAttrs, list[TagChildT]]:
+    """
+    Consolidate attributes and children into a single tuple.
+
+    Convenience function to consolidate attributes and children into a single tuple. All
+    `args` that are not dictionaries are considered children. This helps preserve the
+    non-attribute elements within `args`. To extract the attributes, all `args` and
+    `kwargs` are passed to `Tag` function and the attributes (`.attrs`) are extracted
+    from the resulting `Tag` object.
+
+    Parameters
+    ----------
+    *args
+        Child elements to this tag and attribute dictionaries.
+    **kwargs
+        Named attributes to this tag.
+
+    Returns
+    -------
+    :
+        A tuple of attributes and children. The attributes are a dictionary of combined
+        named attributes, and the children are a list of unaltered child elements.
+    """
+    tag = Tag("consolidate_attrs", *args, **kwargs)
+
+    # Convert to a plain dict to avoid getting custom methods from TagAttrDict
+    # Cast to `TagAttrs` as that is the common type used by py-shiny
+    attrs = cast(TagAttrs, dict(tag.attrs))
+
+    # Do not alter/flatten children structure (like `TagList` does)
+    # Instead, return all `args` who are not dictionaries
+    children = [child for child in args if not isinstance(child, dict)]
+    return (attrs, children)
+
+
 # =============================================================================
 # Utility functions
 # =============================================================================
@@ -1756,7 +1902,7 @@ def _tagchilds_to_tagnodes(x: Iterable[TagChild]) -> list[TagNode]:
     for i, item in enumerate(result):
         if isinstance(item, (int, float)):
             result[i] = str(item)
-        elif not isinstance(item, (HTML, Tagifiable, Tag, MetadataNode, ReprHtml, str)):
+        elif not is_tag_node(item):
             raise TypeError(
                 f"Invalid tag item type: {type(item)}. "
                 + "Consider calling str() on this value before treating it as a tag item."

htmltools/_util.py

@@ -16,7 +16,10 @@
 
 HashableT = TypeVar("HashableT", bound=Hashable)
 
-__all__ = ("css",)
+__all__ = (
+    "css",
+    "html_escape",
+)
 
 
 def css(

tests/test_consolidate_attrs.py

@@ -0,0 +1,18 @@
+from htmltools import HTML, consolidate_attrs
+
+
+def test_consolidate_attrs():
+
+    (attrs, children) = consolidate_attrs(
+        {"class": "&c1"},
+        0,
+        # This tests `__radd__` method of `HTML` class
+        {"id": "foo", "class_": HTML("&c2")},
+        [1, [2]],
+        3,
+        class_=HTML("&c3"),
+        other_attr="other",
+    )
+
+    assert attrs == {"id": "foo", "class": "&c1 &c2 &c3", "other-attr": "other"}
+    assert children == [0, [1, [2]], 3]

tests/test_is.py

@@ -0,0 +1,87 @@
+from typing import List
+
+import pytest
+
+from htmltools import (
+    HTML,
+    HTMLDependency,
+    ReprHtml,
+    Tag,
+    TagAttrs,
+    TagChild,
+    TagList,
+    TagNode,
+    div,
+    is_tag_child,
+    is_tag_node,
+)
+
+tag_attr_obj: TagAttrs = {"test_key": "test_value"}
+
+
+class ReprClass:
+
+    def _repr_html_(self) -> str:
+        return "repr_html"
+
+
+repr_obj = ReprClass()
+
+
+class OtherObj:
+    pass
+
+
+class TagifiableClass:
+    def tagify(self) -> Tag:
+        return Tag("test_element").tagify()
+
+
+def test_is_repr_html():
+    assert isinstance(repr_obj, ReprHtml)
+
+
+tag_node_objs: List[TagNode] = [
+    TagifiableClass(),
+    Tag("test_element2"),
+    TagList([div("div_content")]),
+    HTMLDependency("test_dependency", version="1.0.0"),
+    repr_obj,
+    "test_string",
+    HTML("test_html"),
+]
+tag_child_only_objs: List[TagChild] = [
+    # *tag_node_objs,
+    # [*tag_node_objs],
+    [Tag("test_element3")],
+    None,
+    [],
+]
+
+not_tag_child_objs = [
+    OtherObj(),
+]
+
+
+@pytest.mark.parametrize("obj", tag_node_objs)
+def test_is_tag_node(obj):
+    assert is_tag_node(obj)
+
+
+@pytest.mark.parametrize(
+    "obj", [[*tag_node_objs], *tag_child_only_objs, *not_tag_child_objs]
+)
+def test_not_is_tag_node(obj):
+    assert not is_tag_node(obj)
+
+
+@pytest.mark.parametrize(
+    "obj", [*tag_node_objs, [*tag_node_objs], *tag_child_only_objs]
+)
+def test_is_tag_child(obj):
+    assert is_tag_child(obj)
+
+
+@pytest.mark.parametrize("obj", not_tag_child_objs)
+def test_not_is_tag_child(obj):
+    assert not is_tag_child(obj)