maidr 1.4.10__tar.gz → 1.6.0__tar.gz

{maidr-1.4.10 → maidr-1.6.0}/CHANGELOG.md

@@ -1,6 +1,29 @@
 # CHANGELOG
 
 
+## v1.6.0 (2025-08-04)
+
+### Continuous Integration
+
+- Update uv.lock ([#227](https://github.com/xability/py-maidr/pull/227),
+  [`f162971`](https://github.com/xability/py-maidr/commit/f162971f4e2585e055de3c837ce9342b292cb378))
+
+### Features
+
+- Add WSL compatibility for opening HTML files
+  ([#224](https://github.com/xability/py-maidr/pull/224),
+  [`2f2a899`](https://github.com/xability/py-maidr/commit/2f2a899b1df4137db94aeb843099ee6f0df952f0))
+
+
+## v1.5.0 (2025-08-04)
+
+### Features
+
+- Detect if running in a flask app and render in an iframe
+  ([#225](https://github.com/xability/py-maidr/pull/225),
+  [`dcd0e0f`](https://github.com/xability/py-maidr/commit/dcd0e0fb1f7a995e4eb2578e9f67cc31e45171ea))
+
+
 ## v1.4.10 (2025-07-30)
 
 ### Bug Fixes

{maidr-1.4.10 → maidr-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maidr
-Version: 1.4.10
+Version: 1.6.0
 Summary: Multimodal Access and Interactive Data Representations
 Project-URL: Homepage, https://xability.github.io/py-maidr
 Project-URL: Repository, https://github.com/xability/py-maidr
@@ -34,12 +34,14 @@ Provides-Extra: jupyter
 Requires-Dist: ipykernel>=6.0.0; extra == 'jupyter'
 Requires-Dist: jupyter<2,>=1.0.0; extra == 'jupyter'
 Provides-Extra: test
+Requires-Dist: flask>=3.0.0; extra == 'test'
 Requires-Dist: jupyter<2,>=1.0.0; extra == 'test'
 Requires-Dist: matplotlib>=3.8; extra == 'test'
 Requires-Dist: pytest-mock<4,>=3.12.0; extra == 'test'
 Requires-Dist: pytest<8,>=7.3.2; extra == 'test'
 Requires-Dist: seaborn>=0.12; extra == 'test'
 Provides-Extra: visualization
+Requires-Dist: flask>=3.0.0; extra == 'visualization'
 Requires-Dist: matplotlib>=3.8; extra == 'visualization'
 Requires-Dist: seaborn>=0.12; extra == 'visualization'
 Requires-Dist: statsmodels>=0.14.4; extra == 'visualization'

maidr-1.6.0/example/flask/test_flask_app.py

@@ -0,0 +1,71 @@
+import matplotlib
+matplotlib.use('Agg')  # Use non-interactive backend for Flask
+
+from flask import Flask
+import matplotlib.pyplot as plt
+import seaborn as sns
+import maidr
+from maidr.util.environment import Environment
+import logging
+
+# Set up logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+app = Flask(__name__)
+
+@app.route('/')
+def index():
+    # Log environment detection
+    logger.info("=== Environment Detection ===")
+    logger.info(f"is_flask(): {Environment.is_flask()}")
+    logger.info(f"is_notebook(): {Environment.is_notebook()}")
+    logger.info(f"is_shiny(): {Environment.is_shiny()}")
+    logger.info(f"get_renderer(): {Environment.get_renderer()}")
+
+    # Check iframe detection logic
+    use_iframe = True
+    flask_detected = Environment.is_flask()
+    notebook_detected = Environment.is_notebook()
+    shiny_detected = Environment.is_shiny()
+
+    logger.info("=== Iframe Detection Logic ===")
+    logger.info(f"use_iframe: {use_iframe}")
+    logger.info(f"flask_detected: {flask_detected}")
+    logger.info(f"notebook_detected: {notebook_detected}")
+    logger.info(f"shiny_detected: {shiny_detected}")
+    logger.info("Condition: use_iframe and (flask_detected or notebook_detected or shiny_detected)")
+    logger.info(f"Result: {use_iframe and (flask_detected or notebook_detected or shiny_detected)}")
+
+    # Load the penguins dataset
+    penguins = sns.load_dataset("penguins")
+
+    # Create a bar plot showing the average body mass of penguins by species
+    plt.figure(figsize=(10, 6))
+
+    # Create the bar plot and assign to variable
+    bar_plot = sns.barplot(
+        x="species", y="body_mass_g", data=penguins, errorbar="sd", palette="Blues_d"
+    )
+    plt.title("Average Body Mass of Penguins by Species")
+    plt.xlabel("Species")
+    plt.ylabel("Body Mass (g)")
+
+    # Use the user-facing API: maidr.render() with plot object
+    logger.info("=== Using maidr.render() API ===")
+    maidr_html = maidr.render(bar_plot)
+    logger.info(f"Type of maidr.render(): {type(maidr_html)}")
+    logger.info(f"String representation: {str(maidr_html)[:300]}...")
+
+    # Check if the output contains iframe
+    html_str = str(maidr_html)
+    contains_iframe = "<iframe" in html_str.lower()
+    logger.info(f"Contains iframe: {contains_iframe}")
+
+    # Return the maidr HTML directly
+    return str(maidr_html)
+
+if __name__ == '__main__':
+    logger.info("Starting Flask app with logging...")
+    logger.info("Visit http://localhost:5002 to see the maidr plot in Flask")
+    app.run(debug=False, host='0.0.0.0', port=5002)

{maidr-1.4.10 → maidr-1.6.0}/maidr/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.4.10"
+__version__ = "1.6.0"
 
 from .api import close, render, save_html, show, stacked
 from .core import Maidr

{maidr-1.4.10 → maidr-1.6.0}/maidr/core/maidr.py

@@ -7,6 +7,8 @@ import os
 import tempfile
 import uuid
 import webbrowser
+import subprocess
+from pathlib import Path
 from typing import Any, Literal, cast
 
 import matplotlib.pyplot as plt
@@ -137,7 +139,48 @@ class Maidr:
         html_file_path = self.save_html(
             temp_file_path
         )  # This will use use_iframe=False
-        webbrowser.open(f"file://{html_file_path}")
+        if Environment.is_wsl():
+            wsl_distro_name = Environment.get_wsl_distro_name()
+
+            # Validate that WSL distro name is available
+            if not wsl_distro_name:
+                raise ValueError(
+                    "WSL_DISTRO_NAME environment variable is not set or is empty. "
+                    "Cannot construct WSL file URL. Please ensure you are running in a WSL environment."
+                )
+
+            # Ensure html_file_path is an absolute POSIX path for proper WSL URL construction
+            html_file_path = Path(html_file_path).resolve().as_posix()
+
+            url = f"file://wsl$/{wsl_distro_name}{html_file_path}"
+
+            # Try to open the file in Windows using explorer.exe with robust path detection
+            explorer_path = Environment.find_explorer_path()
+            if explorer_path:
+                try:
+                    result = subprocess.run(
+                        [explorer_path, url],
+                        capture_output=True,
+                        text=True,
+                        timeout=10
+                    )
+
+                    if result.returncode == 0:
+                        return
+                    else:
+                        # Fall back to webbrowser.open() if explorer.exe fails
+                        webbrowser.open(url)
+
+                except subprocess.TimeoutExpired:
+                    webbrowser.open(url)
+                except Exception:
+                    # Fall back to webbrowser.open() if explorer.exe fails
+                    webbrowser.open(url)
+            else:
+                webbrowser.open(url)
+
+        else:
+            webbrowser.open(f"file://{html_file_path}")
 
     def _create_html_tag(self, use_iframe: bool = True) -> Tag:
         """Create the MAIDR HTML using HTML tags."""
@@ -311,7 +354,7 @@ class Maidr:
         # Render the plot inside an iframe if in a Jupyter notebook, Google Colab
         # or VSCode notebook. No need for iframe if this is a Quarto document.
         # For TypeScript we will use iframe by default for now
-        if use_iframe and (Environment.is_notebook() or Environment.is_shiny()):
+        if use_iframe and (Environment.is_flask() or Environment.is_notebook() or Environment.is_shiny()):
             unique_id = "iframe_" + Maidr._unique_id()
 
             def generate_iframe_script(unique_id: str) -> str:

{maidr-1.4.10 → maidr-1.6.0}/maidr/util/environment.py

@@ -1,11 +1,51 @@
 import json
 import os
+import subprocess
 import sys
+from typing import Union
 
 
 class Environment:
     _engine = "ts"
 
+    @staticmethod
+    def is_flask() -> bool:
+        """
+        Check if the current environment is a Flask application.
+
+        This method detects Flask applications by checking if Flask's app context
+        is available using `flask.has_app_context()`. The app context is Flask's
+        way of tracking the current application state and is only available when
+        code is running within a Flask application.
+
+        Returns
+        -------
+        bool
+            True if the environment is a Flask application, False otherwise.
+
+        Examples
+        --------
+        >>> from maidr.util.environment import Environment
+        >>> Environment.is_flask()
+        False  # When not in a Flask app
+        """
+        try:
+            # Import Flask's has_app_context function
+            from flask import has_app_context
+
+            # has_app_context() returns True only when code is running within
+            # a Flask application context. This is Flask's built-in mechanism
+            # for detecting if the current execution environment is a Flask app.
+            #
+            # The app context is automatically created by Flask when:
+            # - A Flask app is running (app.run())
+            # - Code is executed within a Flask request context
+            # - The app context is manually pushed
+            return has_app_context()
+        except ImportError:
+            # Flask is not installed, so we're definitely not in a Flask app
+            return False
+
     @staticmethod
     def is_interactive_shell() -> bool:
         """Return True if the environment is an interactive shell."""
@@ -61,6 +101,93 @@ class Environment:
                 return False
         except ImportError:
             return False
+    @staticmethod
+    def is_wsl() -> bool:
+        """
+        Check if the current environment is WSL (Windows Subsystem for Linux).
+
+        This method detects WSL environments by reading the `/proc/version` file
+        and checking for 'microsoft' or 'wsl' keywords in the version string.
+        WSL environments typically contain these identifiers in their kernel version.
+
+        Returns
+        -------
+        bool
+            True if the environment is WSL, False otherwise.
+
+        Examples
+        --------
+        >>> from maidr.util.environment import Environment
+        >>> Environment.is_wsl()
+        False  # When not in WSL
+        """
+        try:
+            with open('/proc/version', 'r') as f:
+                version_info = f.read().lower()
+                if 'microsoft' in version_info or 'wsl' in version_info:
+                    return True
+        except FileNotFoundError:
+            pass
+        return False
+
+    @staticmethod
+    def get_wsl_distro_name() -> str:
+        """
+        Get the WSL distribution name from environment variables.
+
+        This method retrieves the WSL distribution name from the `WSL_DISTRO_NAME`
+        environment variable, which is automatically set by WSL when running
+        in a WSL environment.
+
+        Returns
+        -------
+        str
+            The WSL distribution name (e.g., 'Ubuntu-20.04', 'Debian') if set,
+            otherwise an empty string.
+
+        Examples
+        --------
+        >>> from maidr.util.environment import Environment
+        >>> Environment.get_wsl_distro_name()
+        ''  # When not in WSL or WSL_DISTRO_NAME not set
+        """
+        return os.environ.get('WSL_DISTRO_NAME', '')
+
+    @staticmethod
+    def find_explorer_path() -> Union[str, None]:
+        """
+        Find the correct path to explorer.exe in WSL environment.
+
+        This method checks if explorer.exe is available in the PATH
+        and returns the path if found.
+
+        Returns
+        -------
+        str | None
+            The path to explorer.exe if found, None otherwise.
+
+        Examples
+        --------
+        >>> from maidr.util.environment import Environment
+        >>> Environment.find_explorer_path()
+        '/mnt/c/Windows/explorer.exe'  # When found
+        """
+        # Check if explorer.exe is in PATH
+        try:
+            result = subprocess.run(
+                ['which', 'explorer.exe'],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            if result.returncode == 0:
+                return result.stdout.strip()
+        except Exception:
+            pass
+
+        return None
+
+
 
     @staticmethod
     def get_renderer() -> str:

{maidr-1.4.10 → maidr-1.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "maidr"
-version = "1.4.10"
+version = "1.6.0"
 description = "Multimodal Access and Interactive Data Representations"
 authors = [
     { name = "JooYoung Seo", email = "jseo1005@illinois.edu" },
@@ -55,7 +55,8 @@ dependencies = [
 visualization = [
     "matplotlib>=3.8",
     "seaborn>=0.12",
-    "statsmodels>=0.14.4"
+    "statsmodels>=0.14.4",
+    "flask>=3.0.0"
 ]
 jupyter = [
     "jupyter>=1.0.0,<2",
@@ -67,6 +68,7 @@ test = [
     "jupyter>=1.0.0,<2",
     "pytest>=7.3.2,<8",
     "pytest-mock>=3.12.0,<4",
+    "flask>=3.0.0"
 ]
 
 [project.urls]

{maidr-1.4.10 → maidr-1.6.0}/uv.lock

@@ -199,6 +199,15 @@ css = [
     { name = "tinycss2" },
 ]
 
+[[package]]
+name = "blinker"
+version = "1.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/21/28/9b3f50ce0e048515135495f198351908d99540d69bfdc8c1d15b73dc55ce/blinker-1.9.0.tar.gz", hash = "sha256:b4ce2265a7abece45e7cc896e98dbebe6cead56bcf805a3d23136d145f5445bf", size = 22460, upload-time = "2024-11-08T17:25:47.436Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/10/cb/f2ad4230dc2eb1a74edf38f1a38b9b52277f75bef262d8908e60d957e13c/blinker-1.9.0-py3-none-any.whl", hash = "sha256:ba0efaa9080b619ff2f3459d1d500c57bddea4a6b424b60a91141db6fd2f08bc", size = 8458, upload-time = "2024-11-08T17:25:46.184Z" },
+]
+
 [[package]]
 name = "cachetools"
 version = "6.1.0"
@@ -720,6 +729,25 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4d/36/2a115987e2d8c300a974597416d9de88f2444426de9571f4b59b2cca3acc/filelock-3.18.0-py3-none-any.whl", hash = "sha256:c401f4f8377c4464e6db25fff06205fd89bdd83b65eb0488ed1b160f780e21de", size = 16215, upload-time = "2025-03-14T07:11:39.145Z" },
 ]
 
+[[package]]
+name = "flask"
+version = "3.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "blinker" },
+    { name = "click", version = "8.1.8", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },
+    { name = "click", version = "8.2.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.10'" },
+    { name = "importlib-metadata", marker = "python_full_version < '3.10'" },
+    { name = "itsdangerous" },
+    { name = "jinja2" },
+    { name = "markupsafe" },
+    { name = "werkzeug" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c0/de/e47735752347f4128bcf354e0da07ef311a78244eba9e3dc1d4a5ab21a98/flask-3.1.1.tar.gz", hash = "sha256:284c7b8f2f58cb737f0cf1c30fd7eaf0ccfcde196099d24ecede3fc2005aa59e", size = 753440, upload-time = "2025-05-13T15:01:17.447Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3d/68/9d4508e893976286d2ead7f8f571314af6c2037af34853a30fd769c02e9d/flask-3.1.1-py3-none-any.whl", hash = "sha256:07aae2bb5eaf77993ef57e357491839f5fd9f4dc281593a81a9e4d79a24f295c", size = 103305, upload-time = "2025-05-13T15:01:15.591Z" },
+]
+
 [[package]]
 name = "fonttools"
 version = "4.58.5"
@@ -1059,6 +1087,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7b/55/e5326141505c5d5e34c5e0935d2908a74e4561eca44108fbfb9c13d2911a/isoduration-20.11.0-py3-none-any.whl", hash = "sha256:b2904c2a4228c3d44f409c8ae8e2370eb21a26f7ac2ec5446df141dde3452042", size = 11321, upload-time = "2020-11-01T10:59:58.02Z" },
 ]
 
+[[package]]
+name = "itsdangerous"
+version = "2.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9c/cb/8ac0172223afbccb63986cc25049b154ecfb5e85932587206f42317be31d/itsdangerous-2.2.0.tar.gz", hash = "sha256:e0050c0b7da1eea53ffaf149c0cfbb5c6e2e2b69c4bef22c81fa6eb73e5f6173", size = 54410, upload-time = "2024-04-16T21:28:15.614Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/96/92447566d16df59b2a776c0fb82dbc4d9e07cd95062562af01e408583fc4/itsdangerous-2.2.0-py3-none-any.whl", hash = "sha256:c6242fc49e35958c8b15141343aa660db5fc54d4f13a1db01a3f5891b98700ef", size = 16234, upload-time = "2024-04-16T21:28:14.499Z" },
+]
+
 [[package]]
 name = "jedi"
 version = "0.19.2"
@@ -1638,7 +1675,7 @@ wheels = [
 
 [[package]]
 name = "maidr"
-version = "1.4.9"
+version = "1.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "htmltools" },
@@ -1657,6 +1694,7 @@ jupyter = [
     { name = "jupyter" },
 ]
 test = [
+    { name = "flask" },
     { name = "jupyter" },
     { name = "matplotlib", version = "3.9.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },
     { name = "matplotlib", version = "3.10.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.10'" },
@@ -1665,6 +1703,7 @@ test = [
     { name = "seaborn" },
 ]
 visualization = [
+    { name = "flask" },
     { name = "matplotlib", version = "3.9.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },
     { name = "matplotlib", version = "3.10.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.10'" },
     { name = "seaborn" },
@@ -1684,6 +1723,8 @@ dev = [
 
 [package.metadata]
 requires-dist = [
+    { name = "flask", marker = "extra == 'test'", specifier = ">=3.0.0" },
+    { name = "flask", marker = "extra == 'visualization'", specifier = ">=3.0.0" },
     { name = "htmltools", specifier = ">=0.5" },
     { name = "ipykernel", marker = "extra == 'jupyter'", specifier = ">=6.0.0" },
     { name = "jupyter", marker = "extra == 'jupyter'", specifier = ">=1.0.0,<2" },
@@ -3900,6 +3941,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/5a/84/44687a29792a70e111c5c477230a72c4b957d88d16141199bf9acb7537a3/websocket_client-1.8.0-py3-none-any.whl", hash = "sha256:17b44cc997f5c498e809b22cdf2d9c7a9e71c02c8cc2b6c56e7c2d1239bfa526", size = 58826, upload-time = "2024-04-23T22:16:14.422Z" },
 ]
 
+[[package]]
+name = "werkzeug"
+version = "3.1.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markupsafe" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9f/69/83029f1f6300c5fb2471d621ab06f6ec6b3324685a2ce0f9777fd4a8b71e/werkzeug-3.1.3.tar.gz", hash = "sha256:60723ce945c19328679790e3282cc758aa4a6040e4bb330f53d30fa546d44746", size = 806925, upload-time = "2024-11-08T15:52:18.093Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/52/24/ab44c871b0f07f491e5d2ad12c9bd7358e527510618cb1b803a88e986db1/werkzeug-3.1.3-py3-none-any.whl", hash = "sha256:54b78bf3716d19a65be4fceccc0d1d7b89e608834989dfae50ea87564639213e", size = 224498, upload-time = "2024-11-08T15:52:16.132Z" },
+]
+
 [[package]]
 name = "widgetsnbextension"
 version = "4.0.14"