FIX: Axes.indicate_inset* methods

clbarnes · clbarnes · commit d4cb80561c85 · 2019-05-21T15:13:52.000-04:00
See #14275 1. Methods now return a tuple as documented, instead of a list. 2. indicate_inset() now does not error when optional inset_ax is not passed, but returns None instead of a tuple.
diff --git a/doc/api/next_api_changes/2019-05-21-CB.rst b/doc/api/next_api_changes/2019-05-21-CB.rst
@@ -0,0 +1,12 @@
+`matplotlib.axes.Axes.indicate_inset` returns a 4-tuple as documented
+---------------------------------------------------------------------
+
+In <= 3.1.0, `matplotlib.axes.Axes.indicate_inset` and
+`matplotlib.axes.Axes.indicate_inset_zoom` were documented as returning
+a 4-tuple of `matplotlib.patches.ConnectionPatch`es, where in fact they
+returned a 4-length list.
+
+They now correctly return a 4-tuple.
+`matplotlib.axes.Axes.indicate_inset` would previously raise an error if
+the optional *inset_ax* was not supplied; it now completes successfully,
+and returns *None* instead of the tuple of ``ConnectionPatch``es.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -530,9 +530,12 @@ def indicate_inset(self, bounds, inset_ax=None, *, transform=None,
         rectangle_patch : `.Patches.Rectangle`
              Rectangle artist.
 
-        connector_lines : 4-tuple of `.Patches.ConnectionPatch`
-            One for each of four connector lines.  Two are set with visibility
-            to *False*,  but the user can set the visibility to True if the
+        connector_lines : optional 4-tuple of `.Patches.ConnectionPatch`
+            Each of four connector lines coming from the given rectangle
+            on this axes in the order lower left, upper left, lower right,
+            upper right: *None* if *inset_ax* is *None*.
+            Two are set with visibility to *False*,
+            but the user can set the visibility to *True* if the
             automatic choice is not deemed correct.
 
         """
@@ -551,19 +554,24 @@ def indicate_inset(self, bounds, inset_ax=None, *, transform=None,
                 zorder=zorder,  label=label, transform=transform, **kwargs)
         self.add_patch(rectpatch)
 
+        connects = []
+
         if inset_ax is not None:
             # want to connect the indicator to the rect....
-            connects = []
             xr = [bounds[0], bounds[0]+bounds[2]]
             yr = [bounds[1], bounds[1]+bounds[3]]
             for xc in range(2):
                 for yc in range(2):
                     xyA = (xc, yc)
                     xyB = (xr[xc], yr[yc])
-                    connects += [mpatches.ConnectionPatch(xyA, xyB,
+                    connects.append(
+                        mpatches.ConnectionPatch(
+                            xyA, xyB,
                             'axes fraction', 'data',
                             axesA=inset_ax, axesB=self, arrowstyle="-",
-                            zorder=zorder, edgecolor=edgecolor, alpha=alpha)]
+                            zorder=zorder, edgecolor=edgecolor, alpha=alpha
+                        )
+                    )
                     self.add_patch(connects[-1])
             # decide which two of the lines to keep visible....
             pos = inset_ax.get_position()
@@ -579,7 +587,7 @@ def indicate_inset(self, bounds, inset_ax=None, *, transform=None,
             connects[2].set_visible(x1 == y0)
             connects[3].set_visible(x1 ^ y1)
 
-        return rectpatch, connects
+        return rectpatch, tuple(connects) if connects else None
 
     def indicate_inset_zoom(self, inset_ax, **kwargs):
         """
@@ -601,7 +609,7 @@ def indicate_inset_zoom(self, inset_ax, **kwargs):
             chosen so as to not overlap with the indicator box.
 
         **kwargs
-            Other *kwargs* are passed on to `.Axes.inset_rectangle`
+            Other *kwargs* are passed on to `.Axes.indicate_inset`
 
         Returns
         -------
@@ -610,17 +618,21 @@ def indicate_inset_zoom(self, inset_ax, **kwargs):
              Rectangle artist.
 
         connector_lines : 4-tuple of `.Patches.ConnectionPatch`
-            One for each of four connector lines.  Two are set with visibility
-            to *False*,  but the user can set the visibility to True if the
-            automatic choice is not deemed correct.
+            Each of four connector lines coming from the rectangle drawn on
+            this axis, in the order lower left, upper left, lower right,
+            upper right.
+            Two are set with visibility to *False*,  but the user can
+            set the visibility to *True* if the automatic choice is not deemed
+            correct.
 
         """
 
         xlim = inset_ax.get_xlim()
         ylim = inset_ax.get_ylim()
-        rect = [xlim[0], ylim[0], xlim[1] - xlim[0], ylim[1] - ylim[0]]
+        rect = (xlim[0], ylim[0], xlim[1] - xlim[0], ylim[1] - ylim[0])
         rectpatch, connects = self.indicate_inset(
-                rect, inset_ax, **kwargs)
+            rect, inset_ax, **kwargs
+        )
 
         return rectpatch, connects
 
