Metadata-Version: 2.1
Name: cs-mplutils
Version: 20241122
Summary: A few conveniences for working with matplotlib.
Author-email: Cameron Simpson <cs@cskk.id.au>
License: GNU General Public License v3 or later (GPLv3+)
Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/mplutils.py
Keywords: python3
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Description-Content-Type: text/markdown
Requires-Dist: cs.buffer>=20240630
Requires-Dist: cs.deco>=20241109
Requires-Dist: cs.lex>=20241122
Requires-Dist: cs.pfx>=20240630
Requires-Dist: matplotlib
Requires-Dist: typeguard

A few conveniences for working with matplotlib.

*Latest release 20241122*:
* FigureSize: fix field factories.
* print_figure: wire a .png extension for the temp image.

## <a name="axes"></a>`axes(figure=None, ax=None, **fig_kw) -> matplotlib.axes._axes.Axes`

Return a set of `Axes`.

Parameters:
* `figure`: optional `Figure` from which to obtain the `Axes`
  or an `(x,y)` figure size or an `(x,y,dpi)` figure size
* `ax`: optional `Axes` or axes index

If `ax` is already an `Axes` it is returned unchanged.
Otherwise `ax` should be the index of a set of axes,
default `0`.

If `figure` is a `Figure`, `ax` is used to select one of its
sets of axes.

Otherwise a `Figure` is created and a set of axes is selected.
The default figure size comes from the `FigureSize` defaults.

The `figure` positional parameter may be supplied
as a 2-tuple `(fig_dx,fig_dy)` to override the default size
or as a 3-tuple `(fig_dx,fig_dy,dpi)` to override the default size and dpi,
or as a `FigureSze`.

## <a name="FigureSize"></a>Class `FigureSize`

Specifications for a `Figure`'s dimensions.

*`FigureSize.Figure(self, **kw)`*:
Return a new `Figure` of this size.
It will have no subplots.

## <a name="print_figure"></a>`print_figure(figure_or_ax, imgformat=None, file=None)`

Print `figure_or_ax` to a file.

Parameters:
* `figure_or_ax`: a `matplotlib.figure.Figure` or an object
  with a `.figure` attribute such as a set of `Axes`
* `imgformat`: optional output format; if omitted use `'sixel'`
  if `file` is a terminal, otherwise `'png'`
* `file`: the output file, default `sys.stdout`

## <a name="remove_decorations"></a>`remove_decorations(figure_or_ax: Union[matplotlib.figure.Figure, matplotlib.axes._axes.Axes])`

Remove all decorations from a `Figure` or `Axes` instance,
intended for making bare plots such as a tile in GUI.

Presently this removes:
- axes markings and legend from each axis
- the padding from all the figure subplots

## <a name="save_figure"></a>`save_figure(figure_or_ax, imgpath: str, force=False)`

Save a `Figure` to the file `imgpath`.

Parameters:
* `figure_or_ax`: a `matplotlib.figure.Figure` or an object
  with a `.figure` attribute such as a set of `Axes`
* `imgpath`: the filesystem path to which to save the image
* `force`: optional flag, default `False`: if true the `imgpath`
  will be written to even if it exists

## <a name="saved_figure"></a>`saved_figure(figure_or_ax, dir=None, ext=None)`

Context manager to save a `Figure` to a file and yield the file path.
The file is removed on exit from the context.

Parameters:
* `figure_or_ax`: a `matplotlib.figure.Figure` or an object
  with a `.figure` attribute such as a set of `Axes`
* `dir`: passed to `tempfile.TemporaryDirectory`
* `ext`: optional file extension, default `'png'`

# Release Log



*Release 20241122*:
* FigureSize: fix field factories.
* print_figure: wire a .png extension for the temp image.

*Release 20230407*:
FigureSize: get defaults via $FIGURE_SIZE_DX, $FIGURE_SIZE_DY and $FIGURE_SIZE_DPI envvars.

*Release 20220918*:
* New FigureSize class.
* axes(): accept a FigureSize for figure.

*Release 20220805*:
Initial PyPI release.
