syd 1.2.5__tar.gz → 1.2.7__tar.gz

{syd-1.2.5 → syd-1.2.7}/.gitignore

@@ -2,6 +2,7 @@
 _historical/
 _planning/
 local/
+data/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

{syd-1.2.5 → syd-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: syd
-Version: 1.2.5
+Version: 1.2.7
 Summary: A Python package for making GUIs for data science easy.
 Project-URL: Homepage, https://github.com/landoskape/syd
 Author-email: Andrew Landau <andrew+tyler+landau+getridofthisanddtheplusses@gmail.com>
@@ -36,6 +36,7 @@ Description-Content-Type: text/markdown
 [![Documentation Status](https://readthedocs.org/projects/shareyourdata/badge/?version=stable)](https://shareyourdata.readthedocs.io/en/stable/?badge=stable)
 [![codecov](https://codecov.io/gh/landoskape/syd/branch/main/graph/badge.svg)](https://codecov.io/gh/landoskape/syd)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.08447/status.svg)](https://doi.org/10.21105/joss.08447)
 
 
 <div>
@@ -59,8 +60,10 @@ pip install syd
 ## Documentation
 The full documentation is available [here](https://shareyourdata.readthedocs.io/). It includes a quick start guide, a comprehensive tutorial, and an API reference for the different elements of Syd. If you have any questions or want to suggest improvements to the docs, please let us know on the [github issues page](https://github.com/landoskape/syd/issues)!
 
+**For AI agents/LLMs:** A comprehensive skills file ([SKILLS.md](./SKILLS.md)) is available with workflow patterns, parameter reference tables, common gotchas, and best practices for using Syd in other projects.
+
 ## Quick Start
-This is an example of a sine wave viewer which is about as simple as it gets. You can choose which env to use - if you use ``env="notebook"`` then the GUI will deploy as the output of a jupyter cell (this only works in jupyter!). If you use ``env="browser"`` then the GUI will open a page in your default web browser and you can interact with the data there (works in jupyter notebooks and also from python scripts!).
+This is an example of a sine wave viewer which is about as simple as it gets. You can choose where you want to display the viewer. If you use ``viewer.show()`` then the GUI will deploy as the output of a jupyter cell (this only works in jupyter or colab!). If you use ``viewer.share()`` then the GUI will open a page in your default web browser and you can interact with the data there (works in jupyter notebooks and also from python scripts!).
 
 ```python
 import numpy as np
@@ -95,7 +98,9 @@ We have several examples of more complex viewers with detailed explanations in t
 | [Making a Viewer Class](examples/2b-subclass_example.ipynb) | Rewrites the comprehensive example as a class, which is useful when you have complex data processing or callbacks. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/2b-subclass_example.ipynb) |
 | [Data Loading](examples/3-data_loading.ipynb) | Showcases different ways to get your data into a Syd viewer. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/3-data_loading.ipynb) |
 | [Hierarchical Callbacks](examples/4-hierarchical_callbacks.ipynb) | Demonstrates how to handle complicated callback situations. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/4-hierarchical_callbacks.ipynb) |
-
+| [Interactive plots with Seaborn](examples/5-interactive-with-seaborn.ipynb) | Showcases how to use Syd with Seaborn. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/5-interactive-with-seaborn.ipynb) |
+| [Histology Viewer](examples/6-histology-viewer.ipynb) | Showcases how to use Syd to create a histology viewer for viewing histology slides on the fly. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/6-histology-viewer.ipynb) |
+| [Image Labeler](examples/7-image-labeler.ipynb) | Showcases how to use Syd to create an image labeler for annotating images (like ROIs). | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/7-image-labeler.ipynb) |
 
 ### Data loading
 Thinking about how to get data into a Syd viewer can be non-intuitive. For some examples that showcase different ways to get your data into a Syd viewer, check out the [data loading example](examples/3-data_loading.ipynb). Or, if you just want a quick and fast example, check this one out:
@@ -232,16 +237,8 @@ pip install black
 black . # from the root directory of the repo
 ```
 
-## To-Do List
-This section doubles as a checklist for things I think could be useful and _a place to get feedback about what users think is useful_. If you think something in this is critical and should be prioritized, or if you think something is missing, please let me know by submitting an issue on the [github issues page](https://github.com/landoskape/syd/issues).
-- Layout controls
-  - [ ] Add a "save" button that saves the current state of the viewer to a json file
-  - [ ] Add a "load" button that loads the viewer state from a json file
-  - [ ] Add a "freeze" button that allows the user to update state variables without updating the plot until unfreezing
-  - [ ] Add a window for capturing any error messages that might be thrown by the plot function. Maybe we could have a little interface for looking at each one (up to a point) and the user could press a button to throw an error for the traceback. 
-- [ ] Consider "app_deployed" context for each deployer...
-- Export options:
-  - [ ] Export lite: export the viewer as a HTML/Java package that contains an incomplete set of renderings of figures -- using a certain set of parameters.
-  - [ ] Export full: export the viewer in a way that contains the data to give full functionality.
-- [ ] Idea for sharing: https://github.com/analyticalmonk/awesome-neuroscience, https://github.com/fasouto/awesome-dataviz
-- [ ] The handling of value in Selection parameters is kind of weird.... I think we need to think more about what to do for fails!!!!
+## Citing this package
+If you use this package, let us know! It's made to help the community so we're happy to hear about how this has helped (or any suggestions!). 
+If you publish anything that depended on Syd, we'd appreciate if you cite the JOSS paper:
+
+Landau, A., (2025). Syd: A package for making interactive data visualizations in python. Journal of Open Source Software, 10(112), 8447, https://doi.org/10.21105/joss.08447

{syd-1.2.5 → syd-1.2.7}/README.md

@@ -5,6 +5,7 @@
 [![Documentation Status](https://readthedocs.org/projects/shareyourdata/badge/?version=stable)](https://shareyourdata.readthedocs.io/en/stable/?badge=stable)
 [![codecov](https://codecov.io/gh/landoskape/syd/branch/main/graph/badge.svg)](https://codecov.io/gh/landoskape/syd)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.08447/status.svg)](https://doi.org/10.21105/joss.08447)
 
 
 <div>
@@ -28,8 +29,10 @@ pip install syd
 ## Documentation
 The full documentation is available [here](https://shareyourdata.readthedocs.io/). It includes a quick start guide, a comprehensive tutorial, and an API reference for the different elements of Syd. If you have any questions or want to suggest improvements to the docs, please let us know on the [github issues page](https://github.com/landoskape/syd/issues)!
 
+**For AI agents/LLMs:** A comprehensive skills file ([SKILLS.md](./SKILLS.md)) is available with workflow patterns, parameter reference tables, common gotchas, and best practices for using Syd in other projects.
+
 ## Quick Start
-This is an example of a sine wave viewer which is about as simple as it gets. You can choose which env to use - if you use ``env="notebook"`` then the GUI will deploy as the output of a jupyter cell (this only works in jupyter!). If you use ``env="browser"`` then the GUI will open a page in your default web browser and you can interact with the data there (works in jupyter notebooks and also from python scripts!).
+This is an example of a sine wave viewer which is about as simple as it gets. You can choose where you want to display the viewer. If you use ``viewer.show()`` then the GUI will deploy as the output of a jupyter cell (this only works in jupyter or colab!). If you use ``viewer.share()`` then the GUI will open a page in your default web browser and you can interact with the data there (works in jupyter notebooks and also from python scripts!).
 
 ```python
 import numpy as np
@@ -64,7 +67,9 @@ We have several examples of more complex viewers with detailed explanations in t
 | [Making a Viewer Class](examples/2b-subclass_example.ipynb) | Rewrites the comprehensive example as a class, which is useful when you have complex data processing or callbacks. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/2b-subclass_example.ipynb) |
 | [Data Loading](examples/3-data_loading.ipynb) | Showcases different ways to get your data into a Syd viewer. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/3-data_loading.ipynb) |
 | [Hierarchical Callbacks](examples/4-hierarchical_callbacks.ipynb) | Demonstrates how to handle complicated callback situations. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/4-hierarchical_callbacks.ipynb) |
-
+| [Interactive plots with Seaborn](examples/5-interactive-with-seaborn.ipynb) | Showcases how to use Syd with Seaborn. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/5-interactive-with-seaborn.ipynb) |
+| [Histology Viewer](examples/6-histology-viewer.ipynb) | Showcases how to use Syd to create a histology viewer for viewing histology slides on the fly. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/6-histology-viewer.ipynb) |
+| [Image Labeler](examples/7-image-labeler.ipynb) | Showcases how to use Syd to create an image labeler for annotating images (like ROIs). | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/landoskape/syd/blob/main/examples/7-image-labeler.ipynb) |
 
 ### Data loading
 Thinking about how to get data into a Syd viewer can be non-intuitive. For some examples that showcase different ways to get your data into a Syd viewer, check out the [data loading example](examples/3-data_loading.ipynb). Or, if you just want a quick and fast example, check this one out:
@@ -201,16 +206,8 @@ pip install black
 black . # from the root directory of the repo
 ```
 
-## To-Do List
-This section doubles as a checklist for things I think could be useful and _a place to get feedback about what users think is useful_. If you think something in this is critical and should be prioritized, or if you think something is missing, please let me know by submitting an issue on the [github issues page](https://github.com/landoskape/syd/issues).
-- Layout controls
-  - [ ] Add a "save" button that saves the current state of the viewer to a json file
-  - [ ] Add a "load" button that loads the viewer state from a json file
-  - [ ] Add a "freeze" button that allows the user to update state variables without updating the plot until unfreezing
-  - [ ] Add a window for capturing any error messages that might be thrown by the plot function. Maybe we could have a little interface for looking at each one (up to a point) and the user could press a button to throw an error for the traceback. 
-- [ ] Consider "app_deployed" context for each deployer...
-- Export options:
-  - [ ] Export lite: export the viewer as a HTML/Java package that contains an incomplete set of renderings of figures -- using a certain set of parameters.
-  - [ ] Export full: export the viewer in a way that contains the data to give full functionality.
-- [ ] Idea for sharing: https://github.com/analyticalmonk/awesome-neuroscience, https://github.com/fasouto/awesome-dataviz
-- [ ] The handling of value in Selection parameters is kind of weird.... I think we need to think more about what to do for fails!!!!
+## Citing this package
+If you use this package, let us know! It's made to help the community so we're happy to hear about how this has helped (or any suggestions!). 
+If you publish anything that depended on Syd, we'd appreciate if you cite the JOSS paper:
+
+Landau, A., (2025). Syd: A package for making interactive data visualizations in python. Journal of Open Source Software, 10(112), 8447, https://doi.org/10.21105/joss.08447

{syd-1.2.5 → syd-1.2.7}/syd/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.2.5"
+__version__ = "1.2.7"
 
 from .viewer import make_viewer, Viewer
 from .support import show_open_servers, close_servers

{syd-1.2.5 → syd-1.2.7}/syd/flask_deployment/deployer.py

@@ -396,49 +396,14 @@ class FlaskDeployer:
                 "Flask app not built. Call build_layout() before display()."
             )
 
+        print(self.port, self.host)
+
         # Find an available port if none is specified
-        self.port = port or _find_available_port()
         self.host = host or socket.gethostbyname(socket.gethostname())
+        self.port = port or _find_available_port(address=self.host)
         self.url = f"http://{self.host}:{self.port}"
         print(f" * Syd Flask server running on {self.url}")
 
-        # if open_browser:
-
-        #     def wait_until_responsive(url, timeout=self.timeout_threshold):
-        #         start_time = time.time()
-        #         while time.time() - start_time < timeout:
-        #             try:
-        #                 r = requests.get(url, timeout=0.5)
-        #                 if r.status_code == 200:
-        #                     return True
-        #             except requests.exceptions.RequestException:
-        #                 pass
-        #             time.sleep(0.1)
-        #         return False
-
-        #     def open_browser_tab_when_ready():
-        #         if wait_until_responsive(self.url):
-        #             out = webbrowser.open(self.url, new=1, autoraise=True)
-        #         else:
-        #             print(
-        #                 f"Could not open browser: server at {self.url} not responding."
-        #                 f"Increase the timeout_threshold to fix this! It's set to {self.timeout_threshold} seconds."
-        #                 "You can do this from viewer.show(timeout_threshold=...) or in the FlaskDeployer constructor."
-        #                 "Also, this is unexpected so please report this issue on GitHub."
-        #             )
-
-        #     threading.Thread(target=open_browser_tab_when_ready, 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=False,
-        #     use_debugger=self.debug,
-        # )
-
         # 1) Spin up the server thread
         srv_thread = ServerThread(self.host, self.port, self.app, debug=self.debug)
         srv_thread.start()
@@ -460,7 +425,7 @@ class FlaskDeployer:
         """
         Deploy the viewer using Flask.
 
-        Builds components (no-op), layout (Flask app/routes),
+        Builds components, layout (Flask app/routes),
         and then starts the server.
         """
         # build_layout creates the Flask app and routes
@@ -704,14 +669,15 @@ class FlaskDeployer:
             )
 
 
-def _find_available_port(start_port=5000, max_attempts=1000):
+def _find_available_port(
+    start_port=5000,
+    max_attempts=1000,
+    address: str = "127.0.0.1",
+):
     """
     Find an available port starting from start_port.
-    (Identical to original)
     """
     for port in range(start_port, start_port + max_attempts):
-        # 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

{syd-1.2.5 → syd-1.2.7}/syd/viewer.py

@@ -209,7 +209,7 @@ class Viewer:
     def plot(self, state: Dict[str, Any]) -> Figure:
         """Create and return a matplotlib figure.
 
-        This is a placeholder. You must either:
+        Hello user! This is a placeholder that raises a NotImplementedError. You must either:
 
         1. Call set_plot() with your plotting function
         This will look like this:
@@ -249,7 +249,19 @@ class Viewer:
         )
 
     def set_plot(self, func: Callable) -> None:
-        """Set the plot method for the viewer"""
+        """Set the plot method for the viewer.
+
+        For viewers created with make_viewer(), this function is used to set the plot method.
+        The input must be a callable function that takes a state dictionary and returns a matplotlib figure.
+
+        Examples
+        --------
+        >>> def plot(state):
+        >>>     ... generate figure, plot stuff ...
+        >>>     return fig
+        >>> viewer = make_viewer()
+        >>> viewer.set_plot(plot)
+        """
         self.plot = self._prepare_function(func, context="Setting plot:")
 
     def show(
@@ -259,9 +271,25 @@ class Viewer:
         suppress_warnings: bool = True,
         update_threshold: float = 1.0,
     ):
-        """Show the viewer in a notebook
+        """
+        Show the viewer locally in a notebook.
 
-        Same as deploy(env="notebook") except it doesn't return the viewer object.
+        This method displays the viewer in a Jupyter notebook environment with interactive controls.
+
+        Parameters
+        ----------
+        controls_position : {'left', 'top', 'right', 'bottom'}, optional
+            Position of the controls relative to the plot (default is 'left').
+        controls_width_percent : int, optional
+            Width of the controls as a percentage of the total viewer width (default is 20).
+        suppress_warnings : bool, optional
+            If True, suppress warnings during deployment (default is True).
+        update_threshold : float, optional
+            Minimum time in seconds between updates to the viewer (default is 1.0).
+
+        Notes
+        -----
+        This method is equivalent to calling `deploy(env="notebook")` but does not return the viewer object.
         """
         _ = self.deploy(
             env="notebook",
@@ -285,9 +313,37 @@ class Viewer:
         update_threshold: float = 1.0,
         timeout_threshold: float = 10.0,
     ):
-        """Share the viewer on a web browser using Flask
+        """
+        Share the viewer on a web browser using Flask.
 
-        Same as deploy(env="browser") except it doesn't return the viewer object.
+        Parameters
+        ----------
+        controls_position : str, optional
+            Position of the controls relative to the plot (default is 'left').
+        fig_dpi : int, optional
+            Dots per inch for the figure resolution (default is 300).
+        controls_width_percent : int, optional
+            Width of the controls as a percentage of the total viewer width (default is 20).
+        plot_margin_percent : float, optional
+            Margin around the plot as a percentage of the plot size (default is 2.5).
+        suppress_warnings : bool, optional
+            If True, suppress warnings during deployment (default is True).
+        debug : bool, optional
+            If True, run the server in debug mode (default is False).
+        host : str, optional
+            Hostname to use for the server (default is None, which uses 'localhost').
+        port : int, optional
+            Port number to use for the server (default is None, which selects the first available port).
+        open_browser : bool, optional
+            If True, automatically open the web browser to the viewer (default is True).
+        update_threshold : float, optional
+            Minimum time in seconds between updates to the viewer (default is 1.0).
+        timeout_threshold : float, optional
+            Maximum time in seconds to wait for a response before timing out (default is 10.0).
+
+        Notes
+        -----
+        This method is equivalent to calling `deploy(env="browser")` but does not return the viewer object.
         """
         _ = self.deploy(
             env="browser",