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

lib/matplotlib/backend_bases.py

@@ -2304,7 +2304,7 @@ def mpl_disconnect(self, cid):
             # ... later
             canvas.mpl_disconnect(cid)
         """
-        return self.callbacks.disconnect(cid)
+        self.callbacks.disconnect(cid)
 
     # Internal subclasses can override _timer_cls instead of new_timer, though
     # this is not a public API for third-party subclasses.

lib/matplotlib/cbook.pyi

@@ -20,6 +20,8 @@ from typing import (
 
 _T = TypeVar("_T")
 
+def _get_running_interactive_framework() -> str | None: ...
+
 class CallbackRegistry:
     exception_handler: Callable[[Exception], Any]
     callbacks: dict[Any, dict[int, Any]]
@@ -162,6 +164,7 @@ def normalize_kwargs(
     kw: dict[str, Any],
     alias_mapping: dict[str, list[str]] | type[Artist] | Artist | None = ...,
 ) -> dict[str, Any]: ...
+def _str_equal(obj: Any, s: str) -> bool: ...
 
 class _OrderedSet(collections.abc.MutableSet):
     def __init__(self) -> None: ...
@@ -171,4 +174,5 @@ class _OrderedSet(collections.abc.MutableSet):
     def add(self, key) -> None: ...
     def discard(self, key) -> None: ...
 
+def _backend_module_name(name: str) -> str: ...
 def _format_approx(number: float, precision: int) -> str: ...

lib/matplotlib/collections.pyi

@@ -42,7 +42,7 @@ class Collection(artist.Artist, cm.ScalarMappable):
     def get_datalim(self, transData: transforms.Transform) -> transforms.Bbox: ...
     def set_pickradius(self, pickradius: float) -> None: ...
     def get_pickradius(self) -> float: ...
-    def set_urls(self, urls: Sequence[str]) -> None: ...
+    def set_urls(self, urls: Sequence[str | None]) -> None: ...
     def get_urls(self) -> Sequence[str | None]: ...
     def set_hatch(self, hatch: str) -> None: ...
     def get_hatch(self) -> str: ...

lib/matplotlib/container.pyi

@@ -10,8 +10,8 @@ from numpy.typing import ArrayLike
 class Container(tuple):
     def __new__(cls, *args, **kwargs): ...
     def __init__(self, kl, label: Any | None = ...) -> None: ...
-    def remove(self): ...
-    def get_children(self): ...
+    def remove(self) -> None: ...
+    def get_children(self) -> list[Artist]: ...
     def get_label(self) -> str | None: ...
     def set_label(self, s: Any) -> None: ...
     def add_callback(self, func: Callable[[Artist], Any]) -> int: ...