DOC: Fixing EX01 - Added examples (#53450)

Added examples

Author: DeaMariaLeon

ci/code_checks.sh

@@ -258,17 +258,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         pandas.IntervalIndex.to_tuples \
         pandas.MultiIndex.dtypes \
         pandas.MultiIndex.drop \
-        pandas.DatetimeIndex \
-        pandas.DatetimeIndex.date \
-        pandas.DatetimeIndex.time \
-        pandas.DatetimeIndex.timetz \
-        pandas.DatetimeIndex.dayofyear \
-        pandas.DatetimeIndex.day_of_year \
-        pandas.DatetimeIndex.quarter \
-        pandas.DatetimeIndex.tz \
-        pandas.DatetimeIndex.freqstr \
-        pandas.DatetimeIndex.inferred_freq \
-        pandas.DatetimeIndex.indexer_at_time \
         pandas.DatetimeIndex.indexer_between_time \
         pandas.DatetimeIndex.snap \
         pandas.DatetimeIndex.as_unit \
@@ -277,7 +266,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         pandas.DatetimeIndex.mean \
         pandas.DatetimeIndex.std \
         pandas.TimedeltaIndex \
-        pandas.TimedeltaIndex.days \
         pandas.TimedeltaIndex.seconds \
         pandas.TimedeltaIndex.microseconds \
         pandas.TimedeltaIndex.nanoseconds \

pandas/core/arrays/datetimelike.py

@@ -825,7 +825,20 @@ def _maybe_mask_results(
     @property
     def freqstr(self) -> str | None:
         """
-        Return the frequency object as a string if its set, otherwise None.
+        Return the frequency object as a string if it's set, otherwise None.
+
+        Examples
+        --------
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00"], freq="D")
+        >>> idx.freqstr
+        'D'
+
+        The frequency can be inferred if there are more than 2 points:
+
+        >>> idx = pd.DatetimeIndex(["2018-01-01", "2018-01-03", "2018-01-05"],
+        ...                        freq="infer")
+        >>> idx.freqstr
+        '2D'
         """
         if self.freq is None:
             return None
@@ -837,6 +850,12 @@ def inferred_freq(self) -> str | None:
         Tries to return a string representing a frequency generated by infer_freq.
 
         Returns None if it can't autodetect the frequency.
+
+        Examples
+        --------
+        >>> idx = pd.DatetimeIndex(["2018-01-01", "2018-01-03", "2018-01-05"])
+        >>> idx.inferred_freq
+        '2D'
         """
         if self.ndim != 1:
             return None

pandas/core/arrays/datetimes.py

@@ -567,6 +567,8 @@ def tz(self) -> tzinfo | None:
 
         Examples
         --------
+        For Series:
+
         >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
         >>> s = pd.to_datetime(s)
         >>> s
@@ -575,6 +577,13 @@ def tz(self) -> tzinfo | None:
         dtype: datetime64[ns, UTC]
         >>> s.dt.tz
         datetime.timezone.utc
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.tz
+        datetime.timezone.utc
         """
         # GH 18595
         return getattr(self.dtype, "tz", None)
@@ -1326,6 +1335,8 @@ def time(self) -> npt.NDArray[np.object_]:
 
         Examples
         --------
+        For Series:
+
         >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
         >>> s = pd.to_datetime(s)
         >>> s
@@ -1336,6 +1347,13 @@ def time(self) -> npt.NDArray[np.object_]:
         0    10:00:00
         1    11:00:00
         dtype: object
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.time
+        array([datetime.time(10, 0), datetime.time(11, 0)], dtype=object)
         """
         # If the Timestamps have a timezone that is not UTC,
         # convert them into their i8 representation while
@@ -1353,6 +1371,8 @@ def timetz(self) -> npt.NDArray[np.object_]:
 
         Examples
         --------
+        For Series:
+
         >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
         >>> s = pd.to_datetime(s)
         >>> s
@@ -1363,6 +1383,14 @@ def timetz(self) -> npt.NDArray[np.object_]:
         0    10:00:00+00:00
         1    11:00:00+00:00
         dtype: object
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.timetz
+        array([datetime.time(10, 0, tzinfo=datetime.timezone.utc),
+        datetime.time(11, 0, tzinfo=datetime.timezone.utc)], dtype=object)
         """
         return ints_to_pydatetime(self.asi8, self.tz, box="time", reso=self._creso)
 
@@ -1376,6 +1404,8 @@ def date(self) -> npt.NDArray[np.object_]:
 
         Examples
         --------
+        For Series:
+
         >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
         >>> s = pd.to_datetime(s)
         >>> s
@@ -1386,6 +1416,13 @@ def date(self) -> npt.NDArray[np.object_]:
         0    2020-01-01
         1    2020-02-01
         dtype: object
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.date
+        array([datetime.date(2020, 1, 1), datetime.date(2020, 2, 1)], dtype=object)
         """
         # If the Timestamps have a timezone that is not UTC,
         # convert them into their i8 representation while
@@ -1667,6 +1704,8 @@ def isocalendar(self) -> DataFrame:
 
         Examples
         --------
+        For Series:
+
         >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
         >>> s = pd.to_datetime(s)
         >>> s
@@ -1677,6 +1716,13 @@ def isocalendar(self) -> DataFrame:
         0    1
         1   32
         dtype: int32
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.dayofyear
+        Index([1, 32], dtype='int32')
         """,
     )
     dayofyear = day_of_year
@@ -1688,6 +1734,8 @@ def isocalendar(self) -> DataFrame:
 
         Examples
         --------
+        For Series:
+
         >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "4/1/2020 11:00:00+00:00"])
         >>> s = pd.to_datetime(s)
         >>> s
@@ -1698,6 +1746,13 @@ def isocalendar(self) -> DataFrame:
         0    1
         1    2
         dtype: int32
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.quarter
+        Index([1, 1], dtype='int32')
         """,
     )
     days_in_month = _field_accessor(

pandas/core/arrays/period.py

@@ -431,6 +431,12 @@ def __arrow_array__(self, type=None):
         "day",
         """
         The days of the period.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(['2020-01-31', '2020-02-28'], freq='D')
+        >>> idx.day
+        Index([31, 28], dtype='int64')
         """,
     )
     hour = _field_accessor(

pandas/core/indexes/datetimes.py

@@ -248,6 +248,13 @@ class DatetimeIndex(DatetimeTimedeltaMixin):
     -----
     To learn more about the frequency strings, please see `this link
     <https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases>`__.
+
+    Examples
+    --------
+    >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
+    >>> idx
+    DatetimeIndex(['2020-01-01 10:00:00+00:00', '2020-02-01 11:00:00+00:00'],
+    dtype='datetime64[ns, UTC]', freq=None)
     """
 
     _typ = "datetimeindex"
@@ -709,6 +716,13 @@ def indexer_at_time(self, time, asof: bool = False) -> npt.NDArray[np.intp]:
         indexer_between_time : Get index locations of values between particular
             times of day.
         DataFrame.at_time : Select values at particular time of day.
+
+        Examples
+        --------
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00", "2/1/2020 11:00",
+        ...                         "3/1/2020 10:00"])
+        >>> idx.indexer_at_time("10:00")
+        array([0, 2])
         """
         if asof:
             raise NotImplementedError("'asof' argument is not supported")