diff --git a/doc/api/next_api_changes/deprecations/22345-JK.rst b/doc/api/next_api_changes/deprecations/22345-JK.rst new file mode 100644 index 000000000000..7db77b0be6d7 --- /dev/null +++ b/doc/api/next_api_changes/deprecations/22345-JK.rst @@ -0,0 +1,14 @@ +Pending deprecation of layout methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The methods `~Figure.set_tight_layout`, `~Figure.set_constrained_layout`, +are discouraged, and now emit a ``PendingDeprecationWarning`` in favor of +explicitly referencing the layout engine via +`figure.set_layout_engine('tight')` and +`figure.set_layout_engine('constrained')`. End users should not see the +warning, but library authors should adjust. + +The methods `~Figure.set_constrained_layout_pads` and +`~Figure.get_constrained_layout_pads` are will be deprecated in favor of +``figure.get_layout_engine().set()`` and +``figure.get_layout_engine().get()``, and currently emit a +``PendingDeprecationWarning``. \ No newline at end of file diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 2780599cc5c9..45562f2eba06 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -2484,11 +2484,16 @@ def get_tight_layout(self): """Return whether `.tight_layout` is called when drawing.""" return isinstance(self.get_layout_engine(), TightLayoutEngine) - @_api.deprecated("3.6", alternative="set_layout_engine") + @_api.deprecated("3.6", alternative="set_layout_engine", + pending=True) def set_tight_layout(self, tight): """ Set whether and how `.tight_layout` is called when drawing. + .. admonition:: Discouraged + + This method is discouraged in favor of `~.set_layout_engine`. + Parameters ---------- tight : bool or dict with keys "pad", "w_pad", "h_pad", "rect" or None @@ -2512,7 +2517,8 @@ def get_constrained_layout(self): """ return isinstance(self.get_layout_engine(), ConstrainedLayoutEngine) - @_api.deprecated("3.6", alternative="set_layout_engine('constrained')") + @_api.deprecated("3.6", alternative="set_layout_engine('constrained')", + pending=True) def set_constrained_layout(self, constrained): """ Set whether ``constrained_layout`` is used upon drawing. If None, @@ -2523,7 +2529,9 @@ def set_constrained_layout(self, constrained): overridden. These pads are in inches and default to 3.0/72.0. ``w_pad`` is the width padding and ``h_pad`` is the height padding. - See :doc:`/tutorials/intermediate/constrainedlayout_guide`. + .. admonition:: Discouraged + + This method is discouraged in favor of `~.set_layout_engine`. Parameters ---------- @@ -2538,7 +2546,8 @@ def set_constrained_layout(self, constrained): self.stale = True @_api.deprecated( - "3.6", alternative="figure.get_layout_engine().set()") + "3.6", alternative="figure.get_layout_engine().set()", + pending=True) def set_constrained_layout_pads(self, **kwargs): """ Set padding for ``constrained_layout``. @@ -2570,7 +2579,8 @@ def set_constrained_layout_pads(self, **kwargs): if isinstance(self.get_layout_engine(), ConstrainedLayoutEngine): self.get_layout_engine().set(**kwargs) - @_api.deprecated("3.6", alternative="fig.get_layout_engine().get_info()") + @_api.deprecated("3.6", alternative="fig.get_layout_engine().get()", + pending=True) def get_constrained_layout_pads(self, relative=False): """ Get padding for ``constrained_layout``. diff --git a/lib/matplotlib/tests/test_constrainedlayout.py b/lib/matplotlib/tests/test_constrainedlayout.py index 13b6f6c70917..3d18e86cf258 100644 --- a/lib/matplotlib/tests/test_constrainedlayout.py +++ b/lib/matplotlib/tests/test_constrainedlayout.py @@ -1,4 +1,3 @@ -from matplotlib._api.deprecation import MatplotlibDeprecationWarning import numpy as np import pytest @@ -594,14 +593,14 @@ def test_discouraged_api(): fig, ax = plt.subplots(constrained_layout=True) fig.draw_without_rendering() - with pytest.warns(MatplotlibDeprecationWarning, - match="was deprecated in Matplotlib 3.6"): + with pytest.warns(PendingDeprecationWarning, + match="will be deprecated"): fig, ax = plt.subplots() fig.set_constrained_layout(True) fig.draw_without_rendering() - with pytest.warns(MatplotlibDeprecationWarning, - match="was deprecated in Matplotlib 3.6"): + with pytest.warns(PendingDeprecationWarning, + match="will be deprecated"): fig, ax = plt.subplots() fig.set_constrained_layout({'w_pad': 0.02, 'h_pad': 0.02}) fig.draw_without_rendering() diff --git a/lib/matplotlib/tests/test_tightlayout.py b/lib/matplotlib/tests/test_tightlayout.py index b976d00546ec..1eb7b4b4534f 100644 --- a/lib/matplotlib/tests/test_tightlayout.py +++ b/lib/matplotlib/tests/test_tightlayout.py @@ -1,5 +1,4 @@ import warnings -from matplotlib._api.deprecation import MatplotlibDeprecationWarning import numpy as np from numpy.testing import assert_array_equal @@ -372,8 +371,8 @@ def test_clipped_to_axes(): def test_tight_pads(): fig, ax = plt.subplots() - with pytest.warns(MatplotlibDeprecationWarning, - match='was deprecated in Matplotlib 3.6'): + with pytest.warns(PendingDeprecationWarning, + match='will be deprecated'): fig.set_tight_layout({'pad': 0.15}) fig.draw_without_rendering()