maidr 1.6.0__py3-none-any.whl → 1.7.0__py3-none-any.whl

maidr/__init__.py

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

maidr/core/plot/candlestick.py

@@ -1,11 +1,15 @@
 from __future__ import annotations
 
+import uuid
+from typing import Union, Dict
 from matplotlib.axes import Axes
 from matplotlib.patches import Rectangle
+import numpy as np
 
 from maidr.core.enum import PlotType
 from maidr.core.plot import MaidrPlot
 from maidr.core.enum.maidr_key import MaidrKey
+from maidr.exception import ExtractionError
 from maidr.util.mplfinance_utils import MplfinanceDataExtractor
 
 
@@ -40,64 +44,112 @@ class CandlestickPlot(MaidrPlot):
         self._maidr_body_collection = kwargs.get("_maidr_body_collection", None)
         self._maidr_date_nums = kwargs.get("_maidr_date_nums", None)
         self._maidr_original_data = kwargs.get("_maidr_original_data", None)  # Store original data
+        self._maidr_datetime_converter = kwargs.get("_maidr_datetime_converter", None)
 
-        # Store the GID for proper selector generation
+        # Store the GID for proper selector generation (legacy/shared)
         self._maidr_gid = None
+        # Modern-path separate gids for body and wick
+        self._maidr_body_gid = None
+        self._maidr_wick_gid = None
         if self._maidr_body_collection:
             self._maidr_gid = self._maidr_body_collection.get_gid()
+            self._maidr_body_gid = self._maidr_gid
         elif self._maidr_wick_collection:
             self._maidr_gid = self._maidr_wick_collection.get_gid()
+            self._maidr_wick_gid = self._maidr_gid
 
     def _extract_plot_data(self) -> list[dict]:
-        """Extract candlestick data from the plot."""
+        """
+        Extract candlestick data from the plot.
+
+        This method processes candlestick plots from both modern (mplfinance.plot) and
+        legacy (original_flavor) pipelines, extracting OHLC data and setting up
+        highlighting elements and GIDs.
+
+        Returns
+        -------
+        list[dict]
+            List of dictionaries containing candlestick data with keys:
+            - 'value': Date string
+            - 'open': Opening price (float)
+            - 'high': High price (float)
+            - 'low': Low price (float)
+            - 'close': Closing price (float)
+            - 'volume': Volume (float, typically 0 for candlestick-only plots)
+        """
 
         # 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()
+            # Store the GIDs from the collections (modern path)
+            self._maidr_body_gid = body_collection.get_gid()
+            self._maidr_wick_gid = wick_collection.get_gid()
+            # Keep legacy gid filled for backward compatibility
+            self._maidr_gid = self._maidr_body_gid or self._maidr_wick_gid
 
             # Use the original collections for highlighting
             self._elements = [body_collection, wick_collection]
 
-            # Use the utility class to extract data
-            data = MplfinanceDataExtractor.extract_candlestick_data(
-                body_collection, wick_collection, self._maidr_date_nums, self._maidr_original_data
-            )
-            return data
-
-        # Fallback to original detection method
-        if not self.axes:
-            return []
-
-        ax_ohlc = self.axes[0]
-
-        # 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
-            data = MplfinanceDataExtractor.extract_rectangle_candlestick_data(
-                body_rectangles, self._maidr_date_nums, self._maidr_original_data
-            )
-            return data
+            # Use datetime converter for enhanced data extraction
+            if self._maidr_datetime_converter is not None:
+                data = self._maidr_datetime_converter.extract_candlestick_data(
+                    self.axes[0], wick_collection, body_collection
+                )
+                return data
+
+            # Fallback to original detection method
+            if not self.axes:
+                return []
+
+            ax_ohlc = self.axes[0]
+
+            # 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:
+                    self._maidr_gid = f"maidr-{uuid.uuid4()}"
+                    # Set GID on all rectangles
+                    for rect in body_rectangles:
+                        rect.set_gid(self._maidr_gid)
+                # Keep a dedicated body gid for legacy dict selectors
+                self._maidr_body_gid = getattr(self, "_maidr_body_gid", None) or self._maidr_gid
+
+                # Assign a shared gid to wick Line2D (vertical 2-point lines) on the same axis
+                wick_lines = []
+                for line in ax_ohlc.get_lines():
+                    try:
+                        xydata = line.get_xydata()
+                        if xydata is None:
+                            continue
+                        xy_arr = np.asarray(xydata)
+                        if xy_arr.ndim == 2 and xy_arr.shape[0] == 2 and xy_arr.shape[1] >= 2:
+                            x0 = float(xy_arr[0, 0])
+                            x1 = float(xy_arr[1, 0])
+                            if abs(x0 - x1) < 1e-10:
+                                wick_lines.append(line)
+                    except Exception:
+                        continue
+                if wick_lines:
+                    if not getattr(self, "_maidr_wick_gid", None):
+                        self._maidr_wick_gid = f"maidr-{uuid.uuid4()}"
+                    for line in wick_lines:
+                        line.set_gid(self._maidr_wick_gid)
+
+                # Use the utility class to extract data
+                data = MplfinanceDataExtractor.extract_rectangle_candlestick_data(
+                    body_rectangles, self._maidr_date_nums, self._maidr_original_data
+                )
+                return data
 
         return []
 
