From 4c2e1d6657a5fffff24d1ffdf2ed3396d35f21c6 Mon Sep 17 00:00:00 2001
From: Travis CI <maged.hennawy@ibm.com>
Date: Mon, 19 Mar 2018 19:35:52 -0400
Subject: [PATCH 1/2] Add legend handler and artist for FancyArrow (clean
 commit)

---
 lib/matplotlib/legend.py                      |  16 +-
 lib/matplotlib/legend_handler.py              | 253 ++++++++++++++++--
 .../legend_all_annotation_text.png            | Bin 0 -> 24064 bytes
 lib/matplotlib/tests/test_legend.py           |  52 +++-
 4 files changed, 296 insertions(+), 25 deletions(-)
 create mode 100644 lib/matplotlib/tests/baseline_images/test_legend/legend_all_annotation_text.png

diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
index a95080ddea1a..e32a34337248 100644
--- a/lib/matplotlib/legend.py
+++ b/lib/matplotlib/legend.py
@@ -39,7 +39,8 @@
 import matplotlib.colors as colors
 from matplotlib.font_manager import FontProperties
 from matplotlib.lines import Line2D
-from matplotlib.patches import Patch, Rectangle, Shadow, FancyBboxPatch
+from matplotlib.patches import (Patch, Rectangle, Shadow, FancyBboxPatch,
+                                    FancyArrowPatch)
 from matplotlib.collections import (LineCollection, RegularPolyCollection,
                                     CircleCollection, PathCollection,
                                     PolyCollection)
@@ -50,6 +51,7 @@
 from matplotlib.offsetbox import DraggableOffsetBox
 
 from matplotlib.container import ErrorbarContainer, BarContainer, StemContainer
+from matplotlib.text import Annotation, Text
 from . import legend_handler
 
 
@@ -565,7 +567,6 @@ def _set_loc(self, loc):
         # value of the find_offset.
         self._loc_real = loc
         self.stale = True
-        self._legend_box.set_offset(self._findoffset)
 
     def _get_loc(self):
         return self._loc_real
@@ -649,7 +650,10 @@ def _approx_text_height(self, renderer=None):
             update_func=legend_handler.update_from_first_child),
         tuple: legend_handler.HandlerTuple(),
         PathCollection: legend_handler.HandlerPathCollection(),
-        PolyCollection: legend_handler.HandlerPolyCollection()
+        PolyCollection: legend_handler.HandlerPolyCollection(),
+        FancyArrowPatch: legend_handler.HandlerFancyArrowPatch(),
+        Text: legend_handler.HandlerText(),
+        Annotation: legend_handler.HandlerAnnotation()
         }
 
     # (get|set|update)_default_handler_maps are public interfaces to
@@ -837,6 +841,7 @@ def _init_legend_box(self, handles, labels, markerfirst=True):
                                    children=[self._legend_title_box,
                                              self._legend_handle_box])
         self._legend_box.set_figure(self.figure)
+        self._legend_box.set_offset(self._findoffset)
         self.texts = text_list
         self.legendHandles = handle_list
 
@@ -1142,12 +1147,13 @@ def _get_legend_handles(axs, legend_handler_map=None):
     handles_original = []
     for ax in axs:
         handles_original += (ax.lines + ax.patches +
-                             ax.collections + ax.containers)
+                             ax.collections + ax.containers + ax.texts)
         # support parasite axes:
         if hasattr(ax, 'parasites'):
             for axx in ax.parasites:
                 handles_original += (axx.lines + axx.patches +
-                                     axx.collections + axx.containers)
+                                     axx.collections + axx.containers +
+                                     axx.texts)
 
     handler_map = Legend.get_default_handler_map()
 
diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py
index 0968a5c4b99b..a1b6a9bd7cd3 100644
--- a/lib/matplotlib/legend_handler.py
+++ b/lib/matplotlib/legend_handler.py
@@ -33,8 +33,9 @@ def legend_artist(self, legend, orig_handle, fontsize, handlebox):
 import numpy as np
 
 from matplotlib.lines import Line2D
-from matplotlib.patches import Rectangle
+from matplotlib.patches import Rectangle, FancyArrowPatch
 import matplotlib.collections as mcoll
+from matplotlib.text import Text, Annotation
 import matplotlib.colors as mcolors
 
 
