maidr 1.10.0__py3-none-any.whl → 1.11.0__py3-none-any.whl

maidr/__init__.py

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

maidr/core/enum/maidr_key.py

@@ -11,6 +11,7 @@ class MaidrKey(str, Enum):
     # Plot data keys.
     AXES = "axes"
     DATA = "data"
+    FORMAT = "format"
     POINTS = "points"
     LEVEL = "level"
     X = "x"

maidr/core/plot/candlestick.py

@@ -47,9 +47,10 @@ class CandlestickPlot(MaidrPlot):
         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
+        if self._maidr_wick_collection:
+            self._maidr_wick_gid = self._maidr_wick_collection.get_gid()
+            if not self._maidr_gid:
+                self._maidr_gid = self._maidr_wick_gid
 
     def _extract_plot_data(self) -> list[dict]:
         """
@@ -147,11 +148,7 @@ class CandlestickPlot(MaidrPlot):
         return {MaidrKey.X: x_labels, MaidrKey.Y: self.ax.get_ylabel()}
 
     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)
-        """
+        """Return selectors for highlighting candlestick elements."""
         # Modern path: build structured selectors using separate gids
         if (
             self._maidr_body_collection
@@ -190,12 +187,12 @@ class CandlestickPlot(MaidrPlot):
             }
             return selectors
 
-        # Legacy path: build shared-id selectors; omit open/close
+        # Legacy path
         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
+        if self._maidr_body_gid or self._maidr_gid:
+            body_gid = self._maidr_body_gid or self._maidr_gid
             legacy_selectors["body"] = f"g[id='{body_gid}'] > path"
-        if getattr(self, "_maidr_wick_gid", None):
+        if self._maidr_wick_gid:
             legacy_selectors["wick"] = f"g[id='{self._maidr_wick_gid}'] > path"
         if legacy_selectors:
             return legacy_selectors
@@ -207,9 +204,12 @@ class CandlestickPlot(MaidrPlot):
         """Initialize the MAIDR schema dictionary with basic plot information."""
         base_schema = super().render()
         base_schema[MaidrKey.TITLE] = "Candlestick Chart"
-        base_schema[MaidrKey.AXES] = self._extract_axes_data()
+        # Update axes labels while preserving format from parent
+        axes_data = self._extract_axes_data()
+        if MaidrKey.AXES in base_schema and MaidrKey.FORMAT in base_schema[MaidrKey.AXES]:
+            axes_data[MaidrKey.FORMAT] = base_schema[MaidrKey.AXES][MaidrKey.FORMAT]
+        base_schema[MaidrKey.AXES] = axes_data
         base_schema[MaidrKey.DATA] = self._extract_plot_data()
-        # Include selector only if the plot supports highlighting.
         if self._support_highlighting:
             base_schema[MaidrKey.SELECTOR] = self._get_selector()
         return base_schema

maidr/core/plot/maidr_plot.py

@@ -5,12 +5,13 @@ from abc import ABC, abstractmethod
 from matplotlib.axes import Axes
 
 from maidr.core.enum import MaidrKey, PlotType
+from maidr.util.mixin import FormatExtractorMixin
 
 # uuid is used to generate unique identifiers for each plot layer in the MAIDR schema.
 import uuid
 
 
-class MaidrPlot(ABC):
+class MaidrPlot(ABC, FormatExtractorMixin):
     """
     Abstract base class for plots managed by the MAIDR system.
 
@@ -61,13 +62,21 @@ class MaidrPlot(ABC):
         """
         Generate the MAIDR schema for this plot layer, including a unique id for layer identification.
         """
+        # Extract axes data first
+        axes_data = self._extract_axes_data()
+
+        # Extract and include format configuration inside axes if available.
+        format_config = self.extract_format(self.ax)
+        if format_config:
+            axes_data[MaidrKey.FORMAT] = format_config
+
         # Generate a unique UUID for this layer to ensure each plot layer can be distinctly identified
         # in the MAIDR frontend. This supports robust layer switching.
         maidr_schema = {
             MaidrKey.ID: str(uuid.uuid4()),
             MaidrKey.TYPE: self.type,
             MaidrKey.TITLE: self.ax.get_title(),
-            MaidrKey.AXES: self._extract_axes_data(),
+            MaidrKey.AXES: axes_data,
             MaidrKey.DATA: self._extract_plot_data(),
         }
 

maidr/core/plot/mplfinance_barplot.py

@@ -142,7 +142,11 @@ class MplfinanceBarPlot(
     def render(self) -> dict:
         base_schema = super().render()
         base_schema[MaidrKey.TITLE] = "Volume Bar Plot"
-        base_schema[MaidrKey.AXES] = self._extract_axes_data()
+        # Update axes labels while preserving format from parent
+        axes_data = self._extract_axes_data()
+        if MaidrKey.AXES in base_schema and MaidrKey.FORMAT in base_schema[MaidrKey.AXES]:
+            axes_data[MaidrKey.FORMAT] = base_schema[MaidrKey.AXES][MaidrKey.FORMAT]
+        base_schema[MaidrKey.AXES] = axes_data
         base_schema[MaidrKey.DATA] = self._extract_plot_data()
         if self._support_highlighting:
             base_schema[MaidrKey.SELECTOR] = self._get_selector()

maidr/core/plot/mplfinance_lineplot.py

@@ -192,7 +192,11 @@ class MplfinanceLinePlot(MaidrPlot, LineExtractorMixin):
     def render(self) -> dict:
         base_schema = super().render()
         base_schema[MaidrKey.TITLE] = "Moving Average Line Plot"
-        base_schema[MaidrKey.AXES] = self._extract_axes_data()
+        # Update axes labels while preserving format from parent
+        axes_data = self._extract_axes_data()
+        if MaidrKey.AXES in base_schema and MaidrKey.FORMAT in base_schema[MaidrKey.AXES]:
+            axes_data[MaidrKey.FORMAT] = base_schema[MaidrKey.AXES][MaidrKey.FORMAT]
+        base_schema[MaidrKey.AXES] = axes_data
         base_schema[MaidrKey.DATA] = self._extract_plot_data()
         if self._support_highlighting:
             base_schema[MaidrKey.SELECTOR] = self._get_selector()

maidr/util/datetime_conversion.py

@@ -6,16 +6,18 @@ from datetime import datetime
 
 class DatetimeConverter:
     """
