TYP: Add CoordsType and use in relevant locations(matplotlib#28532)

* TYP: Fix xycoords and friends

* Fix organization

* Fix linting

* Fix import

* Fix linting

* Fix for earlier Pythons

* Fix again for older Pythons

* Fix long line

* Trailing whitespace

* Fix older Pythons again

* Fix mypy stub check

* Fix mypy stubtests

* Fix stubtest for Python 3.9

* Handle suggestions in PR

* Fix lint and stubtest

Author: mdboom

lib/matplotlib/axes/_axes.pyi

@@ -22,7 +22,8 @@ from matplotlib.mlab import GaussianKDE
 from matplotlib.patches import Rectangle, FancyArrow, Polygon, StepPatch, Wedge
 from matplotlib.quiver import Quiver, QuiverKey, Barbs
 from matplotlib.text import Annotation, Text
-from matplotlib.transforms import Transform, Bbox
+from matplotlib.transforms import Transform
+from matplotlib.typing import CoordsType
 import matplotlib.tri as mtri
 import matplotlib.table as mtable
 import matplotlib.stackplot as mstack
@@ -122,17 +123,8 @@ class Axes(_AxesBase):
         text: str,
         xy: tuple[float, float],
         xytext: tuple[float, float] | None = ...,
-        xycoords: str
-        | Artist
-        | Transform
-        | Callable[[RendererBase], Bbox | Transform]
-        | tuple[float, float] = ...,
-        textcoords: str
-        | Artist
-        | Transform
-        | Callable[[RendererBase], Bbox | Transform]
-        | tuple[float, float]
-        | None = ...,
+        xycoords: CoordsType = ...,
+        textcoords: CoordsType | None = ...,
         arrowprops: dict[str, Any] | None = ...,
         annotation_clip: bool | None = ...,
         **kwargs

lib/matplotlib/offsetbox.pyi

@@ -7,6 +7,7 @@ from matplotlib.font_manager import FontProperties
 from matplotlib.image import BboxImage
 from matplotlib.patches import FancyArrowPatch, FancyBboxPatch
 from matplotlib.transforms import Bbox, BboxBase, Transform
+from matplotlib.typing import CoordsType
 
 import numpy as np
 from numpy.typing import ArrayLike
@@ -219,9 +220,7 @@ class AnnotationBbox(martist.Artist, mtext._AnnotationBase):
     offsetbox: OffsetBox
     arrowprops: dict[str, Any] | None
     xybox: tuple[float, float]
-    boxcoords: str | tuple[str, str] | martist.Artist | Transform | Callable[
-        [RendererBase], Bbox | Transform
-    ]
+    boxcoords: CoordsType
     arrow_patch: FancyArrowPatch | None
     patch: FancyBboxPatch
     prop: FontProperties
@@ -230,17 +229,8 @@ class AnnotationBbox(martist.Artist, mtext._AnnotationBase):
         offsetbox: OffsetBox,
         xy: tuple[float, float],
         xybox: tuple[float, float] | None = ...,
-        xycoords: str
-        | tuple[str, str]
-        | martist.Artist
-        | Transform
-        | Callable[[RendererBase], Bbox | Transform] = ...,
-        boxcoords: str
-        | tuple[str, str]
-        | martist.Artist
-        | Transform
-        | Callable[[RendererBase], Bbox | Transform]
-        | None = ...,
+        xycoords: CoordsType = ...,
+        boxcoords: CoordsType | None = ...,
         *,
         frameon: bool = ...,
         pad: float = ...,
@@ -258,17 +248,11 @@ class AnnotationBbox(martist.Artist, mtext._AnnotationBase):
     @property
     def anncoords(
         self,
-    ) -> str | tuple[str, str] | martist.Artist | Transform | Callable[
-        [RendererBase], Bbox | Transform
-    ]: ...
+    ) -> CoordsType: ...
     @anncoords.setter
     def anncoords(
         self,
-        coords: str
-        | tuple[str, str]
-        | martist.Artist
-        | Transform
-        | Callable[[RendererBase], Bbox | Transform],
+        coords: CoordsType,
     ) -> None: ...
     def get_children(self) -> list[martist.Artist]: ...
     def set_figure(self, fig: Figure | SubFigure) -> None: ...

lib/matplotlib/pyplot.py

@@ -96,7 +96,7 @@
     import matplotlib.backend_bases
     from matplotlib.axis import Tick
     from matplotlib.axes._base import _AxesBase
