string_to_reactpy and reactpy_to_string

Author: Archmonger

src/reactpy/__init__.py

@@ -21,7 +21,7 @@
 from reactpy.core.layout import Layout
 from reactpy.core.vdom import vdom
 from reactpy.pyscript.components import pyscript_component
-from reactpy.utils import Ref, html_to_vdom, vdom_to_html
+from reactpy.utils import Ref, reactpy_to_string, string_to_reactpy
 
 __author__ = "The Reactive Python Team"
 __version__ = "2.0.0a1"
@@ -35,9 +35,10 @@
     "event",
     "hooks",
     "html",
-    "html_to_vdom",
     "logging",
     "pyscript_component",
+    "reactpy_to_string",
+    "string_to_reactpy",
     "types",
     "use_async_effect",
     "use_callback",
@@ -52,7 +53,6 @@
     "use_scope",
     "use_state",
     "vdom",
-    "vdom_to_html",
     "web",
     "widgets",
 ]

src/reactpy/executors/asgi/standalone.py

@@ -31,7 +31,7 @@
     RootComponentConstructor,
     VdomDict,
 )
-from reactpy.utils import html_to_vdom, import_dotted_path
+from reactpy.utils import import_dotted_path, string_to_reactpy
 
 _logger = getLogger(__name__)
 
