FIX: Deprecate using clabel() with filled contours

It's never been intended to be used that way and may cause inconsistent
plots. Closes matplotlib#31344.

Author: timhoffm

lib/matplotlib/contour.py

@@ -145,6 +145,17 @@ def clabel(self, levels=None, *,
             A list of `.Text` instances for the labels.
         """
 
+        if self.filled:
+            _api.warn_deprecated(
+                "3.11",
+                message="clabel() is not designed to be used with filled contours and "
+                        "may result in inconsistent plots. Applying clabel() to filled "
+                        "contours is thus deprecated since %(since)s. If you need "
+                        "labels with filled contours, instead draw contour lines "
+                        "using contour() in addition to contourf() and add the labels "
+                        "to the contour lines."
+            )
+
         # Based on the input arguments, clabel() adds a list of "label
         # specific" attributes to the ContourSet object.  These attributes are
         # all of the form label* and names should be fairly self explanatory.

lib/matplotlib/tests/test_contour.py

@@ -310,6 +310,15 @@ def test_label_contour_start():
     assert 0 in idxs
 
 
+def test_clabel_raises_on_filled_contours():
+    X, Y = np.meshgrid(np.arange(10), np.arange(10))
+    _, ax = plt.subplots()
+    cs = ax.contourf(X, Y, X + Y)
+    # will be an exception once the deprecation expires
+    with pytest.warns(mpl.MatplotlibDeprecationWarning):
+        ax.clabel(cs)
+
+
 @image_comparison(['contour_corner_mask_False.png', 'contour_corner_mask_True.png'],
                   remove_text=True, tol=1.88)
 def test_corner_mask():