Fix behaviour of Figure.clear() for SubplotParams (matplotlib#27183)

* Fix behaviour of Figure.clear() for SubplotParams

* update credits

* lint

* lint

* lint

* lint

* run boilerplate.py

* add tests

* Update doc/users/next_whats_new/subplots_adjust.rst

Co-authored-by: Kyle Sunden <[email protected]>

* update news entry

* increase coverage

* flake8

* lint

* lint

* Update lib/matplotlib/tests/test_figure.py

* increase coverage

* increase coverage

* remove usage of rc_default

* update whatsnew

* whitespace

* whitespace

* Apply suggestions from code review

Co-authored-by: Tim Hoffmann <[email protected]>

* review comments

* fix merge conflicts

* remove duplicate test

* remove redundant test

* ci

* ci

* Update lib/matplotlib/tests/test_gridspec.py

Co-authored-by: Tim Hoffmann <[email protected]>

* Update lib/matplotlib/tests/test_gridspec.py

Co-authored-by: Tim Hoffmann <[email protected]>

* Update doc/users/next_whats_new/subplots_adjust.rst

Co-authored-by: Jody Klymak <[email protected]>

* Update lib/matplotlib/gridspec.py

Co-authored-by: Jody Klymak <[email protected]>

* Update lib/matplotlib/gridspec.py

Co-authored-by: Jody Klymak <[email protected]>

* whitespace

* Update doc/users/next_whats_new/subplots_adjust.rst

Co-authored-by: Jody Klymak <[email protected]>

---------

Co-authored-by: Kyle Sunden <[email protected]>
Co-authored-by: Tim Hoffmann <[email protected]>
Co-authored-by: Jody Klymak <[email protected]>

Author: 4 people

doc/users/next_whats_new/subplots_adjust.rst

@@ -0,0 +1,7 @@
+Resetting the subplot parameters for figure.clear()
+---------------------------------------------------
+
+When calling `.Figure.clear()` the settings for `.gridspec.SubplotParams` are restored to the default values.
+
+`~.SubplotParams.to_dict` is a new method to get the subplot parameters as a dict,
+and `~.SubplotParams.reset` resets the parameters to the defaults.

lib/matplotlib/figure.py

@@ -989,6 +989,7 @@ def clear(self, keep_observers=False):
         self.texts = []
         self.images = []
         self.legends = []
+        self.subplotpars.reset()
         if not keep_observers:
             self._axobservers = cbook.CallbackRegistry()
         self._suptitle = None

lib/matplotlib/gridspec.py

@@ -750,22 +750,22 @@ def __init__(self, left=None, bottom=None, right=None, top=None,
 
         Parameters
         ----------
-        left : float
+        left : float, optional
             The position of the left edge of the subplots,
             as a fraction of the figure width.
-        right : float
+        right : float, optional
             The position of the right edge of the subplots,
             as a fraction of the figure width.
-        bottom : float
+        bottom : float, optional
             The position of the bottom edge of the subplots,
             as a fraction of the figure height.
-        top : float
+        top : float, optional
             The position of the top edge of the subplots,
             as a fraction of the figure height.
-        wspace : float
+        wspace : float, optional
             The width of the padding between subplots,
             as a fraction of the average Axes width.
-        hspace : float
+        hspace : float, optional
             The height of the padding between subplots,
             as a fraction of the average Axes height.
         """
@@ -796,3 +796,12 @@ def update(self, left=None, bottom=None, right=None, top=None,
             self.wspace = wspace
         if hspace is not None:
             self.hspace = hspace
+
+    def reset(self):
+        """Restore the subplot positioning parameters to the default rcParams values"""
+        for key in self.to_dict():
+            setattr(self, key, mpl.rcParams[f'figure.subplot.{key}'])
+
+    def to_dict(self):
+        """Return a copy of the subplot parameters as a dict."""
+        return self.__dict__.copy()

lib/matplotlib/gridspec.pyi

@@ -168,3 +168,7 @@ class SubplotParams:
         wspace: float | None = ...,
         hspace: float | None = ...,
     ) -> None: ...
+    def to_dict(
+        self,
+    ) -> dict[str, float]: ...
+    def reset(self) -> None: ...

lib/matplotlib/tests/test_figure.py

@@ -1770,6 +1770,24 @@ def test_warn_colorbar_mismatch():
         subfig3_1.colorbar(im4_1)
 
 
+def test_clf_subplotpars():
+    keys = ('left', 'right', 'bottom', 'top', 'wspace', 'hspace')
+    rc_params = {key: plt.rcParams['figure.subplot.' + key] for key in keys}
+
+    fig = plt.figure(1)
+    fig.subplots_adjust(**{k: v+0.01 for k, v in rc_params.items()})
+    fig.clf()
+    assert fig.subplotpars.to_dict() == rc_params
+
+
+def test_suplots_adjust_incremental():
+    fig = plt.figure()
+    fig.subplots_adjust(left=0)
+    fig.subplots_adjust(right=1)
+    assert fig.subplotpars.left == 0
+    assert fig.subplotpars.right == 1
+
+
 def test_set_figure():
     fig = plt.figure()
     sfig1 = fig.subfigures()

lib/matplotlib/tests/test_gridspec.py

@@ -1,3 +1,4 @@
+import matplotlib
 import matplotlib.gridspec as gridspec
 import matplotlib.pyplot as plt
 import pytest
@@ -9,6 +10,13 @@ def test_equal():
     assert gs[:, 0] == gs[:, 0]
 
 
+def test_update():
+    gs = gridspec.GridSpec(2, 1)
+
+    gs.update(left=.1)
+    assert gs.left == .1
+
+
 def test_width_ratios():
     """
     Addresses issue #5835.
@@ -27,6 +35,23 @@ def test_height_ratios():
         gridspec.GridSpec(1, 1, height_ratios=[2, 1, 3])
 
 
+def test_SubplotParams():
+    s = gridspec.SubplotParams(.1, .1, .9, .9)
+    assert s.left == 0.1
+
+    s.reset()
+    assert s.left == matplotlib.rcParams['figure.subplot.left']
+
+    with pytest.raises(ValueError, match='left cannot be >= right'):
+        s.update(left=s.right + .01)
+
+    with pytest.raises(ValueError, match='bottom cannot be >= top'):
+        s.update(bottom=s.top + .01)
+
+    with pytest.raises(ValueError, match='left cannot be >= right'):
+        gridspec.SubplotParams(.1, .1, .09, .9)
+
+
 def test_repr():
     ss = gridspec.GridSpec(3, 3)[2, 1:3]
     assert repr(ss) == "GridSpec(3, 3)[2:3, 1:3]"