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

syd/flask_deployment/testing_principles.md

@@ -0,0 +1,300 @@
+# Testing Principles for SYD Flask Deployment
+
+## Overview
+
+Testing an interactive GUI application like the SYD Flask deployment presents unique challenges. While traditional test suites focus on programmatic API testing, interactive GUIs require a different approach that combines several testing methodologies. This document outlines a comprehensive testing strategy for the SYD Flask deployment.
+
+## Testing Pyramid for Interactive GUIs
+
+For the SYD Flask deployment, we recommend implementing a modified testing pyramid with the following layers:
+
+1. **Unit Tests** - Test isolated components and functions
+2. **Integration Tests** - Test interactions between components
+3. **API Tests** - Test Flask API endpoints
+4. **Headless Browser Tests** - Test GUI interactions programmatically
+5. **Visual Regression Tests** - Ensure UI appearance remains consistent
+6. **Manual Testing Checklists** - Structured human verification
+
+## 1. Unit Tests
+
+### What to Test
+- Individual Flask routes
+- Component HTML generation functions
+- Parameter update handlers
+- State synchronization logic
+- Plot generation utilities
+
+### Implementation Strategy
+```python
+import unittest
+from unittest import mock
+from syd.flask_deployment.deployer import FlaskDeployer
+from syd.flask_deployment.components import create_component
+
+class TestFlaskDeployerComponents(unittest.TestCase):
+    def setUp(self):
+        self.mock_viewer = mock.MagicMock()
+        self.deployer = FlaskDeployer(self.mock_viewer)
+        
+    def test_create_float_component(self):
+        mock_param = mock.MagicMock()
+        mock_param.name = "test_param"
+        mock_param.value = 5.0
+        component = create_component(mock_param)
+        self.assertIn("test_param", component.html)
+        self.assertIn("5.0", component.html)
+```
+
+## 2. Integration Tests
+
+### What to Test
+- Parameter creation to HTML rendering pipeline
+- Parameter update → state sync → component update flow
+- Plot generation and serving workflow
+
+### Implementation Strategy
+```python
+def test_parameter_update_state_sync():
+    # Create real viewer with test parameters
+    viewer = Viewer()
+    viewer.add_float('test_param', value=1.0, min_value=0, max_value=10)
+    
+    # Create deployer with this viewer
+    deployer = FlaskDeployer(viewer)
+    
+    # Update parameter and check if components reflect the change
+    deployer._handle_parameter_update('test_param', 5.0)
+    
+    # Verify component has updated
+    component = deployer.parameter_components['test_param']
+    self.assertEqual(component.value, 5.0)
+```
+
+## 3. API Tests
+
+### What to Test
+- All Flask endpoints (`/`, `/update/<name>`, `/state`, `/plot`)
+- Response formats and status codes
+- Error handling
+- Race conditions with concurrent requests
+
+### Implementation Strategy
+```python
+def test_update_parameter_endpoint():
+    viewer = Viewer()
+    viewer.add_float('test_param', value=1.0, min_value=0, max_value=10)
+    deployer = FlaskDeployer(viewer)
+    app = deployer.app
+    
+    with app.test_client() as client:
+        # Test successful update
+        response = client.post('/update/test_param', 
+                               json={'value': 5.0})
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(viewer.state['test_param'], 5.0)
+        
+        # Test parameter not found
+        response = client.post('/update/nonexistent', 
+                               json={'value': 5.0})
+        self.assertEqual(response.status_code, 404)
+```
+
+## 4. Headless Browser Tests
+
+### What to Test
+- User interactions with the web interface
+- Parameter widget interactions
+- UI updates in response to parameter changes
+- Plot refreshes
+
+### Implementation Strategy
+
+Use Selenium or Playwright to automate browser interactions:
+
+```python
+from selenium import webdriver
+from selenium.webdriver.common.by import By
+
+def test_slider_interaction():
+    # Start the Flask app in a separate thread
+    viewer = create_test_viewer()
+    deployer = FlaskDeployer(viewer)
+    thread = threading.Thread(target=deployer.app.run)
+    thread.daemon = True
+    thread.start()
+    
+    # Use Selenium to interact with the web interface
+    driver = webdriver.Chrome()
+    driver.get('http://localhost:5000')
+    
+    # Find a slider and interact with it
+    slider = driver.find_element(By.ID, 'param_amplitude')
+    slider.send_keys(webdriver.Keys.ARROW_RIGHT * 5)  # Increase value
+    
+    # Verify the plot updates
+    # This requires some way to detect that the plot has changed
+    # Could check the src attribute of the image element changes
+    time.sleep(1)  # Allow time for update
+    plot_src = driver.find_element(By.ID, 'plot').get_attribute('src')
+    self.assertTrue(len(plot_src) > 0)
+    
+    driver.quit()
+```
+
+## 5. Visual Regression Tests
+
+### What to Test
+- UI appearance remains consistent across changes
+- Components render correctly with different values
+- Layout adapts properly to different screen sizes
+
+### Implementation Strategy
+
+Use tools like Percy or BackstopJS to capture and compare screenshots:
+
+```python
+def test_visual_appearance():
+    # Set up test app with standard parameters
+    app = create_standard_test_app()
+    
+    # Use a tool like Percy
+    percy_snapshot(driver, 'Main view')
+    
+    # Change to different layout
+    driver.get('http://localhost:5000?controls_position=right')
+    percy_snapshot(driver, 'Right controls layout')
+    
+    # Test responsive views
+    driver.set_window_size(400, 800)  # Mobile size
+    percy_snapshot(driver, 'Mobile view')
+```
+
+## 6. Manual Testing Checklists
+
+For some aspects of interactive GUI applications, manual testing remains necessary. Create structured checklists for testers:
+
+```markdown
+# Manual Testing Checklist
+
+## Parameter Interactions
+- [ ] Sliders respond smoothly to mouse drag
+- [ ] Number inputs accept keyboard input
+- [ ] Range sliders correctly display and update both values
+- [ ] Toggles switch state when clicked
+- [ ] Dropdowns show all options and select correctly
+
+## Plot Updates
+- [ ] Plot updates immediately after parameter change when continuous=True
+- [ ] Plot updates only after interaction ends when continuous=False
+- [ ] Plot maintains aspect ratio when window is resized
+- [ ] No visual glitches during plot transitions
+
+## Layouts
+- [ ] Test all layouts: left, right, top, bottom
+- [ ] Verify responsive behavior on different screen sizes
+```
+
+## Automated Testing Framework
+
+To bring this all together, we recommend implementing a pytest-based testing framework:
+
+```python
+# conftest.py
+import pytest
+from syd import make_viewer
+import numpy as np
+import matplotlib.pyplot as plt
+
+@pytest.fixture
+def standard_test_viewer():
+    """Create a standard viewer for testing."""
+    viewer = make_viewer()
+    
+    def plot(state):
+        fig, ax = plt.subplots()
+        x = np.linspace(0, 10, 1000)
+        y = state['amplitude'] * np.sin(state['frequency'] * x)
+        ax.plot(x, y)
+        return fig
+        
+    viewer.set_plot(plot)
+    viewer.add_float('amplitude', value=1.0, min_value=0, max_value=2)
+    viewer.add_float('frequency', value=1.0, min_value=0.1, max_value=5)
+    
+    return viewer
+
+@pytest.fixture
+def flask_app(standard_test_viewer):
+    """Create a Flask app for testing."""
+    from syd.flask_deployment.deployer import FlaskDeployer
+    deployer = FlaskDeployer(standard_test_viewer)
+    return deployer.app
+```
+
+## Continuous Integration Setup
+
+Integrate these tests into a CI pipeline:
+
+```yaml
+# .github/workflows/flask-tests.yml
+name: Flask Deployment Tests
+
+on:
+  push:
+    paths:
+      - 'syd/flask_deployment/**'
+      - 'tests/flask/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[test]"
+      - name: Run unit and integration tests
+        run: pytest tests/flask/test_unit_integration.py
+      - name: Run API tests
+        run: pytest tests/flask/test_api.py
+      - name: Set up Chrome WebDriver
+        uses: browser-actions/setup-chrome@latest
+      - name: Run headless browser tests
+        run: pytest tests/flask/test_browser.py
+      - name: Upload visual test artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: visual-test-results
+          path: tests/flask/visual/results
+```
+
+## Practical Implementation Plan
+
+For the SYD Flask deployment, we recommend implementing tests in this order:
+
+1. **Start with Unit Tests** - Focus on individual components and functions
+2. **Add API Tests** - Ensure all endpoints work correctly
+3. **Implement Integration Tests** - Test component interactions
+4. **Add Visual Testing** - Simple screenshot comparisons
+5. **Create Browser Tests** - For critical UI workflows
+
+## Testing Challenges and Solutions
+
+| Challenge | Solution |
+|-----------|----------|
+| Testing real-time updates | Use JavaScript triggers and MutationObserver in browser tests |
+| Asynchronous plot generation | Implement wait utilities with timeouts |
+| Visual inconsistencies across platforms | Use Percy or similar to handle cross-platform rendering |
+| Slow browser tests | Run only critical UI tests in CI, more comprehensive ones nightly |
+| Matplotlib backend differences | Mock or standardize backends during testing |
+
+## Conclusion
+
+Testing an interactive GUI like the SYD Flask deployment requires a multi-layered approach. By combining traditional unit and integration tests with specialized GUI testing tools, we can achieve good test coverage while still accommodating the unique challenges of interactive web applications. The most effective strategy is to automate as much as possible while maintaining a structured approach to manual testing for aspects that are difficult to verify programmatically.
+
+For the initial implementation of the testing framework, focus on establishing solid unit and API tests, as these will provide the foundation for more complex tests and help catch the most common issues early in the development process.