@@ -74,7 +74,7 @@ def __init__(
             extra_py = pyscript_options.get("extra_py", [])
             extra_js = pyscript_options.get("extra_js", {})
             config = pyscript_options.get("config", {})
-            pyscript_head_vdom = html_to_vdom(
+            pyscript_head_vdom = string_to_reactpy(
                 pyscript_setup_html(extra_py, extra_js, config)
             )
             pyscript_head_vdom["tagName"] = ""

src/reactpy/executors/utils.py

@@ -13,7 +13,7 @@
     REACTPY_RECONNECT_MAX_RETRIES,
 )
 from reactpy.types import ReactPyConfig, VdomDict
-from reactpy.utils import import_dotted_path, vdom_to_html
+from reactpy.utils import import_dotted_path, reactpy_to_string
 
 logger = logging.getLogger(__name__)
 
@@ -41,7 +41,7 @@ def check_path(url_path: str) -> str:  # nocov
 
 def vdom_head_to_html(head: VdomDict) -> str:
     if isinstance(head, dict) and head.get("tagName") == "head":
-        return vdom_to_html(head)
+        return reactpy_to_string(head)
 
     raise ValueError(
         "Invalid head element! Element must be either `html.head` or a string."

src/reactpy/pyscript/components.py

@@ -6,7 +6,7 @@
 from reactpy import component, hooks
 from reactpy.pyscript.utils import pyscript_component_html
 from reactpy.types import ComponentType, Key
-from reactpy.utils import html_to_vdom
+from reactpy.utils import string_to_reactpy
 
 if TYPE_CHECKING:
     from reactpy.types import VdomDict
@@ -22,15 +22,15 @@ def _pyscript_component(
         raise ValueError("At least one file path must be provided.")
 
     rendered, set_rendered = hooks.use_state(False)
-    initial = html_to_vdom(initial) if isinstance(initial, str) else initial
+    initial = string_to_reactpy(initial) if isinstance(initial, str) else initial
 
     if not rendered:
         # FIXME: This is needed to properly re-render PyScript during a WebSocket
         # disconnection / reconnection. There may be a better way to do this in the future.
         set_rendered(True)
         return None
 
-    component_vdom = html_to_vdom(
+    component_vdom = string_to_reactpy(
         pyscript_component_html(tuple(str(fp) for fp in file_paths), initial, root)
     )
     component_vdom["tagName"] = ""

src/reactpy/pyscript/utils.py

@@ -18,7 +18,7 @@
 import reactpy
 from reactpy.config import REACTPY_DEBUG, REACTPY_PATH_PREFIX, REACTPY_WEB_MODULES_DIR
 from reactpy.types import VdomDict
-from reactpy.utils import vdom_to_html
+from reactpy.utils import reactpy_to_string
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -77,7 +77,7 @@ def pyscript_component_html(
     file_paths: Sequence[str], initial: str | VdomDict, root: str
 ) -> str:
     """Renders a PyScript component with the user's code."""
-    _initial = initial if isinstance(initial, str) else vdom_to_html(initial)
+    _initial = initial if isinstance(initial, str) else reactpy_to_string(initial)
     uuid = uuid4().hex
     executor_code = pyscript_executor_html(file_paths=file_paths, uuid=uuid, root=root)
 

src/reactpy/transforms.py

@@ -7,7 +7,7 @@
 
 
 class RequiredTransforms:
-    """Performs any necessary transformations related to `html_to_vdom` to automatically prevent
+    """Performs any necessary transformations related to `string_to_reactpy` to automatically prevent
     issues with React's rendering engine.
     """
 
@@ -83,7 +83,7 @@ def select_element_to_reactjs(self, vdom: VdomDict) -> None:
     def input_element_value_prop_to_defaultValue(vdom: VdomDict) -> None:
         """ReactJS will complain that inputs are uncontrolled if defining the `value` prop,
         so we use `defaultValue` instead. This has an added benefit of not deleting/overriding
-        any user input when a `html_to_vdom` re-renders fields that do not retain their `value`,
+        any user input when a `string_to_reactpy` re-renders fields that do not retain their `value`,
         such as password fields."""
         if vdom["tagName"] != "input":
             return
@@ -106,7 +106,7 @@ def infer_key_from_attributes(vdom: VdomDict) -> None:
 
         # Infer 'key' from 'attributes.id'
         if key is None:
-        key = attributes.get("id")
+            key = attributes.get("id")
 
         # Infer 'key' from 'attributes.name'
         if key is None and vdom["tagName"] in {"input", "select", "textarea"}:

src/reactpy/utils.py

@@ -61,32 +61,31 @@ def __repr__(self) -> str:
         return f"{type(self).__name__}({current})"
 
 
-def vdom_to_html(vdom: VdomDict) -> str:
-    """Convert a VDOM dictionary into an HTML string
-
-    Only the following keys are translated to HTML:
-
-    - ``tagName``
-    - ``attributes``
-    - ``children`` (must be strings or more VDOM dicts)
+def reactpy_to_string(root: VdomDict | ComponentType) -> str:
+    """Convert a ReactPy component or `reactpy.html` element into an HTML string.
 
     Parameters:
-        vdom: The VdomDict element to convert to HTML
+        root: The ReactPy element to convert to a string.
     """
-    temp_root = etree.Element("__temp__")
-    _add_vdom_to_etree(temp_root, vdom)
-    html = cast(bytes, tostring(temp_root)).decode()  # type: ignore
-    # strip out temp root <__temp__> element
+    temp_container = etree.Element("__temp__")
+
+    if not isinstance(root, dict):
+        root = component_to_vdom(root)
+
+    _add_vdom_to_etree(temp_container, root)
+    html = cast(bytes, tostring(temp_container)).decode()  # type: ignore
+
+    # Strip out temp root <__temp__> element
     return html[10:-11]
 
 
-def html_to_vdom(
+def string_to_reactpy(
     html: str,
     *transforms: _ModelTransform,
     strict: bool = True,
     intercept_links: bool = True,
 ) -> VdomDict:
-    """Transform HTML into a DOM model. Unique keys can be provided to HTML elements
+    """Transform HTML string into a ReactPy DOM model. ReactJS keys can be provided to HTML elements
     using a ``key=...`` attribute within your HTML tag.
 
     Parameters:
@@ -126,7 +125,7 @@ def html_to_vdom(
             "An error has occurred while parsing the HTML.\n\n"
             "This HTML may be malformatted, or may not perfectly adhere to HTML5.\n"
             "If you believe the exception above was due to something intentional, you "
-            "can disable the strict parameter on html_to_vdom().\n"
+            "can disable the strict parameter on string_to_reactpy().\n"
             "Otherwise, repair your broken HTML and try again."
         )
         raise HTMLParseError(msg) from e
@@ -228,12 +227,17 @@ def _generate_vdom_children(
     )
 
 
-def component_to_vdom(component: ComponentType) -> VdomDict | str | None:
+def component_to_vdom(component: ComponentType) -> VdomDict:
     """Convert the first render of a component into a VDOM dictionary"""
     result = component.render()
+
+    if isinstance(result, dict):
+        return result
     if hasattr(result, "render"):
-        result = component_to_vdom(cast(ComponentType, result))
-    return cast(Union[VdomDict, str, None], result)
+        return component_to_vdom(cast(ComponentType, result))
+    elif isinstance(result, str):
+        return make_vdom("div", {}, result)
+    return make_vdom("")
 
 
 def _react_attribute_to_html(key: str, value: Any) -> tuple[str, str]:

tests/test_utils.py

@@ -88,8 +88,8 @@ def test_ref_repr():
         },
     ],
 )
-def test_html_to_vdom(case):
-    assert utils.html_to_vdom(case["source"]) == case["model"]
+def test_string_to_reactpy(case):
+    assert utils.string_to_reactpy(case["source"]) == case["model"]
 
 
 @pytest.mark.parametrize(
@@ -192,18 +192,18 @@ def test_html_to_vdom(case):
         },
     ],
 )
