Backport PR #12203: Document legend best slowness

kbrose · MeeseeksDev[bot] · commit b0e668ab008c · 2018-09-21T18:42:05.000Z
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -136,6 +136,10 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
     corner of the legend in axes coordinates (in which case
     ``bbox_to_anchor`` will be ignored).
 
+    The 'best' option can be quite slow for plots with large amounts
+    of data. Your plotting speed may benefit from providing a specific
+    location.
+
 bbox_to_anchor : `.BboxBase`, 2-tuple, or 4-tuple of floats
     Box that is used to position the legend in conjunction with *loc*.
     Defaults to `axes.bbox` (if called as a method to `.Axes.legend`) or
diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py
@@ -760,6 +760,14 @@ def my_plotter(ax, data1, data2, param_dict):
 #   plt.plot(y)
 #   plt.show()
 #
+# Legends
+# -------
+#
+# The default legend behavior for axes attempts to find the location
+# that covers the fewest data points (`loc='best'`). This can be a
+# very expensive computation if there are lots of data points. In
+# this case, you may want to provide a specific location.
+#
 # Using the *fast* style
 # ----------------------
 #
