TYP: datetimelike (#41830)

Author: jbrockmendel

pandas/core/arrays/datetimes.py

@@ -83,6 +83,7 @@
 if TYPE_CHECKING:
     from typing import Literal
 
+    from pandas import DataFrame
     from pandas.core.arrays import (
         PeriodArray,
         TimedeltaArray,
@@ -1256,7 +1257,7 @@ def day_name(self, locale=None):
         return result
 
     @property
-    def time(self):
+    def time(self) -> np.ndarray:
         """
         Returns numpy array of datetime.time. The time part of the Timestamps.
         """
@@ -1268,15 +1269,15 @@ def time(self):
         return ints_to_pydatetime(timestamps, box="time")
 
     @property
-    def timetz(self):
+    def timetz(self) -> np.ndarray:
         """
         Returns numpy array of datetime.time also containing timezone
         information. The time part of the Timestamps.
         """
         return ints_to_pydatetime(self.asi8, self.tz, box="time")
 
     @property
-    def date(self):
+    def date(self) -> np.ndarray:
         """
         Returns numpy array of python datetime.date objects (namely, the date
         part of Timestamps without timezone information).
@@ -1288,7 +1289,7 @@ def date(self):
 
         return ints_to_pydatetime(timestamps, box="date")
 
-    def isocalendar(self):
+    def isocalendar(self) -> DataFrame:
         """
         Returns a DataFrame with the year, week, and day calculated according to
         the ISO 8601 standard.
@@ -1871,7 +1872,7 @@ def weekofyear(self):
         """,
     )
 
-    def to_julian_date(self):
+    def to_julian_date(self) -> np.ndarray:
         """
         Convert Datetime Array to float64 ndarray of Julian Dates.
         0 Julian date is noon January 1, 4713 BC.

pandas/core/arrays/period.py

@@ -1072,11 +1072,10 @@ def dt64arr_to_periodarr(data, freq, tz=None):
         elif isinstance(data, ABCSeries):
             data, freq = data._values, data.dt.freq
 
-    freq = Period._maybe_convert_freq(freq)
-
-    if isinstance(data, (ABCIndex, ABCSeries)):
+    elif isinstance(data, (ABCIndex, ABCSeries)):
         data = data._values
 
+    freq = Period._maybe_convert_freq(freq)
     base = freq._period_dtype_code
     return c_dt64arr_to_periodarr(data.view("i8"), base, tz), freq
 
@@ -1138,7 +1137,7 @@ def _range_from_fields(
     minute=None,
     second=None,
     freq=None,
-):
+) -> tuple[np.ndarray, BaseOffset]:
     if hour is None:
         hour = 0
     if minute is None:
@@ -1176,7 +1175,7 @@ def _range_from_fields(
     return np.array(ordinals, dtype=np.int64), freq
 
 
-def _make_field_arrays(*fields):
+def _make_field_arrays(*fields) -> list[np.ndarray]:
     length = None
     for x in fields:
         if isinstance(x, (list, np.ndarray, ABCSeries)):

pandas/core/arrays/timedeltas.py

@@ -70,6 +70,7 @@
 from pandas.core.ops.common import unpack_zerodim_and_defer
 
 if TYPE_CHECKING:
+    from pandas import DataFrame
     from pandas.core.arrays import (
         DatetimeArray,
         PeriodArray,
@@ -880,14 +881,14 @@ def to_pytimedelta(self) -> np.ndarray:
     )
 
     @property
-    def components(self):
+    def components(self) -> DataFrame:
         """
         Return a dataframe of the components (days, hours, minutes,
         seconds, milliseconds, microseconds, nanoseconds) of the Timedeltas.
 
         Returns
         -------
-        a DataFrame
+        DataFrame
         """
         from pandas import DataFrame
 

pandas/core/indexes/timedeltas.py

@@ -40,12 +40,6 @@
 )
 @inherit_names(
     [
-        "_bool_ops",
-        "_object_ops",
-        "_field_ops",
-        "_datetimelike_ops",
-        "_datetimelike_methods",
-        "_other_ops",
         "components",
         "to_pytimedelta",
         "sum",
@@ -163,7 +157,7 @@ def _is_comparable_dtype(self, dtype: DtypeObj) -> bool:
         """
         Can we compare values of the given dtype to our own?
         """
-        return is_timedelta64_dtype(dtype)
+        return is_timedelta64_dtype(dtype)  # aka self._data._is_recognized_dtype
 
     # -------------------------------------------------------------------
     # Indexing Methods

pandas/tests/series/accessors/test_cat_accessor.py

@@ -6,17 +6,19 @@
 from pandas import (
     Categorical,
     DataFrame,
-    DatetimeIndex,
     Index,
     Series,
-    TimedeltaIndex,
     Timestamp,
     date_range,
     period_range,
     timedelta_range,
 )
 import pandas._testing as tm
-from pandas.core.arrays import PeriodArray
+from pandas.core.arrays import (
+    DatetimeArray,
+    PeriodArray,
+    TimedeltaArray,
+)
 from pandas.core.arrays.categorical import CategoricalAccessor
 from pandas.core.indexes.accessors import Properties
 
@@ -178,9 +180,9 @@ def test_dt_accessor_api_for_categorical(self):
         get_ops = lambda x: x._datetimelike_ops
 
         test_data = [
-            ("Datetime", get_ops(DatetimeIndex), s_dr, c_dr),
+            ("Datetime", get_ops(DatetimeArray), s_dr, c_dr),
             ("Period", get_ops(PeriodArray), s_pr, c_pr),
-            ("Timedelta", get_ops(TimedeltaIndex), s_tdr, c_tdr),
+            ("Timedelta", get_ops(TimedeltaArray), s_tdr, c_tdr),
         ]
 
         assert isinstance(c_dr.dt, Properties)

pandas/tests/series/accessors/test_dt_accessor.py

@@ -32,7 +32,10 @@
     timedelta_range,
 )
 import pandas._testing as tm
-from pandas.core.arrays import PeriodArray
+from pandas.core.arrays import (
+    PeriodArray,
+    TimedeltaArray,
+)
 import pandas.core.common as com
 
 
@@ -59,7 +62,7 @@ def test_dt_namespace_accessor(self):
             "month_name",
             "isocalendar",
         ]
-        ok_for_td = TimedeltaIndex._datetimelike_ops
+        ok_for_td = TimedeltaArray._datetimelike_ops
         ok_for_td_methods = [
             "components",
             "to_pytimedelta",