html: add parse_html

doc/content/api-reference/html.rst

@@ -174,6 +174,40 @@ given selector.
 Using HTML Strings
 ~~~~~~~~~~~~~~~~~~
 
+To initialize an HTML tree you can use ``lona.html.parse_html``, which returns
+a Lona HTML node or a list of Lona HTML nodes.
+
+``lona.html.parse_html`` uses high level nodes from the standard library like
+``lona.html.TextInput`` which implement high level methods and properties.
+To disable this and parse HTML into blank nodes you can set
+``use_high_level_nodes=False``.
+
+When ``lona.html.parse_html`` parses a HTML string, that results in a HTML
+tree with exacly one root node, and ``flat`` is set to ``True``, which is the
+default, ``lona.html.parse_html`` will flatten the tree, by returning the root
+node instead of the list.
+
+.. code-block:: python
+
+ from lona.html import parse_html
+
+ >>> parse_html('<h1>Hello World</h1><p>Lorem Ipsum</p>')
+ [<h1 data-lona-node-id="9">
+ Hello World
+ </h1>,
+ <p data-lona-node-id="11">
+ Lorem Ipsum
+ </p>]
+
+ >>> parse_html('<h1>Hello World</h1>')
+ <h1 data-lona-node-id="14">
+ Hello World
+ </h1>
+
+
+Using lona.html.HTML
+++++++++++++++++++++
+
 .. note::
 
  Added in 1.5: Support for high level nodes, the keyword

lona/html/__init__.py

@@ -125,13 +125,13 @@
 from lona.html.nodes.scripting import NoScript, Script, Canvas
 from lona.html.nodes.forms.select2 import Select2, Option2
 from lona.html.nodes.web_components import Template, Slot
+from lona.html.parsing import NodeHTMLParser, parse_html
 from lona.html.nodes.forms.select import Select, Option
 from lona.html.nodes.demarcating_edits import Ins, Del
 from lona.html.nodes.svg_and_mathml import Math, SVG
 from lona.events.event_types import * # NOQA: F403
 from lona.html.nodes.sectioning_root import Body
 from lona.html.nodes.raw_nodes import RawHTML
-from lona.html.parsing import NodeHTMLParser
 from lona.html.widgets import HTML as HTML1
 from lona.html.parsing import HTML as HTML2
 from lona.compat import get_client_version

lona/html/parsing.py

@@ -5,7 +5,7 @@
  tagfind_tolerant,
  HTMLParser,
 )
-from typing import List, Dict
+from typing import List, Dict, cast
 from html import unescape
 import logging
 
@@ -198,11 +198,33 @@ def handle_endtag(self, tag):
  self.set_current_node(self._node.parent)
 
 
-def html_string_to_node_list(html_string, use_high_level_nodes=True,
- node_classes=None):
+def parse_html(
+ html_string: str,
+ use_high_level_nodes: bool = True,
+ node_classes: Dict[str, AbstractNode] | None = None,
+ flat: bool = True,
+) -> AbstractNode | List[AbstractNode]:
+
+ """
+ Takes HTML as a string and returns a Lona HTML node or a list of Lona
+ HTML nodes.
+
+ :use_high_level_nodes: When set to True, node classes from the standard
+ library get used. When set to False,
+ `lona.html.Node` will be used for all returned
+ nodes.
+
+ :node_classes: A dict that contains node classes that should be
+ used for the returned HTML nodes.
 
- root_node = Node()
- nodes = []
+ :flat: If set to True and the parsed HTML tree has exactly
+ one root node, this root node gets returned instead
+ of a list of one node.
+
+ """
+
+ root_node: Node = Node()
+ nodes: List[AbstractNode] = []
 
  html_parser = NodeHTMLParser(
  use_high_level_nodes=use_high_level_nodes,
@@ -221,6 +243,9 @@ def html_string_to_node_list(html_string, use_high_level_nodes=True,
  node.remove()
  nodes.append(node)
 
+ if flat and len(nodes) == 1:
+ return nodes[0]
+
  return nodes
 
 
@@ -230,6 +255,8 @@ def HTML(
  node_classes: Dict[str, AbstractNode] | None = None,
 ) -> AbstractNode:
 
+ # TODO: remove HTML parsing in 2.0
+
  _nodes: List[AbstractNode] = []
 
  for node in nodes:
@@ -243,10 +270,14 @@ def HTML(
 
  # html string
  elif '<' in node or '>' in node:
- parsed_nodes = html_string_to_node_list(
- html_string=node,
- use_high_level_nodes=use_high_level_nodes,
- node_classes=node_classes or {},
+ parsed_nodes = cast(
+ list,
+ parse_html(
+ html_string=node,
+ use_high_level_nodes=use_high_level_nodes,
+ node_classes=node_classes or {},
+ flat=False,
+ ),
  )
 
  if len(nodes) > 1:

lona/html/widgets.py

@@ -1,5 +1,5 @@
-from lona.html.parsing import html_string_to_node_list
 from lona.html.text_node import TextNode
+from lona.html.parsing import parse_html
 from lona.html.widget import Widget
 
 
@@ -22,10 +22,11 @@ def __init__(self, *nodes, use_high_level_nodes=True, node_classes=None):
  self.nodes.append(HTML(node))
 
  else:
- self.nodes = html_string_to_node_list(
+ self.nodes = parse_html(
  html_string=node,
  use_high_level_nodes=use_high_level_nodes,
  node_classes=node_classes or {},
+ flat=False,
  )
 
  else: