Improve ChoiceElement's options by making them richer and typed better

nicegui/binding.py

@@ -8,9 +8,9 @@
 from collections import defaultdict
 from collections.abc import Iterable, Mapping
 from contextvars import ContextVar
-from typing import TYPE_CHECKING, Any, Callable, Literal, TypeVar
+from typing import TYPE_CHECKING, Any, Callable, Generic, Literal
 
-from typing_extensions import dataclass_transform
+from typing_extensions import TypeVar, dataclass_transform
 
 from . import core
 from .logging import log
@@ -27,7 +27,8 @@
 active_links: list[tuple[Any, str, Any, str, Callable[[Any], Any] | None]] = []
 
 TC = TypeVar('TC', bound=type)
-T = TypeVar('T')
+T = TypeVar('T', default=Any)
+E = TypeVar('E', default=Any)
 
 
 def _has_attribute(obj: object | Mapping, name: str) -> Any:
@@ -203,18 +204,18 @@ def bind(self_obj: Any, self_name: str, other_obj: Any, other_name: str, *,
     bind_to(self_obj, self_name, other_obj, other_name, forward=forward, self_strict=False, other_strict=False)
 
 
-class BindableProperty:
+class BindableProperty(Generic[T, E]):
 
-    def __init__(self, on_change: Callable[..., Any] | None = None) -> None:
+    def __init__(self, on_change: Callable[[E, T], Any] | None = None) -> None:
         self._change_handler = on_change
 
     def __set_name__(self, _, name: str) -> None:
         self.name = name  # pylint: disable=attribute-defined-outside-init
 
-    def __get__(self, owner: Any, _=None) -> Any:
+    def __get__(self, owner: E, _=None) -> T:
         return getattr(owner, '___' + self.name)
 
-    def __set__(self, owner: Any, value: Any) -> None:
+    def __set__(self, owner: E, value: T) -> None:
         has_attr = hasattr(owner, '___' + self.name)
         if not has_attr:
             _make_copyable(type(owner))

nicegui/element_filter.py

@@ -123,9 +123,8 @@ def __iter__(self) -> Iterator[T]:
                     element_contents.append(element.message)
                 if isinstance(element, ChoiceElement):
                     if isinstance(element, Select):
-                        values = element.value if element.multiple else [element.value]
-                        labels = [value if isinstance(element.options, list) else element.options.get(value, '')
-                                  for value in values]
+                        value_options = element.value if isinstance(element.value, tuple) else (element.value,) if element.value else ()
+                        labels = [option.label for option in value_options]
                         element_contents.extend(labels)
                     if not isinstance(element, Select) or element.is_showing_popup:
                         element_contents.extend(element._labels)  # pylint: disable=protected-access

nicegui/elements/choice_element.py

@@ -1,50 +1,111 @@
-from typing import Any, Optional, Union
+import hashlib
+from dataclasses import dataclass
+from typing import Any, Generic, Optional, Union, overload, Iterable  # pylint: disable=unused-import
+
+# NOTE: pylint ignore is for the `Any` import.
+from typing_extensions import TypedDict, TypeVar
 
 from ..events import Handler, ValueChangeEventArguments
 from .mixins.value_element import ValueElement
 
+JsonPrimitive = Union[str, int, float, bool, None]
+P = TypeVar('P', bound=JsonPrimitive)
+V = TypeVar('V')
+T = TypeVar('T', bound='Option[Any, Any]')
+
+class DEFAULT:
+    pass
+
+default = DEFAULT()
+# ^ used as default value in set_options below
+
+@dataclass
+class Option(Generic[P, V]):
+    label: P
+    value: V
+
+    def __post_init__(self) -> None:
+        self.id = hashlib.md5(f'{self.label}{self.value}'.encode()).hexdigest()
+
+    def __str__(self) -> str:
+        return f"{self.__class__.__name__}({self.label}, {self.value})"
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
 
-class ChoiceElement(ValueElement):
+class OptionDict(TypedDict, Generic[P, V]):
+    label: P
+    value: V
+    id: str
+
+
+@overload
+def to_option(v: P) -> Option[P, P]:
+    ...
+
+@overload
+def to_option(v: Option[P, V]) -> Option[P, V]:
+    ...
+
+def to_option(v: Union[P, Option[P, V]]) -> Union[Option[P, V], Option[P, P]]:
+    """Converts a primitive type to an `Option`. If the value is already an `Option`, it will return that option unchanged.
+
+    :param v: The primitive type (`int`, `float`, `str`, `bool`, `None`)
+    """
+    if isinstance(v, Option):
+        return v
+    return Option(label=v, value=v)
+
+
+class ChoiceElement(ValueElement[V], Generic[V, T]):
 
     def __init__(self, *,
                  tag: Optional[str] = None,
-                 options: Union[list, dict],
-                 value: Any,
-                 on_change: Optional[Handler[ValueChangeEventArguments]] = None,
+                 options: Iterable[T],
+                 value: V,
+                 on_change: Optional[Handler[ValueChangeEventArguments[V]]] = None,
                  ) -> None:
-        self.options = options
-        self._values: list[str] = []
-        self._labels: list[str] = []
-        self._update_values_and_labels()
-        if not isinstance(value, list) and value is not None and value not in self._values:
-            raise ValueError(f'Invalid value: {value}')
+        self.value = value
+        self.options = list(options)
+        self._values = [o.value for o in self.options]
+        self._labels = [o.label for o in self.options]
+        self._id_to_option = {o.id: o for o in self.options}
+        if (invalid_values := self._invalid_values(value)):
+            raise ValueError(f'Invalid values: {invalid_values}')
         super().__init__(tag=tag, value=value, on_value_change=on_change)
         self._update_options()
 
+    def _invalid_values(self, value: V) -> tuple[V, ...]:
+        if value is None:
+            return tuple()
+        return tuple(set([value]) - set(self._values))
+
     def _update_values_and_labels(self) -> None:
-        self._values = self.options if isinstance(self.options, list) else list(self.options.keys())
-        self._labels = self.options if isinstance(self.options, list) else list(self.options.values())
+        self._values = [o.value for o in self.options]
+        self._labels = [o.label for o in self.options]
+        self._id_to_option = {o.id: o for o in self.options}
 
     def _update_options(self) -> None:
         before_value = self.value
-        self._props['options'] = [{'value': index, 'label': option} for index, option in enumerate(self._labels)]
-        self._props[self.VALUE_PROP] = self._value_to_model_value(before_value)
-        if not isinstance(before_value, list):  # NOTE: no need to update value in case of multi-select
-            self.value = before_value if before_value in self._values else None
+        self._props['options'] = self.options
+        new_value = self._value_to_model_value(before_value)
+        self._props[self.VALUE_PROP] = new_value
+        self.value = new_value
 
     def update(self) -> None:
         with self._props.suspend_updates():
             self._update_values_and_labels()
             self._update_options()
         super().update()
 
-    def set_options(self, options: Union[list, dict], *, value: Any = ...) -> None:
+    def set_options(self, options: Iterable[T], *, value: Union[V, DEFAULT] = default) -> None:
         """Set the options of this choice element.
 
         :param options: The new options.
         :param value: The new value. If not given, the current value is kept.
         """
-        self.options = options
-        if value is not ...:
-            self.value = value
+        self.options = list(options)
+        if not isinstance(value, DEFAULT):
+            self.value: V = value
         self.update()

nicegui/elements/dark_mode.py

@@ -4,10 +4,10 @@
 from .mixins.value_element import ValueElement
 
 
-class DarkMode(ValueElement, component='dark_mode.js'):
+class DarkMode(ValueElement[Optional[bool]], component='dark_mode.js'):
     VALUE_PROP = 'value'
 
-    def __init__(self, value: Optional[bool] = False, *, on_change: Optional[Handler[ValueChangeEventArguments]] = None) -> None:
+    def __init__(self, value: Optional[bool] = False, *, on_change: Optional[Handler[ValueChangeEventArguments[Optional[bool]]]] = None) -> None:
         """Dark mode
 
         You can use this element to enable, disable or toggle dark mode on the page.

nicegui/elements/mixins/validation_element.py

@@ -4,28 +4,28 @@
 from typing_extensions import Self
 
 from ... import background_tasks, helpers
-from .value_element import ValueElement
+from .value_element import V, ValueElement
 
-ValidationFunction = Callable[[Any], Union[Optional[str], Awaitable[Optional[str]]]]
-ValidationDict = dict[str, Callable[[Any], bool]]
+ValidationFunction = Callable[[V], Union[Optional[str], Awaitable[Optional[str]]]]
+ValidationDict = dict[str, Callable[[V], bool]]
 
 
-class ValidationElement(ValueElement):
+class ValidationElement(ValueElement[V]):
 
-    def __init__(self, validation: Optional[Union[ValidationFunction, ValidationDict]], **kwargs: Any) -> None:
+    def __init__(self, validation: Optional[Union[ValidationFunction[V], ValidationDict[V]]], **kwargs: Any) -> None:
         self._validation = validation
         self._auto_validation = True
         self._error: Optional[str] = None
         super().__init__(**kwargs)
         self._props['error'] = None if validation is None else False  # NOTE: reserve bottom space for error message
 
     @property
-    def validation(self) -> Optional[Union[ValidationFunction, ValidationDict]]:
+    def validation(self) -> Optional[Union[ValidationFunction[V], ValidationDict[V]]]:
         """The validation function or dictionary of validation functions."""
         return self._validation
 
     @validation.setter
-    def validation(self, validation: Optional[Union[ValidationFunction, ValidationDict]]) -> None:
+    def validation(self, validation: Optional[Union[ValidationFunction[V], ValidationDict[V]]]) -> None:
         """Sets the validation function or dictionary of validation functions.
 
         :param validation: validation function or dictionary of validation functions (``None`` to disable validation)

nicegui/elements/mixins/value_element.py

@@ -1,13 +1,15 @@
-from typing import Any, Callable, Optional, cast
+from typing import Any, Callable, Generic, Optional, cast
 
-from typing_extensions import Self
+from typing_extensions import Self, TypeVar
 
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element
 from ...events import GenericEventArguments, Handler, ValueChangeEventArguments, handle_event
 
+V = TypeVar('V')
 
-class ValueElement(Element):
+
+class ValueElement(Element, Generic[V]):
     VALUE_PROP: str = 'model-value'
     '''Name of the prop that holds the value of the element'''
 
@@ -19,12 +21,12 @@ class ValueElement(Element):
     - ``None``: The value is updated automatically by the Vue element.
     '''
 
-    value = BindableProperty(
-        on_change=lambda sender, value: cast(Self, sender)._handle_value_change(value))  # pylint: disable=protected-access
+    value = BindableProperty[V, 'ValueElement[V]'](
+        on_change=lambda sender, value: sender._handle_value_change(value))  # pylint: disable=protected-access
 
     def __init__(self, *,
-                 value: Any,
-                 on_value_change: Optional[Handler[ValueChangeEventArguments]] = None,
+                 value: V,
+                 on_value_change: Optional[Handler[ValueChangeEventArguments[V]]] = None,
                  throttle: float = 0,
                  **kwargs: Any,
                  ) -> None:
@@ -33,15 +35,15 @@ def __init__(self, *,
         self.set_value(value)
         self._props[self.VALUE_PROP] = self._value_to_model_value(value)
         self._props['loopback'] = self.LOOPBACK
-        self._change_handlers: list[Handler[ValueChangeEventArguments]] = [on_value_change] if on_value_change else []
+        self._change_handlers: list[Handler[ValueChangeEventArguments[V]]] = [on_value_change] if on_value_change else []
 
-        def handle_change(e: GenericEventArguments) -> None:
+        def handle_change(e: GenericEventArguments[V]) -> None:
             self._send_update_on_value_change = self.LOOPBACK is True
             self.set_value(self._event_args_to_value(e))
             self._send_update_on_value_change = True
         self.on(f'update:{self.VALUE_PROP}', handle_change, [None], throttle=throttle)
 
-    def on_value_change(self, callback: Handler[ValueChangeEventArguments]) -> Self:
+    def on_value_change(self, callback: Handler[ValueChangeEventArguments[V]]) -> Self:
         """Add a callback to be invoked when the value changes."""
         self._change_handlers.append(callback)
         return self
@@ -111,15 +113,15 @@ def bind_value(self,
              self_strict=False, other_strict=strict)
         return self
 
-    def set_value(self, value: Any) -> None:
+    def set_value(self, value: V) -> None:
         """Set the value of this element.
 
         :param value: The value to set.
         """
         self.value = value
 
-    def _handle_value_change(self, value: Any) -> None:
-        previous_value = self._props.get(self.VALUE_PROP)
+    def _handle_value_change(self, value: V) -> None:
+        previous_value = cast(V, self._props.get(self.VALUE_PROP))
         with self._props.suspend_updates():
             self._props[self.VALUE_PROP] = self._value_to_model_value(value)
         if self._send_update_on_value_change:
@@ -130,11 +132,11 @@ def _handle_value_change(self, value: Any) -> None:
         for handler in self._change_handlers:
             handle_event(handler, args)
 
-    def _event_args_to_value(self, e: GenericEventArguments) -> Any:
+    def _event_args_to_value(self, e: GenericEventArguments[Any]) -> Any:
         return e.args
 
-    def _value_to_model_value(self, value: Any) -> Any:
+    def _value_to_model_value(self, value: V) -> Any:
         return value
 
-    def _value_to_event_value(self, value: Any) -> Any:
+    def _value_to_event_value(self, value: V) -> Any:
         return value

nicegui/elements/radio.py

@@ -1,16 +1,20 @@
-from typing import Any, Optional, Union
+from typing import Any, Generic, Optional, Union, overload
+from typing_extensions import TypeVar
 
 from ..events import GenericEventArguments, Handler, ValueChangeEventArguments
-from .choice_element import ChoiceElement
+from ..helpers import add_docstring_from
+from .choice_element import ChoiceElement, Option, P, to_option
 from .mixins.disableable_element import DisableableElement
 
+V = TypeVar('V')
 
-class Radio(ChoiceElement, DisableableElement):
+
+class Radio(ChoiceElement[Optional[V], Option[P, V]], DisableableElement, Generic[V, P]):
 
     def __init__(self,
-                 options: Union[list, dict], *,
-                 value: Any = None,
-                 on_change: Optional[Handler[ValueChangeEventArguments]] = None,
+                 options: Union[list[P], dict[V, P]], *,
+                 value: Optional[V] = None,
+                 on_change: Optional[Handler[ValueChangeEventArguments[Optional[V]]]] = None,
                  ) -> None:
         """Radio Selection
 
@@ -23,10 +27,39 @@ def __init__(self,
         :param value: the initial value
         :param on_change: callback to execute when selection changes
         """
-        super().__init__(tag='q-option-group', options=options, value=value, on_change=on_change)
+        if isinstance(options, dict):
+            super().__init__(tag='q-option-group', options=[Option(v, k) for k, v in options.items()], value=value, on_change=on_change)
+        else:
+            super().__init__(tag='q-option-group', options=[to_option(v) for v in options], value=value, on_change=on_change)
+
+    def _event_args_to_value(self, e: GenericEventArguments[Optional[V]]) -> Any:
+        return e.args
+
+    def _value_to_model_value(self, value: Optional[V]) -> Optional[V]:
+        return value if value in self._values else None
+
+
+@overload
+def radio(
+    options: list[P], *,
+    value: Optional[P] = ...,
+    on_change: Optional[Handler[ValueChangeEventArguments[Optional[P]]]] = ...,
+) -> Radio[P, P]:
+    ...
 
-    def _event_args_to_value(self, e: GenericEventArguments) -> Any:
-        return self._values[e.args]
+@overload
+def radio(
+    options: dict[V, P], *,
+    value: Optional[V] = ...,
+    on_change: Optional[Handler[ValueChangeEventArguments[Optional[V]]]] = ...,
+) -> Radio[V, P]:
+    ...
 
-    def _value_to_model_value(self, value: Any) -> Any:
-        return self._values.index(value) if value in self._values else None
+# pylint: disable=missing-function-docstring
+@add_docstring_from(Radio.__init__)
+def radio(
+    options: Union[list[P], dict[V, P]], *,
+    value: Optional[V] = None,
+    on_change: Optional[Handler[ValueChangeEventArguments[Optional[V]]]] = None,
+) -> Union[Radio[V, P], Radio[P, P]]:
+    return Radio(options, value=value, on_change=on_change)