Save & Export

Thin wrappers around matplotlib.Figure.savefig for common workflows: export multiple formats in one call, or save-and-display SVGs sized for notebooks/reports.

Example

import dartwork_mpl as dm

# Multi-format export with validation
dm.save_formats(fig, "report/figures/example",
                formats=("png", "svg", "pdf"), dpi=300)

# Save and preview
dm.save_and_show(fig, size=720)

# Display an existing SVG
dm.show("output/forecast.svg", size=540)

API

dartwork_mpl.save_formats(fig: Figure, image_stem: str, formats: tuple[str, ...] = ('png', 'pdf'), bbox_inches: str | None = None, validate: bool = True, *, adopt_orphan_tick_font: bool = True, **kwargs: Any) → None[source]

Save a figure in multiple specified formats at once.

Parameters:

  • fig (matplotlib.figure.Figure) – The Matplotlib figure to save.

  • image_stem (str) – Base path and filename without extension. If the value accidentally ends with a known image suffix (.png, .pdf, .svg, …) it is stripped automatically and a UserWarning is emitted — prevents double-extension output like chart.png.png.

  • formats (tuple[str, ...], optional) – Tuple of format extensions to save. Default is (“png”, “pdf”).

  • bbox_inches (str | None, optional) – Bounding box setting for the saved figure. Commonly “tight” to minimize whitespace. Default is None.

  • validate (bool, optional) – If True, performs visual validation before saving and prints [VISUAL] warnings to stdout on issues. Default is True.

  • adopt_orphan_tick_font (bool, optional) – If True (default), tick labels (and offset text) on any axis that has no axis label adopt that axis’s label font before saving, via adopt_axis_label_font(). This guarantees the saved output reflects the adoption even when simple_layout() was not called (it already applies the same step by default). Set to False to leave tick fonts untouched.

  • **kwargs – Additional keyword arguments passed to savefig.

Notes

With adopt_orphan_tick_font=True (the default) this call mutates the figure: it restyles the tick-label fonts of any unlabeled axis, and the change persists after the call. This is the one mutation save_formats performs (it otherwise only reads and writes). It is idempotent and matches what simple_layout already applies. It does not re-fit margins — call simple_layout for layouts that must grow to fit enlarged orphan ticks. On figures using matplotlib constrained_layout, the font change can trigger a re-layout on the next draw (expected matplotlib behavior). Pass adopt_orphan_tick_font=False to keep the figure untouched.

dartwork_mpl.save_and_show(fig: Figure, image_path: str | None = None, size: int = 600, unit: str = 'pt', *, adopt_orphan_tick_font: bool = True, **kwargs: Any) → None[source]

Save a figure to disk, then display it in a Jupyter or web environment.

Parameters:

  • fig (matplotlib.figure.Figure) – The Matplotlib figure to save and display.

  • image_path (str | None, optional) – Path to save the image. If None, a system temporary file is used.

  • size (int, optional) – Display width. Default is 600.

  • unit (str, optional) – Unit for the size (‘pt’, ‘px’, etc.). Default is ‘pt’.

  • adopt_orphan_tick_font (bool, optional) – If True (default), apply adopt_axis_label_font() before saving so unlabeled axes’ tick labels take the axis-label font, matching save_formats(). Mutates the figure (see that function’s Notes). Set to False to leave tick fonts untouched.

  • **kwargs – Additional keyword arguments passed to savefig.

dartwork_mpl.show(image_path: str, size: int = 600, unit: str = 'pt') → None[source]

Load an SVG image and display it at the specified size in a browser or Jupyter.

Parameters:

  • image_path (str) – Path to the SVG image to display.

  • size (int, optional) – Desired output width. Default is 600.

  • unit (str, optional) – Unit for the width (‘pt’, ‘px’, etc.). Default is ‘pt’.

Raises:

ImportError – If IPython is not installed. show renders inline in Jupyter via IPython, which is an optional extra — install it with pip install "dartwork-mpl[notebook]".