diff --git a/doc/api/gridspec_api.rst b/doc/api/gridspec_api.rst index 2b9f5a67784c..fe1137d94113 100644 --- a/doc/api/gridspec_api.rst +++ b/doc/api/gridspec_api.rst @@ -19,3 +19,4 @@ Classes SubplotSpec GridSpecBase GridSpecFromSubplotSpec + SubplotParams diff --git a/doc/api/next_api_changes/behavior/26634-TH.rst b/doc/api/next_api_changes/behavior/26634-TH.rst new file mode 100644 index 000000000000..4961722078d6 --- /dev/null +++ b/doc/api/next_api_changes/behavior/26634-TH.rst @@ -0,0 +1,5 @@ +``SubplotParams`` has been moved from ``matplotlib.figure`` to ``matplotlib.gridspec`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is still importable from ``matplotlib.figure``, so does not require any changes to +existing code. diff --git a/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py b/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py index 3bd0d3f2bec1..e0a8c76a0e61 100644 --- a/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py +++ b/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py @@ -83,5 +83,5 @@ def on_draw(event): # - `matplotlib.transforms.BboxBase.union` # - `matplotlib.transforms.Transform.inverted` # - `matplotlib.figure.Figure.subplots_adjust` -# - `matplotlib.figure.SubplotParams` +# - `matplotlib.gridspec.SubplotParams` # - `matplotlib.backend_bases.FigureCanvasBase.mpl_connect` diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 4361ef655c81..c28ba98edec8 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -10,9 +10,6 @@ `SubFigure`) with `Figure.add_subfigure` or `Figure.subfigures` methods (provisional API v3.4). -`SubplotParams` - Control the default spacing between subplots. - Figures are typically created using pyplot methods `~.pyplot.figure`, `~.pyplot.subplots`, and `~.pyplot.subplot_mosaic`. @@ -51,7 +48,7 @@ import matplotlib.image as mimage from matplotlib.axes import Axes -from matplotlib.gridspec import GridSpec +from matplotlib.gridspec import GridSpec, SubplotParams from matplotlib.layout_engine import ( ConstrainedLayoutEngine, TightLayoutEngine, LayoutEngine, PlaceHolderLayoutEngine @@ -118,66 +115,6 @@ def __setstate__(self, state): self._counter = itertools.count(next_counter) -class SubplotParams: - """ - A class to hold the parameters for a subplot. - """ - - def __init__(self, left=None, bottom=None, right=None, top=None, - wspace=None, hspace=None): - """ - Defaults are given by :rc:`figure.subplot.[name]`. - - Parameters - ---------- - left : float - The position of the left edge of the subplots, - as a fraction of the figure width. - right : float - The position of the right edge of the subplots, - as a fraction of the figure width. - bottom : float - The position of the bottom edge of the subplots, - as a fraction of the figure height. - top : float - The position of the top edge of the subplots, - as a fraction of the figure height. - wspace : float - The width of the padding between subplots, - as a fraction of the average Axes width. - hspace : float - The height of the padding between subplots, - as a fraction of the average Axes height. - """ - for key in ["left", "bottom", "right", "top", "wspace", "hspace"]: - setattr(self, key, mpl.rcParams[f"figure.subplot.{key}"]) - self.update(left, bottom, right, top, wspace, hspace) - - def update(self, left=None, bottom=None, right=None, top=None, - wspace=None, hspace=None): - """ - Update the dimensions of the passed parameters. *None* means unchanged. - """ - if ((left if left is not None else self.left) - >= (right if right is not None else self.right)): - raise ValueError('left cannot be >= right') - if ((bottom if bottom is not None else self.bottom) - >= (top if top is not None else self.top)): - raise ValueError('bottom cannot be >= top') - if left is not None: - self.left = left - if right is not None: - self.right = right - if bottom is not None: - self.bottom = bottom - if top is not None: - self.top = top - if wspace is not None: - self.wspace = wspace - if hspace is not None: - self.hspace = hspace - - class FigureBase(Artist): """ Base class for `.Figure` and `.SubFigure` containing the methods that add @@ -2435,7 +2372,7 @@ def __init__(self, frameon : bool, default: :rc:`figure.frameon` If ``False``, suppress drawing the figure background patch. - subplotpars : `SubplotParams` + subplotpars : `~matplotlib.gridspec.SubplotParams` Subplot parameters. If not given, the default subplot parameters :rc:`figure.subplot.*` are used. diff --git a/lib/matplotlib/figure.pyi b/lib/matplotlib/figure.pyi index 40e8fce0321f..f53feb78014d 100644 --- a/lib/matplotlib/figure.pyi +++ b/lib/matplotlib/figure.pyi @@ -11,7 +11,7 @@ from matplotlib.backend_bases import ( from matplotlib.colors import Colormap, Normalize from matplotlib.colorbar import Colorbar from matplotlib.cm import ScalarMappable -from matplotlib.gridspec import GridSpec, SubplotSpec +from matplotlib.gridspec import GridSpec, SubplotSpec, SubplotParams as SubplotParams from matplotlib.image import _ImageBase, FigureImage from matplotlib.layout_engine import LayoutEngine from matplotlib.legend import Legend @@ -27,32 +27,6 @@ from collections.abc import Callable, Iterable from typing import Any, IO, Literal, overload from .typing import ColorType, HashableList -class SubplotParams: - def __init__( - self, - left: float | None = ..., - bottom: float | None = ..., - right: float | None = ..., - top: float | None = ..., - wspace: float | None = ..., - hspace: float | None = ..., - ) -> None: ... - left: float - right: float - bottom: float - top: float - wspace: float - hspace: float - def update( - self, - left: float | None = ..., - bottom: float | None = ..., - right: float | None = ..., - top: float | None = ..., - wspace: float | None = ..., - hspace: float | None = ..., - ) -> None: ... - class FigureBase(Artist): artists: list[Artist] lines: list[Line2D] diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py index b2f1b5d8ff2e..13a7d29ca563 100644 --- a/lib/matplotlib/gridspec.py +++ b/lib/matplotlib/gridspec.py @@ -320,7 +320,7 @@ class GridSpec(GridSpecBase): A grid layout to place subplots within a figure. The location of the grid cells is determined in a similar way to - `~.figure.SubplotParams` using *left*, *right*, *top*, *bottom*, *wspace* + `.SubplotParams` using *left*, *right*, *top*, *bottom*, *wspace* and *hspace*. Indexing a GridSpec instance returns a `.SubplotSpec`. @@ -424,7 +424,7 @@ def get_subplot_params(self, figure=None): if figure is None: kw = {k: mpl.rcParams["figure.subplot."+k] for k in self._AllowedKeys} - subplotpars = mpl.figure.SubplotParams(**kw) + subplotpars = SubplotParams(**kw) else: subplotpars = copy.copy(figure.subplotpars) @@ -517,9 +517,9 @@ def get_subplot_params(self, figure=None): figbox = self._subplot_spec.get_position(figure) left, bottom, right, top = figbox.extents - return mpl.figure.SubplotParams(left=left, right=right, - bottom=bottom, top=top, - wspace=wspace, hspace=hspace) + return SubplotParams(left=left, right=right, + bottom=bottom, top=top, + wspace=wspace, hspace=hspace) def get_topmost_subplotspec(self): """ @@ -736,3 +736,63 @@ def subgridspec(self, nrows, ncols, **kwargs): fig.add_subplot(gssub[0, i]) """ return GridSpecFromSubplotSpec(nrows, ncols, self, **kwargs) + + +class SubplotParams: + """ + Parameters defining the positioning of a subplots grid in a figure. + """ + + def __init__(self, left=None, bottom=None, right=None, top=None, + wspace=None, hspace=None): + """ + Defaults are given by :rc:`figure.subplot.[name]`. + + Parameters + ---------- + left : float + The position of the left edge of the subplots, + as a fraction of the figure width. + right : float + The position of the right edge of the subplots, + as a fraction of the figure width. + bottom : float + The position of the bottom edge of the subplots, + as a fraction of the figure height. + top : float + The position of the top edge of the subplots, + as a fraction of the figure height. + wspace : float + The width of the padding between subplots, + as a fraction of the average Axes width. + hspace : float + The height of the padding between subplots, + as a fraction of the average Axes height. + """ + for key in ["left", "bottom", "right", "top", "wspace", "hspace"]: + setattr(self, key, mpl.rcParams[f"figure.subplot.{key}"]) + self.update(left, bottom, right, top, wspace, hspace) + + def update(self, left=None, bottom=None, right=None, top=None, + wspace=None, hspace=None): + """ + Update the dimensions of the passed parameters. *None* means unchanged. + """ + if ((left if left is not None else self.left) + >= (right if right is not None else self.right)): + raise ValueError('left cannot be >= right') + if ((bottom if bottom is not None else self.bottom) + >= (top if top is not None else self.top)): + raise ValueError('bottom cannot be >= top') + if left is not None: + self.left = left + if right is not None: + self.right = right + if bottom is not None: + self.bottom = bottom + if top is not None: + self.top = top + if wspace is not None: + self.wspace = wspace + if hspace is not None: + self.hspace = hspace diff --git a/lib/matplotlib/gridspec.pyi b/lib/matplotlib/gridspec.pyi index 6e2273080b3b..6f314054a9ee 100644 --- a/lib/matplotlib/gridspec.pyi +++ b/lib/matplotlib/gridspec.pyi @@ -5,7 +5,7 @@ import numpy as np from matplotlib.axes import Axes, SubplotBase from matplotlib.backend_bases import RendererBase -from matplotlib.figure import Figure, SubplotParams +from matplotlib.figure import Figure from matplotlib.transforms import Bbox class GridSpecBase: @@ -132,3 +132,29 @@ class SubplotSpec: def subgridspec( self, nrows: int, ncols: int, **kwargs ) -> GridSpecFromSubplotSpec: ... + +class SubplotParams: + def __init__( + self, + left: float | None = ..., + bottom: float | None = ..., + right: float | None = ..., + top: float | None = ..., + wspace: float | None = ..., + hspace: float | None = ..., + ) -> None: ... + left: float + right: float + bottom: float + top: float + wspace: float + hspace: float + def update( + self, + left: float | None = ..., + bottom: float | None = ..., + right: float | None = ..., + top: float | None = ..., + wspace: float | None = ..., + hspace: float | None = ..., + ) -> None: ...