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

syd/interactive_viewer.py

@@ -1,11 +1,12 @@
 from typing import List, Any, Callable, Dict, Tuple, Union, Optional
-from functools import wraps
+from functools import wraps, partial
+import inspect
 from contextlib import contextmanager
-from abc import ABC, abstractmethod
 from matplotlib.figure import Figure
 
 from .parameters import (
     ParameterType,
+    ActionType,
     Parameter,
     ParameterAddError,
     ParameterUpdateError,
@@ -28,7 +29,7 @@ _NO_UPDATE = _NoUpdate()
 
 
 def validate_parameter_operation(
-    operation: str, parameter_type: ParameterType
+    operation: str, parameter_type: Union[ParameterType, ActionType]
 ) -> Callable:
     """
     Decorator that validates parameter operations for the InteractiveViewer class.
@@ -64,14 +65,14 @@ def validate_parameter_operation(
                 "Incorrect use of validate_parameter_operation decorator. Must be called with 'add' or 'update' as the first argument."
             )
 
+        # Validate operation matches method name (add/update)
+        if not func.__name__.startswith(operation):
+            raise ValueError(
+                f"Invalid operation type specified ({operation}) for method {func.__name__}"
+            )
+
         @wraps(func)
         def wrapper(self: "InteractiveViewer", name: Any, *args, **kwargs):
-            # Validate operation matches method name (add/update)
-            if not func.__name__.startswith(operation):
-                raise ValueError(
-                    f"Invalid operation type specified ({operation}) for method {func.__name__}"
-                )
-
             # Validate parameter name is a string
             if not isinstance(name, str):
                 if operation == "add":
@@ -103,8 +104,8 @@ def validate_parameter_operation(
                         parameter_type.name,
                         "Parameter not found - you can only update registered parameters!",
                     )
-                if type(self.parameters[name]) != parameter_type.value:
-                    msg = f"Parameter called {name} was found but is registered as a different parameter type ({type(self.parameters[name])})"
+                if not isinstance(self.parameters[name], parameter_type.value):
+                    msg = f"Parameter called {name} was found but is registered as a different parameter type ({type(self.parameters[name])}). Expecting {parameter_type.value}."
                     raise ParameterUpdateError(name, parameter_type.name, msg)
 
             try:
@@ -122,7 +123,7 @@ def validate_parameter_operation(
     return decorator
 
 
-class InteractiveViewer(ABC):
+class InteractiveViewer:
     """
     Base class for creating interactive matplotlib figures with GUI controls.
 
@@ -184,13 +185,29 @@ class InteractiveViewer(ABC):
         """
         return {name: param.value for name, param in self.parameters.items()}
 
-    @abstractmethod
-    def plot(self, **kwargs) -> Figure:
-        """
-        Create and return a matplotlib figure.
+    def plot(self, state: Dict[str, Any]) -> Figure:
+        """Create and return a matplotlib figure.
+
+        This is a placeholder. You must either:
+
+        1. Call set_plot() with your plotting function
+        This will look like this:
+        >>> def plot(viewer, state):
+        >>>     ... generate figure, plot stuff ...
+        >>>     return fig
+        >>> viewer.set_plot(plot))
+
+        2. Subclass InteractiveViewer and override this method
+        This will look like this:
+        >>> class YourViewer(InteractiveViewer):
+        >>>     def plot(self, state):
+        >>>         ... generate figure, plot stuff ...
+        >>>         return fig
 
-        This method must be implemented in your subclass. It should create a new
-        figure using the current parameter values from self.parameters.
+        Parameters
+        ----------
+        state : dict
+            Current parameter values
 
         Returns
         -------
@@ -200,27 +217,36 @@ class InteractiveViewer(ABC):
         Notes
         -----
         - Create a new figure each time, don't reuse old ones
-        - Access parameter values using self.parameters['name'].value
-        - Return the figure object, don't call plt.show()
+        - Access parameter values using state['param_name']
+        - Access your viewer class using self (or viewer for the set_plot() method)
+        - Return the figure object, don't call plt.show()!
         """
-        raise NotImplementedError("Subclasses must implement the plot method")
+        raise NotImplementedError(
+            "Plot method not implemented. Either subclass "
+            "InteractiveViewer and override plot(), or use "
+            "set_plot() to provide a plotting function."
+        )
+
+    def set_plot(self, func: Callable) -> None:
+        """Set the plot method for the viewer"""
+        self.plot = self._prepare_function(func, context="Setting plot:")
 
     def deploy(self, env: str = "notebook", **kwargs):
         """Deploy the app in a notebook or standalone environment"""
         if env == "notebook":
-            from .notebook_deploy import NotebookDeployment
+            from .notebook_deployment import NotebookDeployment
 
             deployer = NotebookDeployment(self, **kwargs)
             deployer.deploy()
 
-            return deployer
+            return self
         else:
             raise ValueError(
                 f"Unsupported environment: {env}, only 'notebook' is supported right now."
             )
 
     @contextmanager
-    def deploy_app(self):
+    def _deploy_app(self):
         """Internal context manager to control app deployment state"""
         self._app_deployed = True
         try:
@@ -228,6 +254,139 @@ class InteractiveViewer(ABC):
         finally:
             self._app_deployed = False
 
+    def _prepare_function(
+        self,
+        func: Callable,
+        context: Optional[str] = "",
+    ) -> Callable:
+        # Check if func is Callable
+        if not callable(func):
+            raise ValueError(f"Function {func} is not callable")
+
+        # Handle partial functions
+        if isinstance(func, partial):
+            # Create new partial with self as first arg if not already there
+            get_self = (
+                lambda func: hasattr(func.func, "__self__") and func.func.__self__
+            )
+            get_name = lambda func: func.func.__name__
+        else:
+            get_self = lambda func: hasattr(func, "__self__") and func.__self__
+            get_name = lambda func: func.__name__
+
+        # Check if it's a class method
+        class_method = get_self(func) is self.__class__
+        if class_method:
+            raise ValueError(context + "Class methods are not supported.")
+
+        # Check if it's a bound method to another instance other than this one
+        if get_self(func) and get_self(func) is not self:
+            raise ValueError(
+                context + "Bound methods to other instances are not supported."
+            )
+
+        # Get function signature
+        try:
+            params = list(inspect.signature(func).parameters.values())
+        except ValueError:
+            # Handle built-ins or other objects without signatures
+            raise ValueError(context + f"Cannot inspect function signature for {func}")
+
+        # Look through params and check if there are two positional parameters (including self for bound methods)
+        bound_method = get_self(func) is self
+        positional_params = 0 + bound_method
+        optional_part = ""
+        for param in params:
+            # Check if it's a positional parameter. If it is, count it.
+            # As long as we have less than 2 positional parameters, we're good.
+            # When we already have 2 positional parameters, we need to make sure any other positional parameters have defaults.
+            if param.kind in (
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                inspect.Parameter.POSITIONAL_ONLY,
+            ):
+                if positional_params < 2:
+                    positional_params += 1
+                else:
+                    if param.default == inspect.Parameter.empty:
+                        positional_params += 1
+                    else:
+                        optional_part += f", {param.name}={param.default!r}"
+            elif param.kind == inspect.Parameter.VAR_KEYWORD:
+                optional_part += f", **{param.name}"
+            elif param.kind == inspect.Parameter.KEYWORD_ONLY:
+                optional_part += (
+                    f", {param.name}={param.default!r}"
+                    if param.default != inspect.Parameter.empty
+                    else f", {param.name}"
+                )
+
+        if positional_params != 2:
+            func_name = get_name(func)
+            if isinstance(func, partial):
+                func_sig = str(inspect.signature(func))
+                if bound_method:
+                    func_sig = "(" + "self, " + func_sig[1:]
+                msg = (
+                    context
+                    + "\n"
+                    + f"Your partial function '{func_name}' has an incorrect signature.\n"
+                    "Partial functions must have exactly two positional parameters.\n"
+                    "The first parameter should be self -- it corresponds to the viewer.\n"
+                    "The second parameter should be state -- a dictionary of the current state of the viewer.\n"
+                    "\nYour partial function effectivelylooks like this:\n"
+                    f"def {func_name}{func_sig}:\n"
+                    "    ... your function code ..."
+                )
+                raise ValueError(msg)
+
+            if bound_method:
+                original_method = getattr(get_self(func).__class__, get_name(func))
+                func_sig = str(inspect.signature(original_method))
+
+                msg = (
+                    context + "\n"
+                    f"Your bound method '{func_name}{func_sig}' has an incorrect signature.\n"
+                    "Bound methods must have exactly one positional parameter in addition to self.\n"
+                    "The first parameter should be self -- it corresponds to the viewer.\n"
+                    "The second parameter should be state -- a dictionary of the current state of the viewer.\n"
+                    "\nYour method looks like this:\n"
+                    "class YourViewer(InteractiveViewer):\n"
+                    f"    def {func_name}{func_sig}:\n"
+                    "        ... your function code ...\n"
+                    "\nIt should look like this:\n"
+                    "class YourViewer(InteractiveViewer):\n"
+                    f"    def {func_name}(self, state{optional_part}):\n"
+                    "        ... your function code ..."
+                )
+                raise ValueError(msg)
+            else:
+                func_sig = str(inspect.signature(func))
+
+                msg = (
+                    context + "\n"
+                    f"Your function '{func_name}{func_sig}' has an incorrect signature.\n"
+                    "External functions must have exactly two positional parameters.\n"
+                    "The first parameter should be viewer -- it corresponds to the viewer.\n"
+                    "The second parameter should be state -- a dictionary of the current state of the viewer.\n"
+                    "\nYour function looks like this:\n"
+                    f"def {func_name}{func_sig}:\n"
+                    "    ... your function code ...\n"
+                    "\nIt should look like this:\n"
+                    f"def {func_name}(viewer, state{optional_part}):\n"
+                    "    ... your function code ..."
+                )
+                raise ValueError(msg)
+
+        # If not a bound method, wrap it to inject self when called with just the state
+        if bound_method:
+            return func
+
+        @wraps(func)
+        def func_with_self(*args, **kwargs):
+            return func(self, *args, **kwargs)
+
+        return func_with_self
+
     def perform_callbacks(self, name: str) -> bool:
         """Perform callbacks for all parameters that have changed"""
         if self._in_callbacks:
@@ -266,6 +425,11 @@ class InteractiveViewer(ABC):
         if isinstance(parameter_name, str):
             parameter_name = [parameter_name]
 
+        callback = self._prepare_function(
+            callback,
+            context="Setting on_change callback:",
+        )
+
         for param_name in parameter_name:
             if param_name not in self.parameters:
                 raise ValueError(f"Parameter '{param_name}' is not registered!")
@@ -742,7 +906,7 @@ class InteractiveViewer(ABC):
         else:
             self.parameters[name] = new_param
 
-    @validate_parameter_operation("add", ParameterType.button)
+    @validate_parameter_operation("add", ActionType.button)
     def add_button(
         self,
         name: str,
@@ -774,11 +938,12 @@ class InteractiveViewer(ABC):
         """
         try:
 
-            # Wrap the callback to include state as an input argument
-            def wrapped_callback(button):
-                callback(self.get_state())
+            callback = self._prepare_function(
+                callback,
+                context="Setting button callback:",
+            )
 
-            new_param = ParameterType.button.value(name, label, wrapped_callback)
+            new_param = ActionType.button.value(name, label, callback)
         except Exception as e:
             raise ParameterAddError(name, "button", str(e)) from e
         else:
@@ -1228,7 +1393,7 @@ class InteractiveViewer(ABC):
         if updates:
             self.parameters[name].update(updates)
 
-    @validate_parameter_operation("update", ParameterType.button)
+    @validate_parameter_operation("update", ActionType.button)
     def update_button(
         self,
         name: str,
@@ -1240,7 +1405,7 @@ class InteractiveViewer(ABC):
         Update a button parameter's label and/or callback function.
 
         Updates a parameter created by :meth:`~syd.interactive_viewer.InteractiveViewer.add_button`.
-        See :class:`~syd.parameters.ButtonParameter` for details.
+        See :class:`~syd.parameters.ButtonAction` for details.
 
         Parameters
         ----------
@@ -1263,6 +1428,10 @@ class InteractiveViewer(ABC):
         if label is not _NO_UPDATE:
             updates["label"] = label
         if callback is not _NO_UPDATE:
+            callback = self._prepare_function(
+                callback,
+                context="Updating button callback:",
+            )
             updates["callback"] = callback
         if updates:
             self.parameters[name].update(updates)

syd/{notebook_deploy → notebook_deployment}/deployer.py

@@ -4,9 +4,11 @@ from contextlib import contextmanager
 import ipywidgets as widgets
 from IPython.display import display
 import matplotlib.pyplot as plt
+import warnings
+from ..parameters import ParameterUpdateWarning
 
 from ..interactive_viewer import InteractiveViewer
-from .widgets import BaseParameterWidget, create_parameter_widget
+from .widgets import BaseWidget, create_widget
 
 
 @contextmanager
@@ -26,7 +28,6 @@ class LayoutConfig:
     figure_width: float = 8.0
     figure_height: float = 6.0
     controls_width_percent: int = 30
-    continuous_update: bool = False
 
     def __post_init__(self):
         valid_positions = ["left", "top"]
@@ -50,7 +51,8 @@ class NotebookDeployment:
         self,
         viewer: InteractiveViewer,
         layout_config: Optional[LayoutConfig] = None,
-        continuous_update: bool = False,
+        continuous: bool = False,
+        suppress_warnings: bool = False,
     ):
         if not isinstance(viewer, InteractiveViewer):  # type: ignore
             raise TypeError(
@@ -59,10 +61,11 @@ class NotebookDeployment:
 
         self.viewer = viewer
         self.config = layout_config or LayoutConfig()
-        self.continuous_update = continuous_update
+        self.continuous = continuous
+        self.suppress_warnings = suppress_warnings
 
         # Initialize containers
-        self.parameter_widgets: Dict[str, BaseParameterWidget] = {}
+        self.parameter_widgets: Dict[str, BaseWidget] = {}
         self.layout_widgets = self._create_layout_controls()
         self.plot_output = widgets.Output()
 
@@ -82,7 +85,7 @@ class NotebookDeployment:
                 min=20,
                 max=80,
                 description="Controls Width %",
-                continuous_update=True,
+                continuous=True,
                 layout=widgets.Layout(width="95%"),
                 style={"description_width": "initial"},
             )
@@ -95,38 +98,52 @@ class NotebookDeployment:
     def _create_parameter_widgets(self) -> None:
         """Create widget instances for all parameters."""
         for name, param in self.viewer.parameters.items():
-            widget = create_parameter_widget(
+            widget = create_widget(
                 param,
-                continuous_update=self.continuous_update,
+                continuous=self.continuous,
             )
 
             # Store in widget dict
             self.parameter_widgets[name] = widget
 
-    def _handle_parameter_change(self, name: str) -> None:
-        """Handle changes to parameter widgets."""
+    def _handle_widget_engagement(self, name: str) -> None:
+        """Handle engagement with an interactive widget."""
         if self._updating:
+            print(
+                "Already updating -- there's a circular dependency!"
+                "This is probably caused by failing to disable callbacks for a parameter."
+                "It's a bug --- tell the developer on github issues please."
+            )
             return
 
         try:
             self._updating = True
-            widget = self.parameter_widgets[name]
 
-            if hasattr(widget, "_is_button") and widget._is_button:
-                parameter = self.viewer.parameters[name]
-                parameter.callback(parameter)
-            else:
-                self.viewer.set_parameter_value(name, widget.value)
+            # Optionally suppress warnings during parameter updates
+            with warnings.catch_warnings():
+                if self.suppress_warnings:
+                    warnings.filterwarnings("ignore", category=ParameterUpdateWarning)
 
-            # Update any widgets that changed due to dependencies
-            self._sync_widgets_with_state(exclude=name)
+                widget = self.parameter_widgets[name]
 
-            # Update the plot
-            self._update_plot()
+                if widget._is_action:
+                    parameter = self.viewer.parameters[name]
+                    parameter.callback(self.viewer.get_state())
+                else:
+                    self.viewer.set_parameter_value(name, widget.value)
+
+                # Update any widgets that changed due to dependencies
+                self._sync_widgets_with_state(exclude=name)
+
+                # Update the plot
+                self._update_plot()
 
         finally:
             self._updating = False
 
+    def _handle_action(self, name: str) -> None:
+        """Handle actions for parameter widgets."""
+
     def _sync_widgets_with_state(self, exclude: Optional[str] = None) -> None:
         """Sync widget values with viewer state."""
         for name, parameter in self.viewer.parameters.items():
@@ -181,7 +198,7 @@ class NotebookDeployment:
 
         # Set up parameter widgets with their observe callbacks
         for name, widget in self.parameter_widgets.items():
-            widget.observe(lambda change, n=name: self._handle_parameter_change(n))
+            widget.observe(lambda change, n=name: self._handle_widget_engagement(n))
 
         # Create parameter controls section
         param_box = widgets.VBox(
@@ -225,7 +242,7 @@ class NotebookDeployment:
 
     def deploy(self) -> None:
         """Deploy the interactive viewer with proper state management."""
-        with self.viewer.deploy_app():
+        with self.viewer._deploy_app():
             # Create widgets
             self._create_parameter_widgets()