-    Datetime converter for mplfinance plots.
+    Enhanced datetime converter that automatically detects time periods
+    and provides intelligent date/time formatting for mplfinance plots.
 
-    This utility provides datetime value conversion for financial data visualization.
+    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 (currently unused, kept for compatibility).
+        Custom datetime format string. If None, automatic format detection is used.
 
     Attributes
     ----------
@@ -162,7 +164,9 @@ class DatetimeConverter:
 
     def get_formatted_datetime(self, index: int) -> Optional[str]:
         """
-        Get datetime string for given index.
+        Get formatted datetime string for given index using consistent formatting.
+
+        Always includes year for screen reader accessibility.
 
         Parameters
         ----------
@@ -172,13 +176,13 @@ class DatetimeConverter:
         Returns
         -------
         str or None
-            Datetime string or None if index is invalid.
+            Formatted datetime string or None if index is invalid.
 
         Examples
         --------
         >>> converter = create_datetime_converter(df)
         >>> formatted = converter.get_formatted_datetime(0)
-        >>> print(formatted)  # "2024-01-15 00:00:00"
+        >>> print(formatted)  # "2024-01-15 00:00:00" (plain datetime string)
         """
         if index not in self.date_mapping:
             return None
@@ -188,7 +192,7 @@ class DatetimeConverter:
 
     def _format_datetime_custom(self, dt: datetime) -> str:
         """
-        Format datetime as-is using ISO format.
+        Return plain datetime string representation.
 
         Parameters
         ----------
@@ -198,14 +202,13 @@ class DatetimeConverter:
         Returns
         -------
         str
-            Formatted datetime string in ISO format.
+            Plain string representation of datetime (ISO format).
 
         Notes
         -----
-        Returns the datetime as a string without smart formatting.
-        Output format is "YYYY-MM-DD HH:MM:SS" (e.g., "2024-01-15 00:00:00").
+        Returns the raw string representation of the datetime object,
+        allowing the frontend to handle formatting as needed.
         """
-        # Return string representation of datetime
         return str(dt)
 
     @property

maidr/util/format_config.py

