maidr 1.3.0__tar.gz → 1.4.1__tar.gz

{maidr-1.3.0 → maidr-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: maidr
-Version: 1.3.0
+Version: 1.4.1
 Summary: Multimodal Access and Interactive Data Representations
 License: GPL-3.0-or-later
 Keywords: accessibility,visualization,sonification,braille,tactile,multimodal,data representation,blind,low vision,visual impairments

{maidr-1.3.0 → maidr-1.4.1}/maidr/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.3.0"
+__version__ = "1.4.1"
 
 from .api import close, render, save_html, show, stacked
 from .core import Maidr
@@ -15,6 +15,7 @@ from .patch import (
     scatterplot,
     regplot,
     kdeplot,
+    mplfinance,
 )
 
 __all__ = [

{maidr-1.3.0 → maidr-1.4.1}/maidr/core/maidr.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
 from datetime import datetime
+import urllib.request
+import urllib.error
+import json
 
 import io
 import json
@@ -22,6 +25,11 @@ from maidr.core.plot import MaidrPlot
 from maidr.util.environment import Environment
 from maidr.util.dedup_utils import deduplicate_smooth_and_line
 
+# Module-level cache for version to avoid repeated API calls
+_MAIDR_VERSION_CACHE: str | None = None
+_MAIDR_VERSION_CACHE_TIME: float = 0.0
+_MAIDR_CACHE_DURATION = 3600  # Cache for 1 hour
+
 
 class Maidr:
     """
@@ -34,6 +42,8 @@ class Maidr:
         The matplotlib figure associated with this instance.
     _plots : list[MaidrPlot]
         A list of MaidrPlot objects which hold additional plot-specific configurations.
+    _cached_version : str | None
+        Cached version of maidr from npm registry to avoid repeated API calls.
 
     Methods
     -------
@@ -271,20 +281,77 @@ class Maidr:
         """Generate a unique identifier string using UUID4."""
         return str(uuid.uuid4())
 
+    @staticmethod
+    def _get_latest_maidr_version() -> str:
+        """
+        Query the npm registry API to get the latest version of maidr with caching.
+
+        Returns
+        -------
+        str
+            The latest version of maidr from npm registry, or 'latest' as fallback.
+        """
+        import time
+
+        global _MAIDR_VERSION_CACHE, _MAIDR_VERSION_CACHE_TIME
+
+        # Check if version fetching is disabled via environment variable
+        if os.getenv("MAIDR_DISABLE_VERSION_FETCH", "").lower() in ("true", "1", "yes"):
+            return "latest"
+
+        current_time = time.time()
+
+        # Check if we have a valid cached version
+        if (
+            _MAIDR_VERSION_CACHE is not None
+            and current_time - _MAIDR_VERSION_CACHE_TIME < _MAIDR_CACHE_DURATION
+        ):
+            return _MAIDR_VERSION_CACHE
+
+        try:
+            # Query npm registry API for maidr package
+            with urllib.request.urlopen(
+                "https://registry.npmjs.org/maidr/latest", timeout=5  # 5 second timeout
+            ) as response:
+                if response.status == 200:
+                    data = json.loads(response.read().decode("utf-8"))
+                    version = data.get("version", "latest")
+
+                    # Cache the successful result
+                    _MAIDR_VERSION_CACHE = version
+                    _MAIDR_VERSION_CACHE_TIME = current_time
+
+                    return version
+
+        except Exception:
+            # Any error - just use latest
+            pass
+
+        # Fallback to 'latest' if API call fails
+        return "latest"
+
+    @staticmethod
+    def clear_version_cache() -> None:
+        """Clear the cached version to force a fresh API call on next request."""
+        global _MAIDR_VERSION_CACHE, _MAIDR_VERSION_CACHE_TIME
+        _MAIDR_VERSION_CACHE = None
+        _MAIDR_VERSION_CACHE_TIME = 0.0
+
     @staticmethod
     def _inject_plot(plot: HTML, maidr: str, maidr_id, use_iframe: bool = True) -> Tag:
         """Embed the plot and associated MAIDR scripts into the HTML structure."""
-        # MAIDR_TS_CDN_URL = "http://localhost:8888/tree/maidr/core/maidr.js"  # DEMO URL
-        MAIDR_TS_CDN_URL = "https://cdn.jsdelivr.net/npm/maidr@latest/dist/maidr.js"
-        # Append a query parameter (using TIMESTAMP) to bust the cache (so that the latest (non-cached) version is always loaded).
-        TIMESTAMP = datetime.now().strftime("%Y%m%d%H%M%S")
+        # Get the latest version from npm registry
+        latest_version = Maidr._get_latest_maidr_version()
+        MAIDR_TS_CDN_URL = (
+            f"https://cdn.jsdelivr.net/npm/maidr@{latest_version}/dist/maidr.js"
+        )
 
         script = f"""
-            if (!document.querySelector('script[src="{MAIDR_TS_CDN_URL}?v={TIMESTAMP}"]'))
+            if (!document.querySelector('script[src="{MAIDR_TS_CDN_URL}"]'))
             {{
                 var script = document.createElement('script');
                 script.type = 'module';
-                script.src = '{MAIDR_TS_CDN_URL}?v={TIMESTAMP}';
+                script.src = '{MAIDR_TS_CDN_URL}';
                 script.addEventListener('load', function() {{
                     window.main();
                 }});
@@ -299,7 +366,7 @@ class Maidr:
         base_html = tags.div(
             tags.link(
                 rel="stylesheet",
-                href="https://cdn.jsdelivr.net/npm/maidr/dist/maidr_style.css",
+                href=f"https://cdn.jsdelivr.net/npm/maidr@{latest_version}/dist/maidr_style.css",
             ),
             tags.script(script, type="text/javascript"),
             tags.div(plot),

maidr-1.4.1/maidr/core/plot/candlestick.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import matplotlib.dates as mdates
+import numpy as np
+from matplotlib.axes import Axes
+from matplotlib.patches import Rectangle
+
+from maidr.core.enum import PlotType
+from maidr.core.plot import MaidrPlot
+from maidr.core.enum.maidr_key import MaidrKey
+from maidr.util.mplfinance_utils import MplfinanceDataExtractor
+
+
+class CandlestickPlot(MaidrPlot):
+    """
+    Specialized candlestick plot class for mplfinance OHLC data.
+
+    This class handles the extraction and processing of candlestick data from mplfinance
+    plots, including proper date conversion and data validation.
+    """
+
+    def __init__(self, axes: list[Axes], **kwargs) -> None:
+        """
+        Initialize the CandlestickPlot.
+
+        Parameters
+        ----------
+        axes : list[Axes]
+            A list of Matplotlib Axes objects. Expected to contain at least
+            one Axes for OHLC data, and optionally a second for volume data.
+        **kwargs : dict
+            Additional keyword arguments.
+        """
+        self.axes = axes
+        # Ensure there's at least one axis for the superclass init
+        if not axes:
+            raise ValueError("Axes list cannot be empty.")
+        super().__init__(axes[0], PlotType.CANDLESTICK)
+
+        # Store custom collections passed from mplfinance patch
+        self._maidr_wick_collection = kwargs.get("_maidr_wick_collection", None)
+        self._maidr_body_collection = kwargs.get("_maidr_body_collection", None)
+        self._maidr_date_nums = kwargs.get("_maidr_date_nums", None)
+
+        # Store the GID for proper selector generation
+        self._maidr_gid = None
+        if self._maidr_body_collection:
+            self._maidr_gid = self._maidr_body_collection.get_gid()
+        elif self._maidr_wick_collection:
+            self._maidr_gid = self._maidr_wick_collection.get_gid()
+
+    def _extract_plot_data(self) -> list[dict]:
+        """Extract candlestick data from the plot."""
+
+        # Get the custom collections from kwargs
+        body_collection = self._maidr_body_collection
+        wick_collection = self._maidr_wick_collection
+
+        if body_collection and wick_collection:
+            # Store the GID from the body collection for highlighting
+            self._maidr_gid = body_collection.get_gid()
+
+            # Use the original collections for highlighting
+            self._elements = [body_collection, wick_collection]
+
+            # Use the utility class to extract data
+            return MplfinanceDataExtractor.extract_candlestick_data(
+                body_collection, wick_collection, self._maidr_date_nums
+            )
+
+        # Fallback to original detection method
+        if not self.axes:
+            return []
+
+        ax_ohlc = self.axes[0]
+        candles = []
+
+        # Look for Rectangle patches (original_flavor candlestick)
+        body_rectangles = []
+        for patch in ax_ohlc.patches:
+            if isinstance(patch, Rectangle):
+                body_rectangles.append(patch)
+
+        if body_rectangles:
+            # Set elements for highlighting
+            self._elements = body_rectangles
+
+            # Generate a GID for highlighting if none exists
+            if not self._maidr_gid:
+                import uuid
+
+                self._maidr_gid = f"maidr-{uuid.uuid4()}"
+                # Set GID on all rectangles
+                for rect in body_rectangles:
+                    rect.set_gid(self._maidr_gid)
+
+            # Use the utility class to extract data
+            return MplfinanceDataExtractor.extract_rectangle_candlestick_data(
+                body_rectangles, self._maidr_date_nums
+            )
+
+        return []
+
+    def _extract_axes_data(self) -> dict:
+        """
+        Extract the plot's axes data including labels.
+
+        Returns
+        -------
+        dict
+            Dictionary containing x and y axis labels.
+        """
+        x_labels = self.ax.get_xlabel()
+        if not x_labels:
+            x_labels = self.extract_shared_xlabel(self.ax)
+        if not x_labels:
+            x_labels = "X"
+        return {MaidrKey.X: x_labels, MaidrKey.Y: self.ax.get_ylabel()}
+
+    def _get_selector(self) -> str:
+        """Return the CSS selector for highlighting candlestick elements in the SVG output."""
+        # Use the stored GID if available, otherwise fall back to generic selector
+        if self._maidr_gid:
+            # Use the full GID as the id attribute (since that's what's in the SVG)
+            selector = (
+                f"g[id='{self._maidr_gid}'] > path, g[id='{self._maidr_gid}'] > rect"
+            )
+        else:
+            selector = "g[maidr='true'] > path, g[maidr='true'] > rect"
+        return selector
+
+    def render(self) -> dict:
+        """Initialize the MAIDR schema dictionary with basic plot information."""
+        title = "Candlestick Chart"
+
+        maidr_schema = {
+            MaidrKey.TYPE: self.type,
+            MaidrKey.TITLE: title,
+            MaidrKey.AXES: self._extract_axes_data(),
+            MaidrKey.DATA: self._extract_plot_data(),
+        }
+
+        # Include selector only if the plot supports highlighting.
+        if self._support_highlighting:
+            maidr_schema[MaidrKey.SELECTOR] = self._get_selector()
+
+        return maidr_schema

{maidr-1.3.0 → maidr-1.4.1}/maidr/core/plot/maidr_plot.py

@@ -42,8 +42,13 @@ class MaidrPlot(ABC):
         self._support_highlighting = True
         self._elements = []
         ss = self.ax.get_subplotspec()
-        self.row_index = ss.rowspan.start
-        self.col_index = ss.colspan.start
+        # Handle cases where subplotspec is None (dynamically created axes)
+        if ss is not None:
+            self.row_index = ss.rowspan.start
+            self.col_index = ss.colspan.start
+        else:
+            self.row_index = 0
+            self.col_index = 0
 
         # MAIDR data
         self.type = plot_type

{maidr-1.3.0 → maidr-1.4.1}/maidr/core/plot/maidr_plot_factory.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 from matplotlib.axes import Axes
-
 from maidr.core.enum import PlotType
 from maidr.core.plot.barplot import BarPlot
 from maidr.core.plot.boxplot import BoxPlot
@@ -13,6 +12,9 @@ from maidr.core.plot.lineplot import MultiLinePlot
 from maidr.core.plot.maidr_plot import MaidrPlot
 from maidr.core.plot.scatterplot import ScatterPlot
 from maidr.core.plot.regplot import SmoothPlot
+from maidr.core.plot.mplfinance_barplot import MplfinanceBarPlot
+from maidr.core.plot.mplfinance_lineplot import MplfinanceLinePlot
+from maidr.util.plot_detection import PlotDetectionUtils
 
 
 class MaidrPlotFactory:
@@ -38,17 +40,13 @@ class MaidrPlotFactory:
             single_ax = ax
 
         if plot_type == PlotType.CANDLESTICK:
-            if isinstance(ax, list):
-                # If ax is a list of lists, flatten it
-                if ax and isinstance(ax[0], list):
-                    axes = ax[0]  # Take the first inner list
-                else:
-                    axes = ax  # Use the list as-is
-            else:
-                axes = [ax]  # Wrap single axes in list
+            axes = PlotDetectionUtils.get_candlestick_axes(ax)
             return CandlestickPlot(axes, **kwargs)
         elif PlotType.BAR == plot_type or PlotType.COUNT == plot_type:
-            return BarPlot(single_ax)
+            if PlotDetectionUtils.is_mplfinance_bar_plot(**kwargs):
+                return MplfinanceBarPlot(single_ax, **kwargs)
+            else:
+                return BarPlot(single_ax)
         elif PlotType.BOX == plot_type:
             return BoxPlot(single_ax, **kwargs)
         elif PlotType.HEAT == plot_type:
@@ -56,7 +54,10 @@ class MaidrPlotFactory:
         elif PlotType.HIST == plot_type:
             return HistPlot(single_ax)
         elif PlotType.LINE == plot_type:
-            return MultiLinePlot(single_ax)
+            if PlotDetectionUtils.is_mplfinance_line_plot(single_ax, **kwargs):
+                return MplfinanceLinePlot(single_ax, **kwargs)
+            else:
+                return MultiLinePlot(single_ax, **kwargs)
         elif PlotType.SCATTER == plot_type:
             return ScatterPlot(single_ax)
         elif PlotType.DODGED == plot_type or PlotType.STACKED == plot_type:

maidr-1.4.1/maidr/core/plot/mplfinance_barplot.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from matplotlib.axes import Axes
+from matplotlib.patches import Rectangle
+
+from maidr.core.enum import PlotType
+from maidr.core.plot import MaidrPlot
+from maidr.exception import ExtractionError
+from maidr.util.mixin import (
+    ContainerExtractorMixin,
+    DictMergerMixin,
+    LevelExtractorMixin,
+)
+from maidr.util.mplfinance_utils import MplfinanceDataExtractor
+
+
+class MplfinanceBarPlot(
+    MaidrPlot, ContainerExtractorMixin, LevelExtractorMixin, DictMergerMixin
+):
+    """
+    Specialized bar plot class for mplfinance volume bars.
+
+    This class handles the extraction and processing of volume data from mplfinance
+    plots, including proper date conversion and data validation.
+    """
+
+    def __init__(self, ax: Axes, **kwargs) -> None:
+        super().__init__(ax, PlotType.BAR)
+        # Store custom patches passed from mplfinance patch
+        self._custom_patches = kwargs.get("_maidr_patches", None)
+        # Store date numbers for volume bars (from mplfinance)
+        self._maidr_date_nums = kwargs.get("_maidr_date_nums", None)
+        # Store custom title
+
+    def set_title(self, title: str) -> None:
+        """Set a custom title for this volume bar plot."""
+        self._title = title
+
+    def _extract_plot_data(self) -> list:
+        """Extract data from mplfinance volume patches."""
+        if self._custom_patches:
+            return self._extract_volume_patches_data(self._custom_patches)
+
+        # Fallback to original bar plot logic if no custom patches
+        plot = self.extract_container(
+            self.ax, ContainerExtractorMixin, include_all=True
+        )
+        data = self._extract_bar_container_data(plot)
+        levels = self.extract_level(self.ax)
+        formatted_data = []
+        combined_data = list(
+            zip(levels, data) if plot[0].orientation == "vertical" else zip(data, levels)  # type: ignore
+        )
+        if combined_data:  # type: ignore
+            for x, y in combined_data:  # type: ignore
+                formatted_data.append({"x": x, "y": y})
+            return formatted_data
+        if len(formatted_data) == 0:
+            raise ExtractionError(self.type, plot)
+        if data is None:
+            raise ExtractionError(self.type, plot)
+
+        return data
+
+    def _extract_volume_patches_data(self, volume_patches: list[Rectangle]) -> list:
+        """
+        Extract data from volume Rectangle patches (used by mplfinance volume bars).
+        """
+        if not volume_patches:
+            return []
+
+        # Sort patches by x-coordinate to maintain order
+        sorted_patches = sorted(volume_patches, key=lambda p: p.get_x())
+
+        # Set elements for highlighting (use the patches directly)
+        self._elements = sorted_patches
+
+        # Use the utility class to extract data
+        return MplfinanceDataExtractor.extract_volume_data(
+            sorted_patches, self._maidr_date_nums
+        )
+
+    def _extract_bar_container_data(self, plot: list | None) -> list | None:
+        """Fallback method for regular bar containers."""
+        if plot is None:
+            return None
+
+        # Since v0.13, Seaborn has transitioned from using `list[Patch]` to
+        # `list[BarContainers] for plotting bar plots.
+        # So, extract data correspondingly based on the level.
+        # Flatten all the `list[BarContainer]` to `list[Patch]`.
+        patches = [patch for container in plot for patch in container.patches]
+        level = self.extract_level(self.ax)
+        if level is None or len(level) == 0:  # type: ignore
+            level = ["" for _ in range(len(patches))]  # type: ignore
+
+        if len(patches) != len(level):
+            return None
+
+        self._elements.extend(patches)
+
+        return [float(patch.get_height()) for patch in patches]
+
+    def _extract_axes_data(self) -> dict:
+        """Extract axes data with mplfinance-specific cleaning."""
+        ax_data = super()._extract_axes_data()
+
+        # For mplfinance volume plots, clean up the y-axis label
+        if self._custom_patches:
+            y_label = ax_data.get("y")
+            if y_label:
+                ax_data["y"] = MplfinanceDataExtractor.clean_axis_label(y_label)
+
+        return ax_data
+
+    def _get_selector(self) -> str:
+        """Return the CSS selector for highlighting bar elements in the SVG output."""
+        # Use the standard working selector that gets replaced with UUID by Maidr class
+        # This works for both original bar plots and mplfinance volume bars
+        return "g[maidr='true'] > path"
+
+    def render(self) -> dict:
+        """Initialize the MAIDR schema dictionary with basic plot information."""
+        from maidr.core.enum.maidr_key import MaidrKey
+
+        title = "Volume Bar Plot"
+
+        maidr_schema = {
+            MaidrKey.TYPE: self.type,
+            MaidrKey.TITLE: title,
+            MaidrKey.AXES: self._extract_axes_data(),
+            MaidrKey.DATA: self._extract_plot_data(),
+        }
+
+        # Include selector only if the plot supports highlighting.
+        if self._support_highlighting:
+            maidr_schema[MaidrKey.SELECTOR] = self._get_selector()
+
+        return maidr_schema