-def test_html_to_vdom_default_transforms(case):
-    assert utils.html_to_vdom(case["source"]) == case["model"]
+def test_string_to_reactpy_default_transforms(case):
+    assert utils.string_to_reactpy(case["source"]) == case["model"]
 
 
-def test_html_to_vdom_intercept_links():
+def test_string_to_reactpy_intercept_links():
     source = '<a href="https://example.com">Hello World</a>'
     expected = {
         "tagName": "a",
         "children": ["Hello World"],
         "attributes": {"href": "https://example.com"},
     }
-    result = utils.html_to_vdom(source, intercept_links=True)
+    result = utils.string_to_reactpy(source, intercept_links=True)
 
     # Check if the result equals expected when removing `eventHandlers` from the result dict
     event_handlers = result.pop("eventHandlers", {})
@@ -213,7 +213,7 @@ def test_html_to_vdom_intercept_links():
     assert "onClick" in event_handlers
 
 
-def test_html_to_vdom_custom_transform():
+def test_string_to_reactpy_custom_transform():
     source = "<p>hello <a>world</a> and <a>universe</a>lmao</p>"
 
     def make_links_blue(node):
@@ -241,7 +241,8 @@ def make_links_blue(node):
     }
 
     assert (
-        utils.html_to_vdom(source, make_links_blue, intercept_links=False) == expected
+        utils.string_to_reactpy(source, make_links_blue, intercept_links=False)
+        == expected
     )
 
 
@@ -256,10 +257,10 @@ def test_non_html_tag_behavior():
         ],
     }
 
-    assert utils.html_to_vdom(source, strict=False) == expected
+    assert utils.string_to_reactpy(source, strict=False) == expected
 
     with pytest.raises(utils.HTMLParseError):
-        utils.html_to_vdom(source, strict=True)
+        utils.string_to_reactpy(source, strict=True)
 
 
 SOME_OBJECT = object()
@@ -342,19 +343,23 @@ def example_child():
             html.div(example_parent()),
             '<div><div id="sample" style="padding:15px"><h1>Sample Application</h1></div></div>',
         ),
+        (
+            example_parent(),
+            '<div id="sample" style="padding:15px"><h1>Sample Application</h1></div>',
+        ),
         (
             html.form({"acceptCharset": "utf-8"}),
             '<form accept-charset="utf-8"></form>',
         ),
     ],
 )
-def test_vdom_to_html(vdom_in, html_out):
-    assert utils.vdom_to_html(vdom_in) == html_out
+def test_reactpy_to_string(vdom_in, html_out):
+    assert utils.reactpy_to_string(vdom_in) == html_out
 
 
-def test_vdom_to_html_error():
+def test_reactpy_to_string_error():
     with pytest.raises(TypeError, match="Expected a VDOM dict"):
-        utils.vdom_to_html({"notVdom": True})
+        utils.reactpy_to_string({"notVdom": True})
 
 
 def test_invalid_dotted_path():