Improve typing in pyplot (matplotlib#26385)

* TYP: Fix types for path effects property

* Add typing to _docstring module

This is mainly useful because of its decorators, which previously caused
any usage to lose typing. Consequently, there are several _new_ typing
errors, many of which are fixed here, but not all.

* Add typing to _copy_docstring_and_deprecators

As before, this untyped function caused any decorator usage to make the
wrapped function untyped. Now, these functions are typed again. This
revealed several follow-on type issues, but many of them are expected
(as tests tend to call things with incorrect arguments on purpose, use
property aliases, etc.)

* Add some more typing in pyplot

* Add return annotation for pie

* Remove return from pyplot funcs annotated as None

* TYP: Explicitly re-export some API from pyplot

See matplotlib#26372

Author: QuLogic

galleries/examples/misc/hyperlinks_sgskip.py

@@ -33,7 +33,7 @@
 Z = (Z1 - Z2) * 2
 
 im = plt.imshow(Z, interpolation='bilinear', cmap=cm.gray,
-                origin='lower', extent=[-3, 3, -3, 3])
+                origin='lower', extent=(-3, 3, -3, 3))
 
 im.set_url('https://www.google.com/')
 fig.savefig('image.svg')

galleries/examples/shapes_and_collections/dolphin.py

@@ -33,7 +33,7 @@
 im = plt.imshow(np.random.random((100, 100)),
                 origin='lower', cmap=cm.winter,
                 interpolation='spline36',
-                extent=([-1, 1, -1, 1]))
+                extent=(-1, 1, -1, 1))
 im.set_clip_path(circle)
 
 plt.plot(x, y, 'o', color=(0.9, 0.9, 1.0), alpha=0.8)

galleries/examples/subplots_axes_and_figures/subplots_adjust.py

@@ -25,7 +25,7 @@
 plt.imshow(np.random.random((100, 100)))
 
 plt.subplots_adjust(bottom=0.1, right=0.8, top=0.9)
-cax = plt.axes([0.85, 0.1, 0.075, 0.8])
+cax = plt.axes((0.85, 0.1, 0.075, 0.8))
 plt.colorbar(cax=cax)
 
 plt.show()

galleries/examples/text_labels_and_annotations/autowrap.py

@@ -17,7 +17,7 @@
 import matplotlib.pyplot as plt
 
 fig = plt.figure()
-plt.axis([0, 10, 0, 10])
+plt.axis((0, 10, 0, 10))
 t = ("This is a really long string that I'd rather have wrapped so that it "
      "doesn't go outside of the figure, but if it's long enough it will go "
      "off the top or bottom!")

galleries/tutorials/pyplot.py

@@ -73,7 +73,7 @@
 # example, to plot the above with red circles, you would issue
 
 plt.plot([1, 2, 3, 4], [1, 4, 9, 16], 'ro')
-plt.axis([0, 6, 0, 20])
+plt.axis((0, 6, 0, 20))
 plt.show()
 
 # %%

lib/matplotlib/_docstring.pyi

@@ -0,0 +1,29 @@
+from typing import Any, Callable, TypeVar, overload
+
+
+_T = TypeVar('_T')
+
+
+class Substitution:
+    @overload
+    def __init__(self, *args: str): ...
+    @overload
+    def __init__(self, **kwargs: str): ...
+    def __call__(self, func: _T) -> _T: ...
+    def update(self, *args, **kwargs): ...  # type: ignore[no-untyped-def]
+
+
+class _ArtistKwdocLoader(dict[str, str]):
+    def __missing__(self, key: str) -> str: ...
+
+
+class _ArtistPropertiesSubstitution(Substitution):
+    def __init__(self) -> None: ...
+    def __call__(self, obj: _T) -> _T: ...
+
+
+def copy(source: Any) -> Callable[[_T], _T]: ...
+
+
+dedent_interpd: _ArtistPropertiesSubstitution
+interpd: _ArtistPropertiesSubstitution

lib/matplotlib/artist.py

@@ -715,7 +715,7 @@ def set_path_effects(self, path_effects):
 
         Parameters
         ----------
-        path_effects : `.AbstractPathEffect`
+        path_effects : list of `.AbstractPathEffect`
         """
         self._path_effects = path_effects
         self.stale = True

lib/matplotlib/artist.pyi

@@ -83,8 +83,8 @@ class Artist:
         length: float | None = ...,
         randomness: float | None = ...,
     ) -> None: ...
-    def set_path_effects(self, path_effects: AbstractPathEffect) -> None: ...
-    def get_path_effects(self) -> AbstractPathEffect: ...
+    def set_path_effects(self, path_effects: list[AbstractPathEffect]) -> None: ...
+    def get_path_effects(self) -> list[AbstractPathEffect]: ...
     def get_figure(self) -> Figure | None: ...
     def set_figure(self, fig: Figure) -> None: ...
     def set_clip_box(self, clipbox: Bbox) -> None: ...

lib/matplotlib/axes/_axes.pyi

@@ -20,7 +20,7 @@ from matplotlib.legend import Legend
 from matplotlib.legend_handler import HandlerBase
 from matplotlib.lines import Line2D
 from matplotlib.mlab import GaussianKDE
-from matplotlib.patches import Rectangle, FancyArrow, Polygon, StepPatch
+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
@@ -305,7 +305,7 @@ class Axes(_AxesBase):
         autopct: str | Callable[[float], str] | None = ...,
         pctdistance: float = ...,
         shadow: bool = ...,
-        labeldistance: float = ...,
+        labeldistance: float | None = ...,
         startangle: float = ...,
         radius: float = ...,
         counterclock: bool = ...,
@@ -318,7 +318,9 @@ class Axes(_AxesBase):
         normalize: bool = ...,
         hatch: str | Sequence[str] | None = ...,
         data=...,
-    ): ...
+    ) -> tuple[list[Wedge], list[Text]] | tuple[
+        list[Wedge], list[Text], list[Text]
+    ]: ...
     def errorbar(
         self,
         x: float | ArrayLike,
@@ -564,7 +566,7 @@ class Axes(_AxesBase):
         edges: ArrayLike | None = ...,
         *,
         orientation: Literal["vertical", "horizontal"] = ...,
-        baseline: float | ArrayLike = ...,
+        baseline: float | ArrayLike | None = ...,
         fill: bool = ...,
         data=...,
         **kwargs
@@ -736,7 +738,7 @@ class Axes(_AxesBase):
         showmeans: bool = ...,
         showextrema: bool = ...,
         showmedians: bool = ...,
-        quantiles: Sequence[float] | None = ...,
+        quantiles: Sequence[float | Sequence[float]] | None = ...,
         points: int = ...,
         bw_method: Literal["scott", "silverman"]
         | float

lib/matplotlib/axes/_base.pyi

@@ -39,6 +39,7 @@ class _axis_method_wrapper:
 
 class _AxesBase(martist.Artist):
     name: str
+    patch: Patch
     spines: Spines
     fmt_xdata: Callable[[float], str] | None
     fmt_ydata: Callable[[float], str] | None