API/DOC: Document legend_handles and legend_handlers

oscargus · tacaswell · commit 2a1a1a6e47e4 · 2022-12-16T16:38:41.000-05:00
- deprecate legendHandles
diff --git a/doc/api/next_api_changes/deprecations/24538-OG.rst b/doc/api/next_api_changes/deprecations/24538-OG.rst
@@ -0,0 +1,5 @@
+``legend.legendHandles``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+... was undocumented and has been renamed to ``legend_handles``. Using the
+old name is deprecated.
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -360,12 +360,19 @@ def __init__(
         labels : list of str
             A list of labels to show next to the artists. The length of handles
             and labels should be the same. If they are not, they are truncated
-            to the smaller of both lengths.
+            to the shortest of both lengths.
 
         Other Parameters
         ----------------
         %(_legend_kw_doc)s
 
+        Attributes
+        ----------
+        legend_handles
+            A list of legend handles used by the legend.
+
+            .. versionadded:: 3.7
+
         Notes
         -----
         Users can specify any arbitrary location for the legend using the
@@ -397,7 +404,7 @@ def __init__(
         self._fontsize = self.prop.get_size_in_points()
 
         self.texts = []
-        self.legendHandles = []
+        self.legend_handles = []
         self._legend_title_box = None
 
         #: A dictionary with the extra handler mappings for this Legend
@@ -561,7 +568,7 @@ def val_or_rc(val, rc_name):
                 labelcolor = mpl.rcParams['text.color']
         if isinstance(labelcolor, str) and labelcolor in color_getters:
             getter_names = color_getters[labelcolor]
-            for handle, text in zip(self.legendHandles, self.texts):
+            for handle, text in zip(self.legend_handles, self.texts):
                 try:
                     if handle.get_array() is not None:
                         continue
@@ -594,6 +601,9 @@ def val_or_rc(val, rc_name):
         else:
             raise ValueError(f"Invalid labelcolor: {labelcolor!r}")
 
+    legendHandles = _api.deprecated('3.7', alternative="legend_handles")(
+        property(lambda self: self.legend_handles))
+
     def _set_artist_props(self, a):
         """
         Set the boilerplate props for artists added to axes.
@@ -838,7 +848,7 @@ def _init_legend_box(self, handles, labels, markerfirst=True):
         self._legend_box.set_figure(self.figure)
         self._legend_box.axes = self.axes
         self.texts = text_list
-        self.legendHandles = handle_list
+        self.legend_handles = handle_list
 
     def _auto_legend_data(self):
         """
@@ -885,12 +895,12 @@ def get_frame(self):
 
     def get_lines(self):
         r"""Return the list of `~.lines.Line2D`\s in the legend."""
-        return [h for h in self.legendHandles if isinstance(h, Line2D)]
+        return [h for h in self.legend_handles if isinstance(h, Line2D)]
 
     def get_patches(self):
         r"""Return the list of `~.patches.Patch`\s in the legend."""
         return silent_list('Patch',
-                           [h for h in self.legendHandles
+                           [h for h in self.legend_handles
                             if isinstance(h, Patch)])
 
     def get_texts(self):
diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py
@@ -9,16 +9,16 @@
     </tutorials/intermediate/legend_guide>` before reading this documentation.
 
 Legend handlers are expected to be a callable object with a following
-signature. ::
+signature::
 
     legend_handler(legend, orig_handle, fontsize, handlebox)
 
 Where *legend* is the legend itself, *orig_handle* is the original
-plot, *fontsize* is the fontsize in pixels, and *handlebox* is a
-OffsetBox instance. Within the call, you should create relevant
+plot, *fontsize* is the fontsize in pixels, and *handlebox* is an
+`.OffsetBox` instance. Within the call, you should create relevant
 artists (using relevant properties from the *legend* and/or
-*orig_handle*) and add them into the handlebox. The artists need to
-be scaled according to the fontsize (note that the size is in pixel,
+*orig_handle*) and add them into the *handlebox*. The artists need to
+be scaled according to the *fontsize* (note that the size is in pixel,
 i.e., this is dpi-scaled value).
 
 This module includes definition of several legend handler classes
@@ -49,7 +49,7 @@ class HandlerBase:
     A base class for default legend handlers.
 
     The derived classes are meant to override *create_artists* method, which
-    has a following signature.::
+    has the following signature::
 
       def create_artists(self, legend, orig_handle,
                          xdescent, ydescent, width, height, fontsize,
@@ -61,6 +61,18 @@ def create_artists(self, legend, orig_handle,
 
     """
     def __init__(self, xpad=0., ypad=0., update_func=None):
+        """
+        Parameters
+        ----------
+
+        xpad : float, optional
+            Padding in x-direction.
+        ypad : float, optional
+            Padding in y-direction.
+        update_func : callable, optional
+            Function for updating the legend handler properties from another
+            legend handler, used by `~HandlerBase.update_prop`.
+        """
         self._xpad, self._ypad = xpad, ypad
         self._update_prop_func = update_func
 
@@ -133,6 +145,24 @@ def legend_artist(self, legend, orig_handle,
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize,
                        trans):
+        """
+        Return the legend artists generated.
+
+        Parameters
+        ----------
+        legend : `~matplotlib.legend.Legend`
+            The legend for which these legend artists are being created.
+        orig_handle : `~matplotlib.artist.Artist` or similar
+            The object for which these legend artists are being created.
+        xdescent, ydescent, width, height : int
+            The rectangle (*xdescent*, *ydescent*, *width*, *height*) that the
+            legend artists being created should fit within.
+        fontsize : int
+            The fontsize in pixels. The legend artists being created should
+            be scaled according to the given fontsize.
+        trans :  `~matplotlib.transforms.Transform`
+            The transform that is applied to the legend artists being created.
+        """
         raise NotImplementedError('Derived must override')
 
 
@@ -217,7 +247,7 @@ class HandlerLine2DCompound(HandlerNpoints):
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize,
                        trans):
-
+        # Doc-string inherited
         xdata, xdata_marker = self.get_xdata(legend, xdescent, ydescent,
                                              width, height, fontsize)
 
@@ -276,7 +306,7 @@ class HandlerLine2D(HandlerNpoints):
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize,
                        trans):
-
+        # Doc-string inherited
         xdata, xdata_marker = self.get_xdata(legend, xdescent, ydescent,
                                              width, height, fontsize)
 
@@ -341,6 +371,7 @@ def _create_patch(self, legend, orig_handle,
 
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize, trans):
+        # Doc-string inherited
         p = self._create_patch(legend, orig_handle,
                                xdescent, ydescent, width, height, fontsize)
         self.update_prop(p, orig_handle, legend)
@@ -374,6 +405,7 @@ def _create_line(orig_handle, width, height):
 
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize, trans):
+        # Doc-string inherited
         if orig_handle.get_fill() or (orig_handle.get_hatch() is not None):
             p = self._create_patch(orig_handle, xdescent, ydescent, width,
                                    height)
@@ -404,7 +436,7 @@ def _default_update_prop(self, legend_handle, orig_handle):
 
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize, trans):
-
+        # Doc-string inherited
         xdata, xdata_marker = self.get_xdata(legend, xdescent, ydescent,
                                              width, height, fontsize)
         ydata = np.full_like(xdata, (height - ydescent) / 2)
@@ -471,6 +503,7 @@ def create_collection(self, orig_handle, sizes, offsets, offset_transform):
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize,
                        trans):
+        # Doc-string inherited
         xdata, xdata_marker = self.get_xdata(legend, xdescent, ydescent,
                                              width, height, fontsize)
 
@@ -534,7 +567,7 @@ def get_err_size(self, legend, xdescent, ydescent,
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize,
                        trans):
-
+        # Doc-string inherited
         plotlines, caplines, barlinecols = orig_handle
 
         xdata, xdata_marker = self.get_xdata(legend, xdescent, ydescent,
@@ -653,6 +686,7 @@ def get_ydata(self, legend, xdescent, ydescent, width, height, fontsize):
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize,
                        trans):
+        # Doc-string inherited
         markerline, stemlines, baseline = orig_handle
         # Check to see if the stemcontainer is storing lines as a list or a
         # LineCollection. Eventually using a list will be removed, and this
@@ -730,7 +764,7 @@ def __init__(self, ndivide=1, pad=None, **kwargs):
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize,
                        trans):
-
+        # Doc-string inherited
         handler_map = legend.get_legend_handler_map()
 
         if self._ndivide is None:
@@ -797,6 +831,7 @@ def get_first(prop_array):
 
     def create_artists(self, legend, orig_handle,
                        xdescent, ydescent, width, height, fontsize, trans):
+        # Doc-string inherited
         p = Rectangle(xy=(-xdescent, -ydescent),
                       width=width, height=height)
         self.update_prop(p, orig_handle, legend)
diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py
@@ -147,7 +147,7 @@ def test_legend_label_with_leading_underscore():
     with pytest.warns(UserWarning,
                       match=r"starts with '_'.*excluded from the legend."):
         legend = ax.legend(handles=[line])
-    assert len(legend.legendHandles) == 0
+    assert len(legend.legend_handles) == 0
 
 
 @image_comparison(['legend_labels_first.png'], remove_text=True)
@@ -550,7 +550,7 @@ def test_linecollection_scaled_dashes():
     ax.add_collection(lc3)
 
     leg = ax.legend([lc1, lc2, lc3], ["line1", "line2", 'line 3'])
-    h1, h2, h3 = leg.legendHandles
+    h1, h2, h3 = leg.legend_handles
 
     for oh, lh in zip((lc1, lc2, lc3), (h1, h2, h3)):
         assert oh.get_linestyles()[0] == lh._dash_pattern
@@ -970,7 +970,7 @@ def test_legend_draggable(draggable):
 def test_alpha_handles():
     x, n, hh = plt.hist([1, 2, 3], alpha=0.25, label='data', color='red')
     legend = plt.legend()
-    for lh in legend.legendHandles:
+    for lh in legend.legend_handles:
         lh.set_alpha(1.0)
     assert lh.get_facecolor()[:-1] == hh[1].get_facecolor()[:-1]
     assert lh.get_edgecolor()[:-1] == hh[1].get_edgecolor()[:-1]
@@ -1102,7 +1102,7 @@ def test_handlerline2d():
     ax.scatter([0, 1], [0, 1], marker="v")
     handles = [mlines.Line2D([0], [0], marker="v")]
     leg = ax.legend(handles, ["Aardvark"], numpoints=1)
-    assert handles[0].get_marker() == leg.legendHandles[0].get_marker()
+    assert handles[0].get_marker() == leg.legend_handles[0].get_marker()
 
 
 def test_subfigure_legend():
diff --git a/lib/mpl_toolkits/mplot3d/tests/test_legend3d.py b/lib/mpl_toolkits/mplot3d/tests/test_legend3d.py
@@ -55,7 +55,7 @@ def test_linecollection_scaled_dashes():
     ax.add_collection(lc3)
 
     leg = ax.legend([lc1, lc2, lc3], ['line1', 'line2', 'line 3'])
-    h1, h2, h3 = leg.legendHandles
+    h1, h2, h3 = leg.legend_handles
 
     for oh, lh in zip((lc1, lc2, lc3), (h1, h2, h3)):
         assert oh.get_linestyles()[0] == lh._dash_pattern
@@ -67,7 +67,7 @@ def test_handlerline3d():
     ax.scatter([0, 1], [0, 1], marker="v")
     handles = [art3d.Line3D([0], [0], [0], marker="v")]
     leg = ax.legend(handles, ["Aardvark"], numpoints=1)
-    assert handles[0].get_marker() == leg.legendHandles[0].get_marker()
+    assert handles[0].get_marker() == leg.legend_handles[0].get_marker()
 
 
 def test_contour_legend_elements():
