Properly deprecate num=0 in subplot related functions

tacaswell · tacaswell · commit 9cc4a3ef6000 · 2014-07-06T17:48:25.000-04:00
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -189,6 +189,19 @@ original location:
   If `fontpropreties` is not passed in, but `prop` is, then `prop` is used inplace
   of `fontpropreties`.  If both are passed in, `prop` is silently ignored.
 
+* The use of the index 0 has in `plt.subplot` and related commands is
+  deprecated.  Due to a lack of validation calling `plt.subplots(2, 2,
+  0)` does not raise an exception, but puts an axes in the _last_
+  position.  This is due to the indexing in subplot being 1-based (to
+  support the three-digit number scheme) so before indexing into the
+  `GridSpec` object used to determine where the axes should go one is
+  subtracted off, resulting in getting the last position back.  Even
+  though this behavior is clearly wrong and not intended, we are going
+  through a deprecation cycle in an abundance of caution that any users
+  are exploiting this 'feature'.  The use of 0 as an index will raise
+  a warning in 1.4 and an exception in 1.5.
+
+
 Code removal
 ------------
 
diff --git a/lib/matplotlib/axes/_subplots.py b/lib/matplotlib/axes/_subplots.py
@@ -9,6 +9,9 @@
 import matplotlib.artist as martist
 from matplotlib.axes._axes import Axes
 
+import warnings
+from matplotlib.cbook import mplDeprecation
+
 
 class SubplotBase(object):
     """
@@ -55,10 +58,15 @@ def __init__(self, fig, *args, **kwargs):
                 num = [int(n) for n in num]
                 self._subplotspec = GridSpec(rows, cols)[num[0] - 1:num[1]]
             else:
-                if num == 0 or num > rows*cols:
+                if num < 0 or num > rows*cols:
                     raise ValueError(
-                        "num must be 0 < num <= {maxn}, not {num}".format(
+                        "num must be 0 <= num <= {maxn}, not {num}".format(
                             maxn=rows*cols, num=num))
+                if num == 0:
+                    warnings.warn("The use of 0 (which ends up being the "
+                                  "_last_ sub-plot) is deprecated in 1.4 "
+                                  "and will raise an error in 1.5",
+                                  mplDeprecation)
                 self._subplotspec = GridSpec(rows, cols)[int(num) - 1]
                 # num - 1 for converting from MATLAB to python indexing
         else:
diff --git a/lib/matplotlib/tests/test_subplots.py b/lib/matplotlib/tests/test_subplots.py
@@ -105,7 +105,9 @@ def test_exceptions():
     # TODO should this test more options?
     assert_raises(ValueError, plt.subplots, 2, 2, sharex='blah')
     assert_raises(ValueError, plt.subplots, 2, 2, sharey='blah')
-    assert_raises(ValueError, plt.subplots, 2, 2, 0)
+    assert_raises(ValueError, plt.subplots, 2, 2, -1)
+    # uncomment this for 1.5
+    # assert_raises(ValueError, plt.subplots, 2, 2, 0)
     assert_raises(ValueError, plt.subplots, 2, 2, 5)
 
 
