Merge pull request matplotlib#22345 from jklymak/mnt-make-layout-deprecations-pending

MNT: make layout deprecations pending

Author: timhoffm

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

lib/matplotlib/figure.py

@@ -2455,11 +2455,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
@@ -2483,7 +2488,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,
@@ -2494,7 +2500,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
         ----------
@@ -2509,7 +2517,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``.
@@ -2541,7 +2550,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``.

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()

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()