syd/notebook_deployment/__init__.py

@@ -0,0 +1 @@
+from .deployer import NotebookDeployer

syd/{notebook_deploy/deployer.py → notebook_deployment/_ipympl_deployer.py}

@@ -1,12 +1,14 @@
-from typing import Dict, Any, Optional, cast
+from typing import Dict, Any, Optional
 from dataclasses import dataclass
 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 ..viewer import Viewer
+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"]
@@ -40,31 +41,32 @@ class LayoutConfig:
         return self.controls_position == "left"
 
 
-class NotebookDeployment:
+class NotebookDeployer:
     """
-    A deployment system for InteractiveViewer in Jupyter notebooks using ipywidgets.
+    A deployment system for Viewer in Jupyter notebooks using ipywidgets.
     Built around the parameter widget system for clean separation of concerns.
     """
 
     def __init__(
         self,
-        viewer: InteractiveViewer,
+        viewer: Viewer,
         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(
-                f"viewer must be an InteractiveViewer, got {type(viewer).__name__}"
-            )
+        if not isinstance(viewer, Viewer):  # type: ignore
+            raise TypeError(f"viewer must be an Viewer, got {type(viewer).__name__}")
 
         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()
+        self._canvas_widget = None
 
         # Store current figure
         self._current_figure = None
@@ -82,7 +84,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 +97,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.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():
@@ -155,20 +171,25 @@ class NotebookDeployment:
 
     def _update_plot(self) -> None:
         """Update the plot with current state."""
-        state = self.viewer.get_state()
+        state = self.viewer.state
 
         with _plot_context():
             new_fig = self.viewer.plot(state)
             plt.close(self._current_figure)  # Close old figure
             self._current_figure = new_fig
 
-        self._redraw_plot()
+            # Clear previous output and display new figure
+            self.plot_output.clear_output(wait=True)
+            with self.plot_output:
+                # Make sure the canvas is created and displayed
+                if self._canvas_widget is None:
+                    self._canvas_widget = self._current_figure.canvas
+                display(self._current_figure.canvas)
 
     def _redraw_plot(self) -> None:
         """Clear and redraw the plot in the output widget."""
-        self.plot_output.clear_output(wait=True)
-        with self.plot_output:
-            display(self._current_figure)
+        if self._canvas_widget is not None:
+            self._canvas_widget.draw()
 
     def _create_layout(self) -> widgets.Widget:
         """Create the main layout combining controls and plot."""
@@ -181,7 +202,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 +246,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()