axisbelow should just set zorder.

anntzer · anntzer · commit 29a33332e4ba · 2017-08-25T19:08:23.000-07:00
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -487,7 +487,6 @@ def __init__(self, fig, rect,
         if self._position.width < 0 or self._position.height < 0:
             raise ValueError('Width and height specified must be non-negative')
         self._originalPosition = self._position.frozen()
-        # self.set_axes(self)
         self.axes = self
         self.set_aspect('auto')
         self._adjustable = 'box'
@@ -498,15 +497,11 @@ def __init__(self, fig, rect,
             self._shared_x_axes.join(self, sharex)
             if sharex._adjustable == 'box':
                 sharex._adjustable = 'datalim'
-                # warnings.warn(
-                #    'shared axes: "adjustable" is being changed to "datalim"')
             self._adjustable = 'datalim'
         if sharey is not None:
             self._shared_y_axes.join(self, sharey)
             if sharey._adjustable == 'box':
                 sharey._adjustable = 'datalim'
-                # warnings.warn(
-                #    'shared axes: "adjustable" is being changed to "datalim"')
             self._adjustable = 'datalim'
         self.set_label(label)
         self.set_figure(fig)
@@ -2341,18 +2336,9 @@ def draw(self, renderer=None, inframe=False):
             for spine in six.itervalues(self.spines):
                 artists.remove(spine)
 
-        if self.axison and not inframe:
-            if self._axisbelow is True:
-                self.xaxis.set_zorder(0.5)
-                self.yaxis.set_zorder(0.5)
-            elif self._axisbelow is False:
-                self.xaxis.set_zorder(2.5)
-                self.yaxis.set_zorder(2.5)
-            else:
-                # 'line': above patches, below lines
-                self.xaxis.set_zorder(1.5)
-                self.yaxis.set_zorder(1.5)
-        else:
+        self.xaxis.set_zorder(self.get_zorder())
+        self.yaxis.set_zorder(self.get_zorder())
+        if not self.axison and inframe:
             for _axis in self._get_axis_list():
                 artists.remove(_axis)
 
@@ -2425,34 +2411,39 @@ def get_renderer_cache(self):
     # Axes rectangle characteristics
 
     def get_frame_on(self):
-        """
-        Get whether the axes rectangle patch is drawn
-        """
+        """Get whether the axes rectangle patch is drawn."""
         return self._frameon
 
     def set_frame_on(self, b):
-        """
-        Set whether the axes rectangle patch is drawn
+        """Set whether the axes rectangle patch is drawn.
 
         ACCEPTS: [ *True* | *False* ]
         """
         self._frameon = b
         self.stale = True
 
     def get_axisbelow(self):
-        """
-        Get whether axis below is true or not
-        """
+        """Get whether axis below is true or not."""
         return self._axisbelow
 
     def set_axisbelow(self, b):
-        """
-        Set whether the axis ticks and gridlines are above or below most
-        artists
+        """Set the zorder for the axes ticks and gridlines.
+
+        ``True`` corresponds to a zorder of 0.5, ``False`` to a zorder of 2.5,
+        and ``"line"`` to a zorder of 1.5.
 
         ACCEPTS: [ *True* | *False* | 'line' ]
         """
-        self._axisbelow = validate_axisbelow(b)
+        self._axisbelow = axisbelow = validate_axisbelow(b)
+        if axisbelow is True:
+            zorder = 0.5
+        elif axisbelow is False:
+            zorder = 2.5
+        elif axisbelow == "line":
+            zorder = 1.5
+        else:
+            raise ValueError("Unexpected axisbelow value")
+        self.set_zorder(zorder)
         self.stale = True
 
     @docstring.dedent_interpd
@@ -2481,6 +2472,8 @@ def grid(self, b=None, which='major', axis='both', **kwargs):
 
         %(Line2D)s
 
+        Note that the will be drawn according to the axes' zorder and not its
+        own.
         """
         if len(kwargs):
             b = True
