diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 4962469dbf429..1a79e99966396 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -250,14 +250,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.DatetimeIndex.mean \ pandas.DatetimeIndex.std \ pandas.TimedeltaIndex \ - pandas.TimedeltaIndex.seconds \ - pandas.TimedeltaIndex.microseconds \ - pandas.TimedeltaIndex.nanoseconds \ - pandas.TimedeltaIndex.components \ - pandas.TimedeltaIndex.inferred_freq \ - pandas.TimedeltaIndex.as_unit \ - pandas.TimedeltaIndex.to_pytimedelta \ - pandas.TimedeltaIndex.mean \ pandas.core.window.rolling.Rolling.max \ pandas.core.window.rolling.Rolling.cov \ pandas.core.window.rolling.Rolling.skew \ diff --git a/pandas/core/arrays/datetimelike.py b/pandas/core/arrays/datetimelike.py index c3c0608a766db..8c57496e092c4 100644 --- a/pandas/core/arrays/datetimelike.py +++ b/pandas/core/arrays/datetimelike.py @@ -861,9 +861,20 @@ def inferred_freq(self) -> str | None: Examples -------- + For DatetimeIndex: + >>> idx = pd.DatetimeIndex(["2018-01-01", "2018-01-03", "2018-01-05"]) >>> idx.inferred_freq '2D' + + For TimedeltaIndex: + + >>> tdelta_idx = pd.to_timedelta(["0 days", "10 days", "20 days"]) + >>> tdelta_idx + TimedeltaIndex(['0 days', '10 days', '20 days'], + dtype='timedelta64[ns]', freq=None) + >>> tdelta_idx.inferred_freq + '10D' """ if self.ndim != 1: return None @@ -1535,6 +1546,15 @@ def mean(self, *, skipna: bool = True, axis: AxisInt | None = 0): Notes ----- mean is only defined for Datetime and Timedelta dtypes, not for Period. + + Examples + -------- + >>> tdelta_idx = pd.to_timedelta([1, 2, 3], unit='D') + >>> tdelta_idx + TimedeltaIndex(['1 days', '2 days', '3 days'], + dtype='timedelta64[ns]', freq=None) + >>> tdelta_idx.mean() + Timedelta('2 days 00:00:00') """ if isinstance(self.dtype, PeriodDtype): # See discussion in GH#24757 diff --git a/pandas/core/arrays/timedeltas.py b/pandas/core/arrays/timedeltas.py index 0a28de0b27549..bf62c327de2f0 100644 --- a/pandas/core/arrays/timedeltas.py +++ b/pandas/core/arrays/timedeltas.py @@ -796,6 +796,16 @@ def to_pytimedelta(self) -> npt.NDArray[np.object_]: Returns ------- numpy.ndarray + + Examples + -------- + >>> tdelta_idx = pd.to_timedelta([1, 2, 3], unit='D') + >>> tdelta_idx + TimedeltaIndex(['1 days', '2 days', '3 days'], + dtype='timedelta64[ns]', freq=None) + >>> tdelta_idx.to_pytimedelta() + array([datetime.timedelta(days=1), datetime.timedelta(days=2), + datetime.timedelta(days=3)], dtype=object) """ return ints_to_pytimedelta(self._ndarray) @@ -804,6 +814,8 @@ def to_pytimedelta(self) -> npt.NDArray[np.object_]: Examples -------- + For Series: + >>> ser = pd.Series(pd.to_timedelta([1, 2, 3], unit='d')) >>> ser 0 1 days @@ -814,7 +826,16 @@ def to_pytimedelta(self) -> npt.NDArray[np.object_]: 0 1 1 2 2 3 - dtype: int64""" + dtype: int64 + + For TimedeltaIndex: + + >>> tdelta_idx = pd.to_timedelta(["0 days", "10 days", "20 days"]) + >>> tdelta_idx + TimedeltaIndex(['0 days', '10 days', '20 days'], + dtype='timedelta64[ns]', freq=None) + >>> tdelta_idx.days + Index([0, 10, 20], dtype='int64')""" ) days = _field_accessor("days", "days", days_docstring) @@ -823,6 +844,8 @@ def to_pytimedelta(self) -> npt.NDArray[np.object_]: Examples -------- + For Series: + >>> ser = pd.Series(pd.to_timedelta([1, 2, 3], unit='S')) >>> ser 0 0 days 00:00:01 @@ -833,7 +856,16 @@ def to_pytimedelta(self) -> npt.NDArray[np.object_]: 0 1 1 2 2 3 - dtype: int32""" + dtype: int32 + + For TimedeltaIndex: + + >>> tdelta_idx = pd.to_timedelta([1, 2, 3], unit='S') + >>> tdelta_idx + TimedeltaIndex(['0 days 00:00:01', '0 days 00:00:02', '0 days 00:00:03'], + dtype='timedelta64[ns]', freq=None) + >>> tdelta_idx.seconds + Index([1, 2, 3], dtype='int32')""" ) seconds = _field_accessor( "seconds", @@ -846,6 +878,8 @@ def to_pytimedelta(self) -> npt.NDArray[np.object_]: Examples -------- + For Series: + >>> ser = pd.Series(pd.to_timedelta([1, 2, 3], unit='U')) >>> ser 0 0 days 00:00:00.000001 @@ -856,7 +890,17 @@ def to_pytimedelta(self) -> npt.NDArray[np.object_]: 0 1 1 2 2 3 - dtype: int32""" + dtype: int32 + + For TimedeltaIndex: + + >>> tdelta_idx = pd.to_timedelta([1, 2, 3], unit='U') + >>> tdelta_idx + TimedeltaIndex(['0 days 00:00:00.000001', '0 days 00:00:00.000002', + '0 days 00:00:00.000003'], + dtype='timedelta64[ns]', freq=None) + >>> tdelta_idx.microseconds + Index([1, 2, 3], dtype='int32')""" ) microseconds = _field_accessor( "microseconds", @@ -869,6 +913,8 @@ def to_pytimedelta(self) -> npt.NDArray[np.object_]: Examples -------- + For Series: + >>> ser = pd.Series(pd.to_timedelta([1, 2, 3], unit='N')) >>> ser 0 0 days 00:00:00.000000001 @@ -879,7 +925,17 @@ def to_pytimedelta(self) -> npt.NDArray[np.object_]: 0 1 1 2 2 3 - dtype: int32""" + dtype: int32 + + For TimedeltaIndex: + + >>> tdelta_idx = pd.to_timedelta([1, 2, 3], unit='N') + >>> tdelta_idx + TimedeltaIndex(['0 days 00:00:00.000000001', '0 days 00:00:00.000000002', + '0 days 00:00:00.000000003'], + dtype='timedelta64[ns]', freq=None) + >>> tdelta_idx.nanoseconds + Index([1, 2, 3], dtype='int32')""" ) nanoseconds = _field_accessor( "nanoseconds", @@ -898,6 +954,16 @@ def components(self) -> DataFrame: Returns ------- DataFrame + + Examples + -------- + >>> tdelta_idx = pd.to_timedelta(['1 day 3 min 2 us 42 ns']) + >>> tdelta_idx + TimedeltaIndex(['1 days 00:03:00.000002042'], + dtype='timedelta64[ns]', freq=None) + >>> tdelta_idx.components + days hours minutes seconds milliseconds microseconds nanoseconds + 0 1 0 3 0 0 2 42 """ from pandas import DataFrame diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index 73535f0a57199..d818e1e862c12 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/pandas/core/indexes/datetimelike.py @@ -431,6 +431,15 @@ def as_unit(self, unit: str) -> Self: Returns ------- same type as self + + Examples + -------- + >>> tdelta_idx = pd.to_timedelta(['1 day 3 min 2 us 42 ns']) + >>> tdelta_idx + TimedeltaIndex(['1 days 00:03:00.000002042'], + dtype='timedelta64[ns]', freq=None) + >>> tdelta_idx.as_unit('s') + TimedeltaIndex(['1 days 00:03:00'], dtype='timedelta64[s]', freq=None) """ arr = self._data.as_unit(unit) return type(self)._simple_new(arr, name=self.name)