syd 0.1.5__py3-none-any.whl → 0.1.6__py3-none-any.whl

syd/parameters.py

@@ -1,9 +1,21 @@
-from typing import List, Any, Tuple, Generic, TypeVar, Optional, Dict, Callable
-from dataclasses import dataclass
+from typing import (
+    List,
+    Any,
+    Tuple,
+    Generic,
+    TypeVar,
+    Optional,
+    Dict,
+    Callable,
+    Union,
+    Sequence,
+)
+from dataclasses import dataclass, field
 from abc import ABC, abstractmethod
 from enum import Enum
 from copy import deepcopy
 from warnings import warn
+import numpy as np
 
 T = TypeVar("T")
 
@@ -55,6 +67,29 @@ class ParameterUpdateError(Exception):
         )
 
 
+class ParameterUpdateWarning(Warning):
+    """
+    Warning raised when there is a non-critical issue updating a parameter.
+
+    Parameters
+    ----------
+    parameter_name : str
+        Name of the parameter that had the warning
+    parameter_type : str
+        Type of the parameter
+    message : str, optional
+        Additional warning details
+    """
+
+    def __init__(self, parameter_name: str, parameter_type: str, message: str = None):
+        self.parameter_name = parameter_name
+        self.parameter_type = parameter_type
+        super().__init__(
+            f"Warning updating {parameter_type} parameter '{parameter_name}'"
+            + (f": {message}" if message else "")
+        )
+
+
 def get_parameter_attributes(param_class) -> List[str]:
     """
     Get all valid attributes for a parameter class.
@@ -106,6 +141,7 @@ class Parameter(Generic[T], ABC):
 
     name: str
     value: T
+    _is_action: bool = False
 
     @abstractmethod
     def __init__(self, name: str, value: T):
@@ -324,8 +360,8 @@ class SelectionParameter(Parameter[Any]):
         The name of the parameter
     value : Any
         The initially selected value (must be one of the options)
-    options : list
-        List of valid choices that can be selected
+    options : sequence
+        List, tuple, or 1D numpy array of valid choices that can be selected
 
     Examples
     --------
@@ -336,15 +372,56 @@ class SelectionParameter(Parameter[Any]):
     >>> color.value
     'blue'
     >>> color.update({"value": "yellow"})  # This will raise an error
+    >>> # With numpy array
+    >>> import numpy as np
+    >>> numbers = SelectionParameter("number", 1, options=np.array([1, 2, 3]))
+    >>> numbers.value
+    1
     """
 
     options: List[Any]
 
-    def __init__(self, name: str, value: Any, options: List[Any]):
+    def __init__(self, name: str, value: Any, options: Union[List, Tuple]):
         self.name = name
-        self.options = options
+        self.options = self._validate_options(options)
         self._value = self._validate(value)
 
+    def _validate_options(self, options: Any) -> List[Any]:
+        """
+        Validate options and convert to list if necessary.
+
+        Parameters
+        ----------
+        options : list or tuple
+            The options to validate
+
+        Returns
+        -------
+        list
+            Validated list of options
+
+        Raises
+        ------
+        TypeError
+            If options is not a list or tuple
+        ValueError
+            If any option is not hashable
+        """
+        if not isinstance(options, (list, tuple)):
+            raise TypeError(
+                f"Options for parameter {self.name} must be a list or tuple"
+            )
+
+        # Verify all options are hashable (needed for comparison)
+        try:
+            for opt in options:
+                hash(opt)
+        except TypeError as e:
+            raise ValueError(
+                f"All options for parameter {self.name} must be hashable: {str(e)}"
+            )
+        return list(options)
+
     def _validate(self, new_value: Any) -> Any:
         """
         Validate that value is one of the allowed options.
@@ -372,13 +449,14 @@ class SelectionParameter(Parameter[Any]):
         Raises:
             TypeError: If options is not a list or tuple
         """
-        if not isinstance(self.options, (list, tuple)):
-            raise TypeError(
-                f"Options for parameter {self.name} are not a list or tuple: {self.options}"
-            )
+        self.options = self._validate_options(self.options)
         if self.value not in self.options:
             warn(
-                f"Value {self.value} not in options: {self.options}, setting to first option"
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"Value {self.value} not in options: {self.options}, setting to first option",
+                )
             )
             self.value = self.options[0]
 
@@ -398,8 +476,8 @@ class MultipleSelectionParameter(Parameter[List[Any]]):
         The name of the parameter
     value : list
         List of initially selected values (must all be from options)
-    options : list
-        List of valid choices that can be selected
+    options : sequence
+        List, tuple, or 1D numpy array of valid choices that can be selected
 
     Examples
     --------
