gsplot.save#

save(target, path, *, formats=None, dpi=600, crop=True, pad=None, show=True, close=False, create_parent=False, overwrite=True, transparent=False, metadata=None)#

Save one explicit Figure through a concise transactional workflow.

Parameters:

  • target (Figure | Axes | _AxesBase | Sequence[Axes | _AxesBase] | Mapping[Any, Axes | _AxesBase] | ndarray[tuple[int, ...], dtype[Any]]) – A Figure or finite Axes target resolving to exactly one root Figure.

  • path (str | PathLike[str]) – A supported suffix-bearing path or a suffix-free output base.

  • formats (str | Sequence[str] | None) – Ordered output formats. A suffix-free path defaults to PNG and PDF.

  • dpi (float) – Positive output resolution, defaulting to 600 dots per inch.

  • crop (bool) – Whether to use a tight crop and its non-negative padding in inches. pad=None resolves to 0.1 inch when cropping.

  • pad (float | None) – Whether to use a tight crop and its non-negative padding in inches. pad=None resolves to 0.1 inch when cropping.

  • show (bool) – Display after successful commits or close exactly the saved Figure. Both controls cannot be true together.

  • close (bool) – Display after successful commits or close exactly the saved Figure. Both controls cannot be true together.

  • create_parent (bool) – Create a missing parent directory when true.

  • overwrite (bool) – Replace existing regular files when true. Symlinks are always rejected.

  • transparent (bool) – Forward transparent output to Matplotlib.

  • metadata (Mapping[str, object] | None) – Optional string-keyed metadata forwarded to each selected format.

Returns:

Absolute final paths in requested format order.

Return type:

tuple[pathlib.Path, ]

Raises:

OutputError – If target, controls, rendering, commit, display, or closing fails.

Notes

Every format is rendered to a unique sibling first. Final paths are replaced only after all renders succeed. PDF and PostScript rendering uses Type 42 fonts in a bounded Matplotlib configuration context. Tight crop changes the exported media box; pass crop=False to preserve the exact Figure design canvas.

Examples

>>> import gsplot as gs
>>> figure, axis = gs.subplots()
>>> paths = gs.save(figure, "figure", show=False)
>>> tuple(path.suffix for path in paths)
('.png', '.pdf')
>>> figure.clear()