FIX: add legend kwarg outside

jklymak · jklymak · commit b767add67c8a · 2019-01-01T16:34:16.000-08:00
diff --git a/examples/text_labels_and_annotations/figlegendoutside_demo.py b/examples/text_labels_and_annotations/figlegendoutside_demo.py
@@ -28,8 +28,8 @@
 axs[1].plot(x, y3, 'yd-', label='Line3')
 h4, = axs[1].plot(x, y4, 'k^', label='Line4')
 
-fig.legend_outside(loc='upper center', ncol=2)
-fig.legend_outside(axs=[axs[1]], loc='lower right')
-fig.legend_outside(handles=[h2, h4], labels=['curve2', 'curve4'],
-                   loc='center left', borderaxespad=6)
+fig.legend(loc='upper center', outside=True, ncol=2)
+fig.legend(axs=[axs[1]], outside=True, loc='lower right')
+fig.legend(handles=[h2, h4], labels=['curve2', 'curve4'],
+                   outside=True, loc='center left', borderaxespad=6)
 plt.show()
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1698,7 +1698,7 @@ def get_axes(self):
     # docstring of pyplot.figlegend.
 
     @docstring.dedent_interpd
-    def legend(self, *args, **kwargs):
+    def legend(self, *args, outside=False, axs=None, **kwargs):
         """
         Place a legend on the figure.
 
@@ -1723,6 +1723,15 @@ def legend(self, *args, **kwargs):
         Parameters
         ----------
 
+        outside: bool
+            If ``constrained_layout=True``, then try and place legend outside
+            axes listed in *axs*, or highest-level gridspec if axs is empty.
+            Note, "center" and "best" options to *loc* do not work with
+            ``outside=True``
+
+        axs :  sequence of `~.axes.Axes`
+            axes to gather handles from (if *handles* is empty).
+
         handles : sequence of `.Artist`, optional
             A list of Artists (lines, patches) to be added to the legend.
             Use this together with *labels*, if you need full control on what
@@ -1752,141 +1761,36 @@ def legend(self, *args, **kwargs):
         Not all kinds of artist are supported by the legend command. See
         :doc:`/tutorials/intermediate/legend_guide` for details.
         """
+        if axs is None:
+            axs = self.axes
 
         handles, labels, extra_args, kwargs = mlegend._parse_legend_args(
-                self.axes,
+                axs,
                 *args,
                 **kwargs)
-        # check for third arg
-        if len(extra_args):
-            # cbook.warn_deprecated(
-            #     "2.1",
-            #     message="Figure.legend will accept no more than two "
-            #     "positional arguments in the future.  Use "
-            #     "'fig.legend(handles, labels, loc=location)' "
-            #     "instead.")
-            # kwargs['loc'] = extra_args[0]
-            # extra_args = extra_args[1:]
-            pass
-        l = mlegend.Legend(self, handles, labels, *extra_args, **kwargs)
-        self.legends.append(l)
+        if outside and not self.get_constrained_layout():
+            cbook._warn_external('legend outside=True method needs '
+                                 'constrained_layout=True.  Setting False')
+            outside = False
+
+        if not outside:
+            l = mlegend.Legend(self, handles, labels, *extra_args, **kwargs)
+            self.legends.append(l)
+        else:
+            loc = kwargs.pop('loc')
+            if axs is None:
+                gs = self.get_gridspecs()[0]
+            else:
+                if isinstance(axs, GridSpecBase):
+                    gs = axs
+                else:
+                    gs = axs[0].get_gridspec()
+            l = gs.legend_outside(loc=loc, handles=handles, labels=labels,
+                                     **kwargs)
         l._remove_method = self.legends.remove
         self.stale = True
         return l
 
