mgplot 0.2.20__tar.gz → 0.2.21__tar.gz

{mgplot-0.2.20 → mgplot-0.2.21}/CHANGELOG.md

@@ -1,3 +1,14 @@
+Version 0.2.21 - released 17-Mar-2026 (Canberra, Australia)
+
+* enhancement
+    - axhline, axvline, axhspan, axvspan in finalise_plot() now accept
+      a sequence of dicts to draw multiple lines/spans in a single call,
+      in addition to the existing single dict usage
+    - added test/test_splat_sequences.py
+    - fixed FURB110 ruff warnings (ternary if replaced with or operator)
+
+---
+
 Version 0.2.20 - released 25-Feb-2026 (Canberra, Australia)
 
 * bug fix

{mgplot-0.2.20 → mgplot-0.2.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mgplot
-Version: 0.2.20
+Version: 0.2.21
 Summary: mgplot is a time-series/PeriodIndex frontend for matplotlib
 Project-URL: Repository, https://github.com/bpalmer4/mgplot
 Project-URL: Homepage, https://github.com/bpalmer4/mgplot

{mgplot-0.2.20 → mgplot-0.2.21}/docs/mgplot.html

@@ -2340,7 +2340,7 @@ for color management and finalising plots with consistent styling.</p>
                 <section id="__version__">
                     <div class="attr variable">
             <span class="name">__version__</span>        =
-<span class="default_value">&#39;0.2.19&#39;</span>
+<span class="default_value">&#39;0.2.20&#39;</span>
 
         
     </div>

{mgplot-0.2.20 → mgplot-0.2.21}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mgplot"
-version = "0.2.20"
+version = "0.2.21"
 description = "mgplot is a time-series/PeriodIndex frontend for matplotlib"
 readme = "README.md"
 requires-python = ">=3.12"

{mgplot-0.2.20 → mgplot-0.2.21}/src/mgplot/finalise_plot.py

@@ -43,10 +43,10 @@ class FinaliseKwargs(BaseKwargs):
     yscale: NotRequired[str | None]
     # --- splat options
     legend: NotRequired[bool | dict[str, Any] | None]
-    axhspan: NotRequired[dict[str, Any] | None]
-    axvspan: NotRequired[dict[str, Any] | None]
-    axhline: NotRequired[dict[str, Any] | None]
-    axvline: NotRequired[dict[str, Any] | None]
+    axhspan: NotRequired[dict[str, Any] | Sequence[dict[str, Any]] | None]
+    axvspan: NotRequired[dict[str, Any] | Sequence[dict[str, Any]] | None]
+    axhline: NotRequired[dict[str, Any] | Sequence[dict[str, Any]] | None]
+    axvline: NotRequired[dict[str, Any] | Sequence[dict[str, Any]] | None]
     # --- options for annotations
     lfooter: NotRequired[str]
     rfooter: NotRequired[str]
@@ -135,7 +135,7 @@ def sanitize_filename(filename: str, max_length: int = MAX_FILENAME_LENGTH) -> s
         filename = filename[:max_length].rstrip("-")
 
     # Ensure we have a valid filename
-    return filename if filename else "untitled"
+    return filename or "untitled"
 
 
 def make_legend(axes: Axes, *, legend: None | bool | dict[str, Any]) -> None:
@@ -194,34 +194,47 @@ def apply_value_kwargs(axes: Axes, value_kwargs_: Sequence[str], **kwargs: Unpac
         axes.set(**{setting: value})
 
 
+_SplatValue = bool | dict[str, Any] | Sequence[dict[str, Any]] | None
+
+
+def _apply_splat(axes: Axes, method_name: str, value: _SplatValue) -> None:
+    """Apply a single splat kwarg, which may be a dict or sequence of dicts."""
+    if value is None or value is False:
+        return
+
+    if value is True:  # use the global default settings
+        value = get_setting(method_name)
+
+    # normalise to a list of dicts
+    if isinstance(value, dict):
+        value = [value]
+
+    if isinstance(value, Sequence):
+        method = getattr(axes, method_name)
+        for item in value:
+            if isinstance(item, dict):
+                method(**item)
+            else:
+                print(f"Warning: expected dict in {method_name} sequence, but got {type(item)}.")
+    else:
+        print(f"Warning: expected dict or sequence of dicts for {method_name}, but got {type(value)}.")
+
+
 def apply_splat_kwargs(axes: Axes, settings: tuple, **kwargs: Unpack[FinaliseKwargs]) -> None:
     """Set matplotlib elements dynamically using setting_name and splat."""
     for method_name in settings:
-        if method_name in kwargs:
-            if method_name == "legend":
-                # special case for legend
-                legend_value = kwargs.get(method_name)
-                if isinstance(legend_value, (bool, dict, type(None))):
-                    make_legend(axes, legend=legend_value)
-                else:
-                    print(f"Warning: expected bool, dict, or None for legend, but got {type(legend_value)}.")
-                continue
-
-            value = kwargs.get(method_name)
-            if value is None or value is False:
-                continue
-
-            if value is True:  # use the global default settings
-                value = get_setting(method_name)
-
-            # splat the kwargs to the method
-            if isinstance(value, dict):
-                method = getattr(axes, method_name)
-                method(**value)
+        if method_name not in kwargs:
+            continue
+
+        if method_name == "legend":
+            legend_value = kwargs.get(method_name)
+            if isinstance(legend_value, (bool, dict, type(None))):
+                make_legend(axes, legend=legend_value)
             else:
-                print(
-                    f"Warning expected dict argument for {method_name} but got {type(value)}.",
-                )
+                print(f"Warning: expected bool, dict, or None for legend, but got {type(legend_value)}.")
+            continue
+
+        _apply_splat(axes, method_name, kwargs.get(method_name))
 
 
 def apply_annotations(axes: Axes, **kwargs: Unpack[FinaliseKwargs]) -> None:
@@ -305,8 +318,8 @@ def save_to_file(fig: Figure, **kwargs: Unpack[FinaliseKwargs]) -> None:
         title = kwargs.get("title", "")
         pre_tag = kwargs.get("pre_tag", "")
         tag = kwargs.get("tag", "")
-        name_title = suptitle if suptitle else title
-        file_title = sanitize_filename(name_title if name_title else DEFAULT_FILE_TITLE_NAME)
+        name_title = suptitle or title
+        file_title = sanitize_filename(name_title or DEFAULT_FILE_TITLE_NAME)
         file_type = kwargs.get("file_type", get_setting("file_type")).lower()
         dpi = kwargs.get("dpi", get_setting("dpi"))
 

mgplot-0.2.21/test/test_splat_sequences.py

@@ -0,0 +1,118 @@
+"""Test that axhline, axvline, axhspan, axvspan accept single dicts and sequences.
+
+Run with: uv run python test/test_splat_sequences.py
+"""
+
+import matplotlib.pyplot as plt
+import pandas as pd
+
+from mgplot import line_plot
+from mgplot.finalise_plot import finalise_plot
+
+
+def _make_series() -> pd.Series:
+    return pd.Series(range(1, 11), index=pd.period_range("2020-01", periods=10, freq="M"))
+
+
+def test_axhline_single_dict() -> None:
+    """A single dict should draw one horizontal line."""
+    ax = line_plot(_make_series())
+    finalise_plot(ax, axhline={"y": 5, "color": "red"}, dont_save=True, dont_close=True)
+
+    hlines = [l for l in ax.get_lines() if len(l.get_xdata()) == 2 and l.get_ydata()[0] == 5]
+    assert len(hlines) == 1, f"Expected 1 hline at y=5, found {len(hlines)}"
+
+    plt.close()
+    print("PASS: axhline single dict")
+
+
+def test_axhline_sequence() -> None:
+    """A sequence of dicts should draw multiple horizontal lines."""
+    ax = line_plot(_make_series())
+    finalise_plot(
+        ax,
+        axhline=[{"y": 3, "color": "red"}, {"y": 7, "color": "blue"}],
+        dont_save=True,
+        dont_close=True,
+    )
+
+    ys = {l.get_ydata()[0] for l in ax.get_lines() if len(l.get_xdata()) == 2}
+    assert 3 in ys, "Expected hline at y=3"
+    assert 7 in ys, "Expected hline at y=7"
+
+    plt.close()
+    print("PASS: axhline sequence")
+
+
+def test_axvline_sequence() -> None:
+    """A sequence of dicts should draw multiple vertical lines."""
+    ax = line_plot(_make_series())
+    finalise_plot(
+        ax,
+        axvline=[{"x": 2, "color": "red"}, {"x": 8, "color": "blue"}],
+        dont_save=True,
+        dont_close=True,
+    )
+
+    xs = {l.get_xdata()[0] for l in ax.get_lines() if len(l.get_ydata()) == 2}
+    assert 2 in xs, "Expected vline at x=2"
+    assert 8 in xs, "Expected vline at x=8"
+
+    plt.close()
+    print("PASS: axvline sequence")
+
+
+def test_axhspan_single_dict() -> None:
+    """A single dict should draw one horizontal span."""
+    ax = line_plot(_make_series())
+    n_patches_before = len(ax.patches)
+    finalise_plot(ax, axhspan={"ymin": 2, "ymax": 4, "alpha": 0.3}, dont_save=True, dont_close=True)
+
+    assert len(ax.patches) == n_patches_before + 1, "Expected 1 new patch from axhspan"
+
+    plt.close()
+    print("PASS: axhspan single dict")
+
+
+def test_axhspan_sequence() -> None:
+    """A sequence of dicts should draw multiple horizontal spans."""
+    ax = line_plot(_make_series())
+    n_patches_before = len(ax.patches)
+    finalise_plot(
+        ax,
+        axhspan=[{"ymin": 1, "ymax": 3, "alpha": 0.2}, {"ymin": 6, "ymax": 8, "alpha": 0.2}],
+        dont_save=True,
+        dont_close=True,
+    )
+
+    assert len(ax.patches) == n_patches_before + 2, "Expected 2 new patches from axhspan sequence"
+
+    plt.close()
+    print("PASS: axhspan sequence")
+
+
+def test_axvspan_sequence() -> None:
+    """A sequence of dicts should draw multiple vertical spans."""
+    ax = line_plot(_make_series())
+    n_patches_before = len(ax.patches)
+    finalise_plot(
+        ax,
+        axvspan=[{"xmin": 1, "xmax": 3}, {"xmin": 6, "xmax": 8}],
+        dont_save=True,
+        dont_close=True,
+    )
+
+    assert len(ax.patches) == n_patches_before + 2, "Expected 2 new patches from axvspan sequence"
+
+    plt.close()
+    print("PASS: axvspan sequence")
+
+
+if __name__ == "__main__":
+    test_axhline_single_dict()
+    test_axhline_sequence()
+    test_axvline_sequence()
+    test_axhspan_single_dict()
+    test_axhspan_sequence()
+    test_axvspan_sequence()
+    print("\nAll splat sequence tests passed!")