@@ -117,17 +169,57 @@ class CandlestickPlot(MaidrPlot):
             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 _get_selector(self) -> Union[str, Dict[str, str]]:
+        """Return selectors for highlighting candlestick elements.
+
+        - Modern path (collections present): return a dict with separate selectors for body, wickLow, wickHigh
+        - Legacy path: return a dict with body and shared wick selectors (no open/close keys)
+        """
+        # Modern path: build structured selectors using separate gids
+        if self._maidr_body_collection and self._maidr_wick_collection and self._maidr_body_gid and self._maidr_wick_gid:
+            # Determine candle count N
+            N = None
+            if self._maidr_original_data is not None:
+                try:
+                    N = len(self._maidr_original_data)
+                except Exception:
+                    N = None
+            if N is None and hasattr(self._maidr_wick_collection, "get_paths"):
+                try:
+                    wick_paths = len(list(self._maidr_wick_collection.get_paths()))
+                    if wick_paths % 2 == 0 and wick_paths > 0:
+                        N = wick_paths // 2
+                except Exception:
+                    pass
+            if N is None and hasattr(self._maidr_body_collection, "get_paths"):
+                try:
+                    body_paths = len(list(self._maidr_body_collection.get_paths()))
+                    if body_paths > 0:
+                        N = body_paths
+                except Exception:
+                    pass
+            if N is None:
+                raise ExtractionError(PlotType.CANDLESTICK, self._maidr_wick_collection)
+
+            selectors = {
+                "body": f"g[id='{self._maidr_body_gid}'] > path",
+                "wickLow": f"g[id='{self._maidr_wick_gid}'] > path:nth-child(-n+{N})",
+                "wickHigh": f"g[id='{self._maidr_wick_gid}'] > path:nth-child(n+{N + 1})",
+            }
+            return selectors
+
+        # Legacy path: build shared-id selectors; omit open/close
+        legacy_selectors = {}
+        if getattr(self, "_maidr_body_gid", None) or self._maidr_gid:
+            body_gid = getattr(self, "_maidr_body_gid", None) or self._maidr_gid
+            legacy_selectors["body"] = f"g[id='{body_gid}'] > path"
+        if getattr(self, "_maidr_wick_gid", None):
+            legacy_selectors["wick"] = f"g[id='{self._maidr_wick_gid}'] > path"
+        if legacy_selectors:
+            return legacy_selectors
+
+        # Fallback
+        return "g[maidr='true'] > path, g[maidr='true'] > rect"
 
     def render(self) -> dict:
         """Initialize the MAIDR schema dictionary with basic plot information."""

maidr/core/plot/mplfinance_barplot.py

