mgplot 0.2.23__tar.gz → 0.2.25__tar.gz

mgplot-0.2.25/.python-version

@@ -0,0 +1 @@
+3.14

{mgplot-0.2.23 → mgplot-0.2.25}/CHANGELOG.md

@@ -1,3 +1,63 @@
+Version 0.2.25 - released 5-Jun-2026 (Canberra, Australia)
+
+* enhancement
+    - added tick_relabel keyword argument to line_plot(), bar_plot(),
+      growth_plot(), fill_between_plot() and run_plot() (and their
+      *_finalise variants): a callable applied to each generated x-axis
+      tick label after the contextual labellers have run (e.g. shorten
+      4-digit years to 2 digits)
+    - tick-label options (max_ticks, label rotation, tick_relabel) are
+      now stashed on the Axes by set_labels() and honoured when
+      finalise_plot() refreshes the labels before saving. Previously the
+      refresh regenerated labels with hard-coded defaults (max_ticks=10,
+      rotation=0), silently discarding per-plot settings
+    - added register_label_options() / get_label_options() to
+      axis_utils.py to support the above
+    - keyword checking now validates Callable annotations (checks
+      callability; previously a parameterized Callable would error)
+    - added test/test_tick_relabel.py covering tick_relabel, max_ticks
+      and label_rotation persistence through finalise_plot(), and
+      correct-figure close behaviour
+    - documented tick labelling and the multi-panel axes_only pattern
+      in README.md (new "Axis Tick Labels" and "Multi-Panel Figures"
+      sections)
+
+* bug fix
+    - bar_plot() applied label_rotation via plt.xticks(), which targets
+      pyplot's current axes rather than the axes being plotted (wrong
+      panel in multi-axes figures), and the rotation was then lost when
+      finalise_plot() refreshed PeriodIndex labels. Rotation now goes
+      via the stashed label options (PeriodIndex) or set_xticklabels()
+      (string index)
+    - finalise_plot() closed pyplot's current figure (plt.close()) rather
+      than the figure belonging to the axes being finalised; it now closes
+      the correct figure (walking up from a SubFigure if necessary)
+
+---
+
+Version 0.2.24 - released 4-Jun-2026 (Canberra, Australia)
+
+* enhancement
+    - added the chart_subdir() context manager to settings.py. It
+      temporarily redirects chart output to a subdirectory of the current
+      chart_dir, optionally clearing the subdirectory of image files on
+      entry (clear=True), and restores the previous chart directory on
+      exit, even if an exception is raised. Yields the subdirectory path.
+      Useful in notebooks that group saved charts into per-topic
+      subdirectories
+    - added test/test_chart_subdir.py covering redirect/restore,
+      exception safety, clear=True semantics and nested contexts
+    - sorted __all__ in __init__.py (removed a duplicate "run_plot"
+      entry), fixing a pre-existing RUF022 lint error
+    - resolved all remaining mypy/pyright errors with runtime type
+      narrowing (no casts): plot_latest_datapoint() in summary_plot.py
+      now verifies datapoints are numeric (raising TypeError otherwise)
+      before calling float(), and apply_splat_kwargs() in
+      finalise_plot.py narrows dynamically-fetched kwarg values before
+      passing them to _apply_splat()
+
+---
+
 Version 0.2.23 - released 24-Apr-2026 (Canberra, Australia)
 
 * bug fix