@@ -0,0 +1,679 @@
+"""
+Format configuration utilities for extracting and representing axis formatting.
+
+This module provides classes and utilities for detecting matplotlib axis formatters
+and converting them to MAIDR-compatible format configurations.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Optional
+
+from matplotlib.axes import Axes
+from matplotlib.dates import DateFormatter
+from matplotlib.ticker import (
+    Formatter,
+    FuncFormatter,
+    PercentFormatter,
+    ScalarFormatter,
+    StrMethodFormatter,
+    FormatStrFormatter,
+)
+
+
+class FormatType(str, Enum):
+    """
+    Enumeration of supported format types for MAIDR.
+
+    These types correspond to the formatting options supported by
+    the MAIDR JavaScript library's FormatterService.
+    """
+
+    CURRENCY = "currency"
+    PERCENT = "percent"
+    DATE = "date"
+    NUMBER = "number"
+    SCIENTIFIC = "scientific"
+    FIXED = "fixed"
+
+
+@dataclass
+class FormatConfig:
+    """
+    Configuration for axis value formatting.
+
+    This class represents a format configuration that can be serialized
+    to the MAIDR schema format. It supports both type-based formatting
+    and custom JavaScript function bodies.
+
+    Parameters
+    ----------
+    type : FormatType, optional
+        The type of formatting to apply.
+    function : str, optional
+        JavaScript function body for custom formatting.
+        This is evaluated by MAIDR JS using: new Function('value', functionBody)
+        Example: "return parseFloat(value).toFixed(2)"
+    decimals : int, optional
+        Number of decimal places to display.
+    currency : str, optional
+        Currency code (e.g., "USD", "EUR") for currency formatting.
+    locale : str, optional
+        BCP 47 locale string (e.g., "en-US") for locale-specific formatting.
+    dateFormat : str, optional
+        Date format string (e.g., "%b %d" for "Jan 15") for date formatting.
+
+    Examples
+    --------
+    >>> config = FormatConfig(type=FormatType.CURRENCY, decimals=2, currency="USD")
+    >>> config.to_dict()
+    {'type': 'currency', 'decimals': 2, 'currency': 'USD'}
+
+    >>> config = FormatConfig(function="return '$' + parseFloat(value).toFixed(2)")
+    >>> config.to_dict()
+    {'function': "return '$' + parseFloat(value).toFixed(2)"}
+    """
+
+    type: Optional[FormatType] = None
+    function: Optional[str] = None
+    decimals: Optional[int] = None
+    currency: Optional[str] = None
+    locale: Optional[str] = None
+    dateFormat: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert the format configuration to a dictionary.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Dictionary representation suitable for MAIDR schema.
+            Only includes non-None values. If function is provided,
+            it takes precedence over type-based formatting.
+        """
+        result: Dict[str, Any] = {}
+
+        # Function takes precedence - if provided, use it directly
+        if self.function is not None:
+            result["function"] = self.function
+            return result
+
+        # Otherwise use type-based formatting
+        if self.type is not None:
+            result["type"] = self.type.value
+
+        if self.decimals is not None:
+            result["decimals"] = self.decimals
+        if self.currency is not None:
+            result["currency"] = self.currency
+        if self.locale is not None:
+            result["locale"] = self.locale
+        if self.dateFormat is not None:
+            result["dateFormat"] = self.dateFormat
+
+        return result
+
+
+class JSBodyConverter:
+    """
+    Converter for generating JavaScript function bodies from matplotlib formatters.
+
+    These function bodies are evaluated by MAIDR JS using:
+    new Function('value', functionBody)
+    """
+
+    # Mapping of Python strftime codes to JavaScript date formatting
+    # Common patterns with optimized JS bodies
+    STRFTIME_PATTERNS: Dict[str, str] = {
+        "%b %d": (
+            "var m=['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];"
+            "var d=new Date(value);return m[d.getMonth()]+' '+d.getDate()"
+        ),
+        "%b %d, %Y": (
+            "var m=['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];"
+            "var d=new Date(value);return m[d.getMonth()]+' '+d.getDate()+', '+d.getFullYear()"
+        ),
+        "%Y-%m-%d": (
+            "var d=new Date(value);"
+            "return d.getFullYear()+'-'+String(d.getMonth()+1).padStart(2,'0')+'-'"
+            "+String(d.getDate()).padStart(2,'0')"
+        ),
+        "%m/%d/%Y": (
+            "var d=new Date(value);"
+            "return String(d.getMonth()+1).padStart(2,'0')+'/'"
+            "+String(d.getDate()).padStart(2,'0')+'/'+d.getFullYear()"
+        ),
+        "%d/%m/%Y": (
+            "var d=new Date(value);"
+            "return String(d.getDate()).padStart(2,'0')+'/'"
+            "+String(d.getMonth()+1).padStart(2,'0')+'/'+d.getFullYear()"
+        ),
+        "%Y": "return new Date(value).getFullYear().toString()",
+        "%B %Y": (
+            "var m=['January','February','March','April','May','June',"
+            "'July','August','September','October','November','December'];"
+            "var d=new Date(value);return m[d.getMonth()]+' '+d.getFullYear()"
+        ),
+        "%H:%M": (
+            "var d=new Date(value);"
+            "return String(d.getHours()).padStart(2,'0')+':'"
+            "+String(d.getMinutes()).padStart(2,'0')"
+        ),
+        "%H:%M:%S": (
+            "var d=new Date(value);"
+            "return String(d.getHours()).padStart(2,'0')+':'"
+            "+String(d.getMinutes()).padStart(2,'0')+':'"
+            "+String(d.getSeconds()).padStart(2,'0')"
+        ),
+        "%I:%M %p": (
+            "var d=new Date(value);"
+            "var h=d.getHours();var ampm=h>=12?'PM':'AM';h=h%12;h=h?h:12;"
+            "return String(h).padStart(2,'0')+':'+String(d.getMinutes()).padStart(2,'0')+' '+ampm"
+        ),
+    }
+
+    @staticmethod
+    def date_format_to_js(fmt: str) -> str:
+        """
+        Convert Python strftime format to JavaScript function body.
+
+        Parameters
+        ----------
+        fmt : str
+            Python strftime format string (e.g., '%b %d', '%Y-%m-%d')
+
+        Returns
+        -------
+        str
+            JavaScript function body that formats dates similarly.
+        """
+        if fmt in JSBodyConverter.STRFTIME_PATTERNS:
+            return JSBodyConverter.STRFTIME_PATTERNS[fmt]
+
+        # Fallback: use toLocaleString for unrecognized formats
+        return "return new Date(value).toLocaleDateString()"
+
+    @staticmethod
+    def currency_format_to_js(symbol: str, decimals: int = 2) -> str:
+        """
+        Convert currency format to JavaScript function body.
+
+        Parameters
+        ----------
+        symbol : str
+            Currency symbol ($, €, £, ¥)
+        decimals : int
+            Number of decimal places
+
+        Returns
+        -------
+        str
+            JavaScript function body for currency formatting.
+        """
+        # Map symbols to locales
+        locale_map = {
+            "$": "en-US",
+            "€": "de-DE",
+            "£": "en-GB",
+            "¥": "ja-JP",
+        }
+        locale = locale_map.get(symbol, "en-US")
+
+        # Yen typically has no decimals
+        if symbol == "¥":
+            decimals = 0
+
+        return (
+            f"return '{symbol}'+parseFloat(value).toLocaleString('{locale}',"
+            f"{{minimumFractionDigits:{decimals},maximumFractionDigits:{decimals}}})"
+        )
+
+    @staticmethod
+    def number_format_to_js(decimals: Optional[int] = None) -> str:
+        """
+        Convert number format (with thousands separator) to JavaScript function body.
+
+        Parameters
+        ----------
+        decimals : int, optional
+            Number of decimal places
+
+        Returns
+        -------
+        str
+            JavaScript function body for number formatting.
+        """
+        if decimals is not None:
+            return (
+                f"return parseFloat(value).toLocaleString('en-US',"
+                f"{{minimumFractionDigits:{decimals},maximumFractionDigits:{decimals}}})"
+            )
+        return "return parseFloat(value).toLocaleString('en-US')"
+
+    @staticmethod
+    def fixed_format_to_js(decimals: int) -> str:
+        """
+        Convert fixed decimal format to JavaScript function body.
+
+        Parameters
+        ----------
+        decimals : int
+            Number of decimal places
+
+        Returns
+        -------
+        str
+            JavaScript function body for fixed decimal formatting.
+        """
+        return f"return parseFloat(value).toFixed({decimals})"
+
+    @staticmethod
+    def percent_format_to_js(decimals: int = 1, multiply: bool = True) -> str:
+        """
+        Convert percent format to JavaScript function body.
+
+        Parameters
+        ----------
+        decimals : int
+            Number of decimal places
+        multiply : bool
+            Whether to multiply by 100 (for values stored as decimals)
+
+        Returns
+        -------
+        str
+            JavaScript function body for percent formatting.
+        """
+        if multiply:
+            return f"return (parseFloat(value)*100).toFixed({decimals})+'%'"
+        return f"return parseFloat(value).toFixed({decimals})+'%'"
+
+    @staticmethod
+    def scientific_format_to_js(decimals: int = 2) -> str:
+        """
+        Convert scientific notation format to JavaScript function body.
+
+        Parameters
+        ----------
+        decimals : int
+            Number of decimal places in mantissa
+
+        Returns
+        -------
+        str
+            JavaScript function body for scientific notation formatting.
+        """
+        return f"return parseFloat(value).toExponential({decimals})"
+
+    @staticmethod
+    def default_format_to_js() -> str:
+        """
+        Return default JavaScript function body for unsupported formatters.
+
+        Returns
+        -------
+        str
+            JavaScript function body that returns value as string.
+        """
+        return "return String(value)"
+
+
+class FormatConfigBuilder:
+    """
+    Builder for extracting format configurations from matplotlib formatters.
+
+    This class provides static methods to detect and parse matplotlib axis
+    formatters and convert them to FormatConfig objects with JavaScript
+    function bodies for MAIDR JS evaluation.
+
+    Examples
+    --------
+    >>> from matplotlib import pyplot as plt
+    >>> fig, ax = plt.subplots()
+    >>> ax.yaxis.set_major_formatter('${x:,.2f}')
+    >>> config = FormatConfigBuilder.from_formatter(ax.yaxis.get_major_formatter())
+    >>> config.function
+    "return '$'+parseFloat(value).toLocaleString('en-US',{minimumFractionDigits:2,maximumFractionDigits:2})"
+    """
+
+    # Currency symbol patterns for detection
+    CURRENCY_PATTERNS = {
+        "$": "USD",
+        "USD": "USD",
+        "€": "EUR",
+        "EUR": "EUR",
+        "£": "GBP",
+        "GBP": "GBP",
+        "¥": "JPY",
+        "JPY": "JPY",
+    }
+
+    @staticmethod
+    def from_formatter(formatter: Optional[Formatter]) -> Optional[FormatConfig]:
+        """
+        Create a FormatConfig from a matplotlib Formatter.
+
+        Parameters
+        ----------
+        formatter : Formatter or None
+            A matplotlib ticker Formatter object, or None.
+
+        Returns
+        -------
+        FormatConfig or None
+            The detected format configuration, or None if the formatter
+            type could not be determined.
+        """
+        if formatter is None:
+            return None
+
+        # Check for DateFormatter (for date/time axes)
+        if isinstance(formatter, DateFormatter):
+            return FormatConfigBuilder._parse_date_formatter(formatter)
+
+        # Check for PercentFormatter
+        if isinstance(formatter, PercentFormatter):
+            return FormatConfigBuilder._parse_percent_formatter(formatter)
+
+        # Check for StrMethodFormatter (most common for custom formats)
+        if isinstance(formatter, StrMethodFormatter):
+            return FormatConfigBuilder._parse_str_method_formatter(formatter)
+
+        # Check for FormatStrFormatter (old-style % formatting)
+        if isinstance(formatter, FormatStrFormatter):
+            return FormatConfigBuilder._parse_format_str_formatter(formatter)
+
+        # Check for ScalarFormatter with scientific notation
+        if isinstance(formatter, ScalarFormatter):
+            return FormatConfigBuilder._parse_scalar_formatter(formatter)
+
+        # Check for FuncFormatter (custom function)
+        if isinstance(formatter, FuncFormatter):
+            return FormatConfigBuilder._parse_func_formatter(formatter)
+
+        return None
+
+    @staticmethod
+    def _parse_date_formatter(formatter: DateFormatter) -> FormatConfig:
+        """Parse a DateFormatter to FormatConfig with JS function body."""
+        date_format = None
+        if hasattr(formatter, "fmt") and formatter.fmt is not None:
+            date_format = formatter.fmt
+
+        # Generate JS function body for date formatting
+        js_body = JSBodyConverter.date_format_to_js(date_format) if date_format else None
+
+        if js_body:
+            return FormatConfig(function=js_body)
+
+        # Fallback to type-based config
+        return FormatConfig(type=FormatType.DATE, dateFormat=date_format)
+
+    @staticmethod
+    def _parse_percent_formatter(formatter: PercentFormatter) -> FormatConfig:
+        """Parse a PercentFormatter to FormatConfig using type-based preset."""
+        decimals = None
+        if hasattr(formatter, "decimals") and formatter.decimals is not None:
+            decimals = int(formatter.decimals)
+
+        # Use type-based preset for percent
+        return FormatConfig(type=FormatType.PERCENT, decimals=decimals)
+
+    @staticmethod
+    def _parse_str_method_formatter(
+        formatter: StrMethodFormatter,
+    ) -> Optional[FormatConfig]:
+        """Parse a StrMethodFormatter to FormatConfig using hybrid approach."""
+        fmt = getattr(formatter, "fmt", None)
+        if fmt is None:
+            return None
+
+        return FormatConfigBuilder._parse_format_string_hybrid(fmt)
+
+    @staticmethod
+    def _parse_format_str_formatter(
+        formatter: FormatStrFormatter,
+    ) -> Optional[FormatConfig]:
+        """Parse a FormatStrFormatter (old-style %) to FormatConfig using type-based presets."""
+        fmt = getattr(formatter, "fmt", None)
+        if fmt is None:
+            return None
+
+        # Convert old-style format to type-based config
+        # e.g., "%.2f" -> fixed with 2 decimals
+        match = re.search(r"%\.?(\d*)([efg])", fmt, re.IGNORECASE)
+        if match:
+            decimals_str = match.group(1)
+            format_char = match.group(2).lower()
+
+            decimals = int(decimals_str) if decimals_str else None
+
+            if format_char == "e":
+                return FormatConfig(type=FormatType.SCIENTIFIC, decimals=decimals)
+            elif format_char in ("f", "g"):
+                return FormatConfig(type=FormatType.FIXED, decimals=decimals)
+
+        return None
+
+    @staticmethod
+    def _parse_scalar_formatter(formatter: ScalarFormatter) -> Optional[FormatConfig]:
+        """Parse a ScalarFormatter to FormatConfig using type-based preset.
+
+        ScalarFormatter is the default matplotlib formatter and often has _scientific=True
+        due to auto-detection. We only return a FormatConfig if useMathText is explicitly
+        enabled, as this indicates the user wants formatted scientific notation display.
+        """
+        # useMathText is only True when explicitly set by user via set_useMathText(True)
+        # This provides nice-looking scientific notation like 10^6 instead of 1e6
+        use_math_text = getattr(formatter, "_useMathText", False)
+        if use_math_text is True:
+            return FormatConfig(type=FormatType.SCIENTIFIC)
+
+        # Default ScalarFormatter - no explicit format configured by user
+        # We ignore _scientific since matplotlib auto-sets it based on data magnitude
+        return None
+
+    @staticmethod
+    def _parse_func_formatter(formatter: FuncFormatter) -> Optional[FormatConfig]:
+        """
+        Attempt to parse a FuncFormatter by examining the function.
+
+        This is a best-effort approach since FuncFormatter can contain
+        arbitrary functions. For unsupported functions, returns a default
+        formatter that shows the value as-is.
+        """
+        func = getattr(formatter, "func", None)
+        if func is None:
+            return None
+
+        # Try to get function source or docstring for hints
+        func_name = getattr(func, "__name__", "")
+
+        # Common naming conventions - generate JS function bodies
+        if "percent" in func_name.lower():
+            js_body = JSBodyConverter.percent_format_to_js(1, multiply=True)
+            return FormatConfig(function=js_body)
+        elif "currency" in func_name.lower() or "dollar" in func_name.lower():
+            js_body = JSBodyConverter.currency_format_to_js("$", 2)
+            return FormatConfig(function=js_body)
+        elif "date" in func_name.lower() or "time" in func_name.lower():
+            js_body = "return new Date(value).toLocaleDateString()"
+            return FormatConfig(function=js_body)
+
+        # For unknown FuncFormatters, return default (value as-is)
+        # This ensures the value is still displayed
+        return FormatConfig(function=JSBodyConverter.default_format_to_js())
+
+    @staticmethod
+    def _parse_format_string_hybrid(fmt: str) -> Optional[FormatConfig]:
+        """
+        Parse a format string using hybrid approach: type-based presets for simple
+        formats, JS functions for complex formats.
+
+        Parameters
+        ----------
+        fmt : str
+            A Python format string (e.g., "${x:,.2f}", "{x:.1%}").
+
+        Returns
+        -------
+        FormatConfig or None
+            The detected format configuration using appropriate approach.
+        """
+        if not fmt:
+            return None
+
+        decimals = FormatConfigBuilder._extract_decimals(fmt)
+
+        # Detect currency by symbol prefix - use type-based preset
+        for symbol, currency_code in FormatConfigBuilder.CURRENCY_PATTERNS.items():
+            if symbol in fmt:
+                return FormatConfig(
+                    type=FormatType.CURRENCY, decimals=decimals, currency=currency_code
+                )
+
+        # Detect percent format (ends with %) like {x:.1%} - use type-based preset
+        if "%" in fmt and "{" in fmt:
+            if re.search(r"\{[^}]*%\}", fmt):
+                return FormatConfig(type=FormatType.PERCENT, decimals=decimals)
+
+        # Detect scientific notation like {x:.2e} - use type-based preset
+        if re.search(r"\{[^}]*[eE]\}", fmt):
+            return FormatConfig(type=FormatType.SCIENTIFIC, decimals=decimals)
+
+        # Detect number format with comma separators like {x:,.2f} or {x:,}
+        # - use type-based preset
+        if re.search(r"\{[^}]*,", fmt):
+            return FormatConfig(type=FormatType.NUMBER, decimals=decimals)
+
+        # Detect fixed-point format (no comma separator) like {x:.2f}
+        # - use type-based preset
+        match = re.search(r"\{[^}]*\.(\d+)f\}", fmt)
+        if match:
+            decimals = int(match.group(1))
+            return FormatConfig(type=FormatType.FIXED, decimals=decimals)
+
+        # No recognized format - return None (don't add format config)
+        return None
+
+    @staticmethod
+    def _parse_format_string(fmt: str) -> Optional[FormatConfig]:
+        """
+        Parse a format string to detect the format type and options.
+        (Legacy method - kept for backwards compatibility)
+
+        Parameters
+        ----------
+        fmt : str
+            A Python format string (e.g., "${x:,.2f}", "{x:.1%}").
+
+        Returns
+        -------
+        FormatConfig or None
+            The detected format configuration.
+        """
+        if not fmt:
+            return None
+
+        # Detect currency by symbol prefix
+        for symbol, currency_code in FormatConfigBuilder.CURRENCY_PATTERNS.items():
+            if symbol in fmt:
+                decimals = FormatConfigBuilder._extract_decimals(fmt)
+                return FormatConfig(
+                    type=FormatType.CURRENCY, decimals=decimals, currency=currency_code
+                )
+
+        # Detect percent format (ends with %)
+        if "%" in fmt and "{" in fmt:
+            # Check if it's a percent format like {x:.1%}
+            if re.search(r"\{[^}]*%\}", fmt):
+                decimals = FormatConfigBuilder._extract_decimals(fmt)
+                return FormatConfig(type=FormatType.PERCENT, decimals=decimals)
+
+        # Detect scientific notation
+        if re.search(r"\{[^}]*[eE]\}", fmt):
+            decimals = FormatConfigBuilder._extract_decimals(fmt)
+            return FormatConfig(type=FormatType.SCIENTIFIC, decimals=decimals)
+
+        # Detect number format with comma separators (must check before fixed-point)
+        # This matches formats like {x:,.2f} or {x:,}
+        if re.search(r"\{[^}]*,", fmt):
+            decimals = FormatConfigBuilder._extract_decimals(fmt)
+            return FormatConfig(type=FormatType.NUMBER, decimals=decimals)
+
+        # Detect fixed-point format (no comma separator)
+        match = re.search(r"\{[^}]*\.(\d+)f\}", fmt)
+        if match:
+            decimals = int(match.group(1))
+            return FormatConfig(type=FormatType.FIXED, decimals=decimals)
+
+        return None
+
+    @staticmethod
+    def _extract_decimals(fmt: str) -> Optional[int]:
+        """
+        Extract the number of decimal places from a format string.
+
+        Parameters
+        ----------
+        fmt : str
+            A Python format string.
+
+        Returns
+        -------
+        int or None
+            The number of decimal places, or None if not specified.
+        """
+        # Match patterns like .2f, .1%, .3e
+        match = re.search(r"\.(\d+)[fFeE%]", fmt)
+        if match:
+            return int(match.group(1))
+        return None
+
+
+def extract_axis_format(ax: Optional[Axes]) -> Dict[str, Dict[str, Any]]:
+    """
+    Extract format configurations from both axes of a plot.
+
+    Parameters
+    ----------
+    ax : Axes or None
+        The matplotlib Axes object to extract formats from, or None.
+
+    Returns
+    -------
+    Dict[str, Dict[str, Any]]
+        Dictionary with 'x' and/or 'y' keys containing format configurations.
+        Only includes axes where a format could be detected.
+
+    Examples
+    --------
+    >>> from matplotlib import pyplot as plt
+    >>> fig, ax = plt.subplots()
+    >>> ax.yaxis.set_major_formatter('${x:,.2f}')
+    >>> formats = extract_axis_format(ax)
+    >>> formats
+    {'y': {'type': 'currency', 'decimals': 2, 'currency': 'USD'}}
+    """
+    if ax is None:
+        return {}
+
+    result: Dict[str, Dict[str, Any]] = {}
+
+    # Extract X-axis format
+    x_formatter = ax.xaxis.get_major_formatter()
+    x_config = FormatConfigBuilder.from_formatter(x_formatter)
+    if x_config is not None:
+        result["x"] = x_config.to_dict()
+
+    # Extract Y-axis format
+    y_formatter = ax.yaxis.get_major_formatter()
+    y_config = FormatConfigBuilder.from_formatter(y_formatter)
+    if y_config is not None:
+        result["y"] = y_config.to_dict()
+
+    return result

