html-tstring 0.1.0__py3-none-any.whl

html_tstring/__init__.py

@@ -0,0 +1,17 @@
+from markupsafe import Markup, escape
+
+from .nodes import Comment, DocumentType, Element, Fragment, Text
+from .processor import html
+
+# We consider `Markup` and `escape` to be part of this module's public API
+
+__all__ = [
+    "Comment",
+    "DocumentType",
+    "Element",
+    "escape",
+    "Fragment",
+    "html",
+    "Markup",
+    "Text",
+]

html_tstring/classnames.py

@@ -0,0 +1,46 @@
+def classnames(*args: object) -> str:
+    """
+    Construct a space-separated class string from various inputs.
+
+    Accepts strings, lists/tuples of strings, and dicts mapping class names to
+    boolean values. Ignores None and False values.
+
+    Examples:
+        classnames("btn", "btn-primary") -> "btn btn-primary"
+        classnames("btn", {"btn-primary": True, "disabled": False}) -> "btn btn-primary"
+        classnames(["btn", "btn-primary"], {"disabled": True}) -> "btn btn-primary disabled"
+        classnames("btn", None, False, "active") -> "btn active"
+
+    Args:
+        *args: Variable length argument list containing strings, lists/tuples,
+               or dicts.
+
+    Returns:
+        A single string with class names separated by spaces.
+    """
+    classes: list[str] = []
+    # Use a queue to process arguments iteratively, preserving order.
+    queue = list(args)
+
+    while queue:
+        arg = queue.pop(0)
+
+        if not arg:  # Handles None, False, empty strings/lists/dicts
+            continue
+
+        if isinstance(arg, str):
+            classes.append(arg)
+        elif isinstance(arg, dict):
+            for key, value in arg.items():
+                if value:
+                    classes.append(key)
+        elif isinstance(arg, (list, tuple)):
+            # Add items to the front of the queue to process them next, in order.
+            queue[0:0] = arg
+        elif isinstance(arg, bool):
+            pass  # Explicitly ignore booleans not in a dict
+        else:
+            raise ValueError(f"Invalid class argument type: {type(arg).__name__}")
+
+    # Filter out empty strings and join the result.
+    return " ".join(stripped for c in classes if (stripped := c.strip()))

html_tstring/nodes.py

@@ -0,0 +1,134 @@
+import typing as t
+from dataclasses import dataclass, field
+from functools import cached_property
+from html import escape
+
+# See https://developer.mozilla.org/en-US/docs/Glossary/Void_element
+VOID_ELEMENTS = frozenset(
+    [
+        "area",
+        "base",
+        "br",
+        "col",
+        "embed",
+        "hr",
+        "img",
+        "input",
+        "link",
+        "meta",
+        "param",
+        "source",
+        "track",
+        "wbr",
+    ]
+)
+
+
+CDATA_CONTENT_ELEMENTS = frozenset(["script", "style"])
+RCDATA_CONTENT_ELEMENTS = frozenset(["textarea", "title"])
+CONTENT_ELEMENTS = CDATA_CONTENT_ELEMENTS | RCDATA_CONTENT_ELEMENTS
+
+# TODO: add a pretty-printer for nodes for debugging
+# TODO: consider how significant whitespace is handled from t-string to nodes
+
+
+@t.runtime_checkable
+class HasHTMLDunder(t.Protocol):
+    def __html__(self) -> str: ...
+
+
+type HTMLDunder = t.Callable[[], str]
+
+
+@dataclass(slots=True)
+class Node:
+    def __html__(self) -> str:
+        """Return the HTML representation of the node."""
+        # By default, just return the string representation
+        return str(self)
+
+
+@dataclass(slots=False)
+class Text(Node):
+    # Django's `SafeString` and Markupsafe/Jinja2's `Markup` both inherit
+    # from `str`, but that is not a requirement for the `__html__` dunder.
+    text: str | HasHTMLDunder
+
+    @cached_property
+    def _cached_str(self) -> str:
+        if isinstance(self.text, HasHTMLDunder):
+            return self.text.__html__()
+        return escape(t.cast(str, self.text), quote=False)
+
+    def _as_unescaped(self) -> str:
+        """Return the text as-is, without escaping. For internal use only."""
+        if isinstance(self.text, HasHTMLDunder):
+            return self.text.__html__()
+        return self.text
+
+    def __str__(self) -> str:
+        return self._cached_str
+
+
+@dataclass(slots=True)
+class Fragment(Node):
+    children: list[Node] = field(default_factory=list)
+
+    def __str__(self) -> str:
+        return "".join(str(child) for child in self.children)
+
+
+@dataclass(slots=True)
+class Comment(Node):
+    text: str
+
+    def __str__(self) -> str:
+        return f"<!--{self.text}-->"
+
+
+@dataclass(slots=True)
+class DocumentType(Node):
+    text: str = "html"
+
+    def __str__(self) -> str:
+        return f"<!DOCTYPE {self.text}>"
+
+
+@dataclass(slots=True)
+class Element(Node):
+    tag: str
+    attrs: dict[str, str | None] = field(default_factory=dict)
+    children: list[Node] = field(default_factory=list)
+
+    def __post_init__(self):
+        """Ensure all preconditions are met."""
+        if not self.tag:
+            raise ValueError("Element tag cannot be empty.")
+
+        # Void elements cannot have children
+        if self.is_void and self.children:
+            raise ValueError(f"Void element <{self.tag}> cannot have children.")
+
+    @property
+    def is_void(self) -> bool:
+        return self.tag in VOID_ELEMENTS
+
+    def __str__(self) -> str:
+        # TODO: CONSIDER: should values in attrs support the __html__ dunder?
+        attrs_str = "".join(
+            f" {key}" if value is None else f' {key}="{escape(value, quote=True)}"'
+            for key, value in self.attrs.items()
+        )
+        if self.is_void:
+            return f"<{self.tag}{attrs_str} />"
+        if not self.children:
+            return f"<{self.tag}{attrs_str}></{self.tag}>"
+        if self.tag in CONTENT_ELEMENTS:
+            # Content elements should not escape their content
+            children_str = "".join(
+                child._as_unescaped() if isinstance(child, Text) else str(child)
+                for child in self.children
+            )
+        else:
+            children_str = "".join(str(child) for child in self.children)
+        return f"<{self.tag}{attrs_str}>{children_str}</{self.tag}>"

