make IDOM_DEBUG_MODE mutable + add Option.subscribe

subscribe() allows users to listen when a mutable option is changed

Author: rmorshea

src/idom/_option.py

@@ -16,16 +16,25 @@ class Option(Generic[_O]):
     def __init__(
         self,
         name: str,
-        default: _O,
+        default: _O | Option[_O],
         mutable: bool = True,
         validator: Callable[[Any], _O] = lambda x: cast(_O, x),
     ) -> None:
         self._name = name
-        self._default = default
         self._mutable = mutable
         self._validator = validator
+        self._subscribers: list[Callable[[_O], None]] = []
+
         if name in os.environ:
             self._current = validator(os.environ[name])
+
+        self._default: _O
+        if isinstance(default, Option):
+            self._default = default.default
+            default.subscribe(lambda value: setattr(self, "_default", value))
+        else:
+            self._default = default
+
         logger.debug(f"{self._name}={self.current}")
 
     @property
@@ -55,6 +64,14 @@ def current(self, new: _O) -> None:
         self.set_current(new)
         return None
 
+    def subscribe(self, handler: Callable[[_O], None]) -> Callable[[_O], None]:
+        """Register a callback that will be triggered when this option changes"""
+        if not self.mutable:
+            raise TypeError("Immutable options cannot be subscribed to.")
+        self._subscribers.append(handler)
+        handler(self.current)
+        return handler
+
     def is_set(self) -> bool:
         """Whether this option has a value other than its default."""
         return hasattr(self, "_current")
@@ -66,8 +83,12 @@ def set_current(self, new: Any) -> None:
         """
         if not self._mutable:
             raise TypeError(f"{self} cannot be modified after initial load")
-        self._current = self._validator(new)
+        old = self.current
+        new = self._current = self._validator(new)
         logger.debug(f"{self._name}={self._current}")
+        if new != old:
+            for sub_func in self._subscribers:
+                sub_func(new)
 
     def set_default(self, new: _O) -> _O:
         """Set the value of this option if not :meth:`Option.is_set`

src/idom/config.py

@@ -13,7 +13,6 @@
 IDOM_DEBUG_MODE = _Option(
     "IDOM_DEBUG_MODE",
     default=False,
-    mutable=False,
     validator=lambda x: bool(int(x)),
 )
 """This immutable option turns on/off debug mode
@@ -27,8 +26,7 @@
 
 IDOM_CHECK_VDOM_SPEC = _Option(
     "IDOM_CHECK_VDOM_SPEC",
-    default=IDOM_DEBUG_MODE.current,
-    mutable=False,
+    default=IDOM_DEBUG_MODE,
     validator=lambda x: bool(int(x)),
 )
 """This immutable option turns on/off checks which ensure VDOM is rendered to spec

src/idom/core/layout.py

@@ -135,23 +135,12 @@ async def render(self) -> LayoutUpdate:
                     f"{model_state_id!r} - component already unmounted"
                 )
             else:
-                return self._create_layout_update(model_state)
-
-    if IDOM_CHECK_VDOM_SPEC.current:
-        # If in debug mode inject a function that ensures all returned updates
-        # contain valid VDOM models. We only do this in debug mode or when this check
-        # is explicitely turned in order to avoid unnecessarily impacting performance.
-
-        _debug_render = render
-
-        @wraps(_debug_render)
-        async def render(self) -> LayoutUpdate:
-            result = await self._debug_render()
-            # Ensure that the model is valid VDOM on each render
-            root_id = self._root_life_cycle_state_id
-            root_model = self._model_states_by_life_cycle_state_id[root_id]
-            validate_vdom_json(root_model.model.current)
-            return result
+                update = self._create_layout_update(model_state)
+                if IDOM_CHECK_VDOM_SPEC.current:
+                    root_id = self._root_life_cycle_state_id
+                    root_model = self._model_states_by_life_cycle_state_id[root_id]
+                    validate_vdom_json(root_model.model.current)
+                return update
 
     def _create_layout_update(self, old_state: _ModelState) -> LayoutUpdate:
         new_state = _copy_component_model_state(old_state)

src/idom/core/vdom.py

