TYP: Clean up CapStyle/FillStyle type hints

Inputs generally accept either the enum or the raw string (literal), outputs are only the string literals

plotnine passes string literals, which are accepted, but did not previously type check

Author: ksunden

doc/api/typing_api.rst

@@ -8,4 +8,6 @@
 .. autodata:: matplotlib.typing.DrawStyleType
 .. autodata:: matplotlib.typing.MarkEveryType
 .. autodata:: matplotlib.typing.FillStyleType
+.. autodata:: matplotlib.typing.CapStyleType
+.. autodata:: matplotlib.typing.JoinStyleType
 .. autodata:: matplotlib.typing.RcStyleType

lib/matplotlib/backend_bases.pyi

@@ -11,7 +11,6 @@ from matplotlib import (
     widgets,
     _api,
 )
-from matplotlib._enums import CapStyle, JoinStyle
 from matplotlib._pylab_helpers import Gcf
 from matplotlib.artist import Artist
 from matplotlib.axes import Axes
@@ -28,7 +27,7 @@ from matplotlib.transforms import Affine2D, Transform, TransformedPath, Bbox
 from collections.abc import Callable, Iterable, Sequence
 from typing import Any, IO, Literal, NamedTuple, TypeVar
 from numpy.typing import ArrayLike
-from .typing import ColorType, LineStyleType
+from .typing import ColorType, LineStyleType, CapStyleType, JoinStyleType
 
 def register_backend(
     format: str, backend: str | type[FigureCanvasBase], description: str | None = ...
@@ -150,27 +149,27 @@ class GraphicsContextBase:
     def restore(self) -> None: ...
     def get_alpha(self) -> float: ...
     def get_antialiased(self) -> int: ...
-    def get_capstyle(self) -> CapStyle: ...
+    def get_capstyle(self) -> Literal["butt", "projecting", "round"]: ...
     def get_clip_rectangle(self) -> Bbox | None: ...
     def get_clip_path(
         self,
     ) -> tuple[TransformedPath, Transform] | tuple[None, None]: ...
     def get_dashes(self) -> tuple[float, ArrayLike | None]: ...
     def get_forced_alpha(self) -> bool: ...
-    def get_joinstyle(self) -> JoinStyle: ...
+    def get_joinstyle(self) -> Literal["miter", "round", "bevel"]: ...
     def get_linewidth(self) -> float: ...
     def get_rgb(self) -> tuple[float, float, float, float]: ...
     def get_url(self) -> str | None: ...
     def get_gid(self) -> int | None: ...
     def get_snap(self) -> bool | None: ...
     def set_alpha(self, alpha: float) -> None: ...
     def set_antialiased(self, b: bool) -> None: ...
-    def set_capstyle(self, cs: CapStyle) -> None: ...
+    def set_capstyle(self, cs: CapStyleType) -> None: ...
     def set_clip_rectangle(self, rectangle: Bbox | None) -> None: ...
     def set_clip_path(self, path: TransformedPath | None) -> None: ...
     def set_dashes(self, dash_offset: float, dash_list: ArrayLike | None) -> None: ...
     def set_foreground(self, fg: ColorType, isRGBA: bool = ...) -> None: ...
-    def set_joinstyle(self, js: JoinStyle) -> None: ...
+    def set_joinstyle(self, js: JoinStyleType) -> None: ...
     def set_linewidth(self, w: float) -> None: ...
     def set_url(self, url: str | None) -> None: ...
     def set_gid(self, id: int | None) -> None: ...

lib/matplotlib/collections.pyi

@@ -12,7 +12,7 @@ import numpy as np
 from numpy.typing import ArrayLike
 from collections.abc import Callable, Iterable, Sequence
 from typing import Literal
-from .typing import ColorType, LineStyleType
+from .typing import ColorType, LineStyleType, CapStyleType, JoinStyleType
 
 class Collection(artist.Artist, cm.ScalarMappable):
     def __init__(
@@ -22,8 +22,8 @@ class Collection(artist.Artist, cm.ScalarMappable):
         facecolors: ColorType | Sequence[ColorType] | None = ...,
         linewidths: float | Sequence[float] | None = ...,
         linestyles: LineStyleType | Sequence[LineStyleType] = ...,
-        capstyle: CapStyle | None = ...,
-        joinstyle: JoinStyle | None = ...,
+        capstyle: CapStyleType | None = ...,
+        joinstyle: JoinStyleType | None = ...,
         antialiaseds: bool | Sequence[bool] | None = ...,
         offsets: tuple[float, float] | Sequence[tuple[float, float]] | None = ...,
         offset_transform: transforms.Transform | None = ...,
@@ -51,10 +51,10 @@ class Collection(artist.Artist, cm.ScalarMappable):
     def get_offsets(self) -> ArrayLike: ...
     def set_linewidth(self, lw: float | Sequence[float]) -> None: ...
     def set_linestyle(self, ls: LineStyleType | Sequence[LineStyleType]) -> None: ...
-    def set_capstyle(self, cs: CapStyle | Sequence[CapStyle]) -> None: ...
-    def get_capstyle(self) -> CapStyle | Sequence[CapStyle]: ...
-    def set_joinstyle(self, js: JoinStyle | Sequence[JoinStyle]) -> None: ...
-    def get_joinstyle(self) -> JoinStyle | Sequence[JoinStyle]: ...
+    def set_capstyle(self, cs: CapStyleType) -> None: ...
+    def get_capstyle(self) -> Literal["butt", "projecting", "round"]: ...
+    def set_joinstyle(self, js: JoinStyleType) -> None: ...
+    def get_joinstyle(self) -> Literal["miter", "round", "bevel"]: ...
     def set_antialiased(self, aa: bool | Sequence[bool]) -> None: ...
     def set_color(self, c: ColorType | Sequence[ColorType]) -> None: ...
     def set_facecolor(self, c: ColorType | Sequence[ColorType]) -> None: ...

lib/matplotlib/lines.pyi

@@ -1,5 +1,4 @@
 from . import cbook
-from ._enums import CapStyle, JoinStyle
 from .artist import Artist, allow_rasterization
 from .axes import Axes
 from .backend_bases import MouseEvent, FigureCanvasBase
@@ -23,9 +22,16 @@ from .path import Path
 from .transforms import Bbox, BboxTransformTo, TransformedPath, Transform
 
 from collections.abc import Callable, Sequence
-from typing import Any, overload
+from typing import Any, Literal, overload
 from .typing import (
-    ColorType, DrawStyleType, FillStyleType, LineStyleType, MarkEveryType, MarkerType
+    ColorType,
+    DrawStyleType,
+    FillStyleType,
+    LineStyleType,
+    CapStyleType,
+    JoinStyleType,
+    MarkEveryType,
+    MarkerType,
 )
 from numpy.typing import ArrayLike
 
@@ -59,10 +65,10 @@ class Line2D(Artist):
         markerfacecoloralt: ColorType = ...,
         fillstyle: FillStyleType | None = ...,
         antialiased: bool | None = ...,
-        dash_capstyle: CapStyle | None = ...,
-        solid_capstyle: CapStyle | None = ...,
-        dash_joinstyle: JoinStyle | None = ...,
-        solid_joinstyle: JoinStyle | None = ...,
+        dash_capstyle: CapStyleType | None = ...,
+        solid_capstyle: CapStyleType | None = ...,
+        dash_joinstyle: JoinStyleType | None = ...,
+        solid_joinstyle: JoinStyleType | None = ...,
         pickradius: float = ...,
         drawstyle: DrawStyleType | None = ...,
         markevery: MarkEveryType | None = ...,
@@ -121,14 +127,14 @@ class Line2D(Artist):
     def set_ydata(self, y: ArrayLike) -> None: ...
     def set_dashes(self, seq: Sequence[float] | tuple[None, None]) -> None: ...
     def update_from(self, other: Artist) -> None: ...
-    def set_dash_joinstyle(self, s: JoinStyle) -> None: ...
-    def set_solid_joinstyle(self, s: JoinStyle) -> None: ...
-    def get_dash_joinstyle(self) -> str: ...
-    def get_solid_joinstyle(self) -> str: ...
-    def set_dash_capstyle(self, s: CapStyle) -> None: ...
-    def set_solid_capstyle(self, s: CapStyle) -> None: ...
-    def get_dash_capstyle(self) -> str: ...
-    def get_solid_capstyle(self) -> str: ...
+    def set_dash_joinstyle(self, s: JoinStyleType) -> None: ...
+    def set_solid_joinstyle(self, s: JoinStyleType) -> None: ...
+    def get_dash_joinstyle(self) -> Literal["miter", "round", "bevel"]: ...
+    def get_solid_joinstyle(self) -> Literal["miter", "round", "bevel"]: ...
+    def set_dash_capstyle(self, s: CapStyleType) -> None: ...
+    def set_solid_capstyle(self, s: CapStyleType) -> None: ...
+    def get_dash_capstyle(self) -> Literal["butt", "projecting", "round"]: ...
+    def get_solid_capstyle(self) -> Literal["butt", "projecting", "round"]: ...
     def is_dashed(self) -> bool: ...
 
 class _AxLine(Line2D):

lib/matplotlib/patches.pyi

@@ -1,6 +1,5 @@
 from . import artist, cbook, colors, transforms
 from .axes import Axes
-from ._enums import CapStyle, JoinStyle
 from .backend_bases import RendererBase, MouseEvent
 from .bezier import (
     NonIntersectingPathException,
@@ -19,7 +18,7 @@ from typing import Any, Literal, overload
 
 import numpy as np
 from numpy.typing import ArrayLike
-from .typing import ColorType, LineStyleType
+from .typing import ColorType, LineStyleType, CapStyleType, JoinStyleType
 
 class Patch(artist.Artist):
     zorder: float
@@ -34,8 +33,8 @@ class Patch(artist.Artist):
         antialiased: bool | None = ...,
         hatch: str | None = ...,
         fill: bool = ...,
-        capstyle: CapStyle | None = ...,
-        joinstyle: JoinStyle | None = ...,
+        capstyle: CapStyleType | None = ...,
+        joinstyle: JoinStyleType | None = ...,
         **kwargs,
     ) -> None: ...
     def get_verts(self) -> ArrayLike: ...
@@ -65,10 +64,10 @@ class Patch(artist.Artist):
     def set_fill(self, b: bool) -> None: ...
     def get_fill(self) -> bool: ...
     fill = property(get_fill, set_fill)
-    def set_capstyle(self, s: CapStyle) -> None: ...
-    def get_capstyle(self) -> CapStyle: ...
-    def set_joinstyle(self, s: JoinStyle) -> None: ...
-    def get_joinstyle(self) -> JoinStyle: ...
+    def set_capstyle(self, s: CapStyleType) -> None: ...
+    def get_capstyle(self) -> Literal["butt", "projecting", "round"]: ...
+    def set_joinstyle(self, s: JoinStyleType) -> None: ...
+    def get_joinstyle(self) -> Literal["miter", "round", "bevel"]: ...
     def set_hatch(self, hatch: str) -> None: ...
     def get_hatch(self) -> str: ...
     def get_path(self) -> Path: ...

lib/matplotlib/typing.py

@@ -14,6 +14,7 @@
 from typing import Any, Hashable, Literal, Union
 
 from . import path
+from ._enums import JoinStyle, CapStyle
 from .markers import MarkerStyle
 
 # The following are type aliases. Once python 3.9 is dropped, they should be annotated
@@ -37,6 +38,8 @@
 
 MarkerType = Union[str, path.Path, MarkerStyle]
 FillStyleType = Literal["full", "left", "right", "bottom", "top", "none"]
+JoinStyleType = JoinStyle | Literal["miter", "round", "bevel"]
+CapStyleType = CapStyle | Literal["butt", "projecting", "round"]
 
 RcStyleType = Union[
     str, dict[str, Any], pathlib.Path, list[Union[str, pathlib.Path, dict[str, Any]]]