matplotlib
diff --git a/‎doc/api/api_changes.rst
Lines changed: 15 additions & 0 deletions b/‎doc/api/api_changes.rst
Lines changed: 15 additions & 0 deletions
diff --git a/‎lib/matplotlib/axes/_subplots.py
Lines changed: 12 additions & 0 deletions b/‎lib/matplotlib/axes/_subplots.py
Lines changed: 12 additions & 0 deletions
diff --git a/‎lib/matplotlib/tests/test_subplots.py
Lines changed: 13 additions & 8 deletions b/‎lib/matplotlib/tests/test_subplots.py
Lines changed: 13 additions & 8 deletions
@@ -189,6 +189,21 @@ 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 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
+  mirror MATLAB) so before indexing into the `GridSpec` object used to
+  determine where the axes should go, 1 is subtracted off.  Passing in
+  0 results in passing -1 to `GridSpec` which results 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
 ------------
 
 
@@ -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,6 +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:
+                    raise ValueError(
+                        "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:
 
@@ -6,7 +6,7 @@
 
 import numpy
 import matplotlib.pyplot as plt
-from matplotlib.testing.decorators import image_comparison
+from matplotlib.testing.decorators import image_comparison, cleanup
 
 from nose.tools import assert_raises
 
@@ -105,19 +105,24 @@ 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, -1)
+    # uncomment this for 1.5
+    # assert_raises(ValueError, plt.subplots, 2, 2, 0)
+    assert_raises(ValueError, plt.subplots, 2, 2, 5)
 
 
 @image_comparison(baseline_images=['subplots_offset_text'], remove_text=False)
 def test_subplots_offsettext():
-    x = numpy.arange(0,1e10,1e9)
-    y = numpy.arange(0,100,10)+1e4
-    fig,axes = plt.subplots(2,2, sharex = 'col', sharey = 'all')
-    axes[0,0].plot(x,x)
-    axes[1,0].plot(x,x)
-    axes[0,1].plot(y,x)
-    axes[1,1].plot(y,x)
+    x = numpy.arange(0, 1e10, 1e9)
+    y = numpy.arange(0, 100, 10)+1e4
+    fig, axes = plt.subplots(2, 2, sharex='col', sharey='all')
+    axes[0, 0].plot(x, x)
+    axes[1, 0].plot(x, x)
+    axes[0, 1].plot(y, x)
+    axes[1, 1].plot(y, x)
 
 
+@cleanup
 def test_subplots():
     # things to test
     # - are axes actually shared?