html_tstring/parser.py

@@ -0,0 +1,132 @@
+import typing as t
+from html.parser import HTMLParser
+
+from .nodes import VOID_ELEMENTS, Comment, DocumentType, Element, Fragment, Node, Text
+
+
+class NodeParser(HTMLParser):
+    root: Fragment
+    stack: list[Element]
+
+    def __init__(self):
+        super().__init__()
+        self.root = Fragment(children=[])
+        self.stack = []
+
+    def handle_starttag(
+        self, tag: str, attrs: t.Sequence[tuple[str, str | None]]
+    ) -> None:
+        element = Element(tag, attrs=dict(attrs), children=[])
+        self.stack.append(element)
+
+        # Unfortunately, Python's built-in HTMLParser has inconsistent behavior
+        # with void elements. In particular, it calls handle_endtag() for them
+        # only if they explicitly self-close (e.g., <br />). But in the HTML
+        # spec itself, *there is no distinction* between <br> and <br />.
+        # So we need to handle this case ourselves.
+        #
+        # See https://github.com/python/cpython/issues/69445
+        if tag in VOID_ELEMENTS:
+            # Always call handle_endtag for void elements. If it happens
+            # to be self-closed in the input, handle_endtag() will effectively
+            # be called twice. We ignore the second call there.
+            self.handle_endtag(tag)
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in VOID_ELEMENTS:
+            # Special case: handle Python issue #69445 (see comment above).
+            open_element = self.get_open_element()
+            if open_element and open_element.tag == tag:
+                _ = self.stack.pop()
+                self.append_child(open_element)
+                return
+            most_recent_closed = self.get_most_recent_closed_element()
+            if most_recent_closed and most_recent_closed.tag == tag:
+                # Ignore this call; we've already closed it.
+                return
+            raise ValueError(f"Unexpected closing tag </{tag}> with no open element.")
+
+        element = self.stack.pop()
+        if element.tag != tag:
+            raise ValueError(f"Mismatched closing tag </{tag}> for <{element.tag}>.")
+
+        self.append_child(element)
+
+    def handle_data(self, data: str) -> None:
+        text = Text(data)
+        self.append_child(text)
+
+    def handle_comment(self, data: str) -> None:
+        comment = Comment(data)
+        self.append_child(comment)
+
+    def handle_decl(self, decl: str) -> None:
+        if decl.upper().startswith("DOCTYPE"):
+            doctype_content = decl[7:].strip()
+            doctype = DocumentType(doctype_content)
+            self.append_child(doctype)
+        # For simplicity, we ignore other declarations.
+        pass
+
+    def get_parent(self) -> Fragment | Element:
+        """Return the current parent node to which new children should be added."""
+        return self.stack[-1] if self.stack else self.root
+
+    def get_open_element(self) -> Element | None:
+        """Return the currently open Element, if any."""
+        return self.stack[-1] if self.stack else None
+
+    def get_most_recent_closed_element(self) -> Element | None:
+        """Return the most recently closed Element, if any."""
+        parent = self.get_parent()
+        if parent.children and isinstance(parent.children[-1], Element):
+            return parent.children[-1]
+        return None
+
+    def append_child(self, child: Node) -> None:
+        parent = self.get_parent()
+        # We *know* our parser is using lists for children, so this cast is safe.
+        parent.children.append(child)
+
+    def close(self) -> None:
+        if self.stack:
+            raise ValueError("Invalid HTML structure: unclosed tags remain.")
+        super().close()
+
+    def get_node(self) -> Node:
+        """Get the Node tree parsed from the input HTML."""
+        assert not self.stack, "Did you forget to call close()?"
+        if len(self.root.children) > 1:
+            # The parse structure results in multiple root elements, so we
+            # return a Fragment to hold them all.
+            return self.root
+        elif len(self.root.children) == 1:
+            # The parse structure results in a single root element, so we
+            # return that element directly. This will be a non-Fragment Node.
+            return self.root.children[0]
+        else:
+            # Special case: the parse structure is empty; we treat
+            # this as an empty Text Node.
+            return Text("")
+
+
+def parse_html(input_html: str) -> Node:
+    """Parse an HTML string into a Node tree."""
+    parser = NodeParser()
+    parser.feed(input_html)
+    parser.close()
+    return parser.get_node()
+
+
+def parse_html_iter(input_html: t.Iterable[str]) -> Node:
+    """
+    Parse a sequence of HTML string chunks into a Node tree.
+
+    This is particularly useful if your sequence keeps separate text nodes
+    that you wish to preserve intact.
+    """
+    parser = NodeParser()
+    for chunk in input_html:
+        parser.feed(chunk)
+    parser.close()
+    return parser.get_node()

