errorbar: fmt kwarg default is ''; deprecate None, use 'none' instead

efiring · efiring · commit 65a7ee7c7c58 · 2014-06-02T11:14:35.000-10:00
Closes #2366, replaces #2738.
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,10 @@
+2014-06-01 Changed the fmt kwarg of errorbar to support the
+           the mpl convention that "none" means "don't draw it",
+           and to default to the empty string, so that plotting
+           of data points is done with the plot() function
+           defaults.  Deprecated use of the None object in place
+           "none".
+
 2014-05-22 Allow the linscale keyword parameter of symlog scale to be
            smaller than one.
 
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -54,6 +54,12 @@ original location:
   the upper and lower limits (*lolims*, *uplims*, *xlolims*, *xuplims*) now
   point in the correct direction.
 
+* The *fmt* kwarg for :func:`~matplotlib.pyplot.errorbar now supports
+  the string 'none' to suppress drawing of a line and markers; use
+  of the *None* object for this is deprecated. The default *fmt*
+  value is changed to the empty string (''), so the line and markers
+  are governed by the :func:`~matplotlib.pyplot.plot` defaults.
+
 * A bug has been fixed in the path effects rendering of fonts, which now means
   that the font size is consistent with non-path effect fonts. See
   https://github.com/matplotlib/matplotlib/issues/2889 for more detail.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -15,7 +15,7 @@
 rcParams = matplotlib.rcParams
 
 import matplotlib.cbook as cbook
-from matplotlib.cbook import _string_to_bool
+from matplotlib.cbook import _string_to_bool, mplDeprecation
 import matplotlib.collections as mcoll
 import matplotlib.colors as mcolors
 import matplotlib.contour as mcontour
@@ -2062,7 +2062,7 @@ def make_iterable(x):
 
             errorbar = self.errorbar(x, y,
                                      yerr=yerr, xerr=xerr,
-                                     fmt=None, **error_kw)
+                                     fmt='none', **error_kw)
         else:
             errorbar = None
 
@@ -2520,7 +2520,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
 
     @docstring.dedent_interpd
     def errorbar(self, x, y, yerr=None, xerr=None,
-                 fmt='-', ecolor=None, elinewidth=None, capsize=3,
+                 fmt='', ecolor=None, elinewidth=None, capsize=3,
                  barsabove=False, lolims=False, uplims=False,
                  xlolims=False, xuplims=False, errorevery=1, capthick=None,
                  **kwargs):
@@ -2530,7 +2530,7 @@ def errorbar(self, x, y, yerr=None, xerr=None,
         Call signature::
 
           errorbar(x, y, yerr=None, xerr=None,
-                   fmt='-', ecolor=None, elinewidth=None, capsize=3,
+                   fmt='', ecolor=None, elinewidth=None, capsize=3,
                    barsabove=False, lolims=False, uplims=False,
                    xlolims=False, xuplims=False, errorevery=1,
                    capthick=None)
@@ -2552,10 +2552,12 @@ def errorbar(self, x, y, yerr=None, xerr=None,
             If a sequence of shape 2xN, errorbars are drawn at -row1
             and +row2 relative to the data.
 
-          *fmt*: '-'
-            The plot format symbol. If *fmt* is *None*, only the
-            errorbars are plotted.  This is used for adding
-            errorbars to a bar plot, for example.
+          *fmt*: [ '' | 'none' | plot format string ]
+            The plot format symbol. If *fmt* is 'none' (case-insensitive),
+            only the errorbars are plotted.  This is used for adding
+            errorbars to a bar plot, for example.  Default is '',
+            an empty plot format string; properties are
+            then identical to the defaults for :meth:`plot`.
 
           *ecolor*: [ *None* | mpl color ]
             A matplotlib color arg which gives the color the errorbar lines;
@@ -2635,6 +2637,15 @@ def errorbar(self, x, y, yerr=None, xerr=None,
         holdstate = self._hold
         self._hold = True
 
+        if fmt is None:
+            fmt = 'none'
+            msg = ('Use of None object as fmt keyword argument to '
+                   + 'suppress plotting of data values is deprecated '
+                   + 'since 1.4; use the string "none" instead.')
+            warnings.warn(msg, mplDeprecation, stacklevel=1)
+
+        plot_line = (fmt.lower() != 'none')
+
         label = kwargs.pop("label", None)
 
         # make sure all the args are iterable; use lists not arrays to
@@ -2655,7 +2666,9 @@ def errorbar(self, x, y, yerr=None, xerr=None,
 
         l0 = None
 
-        if barsabove and fmt is not None:
+        # Instead of using zorder, the line plot is being added
+        # either here, or after all the errorbar plot elements.
+        if barsabove and plot_line:
             l0, = self.plot(x, y, fmt, label="_nolegend_", **kwargs)
 
         barcols = []
@@ -2838,7 +2851,7 @@ def xywhere(xs, ys, mask):
                     xup, yup = xywhere(x, y, uplims & everymask)
                     caplines.extend(self.plot(xup, yup, 'k_', **plot_kw))
 
-        if not barsabove and fmt is not None:
+        if not barsabove and plot_line:
             l0, = self.plot(x, y, fmt, **kwargs)
 
         if ecolor is None:
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2603,7 +2603,8 @@ def boxplot(x, notch=False, sym='b+', vert=True, whis=1.5, positions=None,
             widths=None, patch_artist=False, bootstrap=None, usermedians=None,
             conf_intervals=None, meanline=False, showmeans=False, showcaps=True,
             showbox=True, showfliers=True, boxprops=None, labels=None,
-            flierprops=None, medianprops=None, meanprops=None, hold=None):
+            flierprops=None, medianprops=None, meanprops=None,
+            manage_xticks=True, hold=None):
     ax = gca()
     # allow callers to override the hold state by passing hold=True|False
     washold = ax.ishold()
@@ -2620,7 +2621,7 @@ def boxplot(x, notch=False, sym='b+', vert=True, whis=1.5, positions=None,
                          showbox=showbox, showfliers=showfliers,
                          boxprops=boxprops, labels=labels,
                          flierprops=flierprops, medianprops=medianprops,
-                         meanprops=meanprops)
+                         meanprops=meanprops, manage_xticks=manage_xticks)
         draw_if_interactive()
     finally:
         ax.hold(washold)
@@ -2729,7 +2730,7 @@ def csd(x, y, NFFT=None, Fs=None, Fc=None, detrend=None, window=None,
 # This function was autogenerated by boilerplate.py.  Do not edit as
 # changes will be lost
 @_autogen_docstring(Axes.errorbar)
-def errorbar(x, y, yerr=None, xerr=None, fmt='-', ecolor=None, elinewidth=None,
+def errorbar(x, y, yerr=None, xerr=None, fmt='', ecolor=None, elinewidth=None,
              capsize=3, barsabove=False, lolims=False, uplims=False,
              xlolims=False, xuplims=False, errorevery=1, capthick=None,
              hold=None, **kwargs):
