Add type stubs for functions in matplotlib.dates (matplotlib#30385)

* Add type stubs for functions in matplotlib.dates

* Make date typing tighter with overloads

* Fix _dt64_to_ordinalf type

* Remvoe old type alisas

* Add argument defaults

* Remove overload on datestr2num

Author: dstansby

lib/matplotlib/dates.py

@@ -309,7 +309,7 @@ def get_epoch():
 
 def _dt64_to_ordinalf(d):
     """
-    Convert `numpy.datetime64` or an `numpy.ndarray` of those types to
+    Convert a `numpy.ndarray` of np.datetime64 to
     Gregorian date as UTC float relative to the epoch (see `.get_epoch`).
     Roundoff is float64 precision.  Practically: microseconds for dates
     between 290301 BC, 294241 AD, milliseconds for larger dates

lib/matplotlib/dates.pyi

@@ -0,0 +1,37 @@
+import datetime
+from collections.abc import Sequence
+from typing import overload
+
+import numpy as np
+import numpy.typing as npt
+
+TZ = str | datetime.tzinfo
+
+def _get_tzinfo(tz: TZ | None=None) -> datetime.tzinfo: ...
+def _reset_epoch_test_example() -> None: ...
+def set_epoch(epoch: str) -> None: ...
+def get_epoch() -> str: ...
+def _dt64_to_ordinalf(d: npt.NDArray[np.datetime64]) -> npt.NDArray[np.floating]: ...
+def _from_ordinalf(x: float, tz: TZ | None=None) -> datetime.datetime: ...
+# Ideally str | Sequence[str] would get an override, but because a str is a valid Sequence[str],
+# it's not possible to distinguish between them in the type system
+# See https://github.com/python/typing/issues/256
+def datestr2num(d: str | Sequence[str], default: datetime.datetime | None=None) -> float | npt.NDArray[np.floating]: ...
+
+@overload
+def date2num(d: datetime.datetime | np.datetime64) -> float: ...
+@overload
+def date2num(d: Sequence[datetime.datetime] | Sequence[np.datetime64]) -> npt.NDArray[np.floating]: ...
+
+@overload
+def num2date(x: float, tz: TZ | None=None) -> datetime.datetime: ...
+@overload
+def num2date(x: Sequence[float], tz: TZ | None=None) -> list[datetime.datetime]: ...
+
+@overload
+def num2timedelta(x: float) -> datetime.timedelta: ...
+@overload
+def num2timedelta(x: Sequence[float]) -> list[datetime.timedelta]: ...
+
+def drange(dstart: datetime.datetime, dend: datetime.datetime, delta: datetime.timedelta) -> npt.NDArray[np.floating]: ...
+def _wrap_in_tex(text: str) -> str: ...