@@ -58,6 +59,7 @@ def create_artists(self, legend, orig_handle,
     width, height) that are scaled by fontsize if necessary.
 
     """
+
     def __init__(self, xpad=0., ypad=0., update_func=None):
         self._xpad, self._ypad = xpad, ypad
         self._update_prop_func = update_func
@@ -110,10 +112,10 @@ def legend_artist(self, legend, orig_handle,
 
         """
         xdescent, ydescent, width, height = self.adjust_drawing_area(
-                 legend, orig_handle,
-                 handlebox.xdescent, handlebox.ydescent,
-                 handlebox.width, handlebox.height,
-                 fontsize)
+            legend, orig_handle,
+            handlebox.xdescent, handlebox.ydescent,
+            handlebox.width, handlebox.height,
+            fontsize)
         artists = self.create_artists(legend, orig_handle,
                                       xdescent, ydescent, width, height,
                                       fontsize, handlebox.get_transform())
@@ -135,6 +137,7 @@ class HandlerNpoints(HandlerBase):
     """
     A legend handler that shows *numpoints* points in the legend entry.
     """
+
     def __init__(self, marker_pad=0.3, numpoints=None, **kw):
         """
         Parameters
@@ -180,6 +183,7 @@ class HandlerNpointsYoffsets(HandlerNpoints):
     A legend handler that shows *numpoints* in the legend, and allows them to
     be individually offest in the y-direction.
     """
+
     def __init__(self, numpoints=None, yoffsets=None, **kw):
         """
         Parameters
@@ -211,6 +215,7 @@ class HandlerLine2D(HandlerNpoints):
     """
     Handler for `.Line2D` instances.
     """
+
     def __init__(self, marker_pad=0.3, numpoints=None, **kw):
         """
         Parameters
@@ -263,6 +268,7 @@ class HandlerPatch(HandlerBase):
     """
     Handler for `.Patch` instances.
     """
+
     def __init__(self, patch_func=None, **kw):
         """
         Parameters
@@ -309,6 +315,7 @@ class HandlerLineCollection(HandlerLine2D):
     """
     Handler for `.LineCollection` instances.
     """
+
     def get_numpoints(self, legend):
         if self._numpoints is None:
             return legend.scatterpoints
@@ -341,6 +348,7 @@ class HandlerRegularPolyCollection(HandlerNpointsYoffsets):
     """
     Handler for `.RegularPolyCollections`.
     """
+
     def __init__(self, yoffsets=None, sizes=None, **kw):
         HandlerNpointsYoffsets.__init__(self, yoffsets=yoffsets, **kw)
 
@@ -378,7 +386,7 @@ def update_prop(self, legend_handle, orig_handle, legend):
         self._update_prop(legend_handle, orig_handle)
 
         legend_handle.set_figure(legend.figure)
-        #legend._set_artist_props(legend_handle)
+        # legend._set_artist_props(legend_handle)
         legend_handle.set_clip_box(None)
         legend_handle.set_clip_path(None)
 
@@ -416,6 +424,7 @@ class HandlerPathCollection(HandlerRegularPolyCollection):
     """
     Handler for `.PathCollections`, which are used by `~.Axes.scatter`.
     """
+
     def create_collection(self, orig_handle, sizes, offsets, transOffset):
         p = type(orig_handle)([orig_handle.get_paths()[0]],
                               sizes=sizes,
@@ -429,6 +438,7 @@ class HandlerCircleCollection(HandlerRegularPolyCollection):
     """
     Handler for `.CircleCollections`.
     """
+
     def create_collection(self, orig_handle, sizes, offsets, transOffset):
         p = type(orig_handle)(sizes,
                               offsets=offsets,
@@ -441,6 +451,7 @@ class HandlerErrorbar(HandlerLine2D):
     """
     Handler for Errorbars.
     """
+
     def __init__(self, xerr_size=0.5, yerr_size=None,
                  marker_pad=0.3, numpoints=None, **kw):
 
@@ -503,8 +514,8 @@ def create_artists(self, legend, orig_handle,
         handle_caplines = []
 
         if orig_handle.has_xerr:
-            verts = [ ((x - xerr_size, y), (x + xerr_size, y))
-                      for x, y in zip(xdata_marker, ydata_marker)]
+            verts = [((x - xerr_size, y), (x + xerr_size, y))
+                     for x, y in zip(xdata_marker, ydata_marker)]
             coll = mcoll.LineCollection(verts)
             self.update_prop(coll, barlinecols[0], legend)
             handle_barlinecols.append(coll)
@@ -521,8 +532,8 @@ def create_artists(self, legend, orig_handle,
                 handle_caplines.append(capline_right)
 
         if orig_handle.has_yerr:
-            verts = [ ((x, y - yerr_size), (x, y + yerr_size))
-                      for x, y in zip(xdata_marker, ydata_marker)]
+            verts = [((x, y - yerr_size), (x, y + yerr_size))
+                     for x, y in zip(xdata_marker, ydata_marker)]
             coll = mcoll.LineCollection(verts)
             self.update_prop(coll, barlinecols[0], legend)
             handle_barlinecols.append(coll)
@@ -554,6 +565,7 @@ class HandlerStem(HandlerNpointsYoffsets):
     """
     Handler for plots produced by `~.Axes.stem`.
     """
+
     def __init__(self, marker_pad=0.3, numpoints=None,
                  bottom=None, yoffsets=None, **kw):
         """