@@ -31,6 +31,10 @@ class MplfinanceBarPlot(
         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 datetime converter if available
+        self._maidr_datetime_converter = kwargs.get("_maidr_datetime_converter", None)
+
         # Store custom title
 
     def set_title(self, title: str) -> None:
@@ -48,6 +52,13 @@ class MplfinanceBarPlot(
         )
         data = self._extract_bar_container_data(plot)
         levels = self.extract_level(self.ax)
+
+        # Ensure we have valid data and levels before processing
+        if data is None or levels is None:
+            if data is None:
+                raise ExtractionError(self.type, plot)
+            return []
+
         formatted_data = []
         combined_data = list(
             zip(levels, data)
@@ -78,7 +89,13 @@ class MplfinanceBarPlot(
         # Set elements for highlighting (use the patches directly)
         self._elements = sorted_patches
 
-        # Use the utility class to extract data
+        # Use datetime converter for enhanced data extraction
+        if self._maidr_datetime_converter is not None:
+            data = self._maidr_datetime_converter.extract_volume_data(self.ax)
+            if data:  # Only use if successful
+                return [{"x": item[0], "y": item[1]} for item in data]
+
+        # Fallback to existing logic
         return MplfinanceDataExtractor.extract_volume_data(
             sorted_patches, self._maidr_date_nums
         )

maidr/core/plot/mplfinance_lineplot.py

@@ -23,6 +23,9 @@ class MplfinanceLinePlot(MaidrPlot, LineExtractorMixin):
     def __init__(self, ax: Axes, **kwargs):
         super().__init__(ax, PlotType.LINE)
 
+        # Store datetime converter if available
+        self._maidr_datetime_converter = kwargs.get("_maidr_datetime_converter", None)
+
     def _get_selector(self) -> Union[str, List[str]]:
         """Return selectors for all lines that have data."""
         all_lines = self.ax.get_lines()
@@ -101,10 +104,15 @@ class MplfinanceLinePlot(MaidrPlot, LineExtractorMixin):
                 if np.isnan(x) or np.isnan(y) or np.isinf(x) or np.isinf(y):
                     continue
 
-                # Handle x-value conversion - could be string (date) or numeric
-                if isinstance(x, str):
-                    x_value = x  # Keep string as-is (for dates)
+                # Use datetime converter for enhanced data extraction
+                datetime_converter = getattr(line, "_maidr_datetime_converter", None) or self._maidr_datetime_converter
+                if datetime_converter is not None:
+                    # Convert x-coordinate (matplotlib index) to formatted datetime
+                    x_value = datetime_converter.get_formatted_datetime(int(round(x)))
+                    if x_value is None:
+                        x_value = float(x)  # Fallback to numeric
                 else:
+                    # Fallback to existing logic
                     # Check if we have date numbers from mplfinance
                     if date_nums is not None and i < len(date_nums):
                         # Use the date number to convert to date string

maidr/patch/candlestick.py

@@ -2,6 +2,7 @@ import wrapt
 from typing import Any, Callable, Dict, Tuple
 from matplotlib.patches import Rectangle
 from mplfinance import original_flavor
+import numpy as np
 
 from maidr.core.context_manager import ContextManager
 from maidr.core.enum.plot_type import PlotType
@@ -46,10 +47,35 @@ def candlestick(
         # Patch the plotting function.
         plot = wrapped(*args, **kwargs)
 
+    original_data = None
+    date_nums = None
+    if len(args) >= 2:
+        try:
+            quotes = args[1]
+            if quotes is not None:
+                arr = np.asarray(quotes)
+                if arr.ndim == 2 and arr.shape[1] >= 5 and arr.size > 0:
+                    date_nums = arr[:, 0].tolist()
+                    original_data = {
+                        "Open": arr[:, 1].tolist(),
+                        "High": arr[:, 2].tolist(),
+                        "Low": arr[:, 3].tolist(),
+                        "Close": arr[:, 4].tolist(),
+                    }
+        except Exception:
+            pass
+
     axes = []
     for ax in plot:
         axes.append(FigureManager.get_axes(ax))
-    FigureManager.create_maidr(axes, PlotType.CANDLESTICK)
+
+    extra_kwargs: Dict[str, Any] = {}
+    if original_data is not None:
+        extra_kwargs["_maidr_original_data"] = original_data
+    if date_nums is not None:
+        extra_kwargs["_maidr_date_nums"] = date_nums
+
+    FigureManager.create_maidr(axes, PlotType.CANDLESTICK, **extra_kwargs)
 
     return plot
 

maidr/patch/mplfinance.py

@@ -8,6 +8,7 @@ from matplotlib.lines import Line2D
 from maidr.core.enum import PlotType
 from maidr.patch.common import common
 from maidr.core.context_manager import ContextManager
+from maidr.util.datetime_conversion import create_datetime_converter
 
 
 def mplfinance_plot_patch(wrapped, instance, args, kwargs):
@@ -53,26 +54,37 @@ def mplfinance_plot_patch(wrapped, instance, args, kwargs):
         elif volume_ax is None and "volume" in ax.get_ylabel().lower():
             volume_ax = ax
 
-    # Try to extract date numbers from the data
+    # Try to extract date numbers from the data (existing logic preserved)
     date_nums = None
     data = None
+    datetime_converter = None
+
     if len(args) > 0:
         data = args[0]
     elif "data" in kwargs:
         data = kwargs["data"]
 
     if data is not None:
+        # Existing date_nums logic (preserved)
         if hasattr(data, "Date_num"):
             date_nums = list(data["Date_num"])
         elif hasattr(data, "index"):
             # fallback: use index if it's a DatetimeIndex
             try:
                 import matplotlib.dates as mdates
-
                 date_nums = [mdates.date2num(d) for d in data.index]
             except Exception:
                 pass
 
+        # Create datetime converter for DatetimeIndex data
+        if hasattr(data, "index") and hasattr(data.index, "dtype"):
+            if "datetime" in str(data.index.dtype).lower():
+                datetime_converter = create_datetime_converter(data)
+
+                # Use enhanced converter's date_nums for mplfinance compatibility
+                if date_nums is None and hasattr(datetime_converter, 'date_nums'):
+                    date_nums = datetime_converter.date_nums
+
     # Process and register the Candlestick plot
     if price_ax:
         wick_collection = next(
@@ -83,9 +95,10 @@ def mplfinance_plot_patch(wrapped, instance, args, kwargs):
         )
 
         if wick_collection and body_collection:
-            gid = f"maidr-{uuid.uuid4()}"
-            wick_collection.set_gid(gid)
-            body_collection.set_gid(gid)
+            wick_gid = f"maidr-{uuid.uuid4()}"
+            body_gid = f"maidr-{uuid.uuid4()}"
+            wick_collection.set_gid(wick_gid)
+            body_collection.set_gid(body_gid)
 
             candlestick_kwargs = dict(
                 kwargs,
@@ -93,7 +106,13 @@ def mplfinance_plot_patch(wrapped, instance, args, kwargs):
                 _maidr_body_collection=body_collection,
                 _maidr_date_nums=date_nums,
                 _maidr_original_data=data,
+                _maidr_wick_gid=wick_gid,
+                _maidr_body_gid=body_gid,
             )
+
+            # Add datetime converter
+            if datetime_converter is not None:
+                candlestick_kwargs["_maidr_datetime_converter"] = datetime_converter
             common(
                 PlotType.CANDLESTICK,
                 lambda *a, **k: price_ax,
@@ -126,6 +145,11 @@ def mplfinance_plot_patch(wrapped, instance, args, kwargs):
                 _maidr_patches=volume_patches,
                 _maidr_date_nums=date_nums,
             )
+
+            # Add datetime converter
+            if datetime_converter is not None:
+                bar_kwargs["_maidr_datetime_converter"] = datetime_converter  # type: ignore
+
             common(PlotType.BAR, lambda *a, **k: volume_ax, instance, args, bar_kwargs)
 
     # Process and register Moving Averages as LINE plots
@@ -193,6 +217,10 @@ def mplfinance_plot_patch(wrapped, instance, args, kwargs):
             if date_nums is not None:
                 setattr(line, "_maidr_date_nums", date_nums)
 
+            # Store datetime converter
+            if datetime_converter is not None:
+                setattr(line, "_maidr_datetime_converter", datetime_converter)
+
             # Ensure GID is set for highlighting
             if line.get_gid() is None:
                 gid = f"maidr-{uuid.uuid4()}"
@@ -204,6 +232,11 @@ def mplfinance_plot_patch(wrapped, instance, args, kwargs):
         # Register all valid lines as a single LINE plot
         if valid_lines:
             line_kwargs = dict(kwargs)
+
+            # Add datetime converter
+            if datetime_converter is not None:
+                line_kwargs["_maidr_datetime_converter"] = datetime_converter
+
             common(PlotType.LINE, lambda *a, **k: price_ax, instance, args, line_kwargs)
 
     if not original_returnfig:

maidr/util/datetime_conversion.py

@@ -0,0 +1,406 @@
+import pandas as pd
+import numpy as np
+from typing import Optional, Dict, Any, List, Tuple
+from datetime import datetime
+
+class DatetimeConverter:
+    """
+    Enhanced datetime converter that automatically detects time periods
+    and provides intelligent date/time formatting for mplfinance plots.
+
+    This utility automatically detects the time period of financial data and formats
+    datetime values consistently for screen reader accessibility and visual clarity.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        DataFrame with DatetimeIndex containing financial data.
+    datetime_format : str, optional
+        Custom datetime format string. If None, automatic format detection is used.
+
+    Attributes
+    ----------
+    data : pd.DataFrame
+        The input DataFrame with DatetimeIndex.
+    datetime_format : str or None
+        Custom datetime format string if provided.
+    date_mapping : Dict[int, datetime]
+        Mapping from integer index to datetime objects.
+    time_period : str
+        Detected time period ('minute', 'intraday', 'hour', 'day', 'week', 'month').
+
+    Raises
+    ------
+    ValueError
+        If the input data does not have a DatetimeIndex.
+
+    Examples
+    --------
+    >>> import pandas as pd
+    >>> from maidr.util.datetime_conversion import create_datetime_converter
+    >>>
+    >>> # Create sample data with DatetimeIndex
+    >>> dates = pd.date_range('2024-01-15', periods=5, freq='D')
+    >>> df = pd.DataFrame({'Open': [3050, 3078, 3080, 3075, 3087]}, index=dates)
+    >>>
+    >>> # Create converter
+    >>> converter = create_datetime_converter(df)
+    >>>
+    >>> # Get formatted datetime
+    >>> formatted = converter.get_formatted_datetime(0)
+    >>> print(formatted)  # Output: "Jan 15 2024"
+    >>>
+    >>> # For time-based data
+    >>> hourly_dates = pd.date_range('2024-01-15 09:00:00', periods=3, freq='H')
+    >>> df_hourly = pd.DataFrame({'Open': [3050, 3078, 3080]}, index=hourly_dates)
+    >>> converter_hourly = create_datetime_converter(df_hourly)
+    >>> formatted_hourly = converter_hourly.get_formatted_datetime(0)
+    >>> print(formatted_hourly)  # Output: "Jan 15 2024 09:00"
+    """
+
+    def __init__(self, data: pd.DataFrame, datetime_format: Optional[str] = None) -> None:
+        """
+        Initialize the DatetimeConverter.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            DataFrame with DatetimeIndex containing financial data.
+        datetime_format : str, optional
+            Custom datetime format string. If None, automatic format detection is used.
+
+        Raises
+        ------
+        ValueError
+            If the input data does not have a DatetimeIndex.
+
+        Notes
+        -----
+        The converter automatically detects the time period of the data based on
+        average time differences between consecutive data points.
+        """
+        self.data = data
+        self.datetime_format = datetime_format
+
+        if not isinstance(data.index, pd.DatetimeIndex):
+            raise ValueError("Data must have a DatetimeIndex")
+
+        self.date_mapping = self._create_date_mapping()
+        self.time_period = self._detect_time_period()
+
+    def _create_date_mapping(self) -> Dict[int, datetime]:
+        """
+        Create mapping from integer index to datetime objects.
+
+        Returns
+        -------
+        Dict[int, datetime]
+            Dictionary mapping integer indices to corresponding datetime objects
+            from the DataFrame index.
+        """
+        return {i: date for i, date in enumerate(self.data.index)}
+
+    def _detect_time_period(self) -> str:
+        """
+        Detect the time period of the data based on average time differences.
+
+        Returns
+        -------
+        str
+            Detected time period: 'minute', 'intraday', 'hour', 'day', 'week', 'month', or 'unknown'.
+
+        Notes
+        -----
+        Time period detection is based on average time differences between consecutive
+        data points in the DatetimeIndex.
+        """
+        if len(self.data) < 2:
+            return "unknown"
+
+        # Calculate average time difference between consecutive data points
+        time_diffs = []
+        for i in range(1, len(self.data)):
+            diff = self.data.index[i] - self.data.index[i-1]
+            time_diffs.append(diff.total_seconds())
+
+        avg_diff_seconds = np.mean(time_diffs)
+
+        # Determine time period based on average difference
+        if avg_diff_seconds < 60:  # Less than 1 minute
+            return "minute"
+        elif avg_diff_seconds < 3600:  # Less than 1 hour
+            return "intraday"
+        elif avg_diff_seconds < 86400:  # Less than 1 day
+            return "hour"
+        elif avg_diff_seconds < 604800:  # Less than 1 week
+            return "day"
+        elif avg_diff_seconds < 2592000:  # Less than 1 month
+            return "week"
+        else:
+            return "month"
+
+    def get_time_period_description(self) -> str:
+        """
+        Get human-readable description of detected time period.
+
+        Returns
+        -------
+        str
+            Human-readable description of the detected time period.
+        """
+        period_descriptions = {
+            "minute": "Sub-minute data",
+            "intraday": "Intraday (minute-level) data",
+            "hour": "Hourly data",
+            "day": "Daily data",
+            "week": "Weekly data",
+            "month": "Monthly data",
+            "unknown": "Unknown time period"
+        }
+        return period_descriptions.get(self.time_period, "Unknown time period")
+
+    def get_formatted_datetime(self, index: int) -> Optional[str]:
+        """
+        Get formatted datetime string for given index using consistent formatting.
+
+        Always includes year for screen reader accessibility.
+
+        Parameters
+        ----------
+        index : int
+            Integer index into the DataFrame.
+
+        Returns
+        -------
+        str or None
+            Formatted datetime string or None if index is invalid.
+
+        Examples
+        --------
+        >>> converter = create_datetime_converter(df)
+        >>> formatted = converter.get_formatted_datetime(0)
+        >>> print(formatted)  # "Jan 15 2024" for daily data
+        """
+        if index not in self.date_mapping:
+            return None
+
+        dt = self.date_mapping[index]
+        return self._format_datetime_custom(dt)
+
+    def _format_datetime_custom(self, dt: datetime) -> str:
+        """
+        Consistent datetime formatting with year always included.
+
+        Parameters
+        ----------
+        dt : datetime
+            Datetime object to format.
+
+        Returns
+        -------
+        str
+            Formatted datetime string with consistent pattern.
+
+        Notes
+        -----
+        Formatting rules:
+        - Daily data: "Jan 15 2024"
+        - Time-based data: "Jan 15 2024 09:00" or "Jan 15 2024 09:00:30"
+        - Seconds are only shown when they are non-zero for cleaner display.
+        """
+        if self.time_period in ["minute", "intraday", "hour"]:
+            # Time-based data: include time with optional seconds
+            if dt.second == 0:
+                return dt.strftime("%b %d %Y %H:%M")
+            else:
+                return dt.strftime("%b %d %Y %H:%M:%S")
+        else:
+            # Daily/weekly/monthly data: just date
+            return dt.strftime("%b %d %Y")
+
+    @property
+    def date_nums(self) -> List[float]:
+        """
+        Convert DatetimeIndex to matplotlib date numbers for backward compatibility.
+
+        Returns
+        -------
+        List[float]
+            List of matplotlib date numbers converted from the DatetimeIndex.
+            Empty list if conversion fails.
+
+        Notes
+        -----
+        This property provides backward compatibility with existing matplotlib
+        plotting code that expects date numbers instead of datetime objects.
+        """
+        try:
+            import matplotlib.dates as mdates
+            date_nums = []
+            for d in self.data.index:
+                try:
+                    date_num = mdates.date2num(d)
+                    date_nums.append(float(date_num))
+                except (ValueError, TypeError):
+                    continue
+            return date_nums
+        except Exception:
+            return []
+
+    def extract_candlestick_data(self, ax, wick_collection=None, body_collection=None) -> List[Dict[str, Any]]:
+        """
+        Extract candlestick data with proper datetime formatting using original DataFrame.
+
+        Parameters
+        ----------
+        ax : matplotlib.axes.Axes
+            Matplotlib axes object (not used in current implementation).
+        wick_collection : matplotlib.collections.LineCollection, optional
+            Collection containing wick lines for candlestick plots.
+        body_collection : matplotlib.collections.PolyCollection, optional
+            Collection containing body rectangles for candlestick plots.
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of dictionaries containing candlestick data with keys:
+            'value', 'open', 'high', 'low', 'close', 'volume'.
+            Each 'value' contains formatted datetime string.
+
+        Notes
+        -----
+        This method extracts OHLC data from the original DataFrame and formats
+        datetime values using the enhanced datetime conversion logic.
+        """
+        candles = []
+        if not hasattr(self.data, 'Open') or not hasattr(self.data, 'High') or not hasattr(self.data, 'Low') or not hasattr(self.data, 'Close'):
+            return candles
+
+        for i in range(len(self.data)):
+            try:
+                open_price = self.data.iloc[i]['Open']
+                high_price = self.data.iloc[i]['High']
+                low_price = self.data.iloc[i]['Low']
+                close_price = self.data.iloc[i]['Close']
+                volume = self.data.iloc[i].get('Volume', 0.0)
+
+                formatted_datetime = self.get_formatted_datetime(i)
+
+                candle_data = {
+                    'value': formatted_datetime or f"datetime_{i:03d}",
+                    'open': float(open_price),
+                    'high': float(high_price),
+                    'low': float(low_price),
+                    'close': float(close_price),
+                    'volume': float(volume)
+                }
+                candles.append(candle_data)
+            except (KeyError, IndexError, ValueError):
+                continue
+        return candles
+
+    def extract_moving_average_data(self, ax, line_index: int = 0) -> List[Tuple[str, float]]:
+        """
+        Extract moving average data with proper datetime formatting and NaN filtering.
+
+        Parameters
+        ----------
+        ax : matplotlib.axes.Axes
+            Matplotlib axes object containing the moving average lines.
+        line_index : int, default=0
+            Index of the line to extract data from.
+
+        Returns
+        -------
+        List[Tuple[str, float]]
+            List of tuples containing (formatted_datetime, y_value) pairs.
+            NaN and infinite values are filtered out.
+
+        Notes
+        -----
+        This method filters out invalid data points and formats datetime values
+        using the enhanced datetime conversion logic.
+        """
+        ma_data = []
+        lines = ax.get_lines() if ax else []
+        if line_index >= len(lines):
+            return ma_data
+        line = lines[line_index]
+        xydata = line.get_xydata()
+        if xydata is None or len(xydata) == 0:
+            return ma_data
+
+        for i, (x, y) in enumerate(xydata):
+            if np.isnan(y) or np.isinf(y):
+                continue
+            try:
+                df_index = int(round(x))
+                if 0 <= df_index < len(self.data):
+                    formatted_datetime = self.get_formatted_datetime(df_index)
+                    if formatted_datetime:
+                        ma_data.append((formatted_datetime, float(y)))
+            except (ValueError, TypeError):
+                continue
+        return ma_data
+
+    def extract_volume_data(self, ax) -> List[Tuple[str, float]]:
+        """
+        Extract volume data with proper datetime formatting using original DataFrame.
+
+        Parameters
+        ----------
+        ax : matplotlib.axes.Axes
+            Matplotlib axes object (not used in current implementation).
+
+        Returns
+        -------
+        List[Tuple[str, float]]
+            List of tuples containing (formatted_datetime, volume) pairs.
+            Zero and NaN volume values are filtered out.
+
+        Notes
+        -----
+        This method extracts volume data from the original DataFrame and formats
+        datetime values using the enhanced datetime conversion logic.
+        """
+        volume_data = []
+        if hasattr(self.data, 'Volume'):
+            for i in range(len(self.data)):
+                try:
+                    volume = self.data.iloc[i]['Volume']
+                    if pd.isna(volume) or volume <= 0:
+                        continue
+                    formatted_datetime = self.get_formatted_datetime(i)
+                    volume_data.append((formatted_datetime, float(volume)))
+                except (KeyError, IndexError, ValueError):
+                    continue
+        return volume_data
+
+
+def create_datetime_converter(data: pd.DataFrame, datetime_format: Optional[str] = None) -> DatetimeConverter:
+    """
+    Factory function to create a DatetimeConverter instance.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        DataFrame with DatetimeIndex containing financial data.
+    datetime_format : str, optional
+        Custom datetime format string. If None, automatic format detection is used.
+
+    Returns
+    -------
+    DatetimeConverter
+        Configured DatetimeConverter instance for the given data.
+
+    Examples
+    --------
+    >>> import pandas as pd
+    >>> from maidr.util.datetime_conversion import create_datetime_converter
+    >>>
+    >>> dates = pd.date_range('2024-01-15', periods=5, freq='D')
+    >>> df = pd.DataFrame({'Open': [3050, 3078, 3080, 3075, 3087]}, index=dates)
+    >>> converter = create_datetime_converter(df)
+    >>> print(type(converter))  # <class 'maidr.util.datetime_conversion.DatetimeConverter'>
+    """
+    return DatetimeConverter(data, datetime_format)

{maidr-1.6.0.dist-info → maidr-1.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maidr
-Version: 1.6.0
+Version: 1.7.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
@@ -28,7 +28,6 @@ Requires-Dist: htmltools>=0.5
 Requires-Dist: lxml>=5.1.0
 Requires-Dist: mplfinance>=0.12.10b0
 Requires-Dist: numpy>=1.26
-Requires-Dist: virtualenv<21,>=20.26.6
 Requires-Dist: wrapt<2,>=1.16.0
 Provides-Extra: jupyter
 Requires-Dist: ipykernel>=6.0.0; extra == 'jupyter'

{maidr-1.6.0.dist-info → maidr-1.7.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-maidr/__init__.py,sha256=bvyrTCLC6rRb_Iu5wCMtnDYCY0tbaZ--c21hFuNMICE,415
+maidr/__init__.py,sha256=N6tFj8F07eJxaRvcZZNW0wNWTR2I2JcTgM9PTSKWGtM,415
 maidr/api.py,sha256=gRNLXqUWpFGdD-I7Nu6J0_LeEni9KRAr0TBHwHaDAsc,1928
 maidr/core/__init__.py,sha256=WgxLpSEYMc4k3OyEOf1shOxfEq0ASzppEIZYmE91ThQ,25
 maidr/core/context_manager.py,sha256=6cT7ZGOApSpC-SLD2XZWWU_H08i-nfv-JUlzXOtvWYw,3374
@@ -12,15 +12,15 @@ maidr/core/enum/smooth_keywords.py,sha256=z2kVZZ-mETWWh5reWu_hj9WkJD6WFj7_2-6s1e
 maidr/core/plot/__init__.py,sha256=xDIpRGM-4DfaSSL3nKcXrjdMecCHJ6en4K4nA_fPefQ,83
 maidr/core/plot/barplot.py,sha256=0hBgp__putezvxXc9G3qmaktmAzze3cN8pQMD9iqktE,2116
 maidr/core/plot/boxplot.py,sha256=i11GdNuz_c-hilmhydu3ah-bzyVdFoBkNvRi5lpMrrY,9946
-maidr/core/plot/candlestick.py,sha256=dk1MCU5zqGA2CFLT1_1tGrsB6kYNhsUFLPLNaEi9e04,5363
+maidr/core/plot/candlestick.py,sha256=9R1ddSnUkGEE9WJgUPeuZhRtxXNBnOM9rbJdfJcY8bo,9886
 maidr/core/plot/grouped_barplot.py,sha256=_zn4XMeEnSiDHtf6t4-z9ErBqg_CijhAS2CCtlHgYIQ,2077
 maidr/core/plot/heatmap.py,sha256=yMS-31tS2GW4peds9LtZesMxmmTV_YfqYO5M_t5KasQ,2521
 maidr/core/plot/histogram.py,sha256=QV5W-6ZJQQcZsrM91JJBX-ONktJzH7yg_et5_bBPfQQ,1525
 maidr/core/plot/lineplot.py,sha256=48aEkx8rjZ9lYEZSHWCJcSzdVblKwcdJZDZK0vnxmPo,4291
 maidr/core/plot/maidr_plot.py,sha256=9T0boWaonM99jggEed97-rCy_cufRMWXrXo-CbmPudE,4230
 maidr/core/plot/maidr_plot_factory.py,sha256=NW2iFScswgXbAC9rAOo4iMkAFsjY43DAvFioGr0yzx4,2732
-maidr/core/plot/mplfinance_barplot.py,sha256=8H9fKxkLIRiTDMoSjtf87hjFPuP1WCo_mdsyEWBsLjQ,5016
-maidr/core/plot/mplfinance_lineplot.py,sha256=3UP701S8Rz8vjuC5WIEVHnsZMJCo3AoSUrbQG3CBqkM,6750
+maidr/core/plot/mplfinance_barplot.py,sha256=zhTp2i6BH0xn7vQvGTotKgu2HbzlKT4p6zA5CVUUHHc,5673
+maidr/core/plot/mplfinance_lineplot.py,sha256=oRXFAa13wsz5i9tDN267ZSqd1-gGpOEzntmFTAz8o1w,7269
 maidr/core/plot/regplot.py,sha256=b7u6bGTz1IxKahplNUrfwIr_OGSwMJ2BuLgFAVjL0s0,2744
 maidr/core/plot/scatterplot.py,sha256=o0i0uS-wXK9ZrENxneoHbh3-u-2goRONp19Yu9QLsaY,1257
 maidr/exception/__init__.py,sha256=PzaXoYBhyZxMDcJkuxJugDx7jZeseI0El6LpxIwXyG4,46
@@ -28,7 +28,7 @@ maidr/exception/extraction_error.py,sha256=rd37Oxa9gn2OWFWt9AOH5fv0hNd3sAWGvpDMF
 maidr/patch/__init__.py,sha256=FnkoUQJC2ODhLO37GwgRVSitBCRax42Ti0e4NIAgdO0,236
 maidr/patch/barplot.py,sha256=qdUy5Y8zkMg4dH3fFh93OYzLdar4nl1u5O2Jcw4d2zI,2433
 maidr/patch/boxplot.py,sha256=l7wDD4pDi4ZbsL5EX5XDhPRxgtSIFSrFguMOZ7IC2eg,2845
-maidr/patch/candlestick.py,sha256=NFkzwpxmLBpWmb5s05pjk6obNMQee-xIEZTqGkbhhqM,1776
+maidr/patch/candlestick.py,sha256=R2MgPX5ih9W-RBluvF6jFNJBxETH0eMt7Tzn0Ej9LoU,2652
 maidr/patch/clear.py,sha256=2Sc4CIt5jRGkew3TxFsBZm-uowC9yDSxtraEcXZjmGw,396
 maidr/patch/common.py,sha256=RV2NayjPmcWJVhZJV7nmBCjcH7MPDhW_fIluTOPAATk,880
 maidr/patch/heatmap.py,sha256=uxLLg530Ql9KVC5rxk8vnwPHXBWWHwYgJRkyHY-tJzs,1048
@@ -36,10 +36,11 @@ maidr/patch/highlight.py,sha256=I1dGFHJAnVd0AHVnMJzk_TE8BC8Uv-I6fTzSrJLU5QM,1155
 maidr/patch/histogram.py,sha256=k3N0RUf1SQ2402pwbaY5QyS98KnLWvr9glCHQw9NTko,2378
 maidr/patch/kdeplot.py,sha256=qv-OKzuop2aTrkZgUe2OnLxvV-KMyeXt1Td0_uZeHzE,2338
 maidr/patch/lineplot.py,sha256=kvTAiOddy1g5GMP456Awk21NUEZfn-vWaYXy5GTVtuA,1841
-maidr/patch/mplfinance.py,sha256=73aYyFYnAX-AXqPid8ScfexEU2Y8fC9L_tEidzPcKZo,8008
+maidr/patch/mplfinance.py,sha256=L_C_EsIghUVVdtOxooa1a9Lxe-UcUpKuYV2Tw_bMDBw,9490
 maidr/patch/regplot.py,sha256=k86ekd0E4XJ_L1u85zObuDnxuXlM83z7tKtyXRTj2rI,3240
 maidr/patch/scatterplot.py,sha256=kln6zZwjVsdQzICalo-RnBOJrx1BnIB2xYUwItHvSNY,525
 maidr/util/__init__.py,sha256=eRJZfRpDX-n7UoV3JXw_9Lbfu_qNl_D0W1UTvLL-Iv4,81
+maidr/util/datetime_conversion.py,sha256=fl2MnSCmz8IqYIHsiQPWKkNz3lDrFyWoStkQPIDReCA,14364
 maidr/util/dedup_utils.py,sha256=RpgPL5p-3oULUHaTCZJaQKhPHfyPkvBLHMt8lAGpJ5A,438
 maidr/util/environment.py,sha256=SSfxzjmY2ZVA98B-IVql8n9AX3d6h2f7_R4t3_53dYI,9452
 maidr/util/mplfinance_utils.py,sha256=aWNRkNS2IAF4YYEF9w7CcmcKWMGg3KkYJAv0xL8KcyY,14417
@@ -51,7 +52,7 @@ maidr/util/mixin/extractor_mixin.py,sha256=oHtwpmS5kARvaLrSO3DKTPQxyFUw9nOcKN7rz
 maidr/util/mixin/merger_mixin.py,sha256=V0qLw_6DUB7X6CQ3BCMpsCQX_ZuwAhoSTm_E4xAJFKM,712
 maidr/widget/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 maidr/widget/shiny.py,sha256=wrrw2KAIpE_A6CNQGBtNHauR1DjenA_n47qlFXX9_rk,745
-maidr-1.6.0.dist-info/METADATA,sha256=e3l2lyk61dpyniYkOGEIO2Ycyt10LWgPfM-z6OR8fYU,3193
-maidr-1.6.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-maidr-1.6.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
-maidr-1.6.0.dist-info/RECORD,,
+maidr-1.7.0.dist-info/METADATA,sha256=rjXKEyignRmgCOB6C6E_FhvqEkPvjGHIMuxFkZAHpos,3154
+maidr-1.7.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+maidr-1.7.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+maidr-1.7.0.dist-info/RECORD,,