Function html_to_vdom

src/py/reactpy/reactpy/utils.py:81–119

Transform HTML into a DOM model. Unique keys can be provided to HTML elements using a ``key=...`` attribute within your HTML tag. Parameters: html: The raw HTML as a string transforms: Functions of the form ``transform(old) -> new`` where ``old`` is a

(
    html: str, *transforms: _ModelTransform, strict: bool = True
)

def html_to_vdom(
    html: str, *transforms: _ModelTransform, strict: bool = True
) -> VdomDict:
    """Transform HTML into a DOM model. Unique keys can be provided to HTML elements
    using a ``key=...`` attribute within your HTML tag.

    Parameters:
        html:
            The raw HTML as a string
        transforms:
            Functions of the form ``transform(old) -> new`` where ``old`` is a VDOM
            dictionary which will be replaced by ``new``. For example, you could use a
            transform function to add highlighting to a ``<code/>`` block.
        strict:
            If ``True``, raise an exception if the HTML does not perfectly follow HTML5
            syntax.
    """
    if not isinstance(html, str):  # nocov
        msg = f"Expected html to be a string, not {type(html).__name__}"
        raise TypeError(msg)

    # If the user provided a string, convert it to a list of lxml.etree nodes
    try:
        root_node: etree._Element = fromstring(
            html.strip(),
            parser=etree.HTMLParser(
                remove_comments=True,
                remove_pis=True,
                remove_blank_text=True,
                recover=not strict,
            ),
        )
    except etree.XMLSyntaxError as e:
        if not strict:
            raise e  # nocov
        msg = "An error has occurred while parsing the HTML.\n\nThis HTML may be malformatted, or may not perfectly adhere to HTML5.\nIf you believe the exception above was due to something intentional, you can disable the strict parameter on html_to_vdom().\nOtherwise, repair your broken HTML and try again."
        raise HTMLParseError(msg) from e

    return _etree_to_vdom(root_node, transforms)


class HTMLParseError(etree.LxmlSyntaxError):  # type: ignore[misc]