@@ -408,18 +486,58 @@ class MultipleSelectionParameter(Parameter[List[Any]]):
     ...     options=["cheese", "mushrooms", "pepperoni", "olives"])
     >>> toppings.value
     ['cheese', 'mushrooms']
-    >>> toppings.update({"value": ["cheese", "pepperoni"]})
-    >>> toppings.value
-    ['cheese', 'pepperoni']
+    >>> # With numpy array
+    >>> import numpy as np
+    >>> numbers = MultipleSelectionParameter("numbers",
+    ...     value=[1, 3],
+    ...     options=np.array([1, 2, 3, 4]))
+    >>> numbers.value
+    [1, 3]
     """
 
     options: List[Any]
 
-    def __init__(self, name: str, value: List[Any], options: List[Any]):
+    def __init__(self, name: str, value: List[Any], options: Union[List, Tuple]):
         self.name = name
-        self.options = options
+        self.options = self._validate_options(options)
         self._value = self._validate(value)
 
+    def _validate_options(self, options: Any) -> List[Any]:
+        """
+        Validate options and convert to list if necessary.
+
+        Parameters
+        ----------
+        options : list or tuple
+            The options to validate
+
+        Returns
+        -------
+        list
+            Validated list of options
+
+        Raises
+        ------
+        TypeError
+            If options is not a list or tuple
+        ValueError
+            If any option is not hashable
+        """
+        if not isinstance(options, (list, tuple)):
+            raise TypeError(
+                f"Options for parameter {self.name} must be a list or tuple"
+            )
+
+        # Verify all options are hashable (needed for comparison)
+        try:
+            for opt in options:
+                hash(opt)
+        except TypeError as e:
+            raise ValueError(
+                f"All options for parameter {self.name} must be hashable: {str(e)}"
+            )
+        return list(options)
+
     def _validate(self, new_value: Any) -> List[Any]:
         """
         Validate list of selected values against options.
@@ -446,19 +564,24 @@ class MultipleSelectionParameter(Parameter[List[Any]]):
         return [x for x in self.options if x in new_value]
 
     def _validate_update(self) -> None:
-        if not isinstance(self.options, (list, tuple)):
-            raise TypeError(
-                f"Options for parameter {self.name} are not a list or tuple: {self.options}"
-            )
+        self.options = self._validate_options(self.options)
         if not isinstance(self.value, (list, tuple)):
             warn(
-                f"For parameter {self.name}, value {self.value} is not a list or tuple. Setting to empty list."
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"For parameter {self.name}, value {self.value} is not a list or tuple. Setting to empty list.",
+                )
             )
             self.value = []
         if not all(val in self.options for val in self.value):
             invalid = [val for val in self.value if val not in self.options]
             warn(
-                f"For parameter {self.name}, value {self.value} contains invalid options: {invalid}. Setting to empty list."
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"For parameter {self.name}, value {self.value} contains invalid options: {invalid}. Setting to empty list.",
+                )
             )
             self.value = []
         # Keep only unique values while preserving order based on self.options
@@ -535,10 +658,22 @@ class IntegerParameter(Parameter[int]):
 
         if compare_to_range:
             if new_value < self.min_value:
-                warn(f"Value {new_value} below minimum {self.min_value}, clamping")
+                warn(
+                    ParameterUpdateWarning(
+                        self.name,
+                        type(self).__name__,
+                        f"Value {new_value} below minimum {self.min_value}, clamping",
+                    )
+                )
                 new_value = self.min_value
             if new_value > self.max_value:
-                warn(f"Value {new_value} above maximum {self.max_value}, clamping")
+                warn(
+                    ParameterUpdateWarning(
+                        self.name,
+                        type(self).__name__,
+                        f"Value {new_value} above maximum {self.max_value}, clamping",
+                    )
+                )
                 new_value = self.max_value
         return int(new_value)
 
@@ -559,7 +694,13 @@ class IntegerParameter(Parameter[int]):
                 "IntegerParameter must have both min_value and max_value bounds",
             )
         if self.min_value > self.max_value:
-            warn(f"Min value greater than max value, swapping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"Min value greater than max value, swapping",
+                )
+            )
             self.min_value, self.max_value = self.max_value, self.min_value
         self.value = self._validate(self.value)
 
@@ -651,10 +792,22 @@ class FloatParameter(Parameter[float]):
 
         if compare_to_range:
             if new_value < self.min_value:
-                warn(f"Value {new_value} below minimum {self.min_value}, clamping")
+                warn(
+                    ParameterUpdateWarning(
+                        self.name,
+                        type(self).__name__,
+                        f"Value {new_value} below minimum {self.min_value}, clamping",
+                    )
+                )
                 new_value = self.min_value
             if new_value > self.max_value:
-                warn(f"Value {new_value} above maximum {self.max_value}, clamping")
+                warn(
+                    ParameterUpdateWarning(
+                        self.name,
+                        type(self).__name__,
+                        f"Value {new_value} above maximum {self.max_value}, clamping",
+                    )
+                )
                 new_value = self.max_value
 
         return float(new_value)
@@ -676,7 +829,13 @@ class FloatParameter(Parameter[float]):
                 "FloatParameter must have both min_value and max_value bounds",
             )
         if self.min_value > self.max_value:
-            warn(f"Min value greater than max value, swapping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"Min value greater than max value, swapping",
+                )
+            )
             self.min_value, self.max_value = self.max_value, self.min_value
         self.value = self._validate(self.value)
 
@@ -772,14 +931,32 @@ class IntegerRangeParameter(Parameter[Tuple[int, int]]):
         high = self._validate_single(new_value[1])
 
         if low > high:
-            warn(f"Low value {low} greater than high value {high}, swapping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"Low value {low} greater than high value {high}, swapping",
+                )
+            )
             low, high = high, low
 
         if low < self.min_value:
-            warn(f"Low value {low} below minimum {self.min_value}, clamping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"Low value {low} below minimum {self.min_value}, clamping",
+                )
+            )
             low = self.min_value
         if high > self.max_value:
-            warn(f"High value {high} above maximum {self.max_value}, clamping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"High value {high} above maximum {self.max_value}, clamping",
+                )
+            )
             high = self.max_value
 
         return (low, high)
@@ -801,7 +978,13 @@ class IntegerRangeParameter(Parameter[Tuple[int, int]]):
                 "IntegerRangeParameter must have both min_value and max_value bounds",
             )
         if self.min_value > self.max_value:
-            warn(f"Min value greater than max value, swapping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"Min value greater than max value, swapping",
+                )
+            )
             self.min_value, self.max_value = self.max_value, self.min_value
         self.value = self._validate(self.value)
 
@@ -913,14 +1096,32 @@ class FloatRangeParameter(Parameter[Tuple[float, float]]):
         high = self._validate_single(new_value[1])
 
         if low > high:
-            warn(f"Low value {low} greater than high value {high}, swapping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"Low value {low} greater than high value {high}, swapping",
+                )
+            )
             low, high = high, low
 
         if low < self.min_value:
-            warn(f"Low value {low} below minimum {self.min_value}, clamping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"Low value {low} below minimum {self.min_value}, clamping",
+                )
+            )
             low = self.min_value
         if high > self.max_value:
-            warn(f"High value {high} above maximum {self.max_value}, clamping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"High value {high} above maximum {self.max_value}, clamping",
+                )
+            )
             high = self.max_value
 
         return (low, high)
@@ -942,7 +1143,13 @@ class FloatRangeParameter(Parameter[Tuple[float, float]]):
                 "FloatRangeParameter must have both min_value and max_value bounds",
             )
         if self.min_value > self.max_value:
-            warn(f"Min value greater than max value, swapping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"Min value greater than max value, swapping",
+                )
+            )
             self.min_value, self.max_value = self.max_value, self.min_value
         self.value = self._validate(self.value)
 
@@ -1033,10 +1240,22 @@ class UnboundedIntegerParameter(Parameter[int]):
 
         if compare_to_range:
             if self.min_value is not None and new_value < self.min_value:
-                warn(f"Value {new_value} below minimum {self.min_value}, clamping")
+                warn(
+                    ParameterUpdateWarning(
+                        self.name,
+                        type(self).__name__,
+                        f"Value {new_value} below minimum {self.min_value}, clamping",
+                    )
+                )
                 new_value = self.min_value
             if self.max_value is not None and new_value > self.max_value:
-                warn(f"Value {new_value} above maximum {self.max_value}, clamping")
+                warn(
+                    ParameterUpdateWarning(
+                        self.name,
+                        type(self).__name__,
+                        f"Value {new_value} above maximum {self.max_value}, clamping",
+                    )
+                )
                 new_value = self.max_value
         return int(new_value)
 
@@ -1055,7 +1274,13 @@ class UnboundedIntegerParameter(Parameter[int]):
             and self.max_value is not None
             and self.min_value > self.max_value
         ):
-            warn(f"Min value greater than max value, swapping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"Min value greater than max value, swapping",
+                )
+            )
             self.min_value, self.max_value = self.max_value, self.min_value
         self.value = self._validate(self.value)
 
@@ -1161,10 +1386,22 @@ class UnboundedFloatParameter(Parameter[float]):
 
         if compare_to_range:
             if self.min_value is not None and new_value < self.min_value:
-                warn(f"Value {new_value} below minimum {self.min_value}, clamping")
+                warn(
+                    ParameterUpdateWarning(
+                        self.name,
+                        type(self).__name__,
+                        f"Value {new_value} below minimum {self.min_value}, clamping",
+                    )
+                )
                 new_value = self.min_value
             if self.max_value is not None and new_value > self.max_value:
-                warn(f"Value {new_value} above maximum {self.max_value}, clamping")
+                warn(
+                    ParameterUpdateWarning(
+                        self.name,
+                        type(self).__name__,
+                        f"Value {new_value} above maximum {self.max_value}, clamping",
+                    )
+                )
                 new_value = self.max_value
 
         return float(new_value)
@@ -1184,19 +1421,66 @@ class UnboundedFloatParameter(Parameter[float]):
             and self.max_value is not None
             and self.min_value > self.max_value
         ):
-            warn(f"Min value greater than max value, swapping")
+            warn(
+                ParameterUpdateWarning(
+                    self.name,
+                    type(self).__name__,
+                    f"Min value greater than max value, swapping",
+                )
+            )
             self.min_value, self.max_value = self.max_value, self.min_value
         self.value = self._validate(self.value)
 
 
-class ButtonParameter(Parameter):
-    """A parameter that represents a clickable button."""
+@dataclass(init=False)
+class ButtonAction(Parameter[None]):
+    """
+    Parameter for creating clickable buttons with callbacks.
+
+    Creates a button in the GUI that executes a callback function when clicked.
+    See :meth:`~syd.interactive_viewer.InteractiveViewer.add_button` and
+    :meth:`~syd.interactive_viewer.InteractiveViewer.update_button` for usage.
+
+    Parameters
+    ----------
+    name : str
+        The name of the parameter
+    label : str
+        Text to display on the button
+    callback : callable
+        Function to execute when the button is clicked
+
+    Examples
+    --------
+    >>> def print_hello():
+    ...     print("Hello!")
+    >>> button = ButtonAction("greeting", label="Say Hello", callback=print_hello)
+    >>> button.callback()  # Simulates clicking the button
+    Hello!
+    >>> # Update the button's label and callback
+    >>> def print_goodbye():
+    ...     print("Goodbye!")
+    >>> button.update({"label": "Say Goodbye", "callback": print_goodbye})
+    >>> button.callback()
+    Goodbye!
+
+    Notes
+    -----
+    Unlike other Parameter types, ButtonAction:
+    - Has no value (always None)
+    - Is marked as an action (_is_action = True)
+    - Executes code directly rather than storing state
+    - Cannot be updated through the value property
+    """
 
-    _is_button: bool = True
+    label: str
+    callback: Callable
+    value: None = field(default=None, repr=False)
+    _is_action: bool = field(default=True, repr=False)
 
-    def __init__(self, name: str, label: str, callback: Callable[[], None]):
+    def __init__(self, name: str, label: str, callback: Callable):
         """
-        Initialize a button parameter.
+        Initialize a button.
 
         Args:
             name: Internal name of the parameter
@@ -1206,32 +1490,28 @@ class ButtonParameter(Parameter):
         self.name = name
         self.label = label
         self.callback = callback
-        self._value = None  # Buttons don't have a value in the traditional sense
+        self._value = None
 
-    def update(self, updates: Dict[str, Any]) -> None:
-        """Update the button's label and/or callback."""
-        if "label" in updates:
-            self.label = updates["label"]
-        if "callback" in updates:
-            self.callback = updates["callback"]
-
-    @property
-    def value(self) -> None:
-        """Buttons don't have a value, always returns None."""
-        return self._value
-
-    @value.setter
-    def value(self, _: Any) -> None:
-        """Buttons don't store values."""
-        pass
+    def _validate(self, new_value: Any) -> None:
+        """Validate the button's value."""
+        return None
 
     def _validate_update(self) -> None:
-        """Buttons don't need validation."""
-        pass
-
-    def _validate(self, new_value: Any) -> None:
-        """Buttons don't need validation."""
-        pass
+        """Validate the button's value after updates."""
+        if not callable(self.callback):
+            raise ParameterUpdateError(
+                self.name,
+                type(self).__name__,
+                f"Callback {self.callback} is not callable",
+            )
+        try:
+            str(self.label)
+        except Exception:
+            raise ParameterUpdateError(
+                self.name,
+                type(self).__name__,
+                f"Label {self.label} doesn't have a string representation",
+            )
 
 
 class ParameterType(Enum):
@@ -1247,4 +1527,7 @@ class ParameterType(Enum):
     float_range = FloatRangeParameter
     unbounded_integer = UnboundedIntegerParameter
     unbounded_float = UnboundedFloatParameter
-    button = ButtonParameter
+
+
+class ActionType(Enum):
+    button = ButtonAction