@@ -13,6 +13,7 @@
     to_event_handler_function,
 )
 from idom.core.types import (
+    ComponentType,
     EventHandlerDict,
     EventHandlerMapping,
     EventHandlerType,
@@ -295,47 +296,30 @@ def _is_attributes(value: Any) -> bool:
     return isinstance(value, Mapping) and "tagName" not in value
 
 
-if IDOM_DEBUG_MODE.current:
-
-    _debug_is_attributes = _is_attributes
-
-    def _is_attributes(value: Any) -> bool:
-        result = _debug_is_attributes(value)
-        if result and "children" in value:
-            logger.error(f"Reserved key 'children' found in attributes {value}")
-        return result
-
-
 def _is_single_child(value: Any) -> bool:
-    return isinstance(value, (str, Mapping)) or not hasattr(value, "__iter__")
-
-
-if IDOM_DEBUG_MODE.current:
-
-    _debug_is_single_child = _is_single_child
-
-    def _is_single_child(value: Any) -> bool:
-        if _debug_is_single_child(value):
-            return True
-
-        from .types import ComponentType
-
-        if hasattr(value, "__iter__") and not hasattr(value, "__len__"):
-            logger.error(
-                f"Did not verify key-path integrity of children in generator {value} "
-                "- pass a sequence (i.e. list of finite length) in order to verify"
-            )
-        else:
-            for child in value:
-                if isinstance(child, ComponentType) and child.key is None:
-                    logger.error(f"Key not specified for child in list {child}")
-                elif isinstance(child, Mapping) and "key" not in child:
-                    # remove 'children' to reduce log spam
-                    child_copy = {**child, "children": _EllipsisRepr()}
-                    logger.error(f"Key not specified for child in list {child_copy}")
-
-        return False
-
-    class _EllipsisRepr:
-        def __repr__(self) -> str:
-            return "..."
+    if isinstance(value, (str, Mapping)) or not hasattr(value, "__iter__"):
+        return True
+    if IDOM_DEBUG_MODE.current:
+        _validate_child_key_integrity(value)
+    return False
+
+
+def _validate_child_key_integrity(value: Any) -> None:
+    if hasattr(value, "__iter__") and not hasattr(value, "__len__"):
+        logger.error(
+            f"Did not verify key-path integrity of children in generator {value} "
+            "- pass a sequence (i.e. list of finite length) in order to verify"
+        )
+    else:
+        for child in value:
+            if isinstance(child, ComponentType) and child.key is None:
+                logger.error(f"Key not specified for child in list {child}")
+            elif isinstance(child, Mapping) and "key" not in child:
+                # remove 'children' to reduce log spam
+                child_copy = {**child, "children": _EllipsisRepr()}
+                logger.error(f"Key not specified for child in list {child_copy}")
+
+
+class _EllipsisRepr:
+    def __repr__(self) -> str:
+        return "..."

src/idom/logging.py

@@ -10,10 +10,7 @@
         "version": 1,
         "disable_existing_loggers": False,
         "loggers": {
-            "idom": {
-                "level": "DEBUG" if IDOM_DEBUG_MODE.current else "INFO",
-                "handlers": ["console"],
-            },
+            "idom": {"handlers": ["console"]},
         },
         "handlers": {
             "console": {
@@ -37,5 +34,10 @@
 """IDOM's root logger instance"""
 
 
-if IDOM_DEBUG_MODE.current:
-    ROOT_LOGGER.debug("IDOM is in debug mode")
+@IDOM_DEBUG_MODE.subscribe
+def _set_debug_level(debug: bool) -> None:
+    if debug:
+        ROOT_LOGGER.setLevel("DEBUG")
+        ROOT_LOGGER.debug("IDOM is in debug mode")
+    else:
+        ROOT_LOGGER.setLevel("INFO")

src/idom/web/module.py

@@ -35,7 +35,7 @@
 def module_from_url(
     url: str,
     fallback: Optional[Any] = None,
-    resolve_exports: bool = IDOM_DEBUG_MODE.current,
+    resolve_exports: bool | None = None,
     resolve_exports_depth: int = 5,
     unmount_before_update: bool = False,
 ) -> WebModule:
@@ -64,7 +64,11 @@ def module_from_url(
         file=None,
         export_names=(
             resolve_module_exports_from_url(url, resolve_exports_depth)
-            if resolve_exports
+            if (
+                resolve_exports
+                if resolve_exports is not None
+                else IDOM_DEBUG_MODE.current
+            )
             else None
         ),
         unmount_before_update=unmount_before_update,
@@ -79,7 +83,7 @@ def module_from_template(
     package: str,
     cdn: str = "https://esm.sh",
     fallback: Optional[Any] = None,
-    resolve_exports: bool = IDOM_DEBUG_MODE.current,
+    resolve_exports: bool | None = None,
     resolve_exports_depth: int = 5,
     unmount_before_update: bool = False,
 ) -> WebModule:
@@ -153,7 +157,7 @@ def module_from_file(
     name: str,
     file: Union[str, Path],
     fallback: Optional[Any] = None,
-    resolve_exports: bool = IDOM_DEBUG_MODE.current,
+    resolve_exports: bool | None = None,
     resolve_exports_depth: int = 5,
     unmount_before_update: bool = False,
     symlink: bool = False,

tests/test__option.py

@@ -74,3 +74,25 @@ def test_option_set_default():
     assert not opt.is_set()
     assert opt.set_default("new-value") == "new-value"
     assert opt.is_set()
+
+
+def test_cannot_subscribe_immutable_option():
+    opt = Option("A_FAKE_OPTION", "default", mutable=False)
+    with pytest.raises(TypeError, match="Immutable options cannot be subscribed to"):
+        opt.subscribe(lambda value: None)
+
+
+def test_option_subscribe():
+    opt = Option("A_FAKE_OPTION", "default")
+
+    calls = []
+    opt.subscribe(calls.append)
+    assert calls == ["default"]
+
+    opt.current = "default"
+    # value did not change, so no trigger
+    assert calls == ["default"]
+
+    opt.current = "new-1"
+    opt.current = "new-2"
+    assert calls == ["default", "new-1", "new-2"]

tests/test_config.py

@@ -0,0 +1,7 @@
+from idom.config import IDOM_DEBUG_MODE
+
+
+def test_idom_debug_mode_toggle():
+    # just check that nothing breaks
+    IDOM_DEBUG_MODE.current = True
+    IDOM_DEBUG_MODE.current = False