matplotlib · jklymak · Jan 27, 2020 · Jan 26, 2020 · Jan 26, 2020 · Jan 27, 2020
diff --git a/doc/users/next_whats_new/2020-01-25-clabel_zorder.rst b/doc/users/next_whats_new/2020-01-25-clabel_zorder.rst
@@ -0,0 +1,9 @@
+Set zorder of contour labels
+----------------------------
+`~.axes.Axes.clabel` now accepts a ``zorder`` kwarg
+making it easier to set the ``zorder`` of contour labels.
+If not specified, the default ``zorder`` of clabels used to always be 3
+(i.e. the default ``zorder`` of `~.text.Text`) irrespective of the ``zorder``
+passed to `~.axes.Axes.contour`/`~.axes.Axes.contourf`.
+The new default ``zorder`` for clabels has been changed to (2 + ``zorder``
+passed to `~.axes.Axes.contour`/`~.axes.Axes.contourf`).
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -51,7 +51,7 @@ class ContourLabeler:
     def clabel(self, levels=None, *,
                fontsize=None, inline=True, inline_spacing=5, fmt='%1.3f',
                colors=None, use_clabeltext=False, manual=False,
-               rightside_up=True):
+               rightside_up=True, zorder=None):
         """
         Label a contour plot.
 
@@ -124,6 +124,12 @@ def clabel(self, levels=None, *,
             of texts during the drawing time, therefore this can be used if
             aspect of the axes changes.
 
+        zorder : float or None, optional
+            zorder of the contour labels.
+
+            If not specified, the zorder of contour labels is set to
+            (2 + zorder of contours).
+
         Returns
         -------
         labels
@@ -144,6 +150,10 @@ def clabel(self, levels=None, *,
         # Detect if manual selection is desired and remove from argument list.
         self.labelManual = manual
         self.rightside_up = rightside_up
+        if zorder is None:
+            self._clabel_zorder = 2+self._contour_zorder
+        else:
+            self._clabel_zorder = zorder
 
         if levels is None:
             levels = self.levels
@@ -397,7 +407,7 @@ def _get_label_text(self, x, y, rotation):
         dx, dy = self.ax.transData.inverted().transform((x, y))
         t = text.Text(dx, dy, rotation=rotation,
                       horizontalalignment='center',
-                      verticalalignment='center')
+                      verticalalignment='center', zorder=self._clabel_zorder)
         return t
 
     def _get_label_clabeltext(self, x, y, rotation):
@@ -411,7 +421,7 @@ def _get_label_clabeltext(self, x, y, rotation):
                                                   np.array([[x, y]]))
         t = ClabelText(dx, dy, rotation=drotation[0],
                        horizontalalignment='center',
-                       verticalalignment='center')
+                       verticalalignment='center', zorder=self._clabel_zorder)
 
         return t
 
@@ -869,7 +879,7 @@ def __init__(self, ax, *args,
                 self.allkinds = [None] * len(self.allsegs)
 
             # Default zorder taken from Collection
-            zorder = kwargs.pop('zorder', 1)
+            self._contour_zorder = kwargs.pop('zorder', 1)
             for level, level_upper, segs, kinds in \
                     zip(lowers, uppers, self.allsegs, self.allkinds):
                 paths = self._make_paths(segs, kinds)
@@ -880,7 +890,7 @@ def __init__(self, ax, *args,
                     edgecolors='none',
                     alpha=self.alpha,
                     transform=self.get_transform(),
-                    zorder=zorder)
+                    zorder=self._contour_zorder)
                 self.ax.add_collection(col, autolim=False)
                 self.collections.append(col)
         else:
@@ -891,7 +901,7 @@ def __init__(self, ax, *args,
             if aa is not None:
                 aa = (self.antialiased,)
             # Default zorder taken from LineCollection
-            zorder = kwargs.pop('zorder', 2)
+            self._contour_zorder = kwargs.pop('zorder', 2)
             for level, width, lstyle, segs in \
                     zip(self.levels, tlinewidths, tlinestyles, self.allsegs):
                 col = mcoll.LineCollection(
@@ -901,7 +911,7 @@ def __init__(self, ax, *args,
                     linestyles=[lstyle],
                     alpha=self.alpha,
                     transform=self.get_transform(),
-                    zorder=zorder)
+                    zorder=self._contour_zorder)
                 col.set_label('_nolegend_')
                 self.ax.add_collection(col, autolim=False)
                 self.collections.append(col)

diff --git a/lib/matplotlib/tests/test_contour.py b/lib/matplotlib/tests/test_contour.py
@@ -290,6 +290,31 @@ def test_circular_contour_warning():
     assert len(record) == 0
 
 
+@pytest.mark.parametrize("use_clabeltext, contour_zorder, clabel_zorder",
+                         [(True, 123, 1234), (False, 123, 1234),
+                          (True, 123, None), (False, 123, None)])
+def test_clabel_zorder(use_clabeltext, contour_zorder, clabel_zorder):
+    x, y = np.meshgrid(np.arange(0, 10), np.arange(0, 10))
+    z = np.max(np.dstack([abs(x), abs(y)]), 2)
+
+    fig, (ax1, ax2) = plt.subplots(ncols=2)
+    cs = ax1.contour(x, y, z, zorder=contour_zorder)
+    cs_filled = ax2.contourf(x, y, z, zorder=contour_zorder)
+    clabels1 = cs.clabel(zorder=clabel_zorder, use_clabeltext=use_clabeltext)
+    clabels2 = cs_filled.clabel(zorder=clabel_zorder,
+                                use_clabeltext=use_clabeltext)
+
+    if clabel_zorder is None:
+        expected_clabel_zorder = 2+contour_zorder
+    else:
+        expected_clabel_zorder = clabel_zorder
+
+    for clabel in clabels1:
+        assert clabel.get_zorder() == expected_clabel_zorder
+    for clabel in clabels2:
+        assert clabel.get_zorder() == expected_clabel_zorder
+
+
 @image_comparison(['contour_log_extension.png'],
                   remove_text=True, style='mpl20')
 def test_contourf_log_extension():