Merge pull request matplotlib#26634 from timhoffm/move-subplotparams

[MNT] Move SubplotParams from figure to gridspec

Author: jklymak

doc/api/gridspec_api.rst

@@ -19,3 +19,4 @@ Classes
    SubplotSpec
    GridSpecBase
    GridSpecFromSubplotSpec
+   SubplotParams

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.

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`

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.
 

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]

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

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: ...