html_tstring/processor.py

@@ -0,0 +1,356 @@
+import random
+import string
+import typing as t
+from collections.abc import Iterable
+from functools import lru_cache
+from string.templatelib import Interpolation, Template
+
+from markupsafe import Markup
+
+from .classnames import classnames
+from .nodes import Element, Fragment, HasHTMLDunder, Node, Text
+from .parser import parse_html_iter
+from .utils import format_interpolation as base_format_interpolation
+
+# --------------------------------------------------------------------------
+# Value formatting
+# --------------------------------------------------------------------------
+
+
+def _format_safe(value: object, format_spec: str) -> str:
+    assert format_spec == "safe"
+    return Markup(value)
+
+
+CUSTOM_FORMATTERS = (("safe", _format_safe),)
+
+
+def format_interpolation(interpolation: Interpolation) -> object:
+    return base_format_interpolation(
+        interpolation,
+        formatters=CUSTOM_FORMATTERS,
+    )
+
+
+# --------------------------------------------------------------------------
+# Instrumentation, Parsing, and Caching
+# --------------------------------------------------------------------------
+
+_PLACEHOLDER_PREFIX = f"t🐍-{''.join(random.choices(string.ascii_lowercase, k=4))}-"
+_PP_LEN = len(_PLACEHOLDER_PREFIX)
+
+
+def _placeholder(i: int) -> str:
+    """Generate a placeholder for the i-th interpolation."""
+    return f"{_PLACEHOLDER_PREFIX}{i}"
+
+
+def _placholder_index(s: str) -> int:
+    """Extract the index from a placeholder string."""
+    return int(s[_PP_LEN:])
+
+
+def _instrument(
+    strings: tuple[str, ...], callable_ids: tuple[int | None, ...]
+) -> t.Iterable[str]:
+    """
+    Join the strings with placeholders in between where interpolations go.
+
+    This is used to prepare the template string for parsing, so that we can
+    later substitute the actual interpolated values into the parse tree.
+
+    The placeholders are chosen to be unlikely to collide with typical HTML
+    content.
+    """
+    count = len(strings)
+
+    callable_placeholders: dict[int, str] = {}
+
+    for i, s in enumerate(strings):
+        yield s
+        # There are always count-1 placeholders between count strings.
+        if i < count - 1:
+            # Special case for component callables: if the interpolation
+            # is a callable, we need to make sure that any matching closing
+            # tag uses the same placeholder.
+            callable_id = callable_ids[i]
+            if callable_id is not None:
+                # This interpolation is a callable, so we need to make sure
+                # that any matching closing tag uses the same placeholder.
+                if callable_id not in callable_placeholders:
+                    callable_placeholders[callable_id] = _placeholder(i)
+                yield callable_placeholders[callable_id]
+            else:
+                yield _placeholder(i)
+
+
+@lru_cache()
+def _instrument_and_parse_internal(
+    strings: tuple[str, ...], callable_ids: tuple[int | None, ...]
+) -> Node:
+    """
+    Instrument the strings and parse the resulting HTML.
+
+    The result is cached to avoid re-parsing the same template multiple times.
+    """
+    instrumented = _instrument(strings, callable_ids)
+    return parse_html_iter(instrumented)
+
+
+def _callable_id(value: object) -> int | None:
+    """Return a unique identifier for a callable, or None if not callable."""
+    return id(value) if callable(value) else None
+
+
+def _instrument_and_parse(template: Template) -> Node:
+    """Instrument and parse a template, returning a tree of Nodes."""
+    # This is a thin wrapper around the cached internal function that does the
+    # actual work. This exists to handle the syntax we've settled on for
+    # component invocation, namely that callables are directly included as
+    # interpolations both in the open *and* the close tags. We need to make
+    # sure that matching tags... match!
+    #
+    # If we used `tdom`'s approach of component closing tags of <//> then we
+    # wouldn't have to do this. But I worry that tdom's syntax is harder to read
+    # (it's easy to miss the closing tag) and may prove unfamiliar for
+    # users coming from other templating systems.
+    callable_ids = tuple(
+        _callable_id(interpolation.value) for interpolation in template.interpolations
+    )
+    return _instrument_and_parse_internal(template.strings, callable_ids)
+
+
+# --------------------------------------------------------------------------
+# Placeholder Substitution
+# --------------------------------------------------------------------------
+
+
+def _force_dict(value: t.Any, *, kind: str) -> dict:
+    """Try to convert a value to a dict, raising TypeError if not possible."""
+    try:
+        return dict(value)
+    except (TypeError, ValueError):
+        raise TypeError(
+            f"Cannot use {type(value).__name__} as value for {kind} attributes"
+        ) from None
+
+
+def _substitute_aria_attrs(value: object) -> t.Iterable[tuple[str, str | None]]:
+    """Produce aria-* attributes based on the interpolated value for "aria"."""
+    d = _force_dict(value, kind="aria")
+    for sub_k, sub_v in d.items():
+        if sub_v is True:
+            yield f"aria-{sub_k}", "true"
+        elif sub_v is False:
+            yield f"aria-{sub_k}", "false"
+        elif sub_v is None:
+            pass
+        else:
+            yield f"aria-{sub_k}", str(sub_v)
+
+
+def _substitute_data_attrs(value: object) -> t.Iterable[tuple[str, str | None]]:
+    """Produce data-* attributes based on the interpolated value for "data"."""
+    d = _force_dict(value, kind="data")
+    for sub_k, sub_v in d.items():
+        if sub_v is True:
+            yield f"data-{sub_k}", None
+        elif sub_v not in (False, None):
+            yield f"data-{sub_k}", str(sub_v)
+
+
+def _substitute_class_attr(value: object) -> t.Iterable[tuple[str, str | None]]:
+    """Substitute a class attribute based on the interpolated value."""
+    yield ("class", classnames(value))
+
+
+def _substitute_style_attr(value: object) -> t.Iterable[tuple[str, str | None]]:
+    """Substitute a style attribute based on the interpolated value."""
+    try:
+        d = _force_dict(value, kind="style")
+        style_str = "; ".join(f"{k}: {v}" for k, v in d.items())
+        yield ("style", style_str)
+    except TypeError:
+        yield ("style", str(value))
+
+
+def _substitute_spread_attrs(value: object) -> t.Iterable[tuple[str, str | None]]:
+    """
+    Substitute a spread attribute based on the interpolated value.
+
+    A spread attribute is one where the key is a placeholder, indicating that
+    the entire attribute set should be replaced by the interpolated value.
+    The value must be a dict or iterable of key-value pairs.
+    """
+    d = _force_dict(value, kind="spread")
+    for sub_k, sub_v in d.items():
+        yield from _substitute_attr(sub_k, sub_v)
+
+
+# A collection of custom handlers for certain attribute names that have
+# special semantics. This is in addition to the special-casing in
+# _substitute_attr() itself.
+CUSTOM_ATTR_HANDLERS = {
+    "class": _substitute_class_attr,
+    "data": _substitute_data_attrs,
+    "style": _substitute_style_attr,
+    "aria": _substitute_aria_attrs,
+}
+
+
+def _substitute_attr(
+    key: str,
+    value: object,
+) -> t.Iterable[tuple[str, str | None]]:
+    """
+    Substitute a single attribute based on its key and the interpolated value.
+
+    A single parsed attribute with a placeholder may result in multiple
+    attributes in the final output, for instance if the value is a dict or
+    iterable of key-value pairs. Likewise, a value of False will result in
+    the attribute being omitted entirely; nothing is yielded in that case.
+    """
+    # Special handling for certain attribute names that have special semantics
+    if custom_handler := CUSTOM_ATTR_HANDLERS.get(key):
+        yield from custom_handler(value)
+        return
+
+    # General handling for all other attributes:
+    match value:
+        case str():
+            yield (key, value)
+        case True:
+            yield (key, None)
+        case False | None:
+            pass
+        case _:
+            yield (key, str(value))
+
+
+def _substitute_attrs(
+    attrs: dict[str, str | None], interpolations: tuple[Interpolation, ...]
+) -> dict[str, str | None]:
+    """Substitute placeholders in attributes based on the corresponding interpolations."""
+    new_attrs: dict[str, str | None] = {}
+    for key, value in attrs.items():
+        if value and value.startswith(_PLACEHOLDER_PREFIX):
+            index = _placholder_index(value)
+            interpolation = interpolations[index]
+            value = format_interpolation(interpolation)
+            for sub_k, sub_v in _substitute_attr(key, value):
+                new_attrs[sub_k] = sub_v
+        elif key.startswith(_PLACEHOLDER_PREFIX):
+            index = _placholder_index(key)
+            interpolation = interpolations[index]
+            value = format_interpolation(interpolation)
+            for sub_k, sub_v in _substitute_spread_attrs(value):
+                new_attrs[sub_k] = sub_v
+        else:
+            new_attrs[key] = value
+    return new_attrs
+
+
+def _substitute_and_flatten_children(
+    children: t.Iterable[Node], interpolations: tuple[Interpolation, ...]
+) -> list[Node]:
+    """Substitute placeholders in a list of children and flatten any fragments."""
+    new_children: list[Node] = []
+    for child in children:
+        substituted = _substitute_node(child, interpolations)
+        if isinstance(substituted, Fragment):
+            # This can happen if an interpolation results in a Fragment, for
+            # instance if it is iterable.
+            new_children.extend(substituted.children)
+        else:
+            new_children.append(substituted)
+    return new_children
+
+
+def _node_from_value(value: object) -> Node:
+    """
+    Convert an arbitrary value to a Node.
+
+    This is the primary substitution performed when replacing interpolations
+    in child content positions.
+    """
+    match value:
+        case str():
+            return Text(value)
+        case Node():
+            return value
+        case Template():
+            return html(value)
+        case HasHTMLDunder():
+            return Text(value)
+        case False:
+            return Text("")
+        case Iterable():
+            children = [_node_from_value(v) for v in value]
+            return Fragment(children=children)
+        case _:
+            return Text(str(value))
+
+
+def _invoke_component(
+    tag: str,
+    new_attrs: dict[str, str | None],
+    new_children: list[Node],
+    interpolations: tuple[Interpolation, ...],
+) -> Node:
+    """Substitute a component invocation based on the corresponding interpolations."""
+    index = _placholder_index(tag)
+    interpolation = interpolations[index]
+    value = format_interpolation(interpolation)
+    if not callable(value):
+        raise TypeError(
+            f"Expected a callable for component invocation, got {type(value).__name__}"
+        )
+    # Call the component and return the resulting node
+    result = value(*new_children, **new_attrs)
+    match result:
+        case Node():
+            return result
+        case Template():
+            return html(result)
+        case HasHTMLDunder() | str():
+            return Text(result)
+        case _:
+            raise TypeError(
+                f"Component callable must return a Node, Template, str, or "
+                f"HasHTMLDunder, got {type(result).__name__}"
+            )
+
+
+def _substitute_node(p_node: Node, interpolations: tuple[Interpolation, ...]) -> Node:
+    """Substitute placeholders in a node based on the corresponding interpolations."""
+    match p_node:
+        case Text(text) if str(text).startswith(_PLACEHOLDER_PREFIX):
+            index = _placholder_index(str(text))
+            interpolation = interpolations[index]
+            value = format_interpolation(interpolation)
+            return _node_from_value(value)
+        case Element(tag=tag, attrs=attrs, children=children):
+            new_attrs = _substitute_attrs(attrs, interpolations)
+            new_children = _substitute_and_flatten_children(children, interpolations)
+            if tag.startswith(_PLACEHOLDER_PREFIX):
+                return _invoke_component(tag, new_attrs, new_children, interpolations)
+            else:
+                return Element(tag=tag, attrs=new_attrs, children=new_children)
+        case Fragment(children=children):
+            new_children = _substitute_and_flatten_children(children, interpolations)
+            return Fragment(children=new_children)
+        case _:
+            return p_node
+
+
+# --------------------------------------------------------------------------
+# Public API
+# --------------------------------------------------------------------------
+
+
+def html(template: Template) -> Node:
+    """Parse a t-string and return a tree of Nodes."""
+    # Parse the HTML, returning a tree of nodes with placeholders
+    # where interpolations go.
+    p_node = _instrument_and_parse(template)
+    return _substitute_node(p_node, template.interpolations)