@@ -649,11 +661,37 @@ class HandlerTuple(HandlerBase):
     pad : float, optional
         If None, fall back to ``legend.borderpad`` as the default.
         In units of fraction of font size. Default is None.
+
+
+    width_ratios : tuple, optional
+        Specifies the respective widths of a text/arrow legend annotation pair.
+        Must be of length ndivide.
+        If None, all sections will have the same width. Default is None.
+
+
+    handlers : tuple, optionnal
+        The list of handlers to call for each text/arrow legend annotation section.
+        Must be of length ndivide.
+        If None, the default handlers will be fetched automatically. Default is None.
     """
-    def __init__(self, ndivide=1, pad=None, **kwargs):
+
+    def __init__(
+            self,
+            ndivide=1,
+            pad=None,
+            width_ratios=None,
+            handlers=None,
+            **kwargs):
 
         self._ndivide = ndivide
         self._pad = pad
+        self._handlers = handlers
+
+        if (width_ratios is not None) and (len(width_ratios) == ndivide):
+            self._width_ratios = width_ratios
+        else:
+            self._width_ratios = None
+
         HandlerBase.__init__(self, **kwargs)
 
     def create_artists(self, legend, orig_handle,
@@ -672,17 +710,32 @@ def create_artists(self, legend, orig_handle,
         else:
             pad = self._pad * fontsize
 
-        if ndivide > 1:
-            width = (width - pad * (ndivide - 1)) / ndivide
+        if self._width_ratios is not None:
+            sumratios = sum(self._width_ratios)
+            widths = [(width - pad * (ndivide - 1)) * ratio / sumratios
+                      for ratio in self._width_ratios]
+        else:
+            widths = [(width - pad * (ndivide - 1)) / ndivide
+                      for _ in range(ndivide)]
+        widths_cycle = cycle(widths)
 
-        xds_cycle = cycle(xdescent - (width + pad) * np.arange(ndivide))
+        xds = [xdescent - (widths[-i - 1] + pad) * i for i in range(ndivide)]
+        xds_cycle = cycle(xds)
 
         a_list = []
-        for handle1 in orig_handle:
-            handler = legend.get_legend_handler(handler_map, handle1)
-            _a_list = handler.create_artists(
-                legend, handle1,
-                next(xds_cycle), ydescent, width, height, fontsize, trans)
+        for i, handle1 in enumerate(orig_handle):
+            if self._handlers is not None:
+                handler = self._handlers[i]
+            else:
+                handler = legend.get_legend_handler(handler_map, handle1)
+
+            _a_list = handler.create_artists(legend, handle1,
+                                             next(xds_cycle),
+                                             ydescent,
+                                             next(widths_cycle),
+                                             height,
+                                             fontsize,
+                                             trans)
             a_list.extend(_a_list)
 
         return a_list
@@ -692,6 +745,7 @@ class HandlerPolyCollection(HandlerBase):
     """
     Handler for `.PolyCollection` used in `~.Axes.fill_between` and `~.Axes.stackplot`.
     """
+
     def _update_prop(self, legend_handle, orig_handle):
         def first_color(colors):
             if colors is None:
@@ -728,3 +782,164 @@ def create_artists(self, legend, orig_handle,
         self.update_prop(p, orig_handle, legend)
         p.set_transform(trans)
         return [p]
+
+
+class HandlerFancyArrowPatch(HandlerPatch):
+    """
+    Handler for FancyArrowPatch instances.
+    """
+
+    def _create_patch(self, legend, orig_handle,
+                      xdescent, ydescent, width, height, fontsize):
+        arrow = FancyArrowPatch([-xdescent,
+                                 -ydescent + height / 2],
+                                [-xdescent + width,
+                                 -ydescent + height / 2],
+                                mutation_scale=width / 3)
+        arrow.set_arrowstyle(orig_handle.get_arrowstyle())
+        return arrow
+
+
+class HandlerText(HandlerBase):
+    """
+    Handler for Text instances.
+
+    Additional kwargs are passed through to `HandlerBase`.
+
+    Parameters
+    ----------
+    rep_str : string, optional
+        Replacement string used in the legend when the Text string is longer than rep_maxlen.
+        Default is 'Aa'.
+
+
+    rep_maxlen : int, optional
+        Maximum length of Text string to be used in the legend. Default is 2.
+    """
+
+    def __init__(self, rep_str='Aa', rep_maxlen=2, **kwargs):
+
+        self._rep_str = rep_str
+        self._rep_maxlen = rep_maxlen
+
+        HandlerBase.__init__(self, **kwargs)
+
+    def create_artists(self, legend, orig_handle,
+                       xdescent, ydescent, width, height, fontsize, trans):
+        # Use original text if it is short
+        text = orig_handle.get_text()
+        if len(text) > self._rep_maxlen:
+            text = self._rep_str
+
+        # Use smaller fontsize for text repr
+        text_fontsize = 2 * fontsize / 3
+
+        t = Text(x=-xdescent + width / 2 - len(text) * text_fontsize / 4,
+                 y=-ydescent + height / 4,
+                 text=text)
+
+        # Copy text attributes, except fontsize
+        self.update_prop(t, orig_handle, legend)
+        t.set_transform(trans)
+        t.set_fontsize(text_fontsize)
+
+        return [t]
+
+
+class HandlerAnnotation(HandlerText):
+    """
+    Handler for Annotation instances.
+
+    Defers to HandlerText to draw the annotation text (if any).
+    Defers to HandlerFancyArrowPatch to draw the annotation arrow (if any).
+    For annotations made of both text and arrow, HandlerTuple is used to draw them side by side.
+    Additional kwargs are passed through to `HandlerText`.
+
+    Parameters
+    ----------
+
+    pad : float, optional
+        If None, fall back to `legend.borderpad` asstr the default.
+        In units of fraction of font size.
+        Default is None.
+
+    width_ratios : tuple, optional
+        The relative width of the respective text/arrow legend annotation pair.
+        Must be of length 2.
+        Default is [1,4].
+    """
+
+    def __init__(
+        self,
+        pad=None,
+        width_ratios=[1, 4],
+        **kwargs
+    ):
+
+        self._pad = pad
+        self._width_ratios = width_ratios
+
+        HandlerText.__init__(self, **kwargs)
+
+    def create_artists(
+        self,
+        legend,
+        orig_handle,
+        xdescent,
+        ydescent,
+        width,
+        height,
+        fontsize,
+        trans,
+    ):
+        if orig_handle.arrow_patch is not None \
+                and orig_handle.get_text() is not '':
+
+            # Draw a tuple (text, arrow)
+
+            handler = HandlerTuple(
+                ndivide=2,
+                pad=self._pad,
+                width_ratios=self._width_ratios,
+                handlers=[
+                    HandlerText(
+                        rep_str=self._rep_str,
+                        rep_maxlen=self._rep_maxlen),
+                    HandlerFancyArrowPatch()])
+
+            # Create a Text instance from annotation text
+
+            text_handle = Text(text=orig_handle.get_text())
+            text_handle.update_from(orig_handle)
+            handle = (text_handle, orig_handle.arrow_patch)
+        elif orig_handle.arrow_patch is not None:
+
+            # Arrow without text
+
+            handler = HandlerFancyArrowPatch()
+            handle = orig_handle.arrow_patch
+        elif orig_handle.get_text() is not '':
+
+            # Text without arrow
+
+            handler = HandlerText(rep_str=self._rep_str,
+                                  rep_maxlen=self._rep_maxlen)
+            handle = orig_handle
+        else:
+
+            # No text, no arrow
+
+            handler = HandlerPatch()
+            handle = Rectangle(xy=[0, 0], width=0, height=0, color='w',
+                               alpha=0.0)
+
+        return handler.create_artists(
+            legend,
+            handle,
+            xdescent,
+            ydescent,
+            width,
+            height,
+            fontsize,
+            trans,
+        )
diff --git a/lib/matplotlib/tests/baseline_images/test_legend/legend_all_annotation_text.png b/lib/matplotlib/tests/baseline_images/test_legend/legend_all_annotation_text.png
new file mode 100644
index 0000000000000000000000000000000000000000..d49cd37ea3137209854d361ac699ab461fba4211
GIT binary patch
literal 24064
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
NyQ>e8@y)&ye*ncK)C~Xt

literal 0
HcmV?d00001

diff --git a/lib/matplotlib/tests/test_legend.py b/lib/matplotlib/tests/test_legend.py
index 830fe798c44c..8c3232d38b9f 100644
--- a/lib/matplotlib/tests/test_legend.py
+++ b/lib/matplotlib/tests/test_legend.py
@@ -10,7 +10,8 @@
 import matplotlib as mpl
 import matplotlib.transforms as mtransforms
 import matplotlib.collections as mcollections
-from matplotlib.legend_handler import HandlerTuple
+from matplotlib.legend_handler import HandlerTuple, HandlerAnnotation
+import matplotlib.patches as mpatches
 import matplotlib.legend as mlegend
 
 
@@ -216,6 +217,55 @@ def test_hatching():
     ax.legend(handlelength=4, handleheight=4)
 
 
+@image_comparison(baseline_images=['legend_all_annotation_text'],
+                  extensions=['png'],
+                  style='mpl20')
+def test_legend_all_annotation():
+    # Related to issue 8236
+    # Tests all annotations and text in legend
+    fig, ax = plt.subplots(1)
+    ax.plot([0, 1], [0, 0], label='line1')
+    ax.plot([0, 1], [1, 1], label='line2')
+    ax.set_xticklabels('')
+    ax.set_yticklabels('')
+    # no text, no arrow
+    ax.annotate("",
+                xy=(0.1, 0.5),
+                xytext=(0.1, 0.5),
+                label='annotation (empty)')
+    # text, no arrow
+    my_annotation = ax.annotate("X",
+                xy=(0.1, 0.5),
+                xytext=(0.1, 0.5),
+                color='C2',
+                label='annotation (text, no arrow)')
+    # no text, arrow
+    ax.annotate("",
+                xy=(0.3, 1.0),
+                xytext=(0.3, 0.0),
+                arrowprops={'arrowstyle': '<->', 'color': 'C7'},
+                label='annotation (no text, arrow)')
+    # Fancy arrow patch
+    arrpatch = mpatches.FancyArrowPatch([0.5, 0.8], [0.9, 0.9],
+                            arrowstyle='<|-',
+                            mutation_scale=20,
+                            color='C3',
+                            label='arrowpatch')
+    ax.add_patch(arrpatch)
+    # Long text, will not be used in legend
+    ax.text(x=0.1, y=0.1,
+            s='Hello',
+            color='C5',
+            label='text')
+    # Short text, copied in legend
+    ax.text(x=0.1, y=0.2,
+            s='Z',
+            color='C0',
+            label='short text')
+    ax.legend(handler_map={my_annotation: HandlerAnnotation(rep_str='Abcde',
+                                                            rep_maxlen=0)})
+
+
 def test_legend_remove():
     fig = plt.figure()
     ax = fig.add_subplot(1, 1, 1)

From 6cf5e2bd80bc696d2bd8b2ad6e5bee0cf5bdb3a3 Mon Sep 17 00:00:00 2001
From: Thomas A Caswell <tcaswell@gmail.com>
Date: Sun, 8 Jul 2018 23:54:29 -0400
Subject: [PATCH 2/2] DOC: add whats_new entry

---
 doc/users/next_whats_new/more_legend_handlers.rst | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 doc/users/next_whats_new/more_legend_handlers.rst

diff --git a/doc/users/next_whats_new/more_legend_handlers.rst b/doc/users/next_whats_new/more_legend_handlers.rst
new file mode 100644
index 000000000000..1b6051933939
--- /dev/null
+++ b/doc/users/next_whats_new/more_legend_handlers.rst
@@ -0,0 +1,5 @@
+Add legend handlers for FancyArrowPatch, Text, and Annotation
+-------------------------------------------------------------
+
+By setting the label on FancyArrowPatch, Text, and Annotation objects
+they will automatically be included in legends.