Merge pull request #25597 from ksunden/colortype

story645 · web-flow · commit ddb31638bae4 · 2023-04-19T23:22:31.000-04:00
Add (color, alpha) tuple as a valid ColorType in typing.py
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -17,6 +17,7 @@ repos:
     hooks:
       - id: check-added-large-files
       - id: check-docstring-first
+        exclude: lib/matplotlib/typing.py  # docstring used for attribute flagged by check
       - id: end-of-file-fixer
         exclude_types: [svg]
       - id: mixed-line-ending
diff --git a/doc/api/typing_api.rst b/doc/api/typing_api.rst
@@ -2,6 +2,10 @@
 ``matplotlib.typing``
 *********************
 
+.. autodata:: matplotlib.typing.RGBColorType
+.. autodata:: matplotlib.typing.RGBColourType
+.. autodata:: matplotlib.typing.RGBAColorType
+.. autodata:: matplotlib.typing.RGBAColourType
 .. autodata:: matplotlib.typing.ColorType
 .. autodata:: matplotlib.typing.ColourType
 .. autodata:: matplotlib.typing.LineStyleType
@@ -11,3 +15,5 @@
 .. autodata:: matplotlib.typing.CapStyleType
 .. autodata:: matplotlib.typing.JoinStyleType
 .. autodata:: matplotlib.typing.RcStyleType
+.. autodata:: matplotlib.typing.HashableList
+   :annotation: Nested list with Hashable values
diff --git a/lib/matplotlib/typing.py b/lib/matplotlib/typing.py
@@ -20,7 +20,21 @@
 # The following are type aliases. Once python 3.9 is dropped, they should be annotated
 # using ``typing.TypeAlias`` and Unions should be converted to using ``|`` syntax.
 
-ColorType = Union[tuple[float, float, float], tuple[float, float, float, float], str]
+RGBColorType = Union[tuple[float, float, float], str]
+RGBAColorType = Union[
+    str,  # "none" or "#RRGGBBAA"/"#RGBA" hex strings
+    tuple[float, float, float, float],
+    # 2 tuple (color, alpha) representations, not infinitely recursive
+    # RGBColorType includes the (str, float) tuple, even for RGBA strings
+    tuple[RGBColorType, float],
+    # (4-tuple, float) is odd, but accepted as the outer float overriding A of 4-tuple
+    tuple[tuple[float, float, float, float], float]
+]
+
+ColorType = Union[RGBColorType, RGBAColorType]
+
+RGBColourType = RGBColorType
+RGBAColourType = RGBAColorType
 ColourType = ColorType
 
 LineStyleType = Union[str, tuple[float, Sequence[float]]]
@@ -46,3 +60,4 @@
 ]
 
 HashableList = list[Union[Hashable, "HashableList"]]
+"""A nested list of Hashable values."""
