Make GridSpec.update docstring match behavior.

anntzer · anntzer · commit ef9e41860aa6 · 2019-01-04T22:41:53.000+01:00
The sentence "If any kwarg is None, default to the current value, if
set, otherwise to rc." is clearly wrong given the lines just below,
which overwrite the current value unconditonally:

    for k, v in kwargs.items():
        if k in self._AllowedKeys:
            setattr(self, k, v)

This can also be checked with e.g.

    from matplotlib.gridspec import GridSpec
    from matplotlib import pyplot as plt
    gs = GridSpec(1, 1, left=.5)
    gs.update(left=None)
    plt.figure().add_subplot(gs[0, 0])
    plt.show()

where the update reset left to the rc value.

Given that the behavior has been like that ever since gridspec was added
to matplotlib, it seems better to update the docstring.
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -255,16 +255,15 @@ def __setstate__(self, state):
 
     def update(self, **kwargs):
         """
-        Update the current values.  If any kwarg is None, default to
-        the current value, if set, otherwise to rc.
-        """
+        Update the current values.
 
+        Values set to None use the rcParams value.
+        """
         for k, v in kwargs.items():
             if k in self._AllowedKeys:
                 setattr(self, k, v)
             else:
-                raise AttributeError("%s is unknown keyword" % (k,))
-
+                raise AttributeError(f"{k} is an unknown keyword")
         for figmanager in _pylab_helpers.Gcf.figs.values():
             for ax in figmanager.canvas.figure.axes:
                 # copied from Figure.subplots_adjust