{mgplot-0.2.23 → mgplot-0.2.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mgplot
-Version: 0.2.23
+Version: 0.2.25
 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
@@ -94,6 +94,74 @@ ax = mg.line_plot(data)
 mg.finalise_plot(ax, title="My Chart", ylabel="Units", tag="my_chart")
 ```
 
+Axis Tick Labels
+----------------
+For PeriodIndex data, x-axis tick labels are generated contextually:
+the tick density is chosen to fit within `max_ticks`, and labels show
+the period with years marked at transitions (e.g. a monthly axis shows
+`Feb Mar ... 2024 ... Feb`, a quarterly axis shows `Q2 Q3 2025 Q2`).
+
+Three keyword arguments control the labels on the period-indexed plot
+functions (`line_plot`, `bar_plot`, `growth_plot`, `fill_between_plot`,
+`run_plot`, and their `*_finalise` variants):
+
+- `max_ticks` -- the maximum number of ticks (suggestive, not exact).
+  The global default is `mg.get_setting("max_ticks")`.
+- `tick_relabel` -- a callable applied to each generated label string,
+  after the contextual labelling has run. Use it to restyle labels
+  without losing the transition logic.
+- `label_rotation` -- (`bar_plot` only) rotates the x-axis tick labels.
+
+For example, to convert 4-digit year labels to 2-digit years:
+
+```python
+import re
+
+def two_digit_years(label: str) -> str:
+    """Shorten 4-digit years to 2 digits (e.g. 2024 -> 24)."""
+    return re.sub(r"\b(?:19|20)(\d{2})\b", r"\1", label)
+
+# default labels:           2010  2012  2014  ...  2024  2026
+# with tick_relabel:          10    12    14  ...    24    26
+mg.line_plot_finalise(data, title="My Chart", tick_relabel=two_digit_years)
+```
+
+Because `tick_relabel` operates on the label strings, this works
+unchanged on quarterly or monthly axes too: a label such as `2024`
+marking a year transition becomes `24`, while the `Q2`/`Mar` labels
+between transitions pass through untouched.
+
+These options are stashed on the matplotlib Axes when the plot is drawn,
+and `finalise_plot()` honours them when it refreshes the tick labels
+just before saving. Editing tick labels directly on the Axes (e.g. with
+`set_xticklabels()`) does not survive that refresh -- use `tick_relabel`
+instead.
+
+Multi-Panel Figures
+-------------------
+`finalise_plot()` works on a single Axes. For a figure with several
+panels, finalise each panel with `axes_only=True` (axes-level styling
+only: titles, labels, legends), then make the last call a normal
+`finalise_plot()` carrying the figure-level arguments (`suptitle`,
+`lfooter`, `rfooter`, `figsize`, ...), which also saves and closes
+the figure:
+
+```python
+fig, (ax_left, ax_right) = plt.subplots(1, 2)
+mg.line_plot(left_data, ax=ax_left)
+mg.line_plot(right_data, ax=ax_right)
+mg.finalise_plot(ax_left, title="Left Panel", ylabel="Index", axes_only=True)
+mg.finalise_plot(
+    ax_right,
+    title="Right Panel",
+    ylabel="Index",
+    suptitle="Both Panels Together",  # also used for the filename
+    lfooter="Australia. Seasonally adjusted.",
+    rfooter="Source: ABS",
+    figsize=(9, 4.5),
+)
+```
+
 Convenience Finalisers
 ----------------------
 For every plot function, there is a `*_finalise()` variant that combines

{mgplot-0.2.23 → mgplot-0.2.25}/README.md

@@ -78,6 +78,74 @@ ax = mg.line_plot(data)
 mg.finalise_plot(ax, title="My Chart", ylabel="Units", tag="my_chart")
 ```
 
+Axis Tick Labels
+----------------
+For PeriodIndex data, x-axis tick labels are generated contextually:
+the tick density is chosen to fit within `max_ticks`, and labels show
+the period with years marked at transitions (e.g. a monthly axis shows
+`Feb Mar ... 2024 ... Feb`, a quarterly axis shows `Q2 Q3 2025 Q2`).
+
+Three keyword arguments control the labels on the period-indexed plot
+functions (`line_plot`, `bar_plot`, `growth_plot`, `fill_between_plot`,
+`run_plot`, and their `*_finalise` variants):
+
+- `max_ticks` -- the maximum number of ticks (suggestive, not exact).
+  The global default is `mg.get_setting("max_ticks")`.
+- `tick_relabel` -- a callable applied to each generated label string,
+  after the contextual labelling has run. Use it to restyle labels
+  without losing the transition logic.
+- `label_rotation` -- (`bar_plot` only) rotates the x-axis tick labels.
+
+For example, to convert 4-digit year labels to 2-digit years:
+
+```python
+import re
+
+def two_digit_years(label: str) -> str:
+    """Shorten 4-digit years to 2 digits (e.g. 2024 -> 24)."""
+    return re.sub(r"\b(?:19|20)(\d{2})\b", r"\1", label)
+
+# default labels:           2010  2012  2014  ...  2024  2026
+# with tick_relabel:          10    12    14  ...    24    26
+mg.line_plot_finalise(data, title="My Chart", tick_relabel=two_digit_years)
+```
+
+Because `tick_relabel` operates on the label strings, this works
+unchanged on quarterly or monthly axes too: a label such as `2024`
+marking a year transition becomes `24`, while the `Q2`/`Mar` labels
+between transitions pass through untouched.
+
+These options are stashed on the matplotlib Axes when the plot is drawn,
+and `finalise_plot()` honours them when it refreshes the tick labels
+just before saving. Editing tick labels directly on the Axes (e.g. with
+`set_xticklabels()`) does not survive that refresh -- use `tick_relabel`
+instead.
+
+Multi-Panel Figures
+-------------------
+`finalise_plot()` works on a single Axes. For a figure with several
+panels, finalise each panel with `axes_only=True` (axes-level styling
+only: titles, labels, legends), then make the last call a normal
+`finalise_plot()` carrying the figure-level arguments (`suptitle`,
+`lfooter`, `rfooter`, `figsize`, ...), which also saves and closes
+the figure:
+
+```python
+fig, (ax_left, ax_right) = plt.subplots(1, 2)
+mg.line_plot(left_data, ax=ax_left)
+mg.line_plot(right_data, ax=ax_right)
+mg.finalise_plot(ax_left, title="Left Panel", ylabel="Index", axes_only=True)
+mg.finalise_plot(
+    ax_right,
+    title="Right Panel",
+    ylabel="Index",
+    suptitle="Both Panels Together",  # also used for the filename
+    lfooter="Australia. Seasonally adjusted.",
+    rfooter="Source: ABS",
+    figsize=(9, 4.5),
+)
+```
+
 Convenience Finalisers
 ----------------------
 For every plot function, there is a `*_finalise()` variant that combines