ENH: add axisbelow option 'line', make it the default

efiring · efiring · commit 5af57a70112a · 2016-04-10T15:54:17.000-10:00
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -36,6 +36,7 @@
 from matplotlib.artist import allow_rasterization
 
 from matplotlib.rcsetup import cycler
+from matplotlib.rcsetup import validate_axisbelow
 
 rcParams = matplotlib.rcParams
 
@@ -441,8 +442,9 @@ def __init__(self, fig, rect,
           *aspect*           [ 'auto' | 'equal' | aspect_ratio ]
           *autoscale_on*     [ *True* | *False* ] whether or not to
                              autoscale the *viewlim*
-          *axisbelow*        draw the grids and ticks below the other
-                             artists
+          *axisbelow*        [ *True* | *False* | 'line'] draw the grids
+                             and ticks below or above most other artists,
+                             or below lines but above patches
           *cursor_props*     a (*float*, *color*) tuple
           *figure*           a :class:`~matplotlib.figure.Figure`
                              instance
@@ -2308,12 +2310,16 @@ def draw(self, renderer=None, inframe=False):
                 artists.remove(spine)
 
         if self.axison and not inframe:
-            if self._axisbelow:
+            if self._axisbelow == True:
                 self.xaxis.set_zorder(0.5)
                 self.yaxis.set_zorder(0.5)
-            else:
+            elif self._axisbelow == False:
                 self.xaxis.set_zorder(2.5)
                 self.yaxis.set_zorder(2.5)
+            else:
+                # above patches, below lines
+                self.xaxis.set_zorder(1.5)
+                self.yaxis.set_zorder(1.5)
         else:
             for _axis in self._get_axis_list():
                 artists.remove(_axis)
@@ -2413,9 +2419,9 @@ def set_axisbelow(self, b):
         Set whether the axis ticks and gridlines are above or below most
         artists
 
-        ACCEPTS: [ *True* | *False* ]
+        ACCEPTS: [ *True* | *False* | 'line' ]
         """
-        self._axisbelow = b
+        self._axisbelow = validate_axisbelow(b)
         self.stale = True
 
     @docstring.dedent_interpd
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -175,6 +175,17 @@ def validate_string_or_None(s):
     except ValueError:
         raise ValueError('Could not convert "%s" to string' % s)
 
+def validate_axisbelow(s):
+    try:
+        return validate_bool(s)
+    except ValueError:
+        if isinstance(s, six.string_types):
+            s = s.lower()
+            if s.startswith('line'):
+                return 'line'
+    raise ValueError('%s cannot be interpreted as'
+                     ' True, False, or "line"' % s)
+
 
 def validate_dpi(s):
     """confirm s is string 'figure' or convert s to float or raise"""
@@ -981,7 +992,7 @@ def validate_animation_writer_path(p):
     'errorbar.capsize':      [0, validate_float],
 
     # axes props
-    'axes.axisbelow':        [False, validate_bool],
+    'axes.axisbelow':        ['line', validate_axisbelow],
     'axes.hold':             [True, validate_bool],
     'axes.facecolor':        ['w', validate_color],  # background color; white
     'axes.edgecolor':        ['k', validate_color],  # edge color; black
