ENH: Accept ('color', alpha) tuple to define a color

j1642 · j1642 · commit 1c6f99333e0b · 2023-02-10T18:34:04.000-05:00
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -315,6 +315,13 @@ def _to_rgba_no_colorcycle(c, alpha=None):
     *alpha* is ignored for the color value ``"none"`` (case-insensitive),
     which always maps to ``(0, 0, 0, 0)``.
     """
+    if isinstance(c, tuple) and len(c) == 2:
+        if alpha is None:
+            c, alpha = c
+        else:
+            c = c[0]
+    if alpha is not None and not 0 <= alpha <= 1:
+        raise ValueError("'alpha' must be between 0 and 1, inclusive")
     orig_c = c
     if c is np.ma.masked:
         return (0., 0., 0., 0.)
@@ -428,6 +435,11 @@ def to_rgba_array(c, alpha=None):
     # Special-case inputs that are already arrays, for performance.  (If the
     # array has the wrong kind or shape, raise the error during one-at-a-time
     # conversion.)
+    if isinstance(c, tuple) and len(c) == 2:
+        if alpha is None:
+            c, alpha = c
+        else:
+            c = c[0]
     if np.iterable(alpha):
         alpha = np.asarray(alpha).ravel()
     if (isinstance(c, np.ndarray) and c.dtype.kind in "if"
@@ -464,9 +476,11 @@ def to_rgba_array(c, alpha=None):
             return np.array([to_rgba(c, a) for a in alpha], float)
         else:
             return np.array([to_rgba(c, alpha)], float)
-    except (ValueError, TypeError):
-        pass
-
+    except (ValueError, TypeError) as e:
+        if e.__repr__() == """ValueError("'alpha' must be between 0 and 1, """\
+                           """inclusive")""":
+            # ValueError is from _to_rgba_no_colorcycle().
+            raise e
     if isinstance(c, str):
         raise ValueError(f"{c!r} is not a valid color value.")
 
diff --git a/lib/matplotlib/tests/test_colors.py b/lib/matplotlib/tests/test_colors.py
@@ -1301,6 +1301,62 @@ def test_to_rgba_array_alpha_array():
     assert_array_equal(c[:, 3], alpha)
 
 
+@pytest.mark.parametrize('rgba_alpha, alpha',
+                         [(('black', 1), 0.5), (('#000000', 0.5), None)])
+def test_to_rgba_array_color_alpha_tuple(rgba_alpha, alpha):
+    """to_rgba_array() accepts tuple (color, alpha) argument."""
+    booleans = mcolors.to_rgba_array(rgba_alpha, alpha=alpha) \
+               == mcolors.to_rgba_array('black', alpha=0.5)
+    assert booleans.all()
+
+
+def test_to_rgba_array_color_alpha_tuple_multiple_colors():
+    """to_rgba_array() accepts tuple (array of colors, alpha) argument."""
+    color_array = np.array([[1., 1., 1., 1.], [0., 0., 1., 0.]])
+    booleans = mcolors.to_rgba_array((color_array, 0.5), alpha=None) \
+               == np.array([[1., 1., 1., 0.5], [0., 0., 1., 0.5]])
+    assert booleans.all()
+
+    color_sequence = [[1., 1., 1., 1.], [0., 0., 1., 0.]]
+    booleans = mcolors.to_rgba_array((color_sequence, 1), alpha=0.5) \
+               == np.array([[1., 1., 1., 0.5], [0., 0., 1., 0.5]])
+    assert booleans.all()
+
+
+@pytest.mark.parametrize('rgba_alpha',
+                         [('black', -2), ('#000000', -2), ('#000', -2),
+                          ('#000000ff', 2), ((0.0, 0.0, 0.0, 0.0), 2)])
+def test_to_rgba_array_color_alpha_tuple_invalid_alpha(rgba_alpha):
+    """
+    to_rgba_array() rejects tuple (color, alpha) argument when
+    alpha is not between 0 and 1.
+    """
+    with pytest.raises(ValueError, match="'alpha' must be between 0 and 1,"):
+        mcolors.to_rgba_array(rgba_alpha)
+
+
+@pytest.mark.parametrize('rgba_alpha, alpha',
+                         [(('white', 1), 0.5), (('#ffffff', 1), 0.5),
+                          (('#ffffff00', 0.5), None),
+                          (((1.0, 1.0, 1.0, 1.0), 0.5), None)])
+def test_to_rgba_color_alpha_tuple(rgba_alpha, alpha):
+    """to_rgba() accepts tuple (color, alpha) argument."""
+    assert mcolors.to_rgba(rgba_alpha, alpha=alpha) \
+           == mcolors.to_rgba('white', alpha=0.5)
+
+
+@pytest.mark.parametrize('rgba_alpha',
+                         [('blue', -2), ('#0000ff', -2), ('#00f', -2),
+                          ('#0000ffff', 2), ((0.0, 0.0, 1.0, 1.0), 2)])
+def test_to_rgba_color_alpha_tuple_invalid_alpha(rgba_alpha):
+    """
+    to_rgba() rejects tuple (color, alpha) argument when alpha
+    is not between 0 and 1.
+    """
+    with pytest.raises(ValueError, match="'alpha' must be between 0 and 1"):
+        mcolors.to_rgba(rgba_alpha)
+
+
 def test_failed_conversions():
     with pytest.raises(ValueError):
         mcolors.to_rgba('5')