-    @docstring.dedent_interpd
-    def legend_outside(self, *, loc=None, axs=None, **kwargs):
-        """
-        Place a legend on the figure outside a list of axes, and automatically
-        make room, stealing space from the axes specified by *axs* (analogous
-        to what colorbar does).
-
-        To make a legend from existing artists on every axes::
-
-          legend()
-
-        To specify the axes to put the legend beside::
-
-           legend(axs=[ax1, ax2])
-
-        However, note that the legend will appear beside the gridspec that
-        owns these axes, so the following two calls will be the same::
-
-            fig, axs = plt.subplots(2, 2)
-            legend(axs=[axs[0, 0], axs[1, 0]])
-            legend(axs=axs)
-
-        To make a legend for a list of lines and labels::
-
-          legend(
-              handles=(line1, line2, line3),
-              labels=('label1', 'label2', 'label3'),
-              loc='upper right')
-
-
-        Parameters
-        ----------
-
-        loc: location code for legend, optional, default=1
-            A legend location code, but does not support ``best`` or
-            ``center``.
-
-        axs : sequence of `.axes.Axes` or a single `.GridSpecBase`, optional
-            A list of axes to put the legend beside, above, or below.  This is
-            also the list of axes that artists will be taken from if *handles*
-            is empty.  Note that the legend will be placed adjacent to all the
-            axes in the gridspec that the first element in *axs* belongs to,
-            so mixing axes from different gridspecs may lead to confusing
-            results.  Also, its not possible to put the legend between
-            two columns or rows of the same gridspec; the legend is always
-            outside the gridspec.  This can also be passed as a gridspec
-            instance directly.
-
-        handles : sequence of `.Artist`, optional
-            A list of Artists (lines, patches) to be added to the legend.
-            Use this together with *labels*, if you need full control on what
-            is shown in the legend and the automatic mechanism described above
-            is not sufficient.
-
-            The length of handles and labels should be the same in this
-            case. If they are not, they are truncated to the smaller length.
-
-        labels : sequence of strings, optional
-            A list of labels to show next to the artists.
-            Use this together with *handles*, if you need full control on what
-            is shown in the legend and the automatic mechanism described above
-            is not sufficient.
-
-        Other Parameters
-        ----------------
-
-        %(_legend_kw_doc)s
-
-        Returns
-        -------
-        :class:`matplotlib.legend.Legend` instance
-
-        Notes
-        -----
-        Not all kinds of artist are supported by the legend command. See
-        :doc:`/tutorials/intermediate/legend_guide` for details.
-
-        Currently, `~figure.legend_outside` only works if
-        ``constrained_layout=True``.
-
-        See Also
-        --------
-        .figure.legend
-        .gridspec.legend
-        .axes.Axes.legend
-
-        """
-
-        if not self.get_constrained_layout():
-            cbook._warn_external('legend_outside method needs '
-                          'constrained_layout, using default legend')
-            leg = self.legend(loc=loc, **kwargs)
-            return leg
-
-        if loc is None:
-            loc = 1  # upper right
-
-        if axs is None:
-            gs = self.get_gridspecs()[0]
-            handles, labels, extra_args, kwargs = mlegend._parse_legend_args(
-                self.axes, **kwargs)
-        else:
-            if isinstance(axs, GridSpecBase):
-                gs = axs
-            else:
-                gs = axs[0].get_gridspec()
-
-            handles, labels, extra_args, kwargs = mlegend._parse_legend_args(
-                axs, **kwargs)
-
-        return gs.legend_outside(loc=loc, handles=handles, labels=labels,
-                                 **kwargs)
-
     @docstring.dedent_interpd
     def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
         """
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -216,6 +216,7 @@ def legend_outside(self, handles=None, labels=None, axs=None, **kwargs):
                     # stack to the top...
                     layoutbox.vstack([leg._layoutbox, child], padding=paddingh)
         self.figure.legends.append(leg)
+
         return leg
 
 
diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py
@@ -390,7 +390,7 @@ def test_figure_legend_outside():
     for nn, todo in enumerate(todos):
         fig, axs = plt.subplots(constrained_layout=True, dpi=100)
         axs.plot(range(10), label=f'Boo1')
-        leg = fig.legend_outside(loc=todo)
+        leg = fig.legend(loc=todo, outside=True)
         renderer = fig.canvas.get_renderer()
         fig.canvas.draw()
         assert_allclose(axs.get_window_extent(renderer=renderer).extents,
