diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py index 511e1c6df6cc..107cb17e3685 100644 --- a/lib/matplotlib/dates.py +++ b/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 diff --git a/lib/matplotlib/dates.pyi b/lib/matplotlib/dates.pyi new file mode 100644 index 000000000000..426082679393 --- /dev/null +++ b/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: ...