Change VdomDict into a dict subclass

Author: Archmonger

src/reactpy/_html.py

@@ -1,20 +1,18 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, ClassVar, overload
+from typing import ClassVar, overload
 
 from reactpy.core.vdom import Vdom
-
-if TYPE_CHECKING:
-    from reactpy.types import (
-        EventHandlerDict,
-        Key,
-        VdomAttributes,
-        VdomChild,
-        VdomChildren,
-        VdomDict,
-        VdomDictConstructor,
-    )
+from reactpy.types import (
+    EventHandlerDict,
+    Key,
+    VdomAttributes,
+    VdomChild,
+    VdomChildren,
+    VdomDict,
+    VdomDictConstructor,
+)
 
 __all__ = ["html"]
 
@@ -109,7 +107,7 @@ def _fragment(
     if attributes or event_handlers:
         msg = "Fragments cannot have attributes besides 'key'"
         raise TypeError(msg)
-    model: VdomDict = {"tagName": ""}
+    model = VdomDict(tagName="")
 
     if children:
         model["children"] = children
@@ -143,7 +141,7 @@ def _script(
         Doing so may allow for malicious code injection
         (`XSS <https://en.wikipedia.org/wiki/Cross-site_scripting>`__`).
     """
-    model: VdomDict = {"tagName": "script"}
+    model = VdomDict(tagName="script")
 
     if event_handlers:
         msg = "'script' elements do not support event handlers"

src/reactpy/core/hooks.py

@@ -20,7 +20,14 @@
 
 from reactpy.config import REACTPY_DEBUG
 from reactpy.core._life_cycle_hook import HOOK_STACK
-from reactpy.types import Connection, Context, Key, Location, State, VdomDict
+from reactpy.types import (
+    Connection,
+    Context,
+    Key,
+    Location,
+    State,
+    VdomDict,
+)
 from reactpy.utils import Ref
 
 if not TYPE_CHECKING:
@@ -362,7 +369,7 @@ def __init__(
 
     def render(self) -> VdomDict:
         HOOK_STACK.current_hook().set_context_provider(self)
-        return {"tagName": "", "children": self.children}
+        return VdomDict(tagName="ContextProvider", children=self.children)
 
     def __repr__(self) -> str:
         return f"ContextProvider({self.type})"

src/reactpy/core/layout.py

@@ -196,7 +196,7 @@ async def _render_component(
             # wrap the model in a fragment (i.e. tagName="") to ensure components have
             # a separate node in the model state tree. This could be removed if this
             # components are given a node in the tree some other way
-            wrapper_model: VdomDict = {"tagName": "", "children": [raw_model]}
+            wrapper_model = VdomDict(tagName="", children=[raw_model])
             await self._render_model(exit_stack, old_state, new_state, wrapper_model)
         except Exception as error:
             logger.exception(f"Failed to render {component}")

src/reactpy/core/vdom.py

@@ -26,8 +26,9 @@
     EventHandlerType,
     VdomAttributes,
     VdomChildren,
+    VdomDict,
     VdomJson,
-    _VdomDict,
+    VdomTypeDict,
 )
 
 VDOM_JSON_SCHEMA = {
@@ -107,26 +108,8 @@ def validate_vdom_json(value: Any) -> VdomJson:
 
 
 def is_vdom(value: Any) -> bool:
-    """Return whether a value is a :class:`VdomDict`
-
-    This employs a very simple heuristic - something is VDOM if:
-
-    1. It is a ``dict`` instance
-    2. It contains the key ``"tagName"``
-    3. The value of the key ``"tagName"`` is a string
-
-    .. note::
-
-        Performing an ``isinstance(value, VdomDict)`` check is too restrictive since the
-        user would be forced to import ``VdomDict`` every time they needed to declare a
-        VDOM element. Giving the user more flexibility, at the cost of this check's
-        accuracy, is worth it.
-    """
-    return (
-        isinstance(value, dict)
-        and "tagName" in value
-        and isinstance(value["tagName"], str)
-    )
+    """Return whether a value is a :class:`VdomDict`"""
+    return isinstance(value, VdomDict)
 
 
 class Vdom:
@@ -137,7 +120,7 @@ def __init__(
         /,
         allow_children: bool = True,
         custom_constructor: CustomVdomConstructor | None = None,
-        **kwargs: Unpack[_VdomDict],
+        **kwargs: Unpack[VdomTypeDict],
     ) -> None:
         """This init method is used to declare the VDOM dictionary default values, as well as configurable properties
         related to the construction of VDOM dictionaries."""
@@ -159,14 +142,14 @@ def __init__(
     @overload
     def __call__(
         self, attributes: VdomAttributes, /, *children: VdomChildren
-    ) -> _VdomDict: ...
+    ) -> VdomDict: ...
 
     @overload
-    def __call__(self, *children: VdomChildren) -> _VdomDict: ...
+    def __call__(self, *children: VdomChildren) -> VdomDict: ...
 
     def __call__(
         self, *attributes_and_children: VdomAttributes | VdomChildren
-    ) -> _VdomDict:
+    ) -> VdomDict:
         """The entry point for the VDOM API, for example reactpy.html(<WE_ARE_HERE>)."""
         attributes, children = separate_attributes_and_children(attributes_and_children)
         key = attributes.pop("key", None)
@@ -198,7 +181,7 @@ def __call__(
         if REACTPY_DEBUG.current:
             self._validate_keys(result.keys())
 
-        return cast(_VdomDict, self.default_values | result)
+        return VdomDict(**(self.default_values | result))  # type: ignore
 
     @staticmethod
     def _validate_keys(keys: Sequence[str] | Iterable[str]) -> None:

src/reactpy/types.py

@@ -11,6 +11,7 @@
     Literal,
     Protocol,
     TypeVar,
+    Unpack,
     overload,
     runtime_checkable,
 )
@@ -780,8 +781,8 @@ class DangerouslySetInnerHTML(TypedDict):
 }
 
 
-class _VdomDict(TypedDict):
-    """Dictionary representation of what the `Vdom` class eventually resolves into."""
+class VdomTypeDict(TypedDict):
+    """TypedDict representation of what the `VdomDict` should look like."""
 
     tagName: str
     key: NotRequired[Key | None]
@@ -791,7 +792,58 @@ class _VdomDict(TypedDict):
     importSource: NotRequired[ImportSourceDict]
 
 
-VdomDict = _VdomDict | dict[str, Any]
+class VdomDict(dict):
+    """A dictionary representing a virtual DOM element."""
+
+    def __init__(self, **kwargs: Unpack[VdomTypeDict]) -> None:
+        invalid_keys = set(kwargs) - ALLOWED_VDOM_KEYS
+        if invalid_keys:
+            msg = f"Invalid keys: {invalid_keys}."
+            raise ValueError(msg)
+
+        super().__init__(**kwargs)
+
+    @overload
+    def __getitem__(self, key: Literal["tagName"]) -> str: ...
+    @overload
+    def __getitem__(self, key: Literal["key"]) -> Key | None: ...
+    @overload
+    def __getitem__(
+        self, key: Literal["children"]
+    ) -> Sequence[ComponentType | VdomChild]: ...
+    @overload
+    def __getitem__(self, key: Literal["attributes"]) -> VdomAttributes: ...
+    @overload
+    def __getitem__(self, key: Literal["eventHandlers"]) -> EventHandlerDict: ...
+    @overload
+    def __getitem__(self, key: Literal["importSource"]) -> ImportSourceDict: ...
+    def __getitem__(self, key: VdomDictKeys) -> Any:
+        return super().__getitem__(key)
+
+    @overload
+    def __setitem__(self, key: Literal["tagName"], value: str) -> None: ...
+    @overload
+    def __setitem__(self, key: Literal["key"], value: Key | None) -> None: ...
+    @overload
+    def __setitem__(
+        self, key: Literal["children"], value: Sequence[ComponentType | VdomChild]
+    ) -> None: ...
+    @overload
+    def __setitem__(
+        self, key: Literal["attributes"], value: VdomAttributes
+    ) -> None: ...
+    @overload
+    def __setitem__(
+        self, key: Literal["eventHandlers"], value: EventHandlerDict
+    ) -> None: ...
+    @overload
+    def __setitem__(
+        self, key: Literal["importSource"], value: ImportSourceDict
+    ) -> None: ...
+    def __setitem__(self, key: VdomDictKeys, value: Any) -> None:
+        if key not in ALLOWED_VDOM_KEYS:
+            raise KeyError(f"Invalid key: {key}")
+        super().__setitem__(key, value)
 
 
 VdomChild: TypeAlias = ComponentType | VdomDict | str | None | Any
@@ -875,14 +927,14 @@ class VdomDictConstructor(Protocol):
     @overload
     def __call__(
         self, attributes: VdomAttributes, /, *children: VdomChildren
-    ) -> VdomDict | dict[str, Any]: ...
+    ) -> VdomDict: ...
 
     @overload
-    def __call__(self, *children: VdomChildren) -> VdomDict | dict[str, Any]: ...
+    def __call__(self, *children: VdomChildren) -> VdomDict: ...
 
     def __call__(
         self, *attributes_and_children: VdomAttributes | VdomChildren
-    ) -> VdomDict | dict[str, Any]: ...
+    ) -> VdomDict: ...
 
 
 class LayoutUpdateMessage(TypedDict):

src/reactpy/widgets.py

@@ -30,7 +30,7 @@ def image(
     base64_value = b64encode(bytes_value).decode()
     src = f"data:image/{format};base64,{base64_value}"
 
-    return {"tagName": "img", "attributes": {"src": src, **(attributes or {})}}
+    return VdomDict(tagName="img", attributes={"src": src, **(attributes or {})})
 
 
 _Value = TypeVar("_Value")

tests/sample.py

@@ -2,11 +2,10 @@
 
 from reactpy import html
 from reactpy.core.component import component
-from reactpy.types import VdomDict
 
 
 @component
-def SampleApp() -> VdomDict:
+def SampleApp():
     return html.div(
         {"id": "sample", "style": {"padding": "15px"}},
         html.h1("Sample Application"),

tests/test_core/test_vdom.py

@@ -7,7 +7,7 @@
 from reactpy.config import REACTPY_DEBUG
 from reactpy.core.events import EventHandler
 from reactpy.core.vdom import Vdom, is_vdom, validate_vdom_json
-from reactpy.types import _VdomDict
+from reactpy.types import VdomDict, VdomTypeDict
 
 FAKE_EVENT_HANDLER = EventHandler(lambda data: None)
 FAKE_EVENT_HANDLER_DICT = {"onEvent": FAKE_EVENT_HANDLER}
@@ -18,13 +18,15 @@
     [
         (False, {}),
         (False, {"tagName": None}),
-        (False, _VdomDict()),
-        (True, {"tagName": ""}),
-        (True, _VdomDict(tagName="")),
+        (False, {"tagName": ""}),
+        (False, VdomTypeDict()),
+        (False, VdomDict()),
+        (True, VdomDict(tagName="")),
+        (True, VdomDict(tagName="div")),
     ],
 )
 def test_is_vdom(result, value):
-    assert is_vdom(value) == result
+    assert result == is_vdom(value)
 
 
 @pytest.mark.parametrize(
@@ -332,3 +334,9 @@ def test_invalid_vdom_keys():
 
     with pytest.raises(ValueError, match="You must specify a 'tagName'*"):
         reactpy.Vdom()
+
+    with pytest.raises(ValueError, match="Invalid keys:*"):
+        reactpy.types.VdomDict(foo="bar")
+
+    with pytest.raises(KeyError, match="Invalid key:*"):
+        reactpy.types.VdomDict()["foo"] = "bar"