dt.time

Author: jbrockmendel

pandas/core/arrays/datetimes.py

@@ -15,6 +15,8 @@
 
 import numpy as np
 
+from pandas._config import get_option
+
 from pandas._libs import (
     lib,
     tslib,
@@ -1342,7 +1344,32 @@ def time(self) -> npt.NDArray[np.object_]:
         # keeping their timezone and not using UTC
         timestamps = self._local_timestamps()
 
-        return ints_to_pydatetime(timestamps, box="time", reso=self._creso)
+        result = ints_to_pydatetime(timestamps, box="time", reso=self._creso)
+
+        opt = get_option("future.infer_time")
+        if opt is None:
+            warnings.warn(
+                f"The behavior of {type(self).__name__}.time is deprecated. "
+                "In a future version, this will an array with pyarrow time "
+                "dtype instead of object dtype. To opt in to the future behavior, "
+                "set `pd.set_option('future.infer_time', True)`.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        elif opt is True:
+            # TODO: optimize this to avoid going through ints_to_pydatetime
+            import pyarrow as pa
+
+            from pandas.core.arrays.arrow import ArrowDtype
+
+            pa_type = pa.time64(self.unit)
+            result[self.isna()] = None
+            obj = pa.array(result, type=pa_type)
+            dtype = ArrowDtype(obj.type)
+            out = dtype.construct_array_type()(obj)
+            return out
+
+        return result
 
     @property
     def timetz(self) -> npt.NDArray[np.object_]:

pandas/core/indexes/accessors.py

@@ -101,8 +101,6 @@ def _delegate_property_get(self, name: str):  # type: ignore[override]
         elif not is_list_like(result):
             return result
 
-        result = np.asarray(result)
-
         if self.orig is not None:
             index = self.orig.index
         else:

pandas/tests/arrays/test_datetimes.py

@@ -155,8 +155,14 @@ def test_to_pydatetime(self, dta_dti):
     def test_time_date(self, dta_dti, meth):
         dta, dti = dta_dti
 
-        result = getattr(dta, meth)
-        expected = getattr(dti, meth)
+        warn = None
+        msg = "In a future version, this will an array with pyarrow time dtype"
+        if meth == "time":
+            warn = FutureWarning
+
+        with tm.assert_produces_warning(warn, match=msg):
+            result = getattr(dta, meth)
+            expected = getattr(dti, meth)
         tm.assert_numpy_array_equal(result, expected)
 
     def test_format_native_types(self, unit, dtype, dta_dti):

pandas/tests/generic/test_finalize.py

@@ -8,6 +8,7 @@
 import pytest
 
 import pandas as pd
+import pandas._testing as tm
 
 # TODO:
 # * Binary methods (mul, div, etc.)
@@ -681,7 +682,14 @@ def test_datetime_method(method):
 def test_datetime_property(attr):
     s = pd.Series(pd.date_range("2000", periods=4))
     s.attrs = {"a": 1}
-    result = getattr(s.dt, attr)
+
+    warn = None
+    msg = "In a future version, this will an array with pyarrow time dtype"
+    if attr == "time":
+        warn = FutureWarning
+    with tm.assert_produces_warning(warn, match=msg):
+        result = getattr(s.dt, attr)
+
     assert result.attrs == {"a": 1}
 
 

pandas/tests/indexes/datetimes/test_scalar_compat.py

@@ -24,7 +24,9 @@
 class TestDatetimeIndexOps:
     def test_dti_time(self):
         rng = date_range("1/1/2000", freq="12min", periods=10)
-        result = pd.Index(rng).time
+        msg = "In a future version, this will an array with pyarrow time dtype"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            result = pd.Index(rng).time
         expected = [t.time() for t in rng]
         assert (result == expected).all()
 

pandas/tests/indexes/datetimes/test_timezones.py

@@ -853,7 +853,10 @@ def test_time_accessor(self, dtype):
         expected = np.array([time(10, 20, 30), pd.NaT])
 
         index = DatetimeIndex(["2018-06-04 10:20:30", pd.NaT], dtype=dtype)
-        result = index.time
+
+        msg = "In a future version, this will an array with pyarrow time dtype"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            result = index.time
 
         tm.assert_numpy_array_equal(result, expected)
 

pandas/tests/io/parser/test_parse_dates.py

@@ -479,7 +479,9 @@ def test_date_col_as_index_col(all_parsers):
     if parser.engine == "pyarrow":
         # https://github.com/pandas-dev/pandas/issues/44231
         # pyarrow 6.0 starts to infer time type
-        expected["X2"] = pd.to_datetime("1970-01-01" + expected["X2"]).dt.time
+        msg = "In a future version, this will an array with pyarrow time dtype"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            expected["X2"] = pd.to_datetime("1970-01-01" + expected["X2"]).dt.time
 
     tm.assert_frame_equal(result, expected)
 

pandas/tests/series/accessors/test_cat_accessor.py

@@ -212,8 +212,12 @@ def test_dt_accessor_api_for_categorical(self, idx):
             tm.assert_equal(res, exp)
 
         for attr in attr_names:
-            res = getattr(cat.dt, attr)
-            exp = getattr(ser.dt, attr)
+            with warnings.catch_warnings():
+                if attr == "time":
+                    # deprecated to return pyarrow time dtype
+                    warnings.simplefilter("ignore", FutureWarning)
+                res = getattr(cat.dt, attr)
+                exp = getattr(ser.dt, attr)
 
             tm.assert_equal(res, exp)
 

pandas/tests/series/accessors/test_dt_accessor.py

@@ -12,6 +12,7 @@
 import pytz
 
 from pandas._libs.tslibs.timezones import maybe_get_tz
+from pandas.compat import pa_version_under7p0
 from pandas.errors import SettingWithCopyError
 
 from pandas.core.dtypes.common import (
@@ -89,8 +90,15 @@ def get_expected(ser, prop):
                 return result
             return Series(result, index=ser.index, name=ser.name, dtype=result.dtype)
 
-        left = getattr(ser.dt, name)
-        right = get_expected(ser, name)
+        if name == "time":
+            msg = "In a future version, this will an array with pyarrow time dtype"
+            with tm.assert_produces_warning(FutureWarning, match=msg):
+                left = getattr(ser.dt, name)
+                right = get_expected(ser, name)
+        else:
+            left = getattr(ser.dt, name)
+            right = get_expected(ser, name)
+
         if not (is_list_like(left) and is_list_like(right)):
             assert left == right
         elif isinstance(left, DataFrame):
@@ -672,10 +680,31 @@ def test_valid_dt_with_missing_values(self):
         )
         tm.assert_series_equal(result, expected)
 
-        result = ser.dt.time
+        msg = "In a future version, this will an array with pyarrow time"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            result = ser.dt.time
         expected = Series([time(0), time(0), np.nan, time(0), time(0)], dtype="object")
         tm.assert_series_equal(result, expected)
 
+        with pd.option_context("future.infer_time", False):
+            with tm.assert_produces_warning(None):
+                result = ser.dt.time
+        tm.assert_series_equal(result, expected)
+
+        if pa_version_under7p0:
+            return
+
+        with pd.option_context("future.infer_time", True):
+            with tm.assert_produces_warning(None):
+                result_pa = ser.dt.time
+
+        import pyarrow as pa
+
+        pa_dtype = pa.time64("ns")
+        dtype = pd.ArrowDtype(pa_dtype)
+        expected_pa = expected.astype(dtype)
+        tm.assert_series_equal(result_pa, expected_pa)
+
     def test_dt_accessor_api(self):
         # GH 9322
         from pandas.core.indexes.accessors import (