Tweak argument checking in tripcolor().

For incorrect number of parameters, switch to raising a (standard)
TypeError and use a standard-ish signature mismatch error message.  Note
that exception type stability was already broken in 3.6 because it was
previously an IndexError (that was triggered later) and 703b574 changed
that to a ValueError.

Also deprecate support for passing extra parameters (as we now tend to
do for all such overly accepting APIs).  Note that the changelog entry
states that such parameters were previously silently ignored, even
though the patch replaces a warn_external() by a warn_deprecated(); this
is simply because the warn_external() wasn't present yet in the last
released version.

Author: anntzer

doc/api/next_api_changes/deprecations/22883-AL.rst

@@ -0,0 +1,3 @@
+Passing too many positional arguments to ``tripcolor``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... is now deprecated (extra arguments were previously silently ignored).

lib/matplotlib/tests/test_triangulation.py

@@ -242,7 +242,7 @@ def test_tripcolor_color():
     x = [-1, 0, 1, 0]
     y = [0, -1, 0, 1]
     fig, ax = plt.subplots()
-    with pytest.raises(ValueError, match="Missing color parameter"):
+    with pytest.raises(TypeError, match=r"tripcolor\(\) missing 1 required "):
         ax.tripcolor(x, y)
     with pytest.raises(ValueError, match="The length of C must match either"):
         ax.tripcolor(x, y, [1, 2, 3])
@@ -255,8 +255,8 @@ def test_tripcolor_color():
     with pytest.raises(ValueError,
                        match="'gouraud' .* at the points.* not at the faces"):
         ax.tripcolor(x, y, [1, 2], shading='gouraud')  # faces
-    with pytest.raises(ValueError,
-                       match=r"pass C positionally or facecolors via keyword"):
+    with pytest.raises(TypeError,
+                       match="positional.*'C'.*keyword-only.*'facecolors'"):
         ax.tripcolor(x, y, C=[1, 2, 3, 4])
 
     # smoke test for valid color specifications (via C or facecolors)
@@ -282,7 +282,7 @@ def test_tripcolor_warnings():
     C = [0.4, 0.5]
     fig, ax = plt.subplots()
     # additional parameters
-    with pytest.warns(UserWarning, match="Additional positional parameters"):
+    with pytest.warns(DeprecationWarning, match="Additional positional param"):
         ax.tripcolor(x, y, C, 'unused_positional')
     # facecolors takes precednced over C
     with pytest.warns(UserWarning, match="Positional parameter C .*no effect"):

lib/matplotlib/tri/tripcolor.py

@@ -79,12 +79,14 @@ def tripcolor(ax, *args, alpha=1.0, norm=None, cmap=None, vmin=None,
     else:
         # Color from positional parameter C
         if not args:
-            raise ValueError(
-                "Missing color parameter. Please pass C positionally or "
-                "facecolors via keyword")
+            raise TypeError(
+                "tripcolor() missing 1 required positional argument: 'C'; or "
+                "1 required keyword-only argument: 'facecolors'")
         elif len(args) > 1:
-            _api.warn_external(
-                "Additional positional parameters {args[1:]!r} are ignored")
+            _api.warn_deprecated(
+                "3.6", message=f"Additional positional parameters "
+                f"{args[1:]!r} are ignored; support for them is deprecated "
+                f"since %(since)s and will be removed %(removal)s")
         C = np.asarray(args[0])
         if len(C) == len(tri.x):
             # having this before the len(tri.triangles) comparison gives