html_tstring/utils.py

@@ -0,0 +1,88 @@
+import typing as t
+from string.templatelib import Interpolation
+
+
+@t.overload
+def convert[T](value: T, conversion: None) -> T: ...
+
+
+@t.overload
+def convert(value: object, conversion: t.Literal["a", "r", "s"]) -> str: ...
+
+
+def convert[T](value: T, conversion: t.Literal["a", "r", "s"] | None) -> T | str:
+    """
+    Convert a value according to the given conversion specifier.
+
+    In the future, something like this should probably ship with Python itself.
+    """
+    if conversion == "a":
+        return ascii(value)
+    elif conversion == "r":
+        return repr(value)
+    elif conversion == "s":
+        return str(value)
+    else:
+        return value
+
+
+type FormatMatcher = t.Callable[[str], bool]
+"""A predicate function that returns True if a given format specifier matches its criteria."""
+
+type CustomFormatter = t.Callable[[object, str], str]
+"""A function that takes a value and a format specifier and returns a formatted string."""
+
+type MatcherAndFormatter = tuple[str | FormatMatcher, CustomFormatter]
+"""
+A pair of a matcher and its corresponding formatter.
+
+The matcher is used to determine if the formatter should be applied to a given 
+format specifier. If the matcher is a string, it must exactly match the format
+specifier. If it is a FormatMatcher, it is called with the format specifier and
+should return True if the formatter should be used.
+"""
+
+
+def _matcher_matches(matcher: str | FormatMatcher, format_spec: str) -> bool:
+    """Check if a matcher matches a given format specifier."""
+    return matcher == format_spec if isinstance(matcher, str) else matcher(format_spec)
+
+
+def _format_interpolation(
+    value: object,
+    format_spec: str,
+    conversion: t.Literal["a", "r", "s"] | None,
+    *,
+    formatters: t.Sequence[MatcherAndFormatter],
+) -> object:
+    converted = convert(value, conversion)
+    if format_spec:
+        for matcher, formatter in formatters:
+            if _matcher_matches(matcher, format_spec):
+                return formatter(converted, format_spec)
+        return format(converted, format_spec)
+    return converted
+
+
+def format_interpolation(
+    interpolation: Interpolation,
+    *,
+    formatters: t.Sequence[MatcherAndFormatter] = tuple(),
+) -> object:
+    """
+    Format an Interpolation's value according to its format spec and conversion.
+
+    PEP 750 allows t-string processing code to decide whether, and how, to
+    interpret format specifiers. This function takes an optional sequence of
+    (matcher, formatter) pairs. If a matcher returns True for the given format
+    spec, the corresponding formatter is used to format the value. If no
+    matchers match, the default formatting behavior is used.
+
+    Conversions are always applied before formatting.
+    """
+    return _format_interpolation(
+        interpolation.value,
+        interpolation.format_spec,
+        interpolation.conversion,
+        formatters=formatters,
+    )