-    from matplotlib.backend_bases import RendererBase, Event
+    from matplotlib.backend_bases import Event
     from matplotlib.cm import ScalarMappable
     from matplotlib.contour import ContourSet, QuadContourSet
     from matplotlib.collections import (
@@ -120,8 +120,13 @@
     from matplotlib.patches import FancyArrow, StepPatch, Wedge
     from matplotlib.quiver import Barbs, Quiver, QuiverKey
     from matplotlib.scale import ScaleBase
-    from matplotlib.transforms import Transform, Bbox
-    from matplotlib.typing import ColorType, LineStyleType, MarkerType, HashableList
+    from matplotlib.typing import (
+        ColorType,
+        CoordsType,
+        HashableList,
+        LineStyleType,
+        MarkerType,
+    )
     from matplotlib.widgets import SubplotTool
 
     _P = ParamSpec('_P')
@@ -2860,17 +2865,8 @@ def annotate(
     text: str,
     xy: tuple[float, float],
     xytext: tuple[float, float] | None = None,
-    xycoords: str
-    | Artist
-    | Transform
-    | Callable[[RendererBase], Bbox | Transform]
-    | tuple[float, float] = "data",
-    textcoords: str
-    | Artist
-    | Transform
-    | Callable[[RendererBase], Bbox | Transform]
-    | tuple[float, float]
-    | None = None,
+    xycoords: CoordsType = "data",
+    textcoords: CoordsType | None = None,
     arrowprops: dict[str, Any] | None = None,
     annotation_clip: bool | None = None,
     **kwargs,

lib/matplotlib/text.pyi

@@ -16,7 +16,7 @@ from .transforms import (
 
 from collections.abc import Callable, Iterable
 from typing import Any, Literal
-from .typing import ColorType
+from .typing import ColorType, CoordsType
 
 class Text(Artist):
     zorder: float
@@ -120,17 +120,11 @@ class OffsetFrom:
 
 class _AnnotationBase:
     xy: tuple[float, float]
-    xycoords: str | tuple[str, str] | Artist | Transform | Callable[
-        [RendererBase], Bbox | Transform
-    ]
+    xycoords: CoordsType
     def __init__(
         self,
         xy,
-        xycoords: str
-        | tuple[str, str]
-        | Artist
-        | Transform
-        | Callable[[RendererBase], Bbox | Transform] = ...,
+        xycoords: CoordsType = ...,
         annotation_clip: bool | None = ...,
     ) -> None: ...
     def set_annotation_clip(self, b: bool | None) -> None: ...
@@ -147,67 +141,40 @@ class Annotation(Text, _AnnotationBase):
         text: str,
         xy: tuple[float, float],
         xytext: tuple[float, float] | None = ...,
-        xycoords: str
-        | tuple[str, str]
-        | Artist
-        | Transform
-        | Callable[[RendererBase], Bbox | Transform] = ...,
-        textcoords: str
-        | tuple[str, str]
-        | Artist
-        | Transform
-        | Callable[[RendererBase], Bbox | Transform]
-        | None = ...,
+        xycoords: CoordsType = ...,
+        textcoords: CoordsType | None = ...,
         arrowprops: dict[str, Any] | None = ...,
         annotation_clip: bool | None = ...,
         **kwargs
     ) -> None: ...
     @property
     def xycoords(
         self,
-    ) -> str | tuple[str, str] | Artist | Transform | Callable[
-        [RendererBase], Bbox | Transform
-    ]: ...
+    ) -> CoordsType: ...
     @xycoords.setter
     def xycoords(
         self,
-        xycoords: str
-        | tuple[str, str]
-        | Artist
-        | Transform
-        | Callable[[RendererBase], Bbox | Transform],
+        xycoords: CoordsType,
     ) -> None: ...
     @property
     def xyann(self) -> tuple[float, float]: ...
     @xyann.setter
     def xyann(self, xytext: tuple[float, float]) -> None: ...
     def get_anncoords(
         self,
-    ) -> str | tuple[str, str] | Artist | Transform | Callable[
-        [RendererBase], Bbox | Transform
-    ]: ...
+    ) -> CoordsType: ...
     def set_anncoords(
         self,
-        coords: str
-        | tuple[str, str]
-        | Artist
-        | Transform
-        | Callable[[RendererBase], Bbox | Transform],
+        coords: CoordsType,
     ) -> None: ...
     @property
     def anncoords(
         self,
-    ) -> str | tuple[str, str] | Artist | Transform | Callable[
-        [RendererBase], Bbox | Transform
-    ]: ...
+    ) -> CoordsType: ...
     @anncoords.setter
     def anncoords(
         self,
-        coords: str
-        | tuple[str, str]
-        | Artist
-        | Transform
-        | Callable[[RendererBase], Bbox | Transform],
+        coords: CoordsType,
     ) -> None: ...
     def update_positions(self, renderer: RendererBase) -> None: ...
     # Drops `dpi` parameter from superclass

lib/matplotlib/typing.py

@@ -11,11 +11,14 @@
 """
 from collections.abc import Hashable, Sequence
 import pathlib
-from typing import Any, Literal, TypeAlias, TypeVar
+from typing import Any, Callable, Literal, TypeAlias, TypeVar, Union
 
 from . import path
 from ._enums import JoinStyle, CapStyle
+from .artist import Artist
+from .backend_bases import RendererBase
 from .markers import MarkerStyle
+from .transforms import Bbox, Transform
 
 RGBColorType: TypeAlias = tuple[float, float, float] | str
 RGBAColorType: TypeAlias = (
@@ -49,6 +52,20 @@
 JoinStyleType: TypeAlias = JoinStyle | Literal["miter", "round", "bevel"]
 CapStyleType: TypeAlias = CapStyle | Literal["butt", "projecting", "round"]
 
+CoordsBaseType = Union[
+    str,
+    Artist,
+    Transform,
+    Callable[
+        [RendererBase],
+        Union[Bbox, Transform]
+    ]
+]
+CoordsType = Union[
+    CoordsBaseType,
+    tuple[CoordsBaseType, CoordsBaseType]
+]
+
 RcStyleType: TypeAlias = (
     str |
     dict[str, Any] |