Improve warning for case where data kwarg entry is ambiguous.

anntzer · anntzer · commit bfec0e7c2e5d · 2019-05-31T14:03:07.000+02:00
A call like `plot("x", "y", data={"x": ..., "y": ...})` currently
results in a warning suggesting to use a 3-arg call or renaming the
entry, because "y" is ambiguous.

Renaming the entry is not always an option (if you do not control
'data'), and it may not be obvious how to do a 3-arg call that just uses
the normal property cycle.  As it turns out, passing an empty string
works, so document that possibility.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -194,10 +194,13 @@ def __call__(self, *args, **kwargs):
                 else:
                     if replaced[1] is not args[1]:  # case 2a)
                         cbook._warn_external(
-                            "Second argument {!r} is ambiguous: could be a "
-                            "color spec but is in data; using as data.  "
-                            "Either rename the entry in data or use three "
-                            "arguments to plot.".format(args[1]),
+                            f"Second argument {args[1]!r} is ambiguous: could "
+                            f"be a format string but is in 'data'; using as "
+                            f"data.  If it was intended as data, set the "
+                            f"format string to an empty string to suppress "
+                            f"this warning.  If it was intended as a format "
+                            f"string, explicitly pass the x-values as well.  "
+                            f"Alternatively, rename the entry in 'data'.",
                             RuntimeWarning)
                         label_namer_idx = 1
                     else:  # case 2b)
