DOC: Fixing EX01 - Added more examples (pandas-dev#53528)

More examples

Author: DeaMariaLeon

ci/code_checks.sh

@@ -241,14 +241,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 \

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

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
 

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)