syd 0.2.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

syd/flask_deployment/deployer.py

@@ -1,26 +1,16 @@
-"""
-Flask deployer for Syd Viewer objects.
-
-This module provides tools to deploy Syd viewers as Flask web applications.
-"""
-
 import os
 import json
 import logging
-from typing import Dict, Any, Optional, List, Union, Callable, Type
+from typing import Dict, Any, Optional
 from dataclasses import dataclass
-from contextlib import contextmanager
 import matplotlib as mpl
 import matplotlib.pyplot as plt
-from matplotlib.figure import Figure
 import io
-import numpy as np
 import time
-from functools import wraps
 import webbrowser
 import threading
 import socket
-
+import warnings
 
 from flask import (
     Flask,
@@ -29,10 +19,10 @@ from flask import (
     make_response,
     jsonify,
     render_template,
-    url_for,
 )
 from werkzeug.serving import run_simple
 
+# Use Deployer base class
 from ..viewer import Viewer
 from ..parameters import (
     Parameter,
@@ -47,42 +37,17 @@ from ..parameters import (
     UnboundedIntegerParameter,
     UnboundedFloatParameter,
     ButtonAction,
-    ParameterType,
-    ActionType,
 )
+from ..support import ParameterUpdateWarning, plot_context
 
 mpl.use("Agg")
 
 
-def debounce(wait_time=0.1):
-    """
-    Decorator to debounce function calls.
-    Prevents a function from being called too frequently.
-    """
-
-    def decorator(fn):
-        last_call_time = [0]
-
-        @wraps(fn)
-        def debounced(*args, **kwargs):
-            current_time = time.time()
-            if current_time - last_call_time[0] > wait_time:
-                last_call_time[0] = current_time
-                return fn(*args, **kwargs)
-            return None
-
-        return debounced
-
-    return decorator
-
-
 @dataclass
 class FlaskLayoutConfig:
     """Configuration for the Flask viewer layout."""
 
     controls_position: str = "left"  # Options are: 'left', 'top', 'right', 'bottom'
-    figure_width: float = 8.0
-    figure_height: float = 6.0
     controls_width_percent: int = 30
 
     def __post_init__(self):
@@ -99,7 +64,7 @@ class FlaskLayoutConfig:
 
 class FlaskDeployer:
     """
-    A deployment system for Viewer as a Flask web application.
+    A deployment system for Viewer as a Flask web application using the Deployer base class.
     Creates a Flask app with routes for the UI, data API, and plot generation.
     """
 
@@ -108,12 +73,12 @@ class FlaskDeployer:
         viewer: Viewer,
         controls_position: str = "left",
         fig_dpi: int = 300,
-        figure_width: float = 8.0,
-        figure_height: float = 6.0,
-        controls_width_percent: int = 30,
-        static_folder: Optional[str] = None,
-        template_folder: Optional[str] = None,
+        controls_width_percent: int = 20,
+        suppress_warnings: bool = True,
         debug: bool = False,
+        host: str = "127.0.0.1",
+        port: Optional[int] = None,
+        open_browser: bool = True,
     ):
         """
         Initialize the Flask deployer.
@@ -127,515 +92,536 @@ class FlaskDeployer:
         fig_dpi : int, optional
             DPI of the figure - higher is better quality but takes longer to generate
         figure_width : float, optional
-            Width of the figure in inches
+            Approximate width for template layout guidance (inches)
         figure_height : float, optional
-            Height of the figure in inches
+            Approximate height for template layout guidance (inches)
         controls_width_percent : int, optional
-            Width of the controls as a percentage of the total width
-        static_folder : str, optional
-            Custom path to static files
-        template_folder : str, optional
-            Custom path to template files
+            Width of the controls panel as a percentage of the total width
+        suppress_warnings : bool, optional
+            Whether to suppress ParameterUpdateWarning during updates
         debug : bool, optional
-            Whether to enable debug mode
+            Whether to enable debug mode for Flask
+        host : str, optional
+            Host address for the server (default: '127.0.0.1')
+        port : int, optional
+            Port for the server. If None, finds an available port (default: None).
+        open_browser : bool, optional
+            Whether to open the web application in a browser tab (default: True).
         """
         self.viewer = viewer
+        self.suppress_warnings = suppress_warnings
+        self._updating = False  # Flag to check circular updates
+
+        # Flask specific configurations
         self.config = FlaskLayoutConfig(
             controls_position=controls_position,
-            figure_width=figure_width,
-            figure_height=figure_height,
             controls_width_percent=controls_width_percent,
         )
         self.fig_dpi = fig_dpi
         self.debug = debug
 
-        # Use default folders if not specified
+        # Determine static and template folder paths
         package_dir = os.path.dirname(os.path.abspath(__file__))
-        self.static_folder = static_folder or os.path.join(package_dir, "static")
-        self.template_folder = template_folder or os.path.join(package_dir, "templates")
-
-        # State tracking
-        self.in_callbacks = False
-
-        # Create Flask app
-        self.app = self.create_app()
-
-    def create_app(self) -> Flask:
-        """
-        Create and configure the Flask application.
+        self.static_folder = os.path.join(package_dir, "static")
+        self.template_folder = os.path.join(package_dir, "templates")
+
+        # Flask app instance - will be created in build_layout
+        self.app: Optional[Flask] = None
+
+        # Server details - will be set in display
+        self.host: Optional[str] = host
+        self.port: Optional[int] = port
+        self.url: Optional[str] = None
+        self.open_browser: bool = open_browser
+
+    def build_layout(self) -> None:
+        """Create and configure the Flask application and its routes."""
+        # Avoid re-building the app if called multiple times
+        if self.app:
+            return
 
-        Returns
-        -------
-        Flask
-            The configured Flask application
-        """
         app = Flask(
-            __name__,
+            "SydFlaskDeployer",
             static_folder=self.static_folder,
             template_folder=self.template_folder,
         )
+        self.app = app
 
         # Configure logging
         if not self.debug:
             log = logging.getLogger("werkzeug")
             log.setLevel(logging.ERROR)
 
-        # Define routes
-
         @app.route("/")
         def home():
-            """Render the main page."""
-            return render_template("index.html", config=self.config)
+            """Render the main page using the index.html template."""
+            # Pass the layout config to the template
+            return render_template("index.html", title="Syd Viewer", config=self.config)
 
         @app.route("/init-data")
         def init_data():
-            """Provide initial parameter information."""
-            param_info = {}
-
-            for name, param in self.viewer.parameters.items():
-                param_info[name] = self._get_parameter_info(param)
-
-            return jsonify({"params": param_info})
+            """Provide initial parameter information to the frontend."""
+            param_info = {
+                name: self._get_parameter_info(param)
+                for name, param in self.viewer.parameters.items()
+            }
+            # Get the order of parameters
+            param_order = list(self.viewer.parameters.keys())
+            # Also include the initial state
+            return jsonify(
+                {
+                    "params": param_info,
+                    "param_order": param_order,
+                    "state": self.viewer.state,
+                }
+            )
 
         @app.route("/plot")
         def plot():
-            """Generate and return a plot based on the current state."""
-            try:
-                # Get parameters from request
-                state = self._parse_request_args(request.args)
+            """Generate and return the plot image based on the current viewer state."""
+            if self._updating:
+                # Avoid plot generation during an update cycle if possible,
+                # though frontend usually waits for update response before fetching plot.
+                # Return a placeholder or error? For now, just proceed.
+                app.logger.warning("Plot requested while parameters are updating.")
 
-                # Update viewer state
-                for name, value in state.items():
-                    if name in self.viewer.parameters:
-                        self.viewer.parameters[name].value = value
-
-                # Get the plot from the viewer
-                with _plot_context():
+            try:
+                # Generate the plot using the current state from the viewer instance
+                # The _plot_context ensures plt state is managed correctly.
+                with plot_context():
+                    # Use the viewer's plot method with its current state
                     fig = self.viewer.plot(self.viewer.state)
+                    if not isinstance(fig, mpl.figure.Figure):
+                        raise TypeError(
+                            f"viewer.plot() must return a matplotlib Figure, but got {type(fig)}"
+                        )
 
                 # Save the plot to a buffer
                 buf = io.BytesIO()
                 fig.savefig(buf, format="png", bbox_inches="tight", dpi=self.fig_dpi)
                 buf.seek(0)
-                plt.close(fig)
+                plt.close(fig)  # Ensure figure is closed
 
-                # Return the image
+                # Return the image as a response
                 response = make_response(send_file(buf, mimetype="image/png"))
-                response.headers["Cache-Control"] = "no-cache"
+                response.headers["Cache-Control"] = (
+                    "no-cache, no-store, must-revalidate"
+                )
+                response.headers["Pragma"] = "no-cache"
+                response.headers["Expires"] = "0"
                 return response
 
             except Exception as e:
-                app.logger.error(f"Error: {str(e)}")
-                return f"Error generating plot: {str(e)}", 500
+                app.logger.error(f"Error generating plot: {str(e)}", exc_info=True)
+                # Return a JSON error for easier frontend handling
+                return jsonify({"error": f"Error generating plot: {str(e)}"}), 500
 
         @app.route("/update-param", methods=["POST"])
         def update_param():
-            """Update a parameter and run its callbacks."""
+            """Handle parameter updates or actions triggered from the frontend."""
+            if self._updating:
+                # Prevent processing new updates if already updating (potential cycle)
+                app.logger.warning(
+                    "Update requested while already processing an update."
+                )
+                # Return current state to avoid frontend hanging.
+                return (
+                    jsonify(
+                        {
+                            "success": False,
+                            "error": "Server busy processing previous update.",
+                            "state": self.viewer.state,
+                        }
+                    ),
+                    429,
+                )  # Too Many Requests
+
             try:
+                self._updating = True  # Set base class flag
+
                 data = request.get_json()
                 name = data.get("name")
-                value = data.get("value")
-                is_action = data.get("action", False)
-
-                if name not in self.viewer.parameters:
-                    return jsonify({"error": f"Parameter {name} not found"}), 404
-
-                # Handle the parameter update or action
-                if is_action:
-                    # For button actions, run the callback
-                    self._handle_action(name)
-                else:
-                    # For normal parameters, update value and run callbacks
-                    parsed_value = self._parse_parameter_value(name, value)
-                    self._handle_parameter_update(name, parsed_value)
-
-                # Return the updated state
-                return jsonify({"success": True, "state": self.viewer.state})
+                value = data.get("value", None)
+                action = data.get("action", False)
+
+                if not name or name not in self.viewer.parameters:
+                    app.logger.error(f"Invalid parameter name received: {name}")
+                    return jsonify({"error": f"Parameter '{name}' not found"}), 404
+
+                parameter = self.viewer.parameters[name]
+
+                # Optionally suppress warnings during updates
+                with warnings.catch_warnings():
+                    if self.suppress_warnings:
+                        warnings.filterwarnings(
+                            "ignore", category=ParameterUpdateWarning
+                        )
+
+                    if action:
+                        # Handle button actions: directly call the callback
+                        if isinstance(parameter, ButtonAction) and parameter.callback:
+                            # Pass the current state dictionary to the callback
+                            parameter.callback(self.viewer.state)
+                        else:
+                            app.logger.warning(
+                                f"Received action request for non-action parameter: {name}"
+                            )
+                    else:
+                        # Handle regular parameter updates: parse and set value
+                        try:
+                            parsed_value = self._parse_parameter_value(name, value)
+                            # Use base class method to set value and trigger callbacks
+                            self.viewer.set_parameter_value(name, parsed_value)
+                        except (ValueError, TypeError, json.JSONDecodeError) as e:
+                            app.logger.error(
+                                f"Error parsing value for parameter '{name}': {e}"
+                            )
+                            return (
+                                jsonify(
+                                    {"error": f"Invalid value format for {name}: {e}"}
+                                ),
+                                400,
+                            )
+
+                # State might have changed due to callbacks, return the *final* state
+                final_state = self.viewer.state
+                final_param_info = {
+                    name: self._get_parameter_info(param)
+                    for name, param in self.viewer.parameters.items()
+                }
+                return jsonify(
+                    {"success": True, "state": final_state, "params": final_param_info}
+                )
 
             except Exception as e:
-                app.logger.error(f"Error updating parameter: {str(e)}")
-                return jsonify({"error": str(e)}), 500
-
-        return app
-
-    @debounce(0.1)
-    def _handle_parameter_update(self, name: str, value: Any) -> None:
-        """
-        Handle a parameter update, including running callbacks.
-
-        Parameters
-        ----------
-        name : str
-            The name of the parameter to update
-        value : Any
-            The new value for the parameter
-        """
-        # Prevent recursive callback cycles
-        if self.in_callbacks:
-            return
-
-        try:
-            # Update the parameter value
-            self.viewer.parameters[name].value = value
+                app.logger.error(
+                    f"Error updating parameter '{name}': {str(e)}", exc_info=True
+                )
+                # Return the state *before* the error if possible? Or just error.
+                return (
+                    jsonify(
+                        {
+                            "error": f"Server error updating parameter: {str(e)}",
+                            "state": self.viewer.state,
+                        }
+                    ),
+                    500,
+                )
+            finally:
+                self._updating = False  # Clear base class flag
+
+    def display(
+        self,
+        host: str = "127.0.0.1",
+        port: Optional[int] = None,
+        open_browser: bool = True,
+        **kwargs,
+    ) -> None:
+        """Starts the Flask development server."""
+        if not self.app:
+            raise RuntimeError(
+                "Flask app not built. Call build_layout() before display()."
+            )
 
-            # Run callbacks for this parameter
-            self.in_callbacks = True
+        # Find an available port if none is specified
+        self.port = port or _find_available_port()
+        self.host = host
+        self.url = f"http://{self.host}:{self.port}"
+        print(f" * Syd Flask server running on {self.url}")
+
+        if open_browser:
+
+            def open_browser_tab():
+                time.sleep(1.0)
+                webbrowser.open(self.url)
+
+            threading.Thread(target=open_browser_tab, daemon=True).start()
+
+        # Run the Flask server using Werkzeug's run_simple
+        # Pass debug status to run_simple for auto-reloading
+        run_simple(
+            self.host,
+            self.port,
+            self.app,
+            use_reloader=self.debug,
+            use_debugger=self.debug,
+            **kwargs,
+        )
 
-            # The viewer's perform_callbacks method will automatically
-            # pass the state dictionary to the callbacks
-            self.viewer.perform_callbacks(name)
-        finally:
-            self.in_callbacks = False
+    # --- Overridden Methods ---
 
-    def _handle_action(self, name: str) -> None:
+    def deploy(self) -> None:
         """
-        Handle a button action by executing its callback.
+        Deploy the viewer using Flask.
 
-        Parameters
-        ----------
-        name : str
-            The name of the button parameter
+        Builds components (no-op), layout (Flask app/routes),
+        and then starts the server.
         """
-        # Prevent recursive callback cycles
-        if self.in_callbacks:
-            return
-
-        try:
-            # Execute the button callback
-            param = self.viewer.parameters[name]
-            if isinstance(param, ButtonAction) and param.callback:
-                self.in_callbacks = True
-
-                # Pass the current state to the callback
-                param.callback(self.viewer.state)
-        finally:
-            self.in_callbacks = False
+        # build_layout creates the Flask app and routes
+        self.build_layout()
+
+        # Initial plot generation is handled implicitly when the first client connects
+        # and requests /plot. We don't need an explicit initial self.update_plot() call here,
+        # though the base class might call it if not overridden. Let's rely on the
+        # frontend fetching the initial plot based on the initial state from /init-data.
+
+        print("Starting Flask server...")
+        # Display starts the server
+        self.display(
+            host=self.host,
+            port=self.port,
+            open_browser=self.open_browser,
+        )
 
     def _get_parameter_info(self, param: Parameter) -> Dict[str, Any]:
         """
         Convert a Parameter object to a dictionary of information for the frontend.
-
-        Parameters
-        ----------
-        param : Parameter
-            The parameter to convert
-
-        Returns
-        -------
-        Dict[str, Any]
-            Parameter information for the frontend
+        (Identical to original, kept for clarity)
         """
+        # Add name/label
+        info = {
+            "name": param.name,
+            "value": param.value,
+        }
+
         if isinstance(param, TextParameter):
-            return {"type": "text", "value": param.value}
+            info.update({"type": "text"})
         elif isinstance(param, BooleanParameter):
-            return {"type": "boolean", "value": param.value}
+            info.update({"type": "boolean"})
         elif isinstance(param, SelectionParameter):
-            return {"type": "selection", "value": param.value, "options": param.options}
+            info.update({"type": "selection", "options": param.options})
         elif isinstance(param, MultipleSelectionParameter):
-            return {
-                "type": "multiple-selection",
-                "value": param.value,
-                "options": param.options,
-            }
+            info.update(
+                {
+                    "type": "multiple-selection",
+                    "options": param.options,
+                }
+            )
         elif isinstance(param, IntegerParameter):
-            return {
-                "type": "integer",
-                "value": param.value,
-                "name": param.name,
-                "min": param.min,
-                "max": param.max,
-            }
+            info.update(
+                {
+                    "type": "integer",
+                    "min": param.min,
+                    "max": param.max,
+                }
+            )
         elif isinstance(param, FloatParameter):
-            return {
-                "type": "float",
-                "value": param.value,
-                "name": param.name,
-                "min": param.min,
-                "max": param.max,
-                "step": param.step,
-            }
+            info.update(
+                {
+                    "type": "float",
+                    "min": param.min,
+                    "max": param.max,
+                    "step": param.step,
+                }
+            )
         elif isinstance(param, IntegerRangeParameter):
-            return {
-                "type": "integer-range",
-                "value": param.value,
-                "name": param.name,
-                "min": param.min,
-                "max": param.max,
-            }
+            info.update(
+                {
+                    "type": "integer-range",
+                    "min": param.min,
+                    "max": param.max,
+                }
+            )
         elif isinstance(param, FloatRangeParameter):
-            return {
-                "type": "float-range",
-                "value": param.value,
-                "name": param.name,
-                "min": param.min,
-                "max": param.max,
-                "step": param.step,
-            }
+            info.update(
+                {
+                    "type": "float-range",
+                    "min": param.min,
+                    "max": param.max,
+                    "step": param.step,
+                }
+            )
         elif isinstance(param, UnboundedIntegerParameter):
-            return {"type": "unbounded-integer", "value": param.value}
+            info.update({"type": "unbounded-integer"})
         elif isinstance(param, UnboundedFloatParameter):
-            return {"type": "unbounded-float", "value": param.value, "step": param.step}
+            info.update({"type": "unbounded-float", "step": param.step})
         elif isinstance(param, ButtonAction):
-            return {"type": "button", "label": param.label, "is_action": True}
+            # Button doesn't have a 'value' in the same way, label is important
+            info.update({"type": "button", "is_action": True})
+            # Remove 'value' as it's not applicable
+            info.pop("value", None)
         else:
-            return {"type": "unknown", "value": str(param.value)}
-
-    def _parse_request_args(self, args) -> Dict[str, Any]:
-        """
-        Parse request arguments into appropriate Python types based on parameter types.
-
-        Parameters
-        ----------
-        args : MultiDict
-            Request arguments
+            # Fallback for unknown types
+            info.update(
+                {"type": "unknown", "value": str(param.value)}
+            )  # Keep value as string
 
-        Returns
-        -------
-        Dict[str, Any]
-            Parsed parameters
-        """
-        result = {}
-
-        for name, value in args.items():
-            # Skip if parameter doesn't exist
-            if name not in self.viewer.parameters:
-                continue
-
-            result[name] = self._parse_parameter_value(name, value)
-
-        return result
+        return info
 
     def _parse_parameter_value(self, name: str, value: Any) -> Any:
         """
-        Parse a parameter value based on its type.
+        Parse a parameter value from the frontend based on its type.
+        Handles type conversions (e.g., string 'true' to bool True, string '5' to int 5).
 
-        Parameters
-        ----------
-        name : str
-            Parameter name
-        value : Any
-            Raw value
-
-        Returns
-        -------
-        Any
-            Parsed value
+        Raises ValueError or TypeError on parsing failure.
         """
-        param = self.viewer.parameters[name]
+        if name not in self.viewer.parameters:
+            # Should not happen if checked before calling, but defensive check
+            raise ValueError(f"Parameter '{name}' not found during parsing.")
 
-        if isinstance(param, TextParameter):
-            return str(value)
-        elif isinstance(param, BooleanParameter):
-            return value.lower() == "true" if isinstance(value, str) else bool(value)
-        elif isinstance(param, (IntegerParameter, UnboundedIntegerParameter)):
-            return int(value)
-        elif isinstance(param, (FloatParameter, UnboundedFloatParameter)):
-            return float(value)
-        elif isinstance(param, (IntegerRangeParameter, FloatRangeParameter)):
-            # Parse JSON array for range parameters
-            if isinstance(value, str):
-                try:
-                    return json.loads(value)
-                except json.JSONDecodeError:
-                    raise ValueError(f"Invalid range format: {value}")
-            return value
-        elif isinstance(param, MultipleSelectionParameter):
-            # Parse JSON array for multiple selection
-            if isinstance(value, str):
-                try:
-                    return json.loads(value)
-                except json.JSONDecodeError:
-                    return [value] if value else []
-            return value
-        elif isinstance(param, SelectionParameter):
-            # For SelectionParameter, we need to handle various type conversion scenarios
+        param = self.viewer.parameters[name]
 
-            # First check if the value is already in options (exact match)
-            if value in param.options:
+        # Handle specific types
+        try:
+            if isinstance(param, TextParameter):
+                return str(value)  # Ensure it's a string
+            elif isinstance(param, BooleanParameter):
+                # Handle 'true'/'false' strings robustly
+                if isinstance(value, str):
+                    if value.lower() == "true":
+                        return True
+                    if value.lower() == "false":
+                        return False
+                    # Try converting string numbers to bool (e.g., "1" -> True)
+                    try:
+                        return bool(int(value))
+                    except ValueError:
+                        pass  # Ignore if not int-like string
+                return bool(value)  # Standard bool conversion
+            elif isinstance(param, (IntegerParameter, UnboundedIntegerParameter)):
+                return int(value)
+            elif isinstance(param, (FloatParameter, UnboundedFloatParameter)):
+                return float(value)
+            elif isinstance(param, (IntegerRangeParameter, FloatRangeParameter)):
+                # Expect a list/tuple from JSON, e.g., [min, max]
+                if isinstance(value, (list, tuple)) and len(value) == 2:
+                    # Ensure types match the parameter type
+                    if isinstance(param, IntegerRangeParameter):
+                        return [int(v) for v in value]
+                    else:  # FloatRangeParameter
+                        return [float(v) for v in value]
+                # Allow JSON string representation '[min, max]'
+                elif isinstance(value, str):
+                    try:
+                        parsed_list = json.loads(value)
+                        if isinstance(parsed_list, list) and len(parsed_list) == 2:
+                            if isinstance(param, IntegerRangeParameter):
+                                return [int(v) for v in parsed_list]
+                            else:
+                                return [float(v) for v in parsed_list]
+                        else:
+                            raise ValueError(
+                                "Range requires a list/tuple of two numbers."
+                            )
+                    except json.JSONDecodeError:
+                        raise ValueError(f"Invalid JSON string for range: {value}")
+                else:
+                    raise ValueError(
+                        f"Invalid format for range parameter '{name}'. Expected list/tuple of two numbers or JSON string."
+                    )
+
+            elif isinstance(param, MultipleSelectionParameter):
+                # Expect a list from JSON, e.g., ['a', 'b']
+                if isinstance(value, list):
+                    # Ensure options are valid? Base Parameter class might do this.
+                    # Return as is for now.
+                    return value
+                # Allow JSON string representation '["a", "b"]'
+                elif isinstance(value, str):
+                    try:
+                        parsed_list = json.loads(value)
+                        if isinstance(parsed_list, list):
+                            return parsed_list
+                        else:  # Allow single non-list value to be wrapped? No, spec is list.
+                            raise ValueError("Multiple selection requires a list.")
+                    except json.JSONDecodeError:
+                        # Handle case where a single string value might be sent for a multi-select
+                        # if the frontend logic is imperfect. Treat as a list with one item?
+                        # Let's be strict for now.
+                        raise ValueError(
+                            f"Invalid JSON string for multiple selection: {value}"
+                        )
+                else:
+                    # If it's not a list or valid JSON string, treat as empty list? Or error?
+                    # Error seems safer.
+                    raise ValueError(
+                        f"Invalid format for multiple selection parameter '{name}'. Expected list or JSON string list."
+                    )
+
+            elif isinstance(param, SelectionParameter):
+                # Value needs to match one of the options *by type* if possible.
+                # The original logic was quite complex. Let's simplify:
+                # Try direct match first.
+                if value in param.options:
+                    return value
+
+                # Try converting the incoming value to the types present in options.
+                option_types = {type(opt) for opt in param.options}
+
+                # Prioritize type conversion based on options
+                if float in option_types:
+                    try:
+                        float_val = float(value)
+                        # Check if float matches any option (handle float inaccuracies)
+                        for opt in param.options:
+                            if (
+                                isinstance(opt, (int, float))
+                                and abs(float_val - float(opt)) < 1e-9
+                            ):
+                                return opt  # Return the original option instance
+                        # If no close match, but float conversion worked, maybe return float_val?
+                        # Let's stick to returning existing options.
+                    except (ValueError, TypeError):
+                        pass
+
+                if int in option_types:
+                    try:
+                        int_val = int(value)
+                        if int_val in param.options:
+                            return int_val
+                    except (ValueError, TypeError):
+                        pass
+
+                if str in option_types:
+                    str_val = str(value)
+                    if str_val in param.options:
+                        return str_val
+
+                # If no match after trying conversions, raise error. Let Parameter handle validation.
+                # Returning the original value might bypass validation.
+                raise ValueError(
+                    f"Value '{value}' is not a valid option for '{name}'. Valid options: {param.options}"
+                )
+
+            elif isinstance(param, ButtonAction):
+                # Actions don't have a value to parse
+                return None  # Or raise error? None seems okay.
+
+            else:
+                # Fallback for unknown - return as is, let Parameter validate
                 return value
 
-            # Handle string conversion if value is a string but options might be numeric
-            if isinstance(value, str):
-                # Try to convert to integer if it looks like an integer
-                if value.isdigit():
-                    int_value = int(value)
-                    if int_value in param.options:
-                        return int_value
-
-                # Try to convert to float if it has a decimal point
-                try:
-                    float_value = float(value)
-                    # Check for direct float match
-                    if float_value in param.options:
-                        return float_value
-
-                    # Check for float equality with integer or other float options
-                    for option in param.options:
-                        if (
-                            isinstance(option, (int, float))
-                            and abs(float_value - float(option)) < 1e-10
-                        ):
-                            return option
-                except ValueError:
-                    pass
-
-            # Handle numeric conversion - when value is numeric but needs type matching
-            if isinstance(value, (int, float)):
-                for option in param.options:
-                    # Convert both to float for comparison to handle int/float mismatches
-                    if (
-                        isinstance(option, (int, float))
-                        and abs(float(value) - float(option)) < 1e-10
-                    ):
-                        return option
-
-                    # Also try string conversion as a fallback
-                    if isinstance(option, str):
-                        try:
-                            if abs(float(value) - float(option)) < 1e-10:
-                                return option
-                        except ValueError:
-                            pass
-
-            # If we couldn't find a match, return the original value (will likely cause an error)
-            return value
-        else:
-            return value
-
-    def run(self, host: str = "127.0.0.1", port: Optional[int] = None, **kwargs):
-        """
-        Run the Flask application server.
-
-        Parameters
-        ----------
-        host : str, optional
-            Host to run the server on
-        port : int, optional
-            Port to run the server on. If None, an available port will be automatically found.
-        **kwargs
-            Additional arguments to pass to app.run()
-        """
-        # Find an available port if none is specified
-        if port is None:
-            port = _find_available_port()
-
-        run_simple(host, port, self.app, use_reloader=self.debug, **kwargs)
+        except (ValueError, TypeError, json.JSONDecodeError) as e:
+            # Re-raise with more context
+            raise ValueError(
+                f"Failed to parse value '{value}' for parameter '{name}' ({type(param).__name__}): {e}"
+            )
 
 
 def _find_available_port(start_port=5000, max_attempts=100):
     """
     Find an available port starting from start_port.
-
-    Parameters
-    ----------
-    start_port : int, optional
-        Port to start searching from
-    max_attempts : int, optional
-        Maximum number of ports to try
-
-    Returns
-    -------
-    int
-        An available port number
-
-    Raises
-    ------
-    RuntimeError
-        If no available port is found after max_attempts
+    (Identical to original)
     """
     for port in range(start_port, start_port + max_attempts):
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-            try:
-                s.bind(("127.0.0.1", port))
+        # Use localhost address explicitly
+        address = "127.0.0.1"
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                # Check if the port is usable
+                s.bind((address, port))
+                # If bind succeeds, the port is available
                 return port
-            except OSError:
+        except OSError as e:
+            # If error is Address already in use, try next port
+            if e.errno == socket.errno.EADDRINUSE:
+                # print(f"Port {port} already in use.") # Optional debug msg
                 continue
+            else:
+                # Re-raise other OS errors
+                raise e
 
+    # If loop finishes without finding a port
     raise RuntimeError(
-        f"Could not find an available port after {max_attempts} attempts starting from {start_port}"
+        f"Could not find an available port between {start_port} and {start_port + max_attempts - 1}"
     )
-
-
-@contextmanager
-def _plot_context():
-    """Context manager for creating matplotlib plots."""
-    try:
-        fig = plt.figure()
-        yield fig
-    finally:
-        plt.close(fig)
-
-
-def deploy_flask(
-    viewer: Viewer,
-    host: str = "127.0.0.1",
-    port: Optional[int] = None,
-    controls_position: str = "left",
-    figure_width: float = 8.0,
-    figure_height: float = 6.0,
-    controls_width_percent: int = 30,
-    debug: bool = False,
-    open_browser: bool = True,
-    **kwargs,
-):
-    """
-    Deploy a Viewer as a Flask web application.
-
-    Parameters
-    ----------
-    viewer : Viewer
-        The viewer to deploy
-    host : str, optional
-        Host to run the server on
-    port : int, optional
-        Port to run the server on. If None, an available port will be automatically found.
-    controls_position : str, optional
-        Position of the controls ('left', 'top', 'right', 'bottom')
-    figure_width : float, optional
-        Width of the figure in inches
-    figure_height : float, optional
-        Height of the figure in inches
-    controls_width_percent : int, optional
-        Width of the controls as a percentage of the total width
-    debug : bool, optional
-        Whether to enable debug mode
-    open_browser : bool, optional
-        Whether to open the browser automatically
-    **kwargs
-        Additional arguments to pass to app.run()
-
-    Returns
-    -------
-    FlaskDeployer
-        The deployer instance
-    """
-    deployer = FlaskDeployer(
-        viewer,
-        controls_position=controls_position,
-        figure_width=figure_width,
-        figure_height=figure_height,
-        controls_width_percent=controls_width_percent,
-        debug=debug,
-    )
-
-    # Find an available port if none is specified
-    if port is None:
-        port = _find_available_port()
-
-    url = f"http://{host}:{port}"
-    print(f"Interactive plot server running on {url}")
-
-    if open_browser:
-        # Open browser in a separate thread after a small delay
-        # to ensure the server has started
-        def open_browser_tab():
-            time.sleep(1.0)  # Short delay to allow server to start
-            webbrowser.open(url)
-
-        threading.Thread(target=open_browser_tab).start()
-
-    # This is included as an argument in some deployers but will break the Flask deployer
-    kwargs.pop("continuous", None)
-    deployer.run(host=host, port=port, **kwargs)
-
-    return deployer