html_tstring-0.1.0.dist-info/METADATA

@@ -0,0 +1,316 @@
+Metadata-Version: 2.4
+Name: html-tstring
+Version: 0.1.0
+Summary: A 🤘 rockin' t-string HTML templating system for Python 3.14.
+Project-URL: Homepage, https://github.com/t-strings/html-tstring
+Project-URL: Changelog, https://github.com/t-strings/html-tstring/releases
+Project-URL: Issues, https://github.com/t-strings/html-tstring/issues
+Project-URL: CI, https://github.com/t-strings/html-tstring/actions
+Author-email: Dave Peck <davepeck@davepeck.org>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: markupsafe>=3.0.2
+Description-Content-Type: text/markdown
+
+# html-tstring
+
+A 🤘 rockin' t-string HTML templating system for Python 3.14.
+
+[![PyPI](https://img.shields.io/pypi/v/html-tstring.svg)](https://pypi.org/project/html-tstring/)
+[![Tests](https://github.com/t-strings/html-tstring/actions/workflows/ci.yml/badge.svg)](https://github.com/t-strings/tdom/actions/workflows/pytest.yml)
+[![Changelog](https://img.shields.io/github/v/release/t-strings/html-tstring?include_prereleases&label=changelog)](https://github.com/t-strings/html-tstring/releases)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/t-strings/html-tstring/blob/main/LICENSE)
+
+## Installation
+
+Just run:
+
+```bash
+pip install html-tstring
+```
+
+Python 3.14 isn't out yet, but you can use [Astral's `uv`](https://docs.astral.sh/uv/) to easily try `html-tstring` in a Python 3.14 environment:
+
+```bash
+uv run --with html-tstring --python 3.14 python
+```
+
+## Usage
+
+`html-tstring` leverages Python 3.14's [new t-strings feature](https://t-strings.help/introduction.html) to provide a powerful HTML templating system that feels familiar if you've used JSX, Jinja2, or Django templates.
+
+T-strings work just like f-strings but use a `t` prefix and [create `Template` objects](https://docs.python.org/3.14/library/string.templatelib.html#template-strings) instead of strings.
+
+Once you have a `Template`, you can call this package's `html()` function to convert it into a tree of `Node` objects that represent your HTML structure. From there, you can render it to a string, manipulate it programmatically, or compose it with other templates for maximum flexibility.
+
+### Getting Started
+
+Import the `html` function and start creating templates:
+
+```python
+from html_tstring import html
+greeting = html(t"<h1>Hello, World!</h1>")
+print(type(greeting))  # <class 'html_tstring.nodes.Element'>
+print(greeting)  # <h1>Hello, World!</h1>
+```
+
+### Variable Interpolation
+
+Just like f-strings, you can interpolate (substitute) variables directly into your templates:
+
+```python
+name = "Alice"
+age = 30
+user_info = html(t"<p>Hello, {name}! You are {age} years old.</p>")
+print(user_info)  # <p>Hello, Alice! You are 30 years old.</p>
+```
+
+The `html()` function ensures that interpolated values are automatically escaped to prevent XSS attacks:
+
+```python
+user_name = "<script>alert('owned')</script>"
+safe_output = html(t"<p>Hello, {user_name}!</p>")
+print(safe_output)  # <p>Hello, &lt;script&gt;alert('owned')&lt;/script&gt;!</p>
+```
+
+### Attribute Substitution
+
+The `html()` function provides a number of convenient ways to define HTML attributes.
+
+#### Direct Attribute Values
+
+You can place values directly in attribute positions:
+
+```python
+url = "https://example.com"
+link = html(t'<a href="{url}">Visit our site</a>')
+# <a href="https://example.com">Visit our site</a>
+```
+
+You don't _have_ to wrap your attribute values in quotes:
+
+```python
+element_id = "my-button"
+button = html(t"<button id={element_id}>Click me</button>")
+# <button id="my-button">Click me</button>
+```
+
+Boolean attributes are supported too. Just use a boolean value in the attribute position:
+
+```python
+form_button = html(t"<button disabled={True} hidden={False}>Submit</button>")
+print(form_button)
+# <button disabled>Submit</button>
+```
+
+#### The `class` Attribute
+
+The `class` attribute has special handling to make it easy to combine multiple classes from different sources. The simplest way is to provide a list of class names:
+
+```python
+classes = ["btn", "btn-primary", "active"]
+button = html(t'<button class="{classes}">Click me</button>')
+# <button class="btn btn-primary active">Click me</button>
+```
+
+For flexibility, you can also provide a list of strings, dictionaries, or a mix of both:
+
+```python
+classes = ["btn", "btn-primary", {"active": True}, None, False and "disabled"]
+button = html(t'<button class="{classes}">Click me</button>')
+# <button class="btn btn-primary active">Click me</button>
+```
+
+See the [`classnames()`](./html_tstring/classnames_test.py) helper function for more information on how class names are combined.
+
+#### The `style` Attribute
+
+In addition to strings, you can also provide a dictionary of CSS properties and values for the `style` attribute:
+
+```python
+# Style attributes from dictionaries
+styles = {"color": "red", "font-weight": "bold", "margin": "10px"}
+styled = html(t"<p style={styles}>Important text</p>")
+# <p style="color: red; font-weight: bold; margin: 10px">Important text</p>
+```
+
+#### The `data` and `aria` Attributes
+
+The `data` and `aria` attributes also have special handling to convert dictionary keys to the appropriate attribute names:
+
+```python
+data_attrs = {"user-id": 123, "role": "admin"}
+aria_attrs = {"label": "Close dialog", "hidden": True}
+element = html(t"<div data={data_attrs} aria={aria_attrs}>Content</div>")
+# <div data-user-id="123" data-role="admin" aria-label="Close dialog"
+# aria-hidden="true">Content</div>
+```
+
+Note that boolean values in `aria` attributes are converted to `"true"` or `"false"` as per [the ARIA specification](https://www.w3.org/TR/wai-aria-1.2/).
+
+#### Attribute Spreading
+
+It's possible to specify multiple attributes at once by using a dictionary and spreading it into an element using curly braces:
+
+```python
+attrs = {"href": "https://example.com", "target": "_blank"}
+link = html(t"<a {attrs}>External link</a>")
+# <a href="https://example.com" target="_blank">External link</a>
+```
+
+You can also combine spreading with individual attributes:
+
+```python
+base_attrs = {"id": "my-link"}
+target = "_blank"
+link = html(t'<a {base_attrs} target="{target}">Link</a>')
+# <a id="my-link" target="_blank">Link</a>
+```
+
+Special attributes likes `class` behave as expected when combined with spreading:
+
+```python
+classes = ["btn", {"active": True}]
+attrs = {"class": classes, "id": "act_now", "data": {"wow": "such-attr"}}
+button = html(t'<button {attrs}>Click me</button>')
+# <button class="btn active" id="act_now" data-wow="such-attr">Click me</button>
+```
+
+### Conditional Rendering
+
+You can use Python's conditional expressions for dynamic content:
+
+```python
+is_logged_in = True
+user_content = t"<span>Welcome back!</span>"
+guest_content = t"<a href='/login'>Please log in</a>"
+header = html(t"<div>{user_content if is_logged_in else guest_content}</div>")
+# <div><span>Welcome back!</span></div>
+```
+
+Short-circuit evaluation is also supported for conditionally including elements:
+
+```python
+show_warning = False
+warning = t'<div class="alert">Warning message</div>'
+page = html(t"<main>{show_warning and warning}</main>")
+# <main></main>
+```
+
+### Lists and Iteration
+
+Generate repeated elements using list comprehensions:
+
+```python
+fruits = ["Apple", "Banana", "Cherry"]
+fruit_list = html(t"<ul>{[t'<li>{fruit}</li>' for fruit in fruits]}</ul>")
+# <ul><li>Apple</li><li>Banana</li><li>Cherry</li></ul>
+```
+
+### Raw HTML Injection
+
+The `html-tstring` package provides several ways to include trusted raw HTML content in your templates. This is useful when you have HTML content that you _know_ is safe and do not wish to escape.
+
+Under the hood, `html-tstring` builds on top of the familiar [MarkupSafe](https://pypi.org/project/MarkupSafe/) library to handle trusted HTML content. If you've used Flask, Jinja2, or similar libraries, this will feel very familiar.
+
+The `Markup` class from MarkupSafe is available for use:
+
+```python
+from html_tstring import html, Markup
+
+trusted_html = Markup("<strong>This is safe HTML</strong>")
+content = html(t"<div>{trusted_html}</div>")
+# <div><strong>This is safe HTML</strong></div>
+```
+
+As a convenience, `html-tstring` also supports a `:safe` format specifier that marks a string as safe HTML:
+
+```python
+trusted_html = "<em>Emphasized text</em>"
+page = html(t"<p>Here is some {trusted_html:safe} content.</p>")
+# <p>Here is some <em>Emphasized text</em> content.</p>
+```
+
+For interoperability with other templating libraries, any object that implements a `__html__` method will be treated as safe HTML. Many popular libraries (including MarkupSafe and Django) use this convention:
+
+```python
+class SafeWidget:
+    def __html__(self):
+        return "<button>Custom Widget</button>"
+
+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.
+
+### Template Composition
+
+You can easily combine multiple templates and create reusable components.
+
+Template nesting is straightforward:
+
+```python
+content = t"<h1>My Site</h1>"
+page = html(t"<div>{content}</div>")
+# <div><h1>My Site</h1></div>
+```
+
+In the example above, `content` is a `Template` object that gets correctly parsed and embedded within the outer template. You can also explicitly call `html()` on nested templates if you prefer:
+
+```python
+content = html(t"<h1>My Site</h1>")
+page = html(t"<div>{content}</div>")
+# <div><h1>My Site</h1></div>
+```
+
+The result is the same either way.
+
+### Advanced Features
+
+#### Component Functions
+
+You can create reusable component functions that generate templates with dynamic content and attributes. Use these like custom HTML elements in your templates.
+
+The basic form of all component functions is:
+
+```python
+from typing import Any
+
+def MyComponent(*children: Node, **attrs: Any) -> Template:
+    # Build your template using the provided props
+    return t"<div {attrs}>{children}</div>"
+```
+
+To _invoke_ your component within an HTML template, use the special `<{ComponentName} ... />` syntax:
+
+```python
+result = html(t"<{MyComponent} id='comp1'>Hello, Component!</{MyComponent}>")
+# <div id="comp1">Hello, Component!</div>
+```
+
+Because attributes are passed as keyword arguments, you can explicitly provide type hints for better editor support:
+
+```python
+from typing import Any
+
+def Link(*, href: str, text: str, **props: Any) -> Template:
+    return t'<a href="{href}" {props}>{text}</a>'
+
+result = html(t'<{Link} href="https://example.com" text="Example" target="_blank" />')
+# <a href="https://example.com" target="_blank">Example</a>
+```
+
+In addition to returning a `Template` directly, component functions may also return any `Node` type found in [`html_tstring.nodes`](./html_tstring/nodes.py). This allows you to build more complex components that manipulate the HTML structure programmatically.
+
+#### Context
+
+TODO: implement context feature
+
+#### Working with `Node` Objects
+
+TODO: say more about working with them directly

html_tstring-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+html_tstring/__init__.py,sha256=qKgfEk1p3-rGfGUIIGpRneBAEJ4354MpCKsIFkLkxNs,342
+html_tstring/classnames.py,sha256=nRELUKM5CSE0ROnbA7eIFEluCadA32DPcoZ9eq0TLdU,1712
+html_tstring/nodes.py,sha256=xD2T9bK7H5oz_f7qy5kslITZtdD7wFmkfZU4Q7w-Oc8,3779
+html_tstring/parser.py,sha256=oprMhiEk1f61i9c16-THubRLFvcNyfOBxtHv-VBiSxg,4979
+html_tstring/processor.py,sha256=zirUi-CBK6UTAVmyma2zcDvFWWdVOgQMwSwleBY2qv4,13007
+html_tstring/utils.py,sha256=SqAA4jZKv5D7MHmp7hXOMuPBEwA2ELKGIiiwKC7psJs,2910
+html_tstring-0.1.0.dist-info/METADATA,sha256=uhO_3ZuN6LoUPhkxBgp_9Q_Sy9Sc2fglgPgaKmcFjz0,11193
+html_tstring-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+html_tstring-0.1.0.dist-info/licenses/LICENSE,sha256=wsfEeu57NkGuQ7NHD5ZcL5g0EnqLN_PGCaq-D--b-HQ,1090
+html_tstring-0.1.0.dist-info/RECORD,,

html_tstring-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

html_tstring-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dave Peck <davepeck@davepeck.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.