maidr/util/mixin/__init__.py

@@ -5,4 +5,15 @@ from .extractor_mixin import (
     LineExtractorMixin,
     ScalarMappableExtractorMixin,
 )
+from .format_extractor_mixin import FormatExtractorMixin
 from .merger_mixin import DictMergerMixin
+
+__all__ = [
+    "CollectionExtractorMixin",
+    "ContainerExtractorMixin",
+    "LevelExtractorMixin",
+    "LineExtractorMixin",
+    "ScalarMappableExtractorMixin",
+    "FormatExtractorMixin",
+    "DictMergerMixin",
+]

maidr/util/mixin/format_extractor_mixin.py

@@ -0,0 +1,83 @@
+"""
+Mixin for extracting format configuration from matplotlib axes.
+
+This module provides a mixin class that can be used by plot classes
+to extract axis formatting information for the MAIDR schema.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from matplotlib.axes import Axes
+
+from maidr.util.format_config import extract_axis_format
+
+
+class FormatExtractorMixin:
+    """
+    Mixin class for extracting format configuration from axes.
+
+    This mixin provides methods to detect and extract formatting
+    configurations from matplotlib axis formatters, which can then
+    be included in the MAIDR schema.
+
+    Examples
+    --------
+    >>> class MyPlot(MaidrPlot, FormatExtractorMixin):
+    ...     def render(self):
+    ...         schema = super().render()
+    ...         format_config = self.extract_format(self.ax)
+    ...         if format_config:
+    ...             schema["format"] = format_config
+    ...         return schema
+    """
+
+    @staticmethod
+    def extract_format(ax: Axes) -> Optional[Dict[str, Dict[str, Any]]]:
+        """
+        Extract format configuration from an axes object.
+
+        This method detects matplotlib formatters applied to the x and y axes
+        and converts them to MAIDR-compatible format configurations.
+
+        Parameters
+        ----------
+        ax : Axes
+            The matplotlib Axes object to extract formats from.
+
+        Returns
+        -------
+        Dict[str, Dict[str, Any]] or None
+            Dictionary with 'x' and/or 'y' keys containing format configurations,
+            or None if no formats could be detected.
+
+        Notes
+        -----
+        Supported formatter types:
+        - StrMethodFormatter: Detected by parsing format string
+        - PercentFormatter: Detected as percent type
+        - ScalarFormatter: Detected for scientific notation
+        - FormatStrFormatter: Detected by parsing old-style format string
+
+        Format detection examples:
+        - "${x:,.2f}" -> {"type": "currency", "currency": "USD", "decimals": 2}
+        - "{x:.1%}" -> {"type": "percent", "decimals": 1}
+        - "{x:.2e}" -> {"type": "scientific", "decimals": 2}
+
+        Examples
+        --------
+        >>> from matplotlib import pyplot as plt
+        >>> fig, ax = plt.subplots()
+        >>> ax.yaxis.set_major_formatter('${x:,.2f}')
+        >>> format_config = FormatExtractorMixin.extract_format(ax)
+        >>> format_config
+        {'y': {'type': 'currency', 'decimals': 2, 'currency': 'USD'}}
+        """
+        if ax is None:
+            return None
+
+        format_config = extract_axis_format(ax)
+
+        # Return None if no formats were detected
+        return format_config if format_config else None

{maidr-1.10.0.dist-info → maidr-1.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maidr
-Version: 1.10.0
+Version: 1.11.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

{maidr-1.10.0.dist-info → maidr-1.11.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-maidr/__init__.py,sha256=BXkAG-4A4pF_IjbBj6cOmPTmQYICXnfPniPJ-4OHnr0,416
+maidr/__init__.py,sha256=F_rKqEP7cG3G5_iKehrmY967FA1fiwdVXlibD7MotpM,416
 maidr/api.py,sha256=WK7jfQttuPeF1q45RuF_wTciYyiFY6SyjfZVSOVkiUs,4316
 maidr/core/__init__.py,sha256=WgxLpSEYMc4k3OyEOf1shOxfEq0ASzppEIZYmE91ThQ,25
 maidr/core/context_manager.py,sha256=6cT7ZGOApSpC-SLD2XZWWU_H08i-nfv-JUlzXOtvWYw,3374
@@ -6,21 +6,21 @@ maidr/core/figure_manager.py,sha256=t-lhe4jj2gsF5-8VUBUZOPlDutKjm_AZ8xXWJU2pFRc,
 maidr/core/maidr.py,sha256=Ye2C8tQPY1o8gfURiTyDPMWFoRT0toZOOCugKAz4uQU,22370
 maidr/core/enum/__init__.py,sha256=9ee78L0dlxEx4ulUGVlD-J23UcUZmrGu0rXms54up3c,93
 maidr/core/enum/library.py,sha256=e8ujT_L-McJWfoVJd1ty9K_2bwITnf1j0GPLsnAcHes,104
-maidr/core/enum/maidr_key.py,sha256=ljG0omqzd8K8Yk213N7i7PXGvG-IOlnE5v7o6RoGJzc,795
+maidr/core/enum/maidr_key.py,sha256=qO8dsRuMqiGmBHygSLRcu-wvfhch_3nY0PUvFBZkLH4,817
 maidr/core/enum/plot_type.py,sha256=7Orx3b_0NdpI_PtVJfLyJPh4qBqYMTsYBBr8VwOtiAM,347
 maidr/core/enum/smooth_keywords.py,sha256=z2kVZZ-mETWWh5reWu_hj9WkJD6WFj7_2-6s1e4C1JE,236
 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=qOsYIbn2sRdGE2ES-YJ-Rwhu4NsScHs52mtKe6Bl7_A,8236
+maidr/core/plot/candlestick.py,sha256=r_x3KVLNn6wFX7wYsRUFEp_rNTEjhbAkLk55kX2tIso,8170
 maidr/core/plot/grouped_barplot.py,sha256=odZ52Pl22nb9cWKD3NGsZsyFDxXdBDAEcbOj66HKp9I,4063
 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=uoJpGkJB3IJSDJTwH6ECxLyXGdarsVQNULELp5NncWg,4522
-maidr/core/plot/maidr_plot.py,sha256=heotWue1IzMOXnpoHVCqKSW88Sfep1IuuP4MBarpSek,4231
+maidr/core/plot/maidr_plot.py,sha256=_Jt0ILyUaMP68kX35Fgd16FcsizUAy52Y54YfVm2bEs,4580
 maidr/core/plot/maidr_plot_factory.py,sha256=NW2iFScswgXbAC9rAOo4iMkAFsjY43DAvFioGr0yzx4,2732
-maidr/core/plot/mplfinance_barplot.py,sha256=zhTp2i6BH0xn7vQvGTotKgu2HbzlKT4p6zA5CVUUHHc,5673
-maidr/core/plot/mplfinance_lineplot.py,sha256=pIbsusnQg1_GrstVVHfMw-t9yipWJowa9ZvGsiVV6l8,7329
+maidr/core/plot/mplfinance_barplot.py,sha256=WSr5OPK05SEDK1VCjMeCb2vNWJgMcz2c8TTbTZqow7U,5944
+maidr/core/plot/mplfinance_lineplot.py,sha256=bE6NHuUYzym_yG7WvjMTIDKOiiqSe67KvCtYHjLhPJ8,7600
 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
@@ -40,19 +40,21 @@ maidr/patch/mplfinance.py,sha256=ySD32onanoMgdQkV6XlSAbVd_BQuLWuEQtpkYSEDSzA,949
 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=BF115xweGcrKyDnnjYPeScc0WgeNpCylV0Z-mYKaP4w,13769
+maidr/util/datetime_conversion.py,sha256=7L8gYw3Fb7oL1swiMRpXgFO06U473vbnJ81Bexnyb2o,14043
 maidr/util/dedup_utils.py,sha256=RpgPL5p-3oULUHaTCZJaQKhPHfyPkvBLHMt8lAGpJ5A,438
 maidr/util/environment.py,sha256=C4VMyB16mqzrFxpJdxFdm40M0IZojxh60UX80680jgo,9403
+maidr/util/format_config.py,sha256=mU4BEZJ05FFYTk8mbDQrjADLn486Blb7_eKZQZORvYA,23438
 maidr/util/mplfinance_utils.py,sha256=00YEjrCUbigZZL1j9jzOTamNnwfy5ZZmXJj65AhgNbw,3662
 maidr/util/plot_detection.py,sha256=bgLHoDcHSRwOiyKzUK3EqGwdAIhF44ocHW5ox6xYGZw,3883
 maidr/util/regression_line_utils.py,sha256=yFKr-H0whT_su2YVZwNksBLp5EC5s77sr6HUFgNcsyY,2329
 maidr/util/svg_utils.py,sha256=2gyzBtNKFHs0utrw1iOlxTmznzivOWQMV2aW8zu2c8E,1442
-maidr/util/mixin/__init__.py,sha256=aGJZNhtWh77yIVPc7ipIZm1OajigjMtCWYKPuDWTC-c,217
+maidr/util/mixin/__init__.py,sha256=f_70pOT9tAUm8KXjoU2TJcTNXCTlDBsfPsDuxV101j4,492
 maidr/util/mixin/extractor_mixin.py,sha256=j2Rv2vh_gqqcxLV1ka3xsPaPAfWsX94CtKIW2FgPLnI,6937
+maidr/util/mixin/format_extractor_mixin.py,sha256=jBmZ8JflDOC3Co-tKC2yka0viZawyI-zKNZijQPU8_Y,2726
 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.10.0.dist-info/METADATA,sha256=6llsnqQI7-gfp62yZJ1ucSXxf9xvrUVNtcItkoxnwnM,3155
-maidr-1.10.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-maidr-1.10.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
-maidr-1.10.0.dist-info/RECORD,,
+maidr-1.11.0.dist-info/METADATA,sha256=kriH4WLxxakBNSpLxHNk_nvPdqMXbw4JuK8aejvP9-4,3155
+maidr-1.11.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+maidr-1.11.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+maidr-1.11.0.dist-info/RECORD,,