DOC: Fixed examples in pandas/core/indexes/ (#33208)

Author: ShaharNaveh

ci/code_checks.sh

@@ -278,6 +278,10 @@ if [[ -z "$CHECK" || "$CHECK" == "doctests" ]]; then
     pytest -q --doctest-modules pandas/core/groupby/groupby.py -k"-cumcount -describe -pipe"
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
+    MSG='Doctests indexes' ; echo $MSG
+    pytest -q --doctest-modules pandas/core/indexes/
+    RET=$(($RET + $?)) ; echo $MSG "DONE"
+
     MSG='Doctests tools' ; echo $MSG
     pytest -q --doctest-modules pandas/core/tools/
     RET=$(($RET + $?)) ; echo $MSG "DONE"
@@ -286,10 +290,6 @@ if [[ -z "$CHECK" || "$CHECK" == "doctests" ]]; then
     pytest -q --doctest-modules pandas/core/reshape/
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
-    MSG='Doctests interval classes' ; echo $MSG
-    pytest -q --doctest-modules pandas/core/indexes/interval.py
-    RET=$(($RET + $?)) ; echo $MSG "DONE"
-
     MSG='Doctests arrays'; echo $MSG
     pytest -q --doctest-modules pandas/core/arrays/
     RET=$(($RET + $?)) ; echo $MSG "DONE"

pandas/core/indexes/accessors.py

@@ -129,9 +129,41 @@ class DatetimeProperties(Properties):
 
     Examples
     --------
-    >>> s.dt.hour
-    >>> s.dt.second
-    >>> s.dt.quarter
+    >>> seconds_series = pd.Series(pd.date_range("2000-01-01", periods=3, freq="s"))
+    >>> seconds_series
+    0   2000-01-01 00:00:00
+    1   2000-01-01 00:00:01
+    2   2000-01-01 00:00:02
+    dtype: datetime64[ns]
+    >>> seconds_series.dt.second
+    0    0
+    1    1
+    2    2
+    dtype: int64
+
+    >>> hours_series = pd.Series(pd.date_range("2000-01-01", periods=3, freq="h"))
+    >>> hours_series
+    0   2000-01-01 00:00:00
+    1   2000-01-01 01:00:00
+    2   2000-01-01 02:00:00
+    dtype: datetime64[ns]
+    >>> hours_series.dt.hour
+    0    0
+    1    1
+    2    2
+    dtype: int64
+
+    >>> quarters_series = pd.Series(pd.date_range("2000-01-01", periods=3, freq="q"))
+    >>> quarters_series
+    0   2000-03-31
+    1   2000-06-30
+    2   2000-09-30
+    dtype: datetime64[ns]
+    >>> quarters_series.dt.quarter
+    0    1
+    1    2
+    2    3
+    dtype: int64
 
     Returns a Series indexed like the original Series.
     Raises TypeError if the Series does not contain datetimelike values.
@@ -200,13 +232,24 @@ class TimedeltaProperties(Properties):
     """
     Accessor object for datetimelike properties of the Series values.
 
-    Examples
-    --------
-    >>> s.dt.hours
-    >>> s.dt.seconds
-
     Returns a Series indexed like the original Series.
     Raises TypeError if the Series does not contain datetimelike values.
+
+    Examples
+    --------
+    >>> seconds_series = pd.Series(
+    ...     pd.timedelta_range(start="1 second", periods=3, freq="S")
+    ... )
+    >>> seconds_series
+    0   00:00:01
+    1   00:00:02
+    2   00:00:03
+    dtype: timedelta64[ns]
+    >>> seconds_series.dt.seconds
+    0    1
+    1    2
+    2    3
+    dtype: int64
     """
 
     def to_pytimedelta(self) -> np.ndarray:
@@ -229,7 +272,7 @@ def to_pytimedelta(self) -> np.ndarray:
 
         Examples
         --------
-        >>> s = pd.Series(pd.to_timedelta(np.arange(5), unit='d'))
+        >>> s = pd.Series(pd.to_timedelta(np.arange(5), unit="d"))
         >>> s
         0   0 days
         1   1 days
@@ -239,9 +282,9 @@ def to_pytimedelta(self) -> np.ndarray:
         dtype: timedelta64[ns]
 
         >>> s.dt.to_pytimedelta()
-        array([datetime.timedelta(0), datetime.timedelta(1),
-               datetime.timedelta(2), datetime.timedelta(3),
-               datetime.timedelta(4)], dtype=object)
+        array([datetime.timedelta(0), datetime.timedelta(days=1),
+        datetime.timedelta(days=2), datetime.timedelta(days=3),
+        datetime.timedelta(days=4)], dtype=object)
         """
         return self._get_values().to_pytimedelta()
 
@@ -289,14 +332,60 @@ class PeriodProperties(Properties):
     """
     Accessor object for datetimelike properties of the Series values.
 
-    Examples
-    --------
-    >>> s.dt.hour
-    >>> s.dt.second
-    >>> s.dt.quarter
-
     Returns a Series indexed like the original Series.
     Raises TypeError if the Series does not contain datetimelike values.
+
+    Examples
+    --------
+    >>> seconds_series = pd.Series(
+    ...     pd.period_range(
+    ...         start="2000-01-01 00:00:00", end="2000-01-01 00:00:03", freq="s"
+    ...     )
+    ... )
+    >>> seconds_series
+    0    2000-01-01 00:00:00
+    1    2000-01-01 00:00:01
+    2    2000-01-01 00:00:02
+    3    2000-01-01 00:00:03
+    dtype: period[S]
+    >>> seconds_series.dt.second
+    0    0
+    1    1
+    2    2
+    3    3
+    dtype: int64
+
+    >>> hours_series = pd.Series(
+    ...     pd.period_range(start="2000-01-01 00:00", end="2000-01-01 03:00", freq="h")
+    ... )
+    >>> hours_series
+    0    2000-01-01 00:00
+    1    2000-01-01 01:00
+    2    2000-01-01 02:00
+    3    2000-01-01 03:00
+    dtype: period[H]
+    >>> hours_series.dt.hour
+    0    0
+    1    1
+    2    2
+    3    3
+    dtype: int64
+
+    >>> quarters_series = pd.Series(
+    ...     pd.period_range(start="2000-01-01", end="2000-12-31", freq="Q-DEC")
+    ... )
+    >>> quarters_series
+    0    2000Q1
+    1    2000Q2
+    2    2000Q3
+    3    2000Q4
+    dtype: period[Q-DEC]
+    >>> quarters_series.dt.quarter
+    0    1
+    1    2
+    2    3
+    3    4
+    dtype: int64
     """
 
 

pandas/core/indexes/base.py

@@ -1841,7 +1841,7 @@ def is_object(self) -> bool:
 
         >>> idx = pd.Index(["Watermelon", "Orange", "Apple",
         ...                 "Watermelon"]).astype("category")
-        >>> idx.object()
+        >>> idx.is_object()
         False
 
         >>> idx = pd.Index([1.0, 2.0, 3.0, 4.0])
@@ -2053,7 +2053,7 @@ def isna(self):
         >>> idx
         Float64Index([5.2, 6.0, nan], dtype='float64')
         >>> idx.isna()
-        array([False, False,  True], dtype=bool)
+        array([False, False,  True])
 
         Empty strings are not considered NA values. None is considered an NA
         value.
@@ -2062,7 +2062,7 @@ def isna(self):
         >>> idx
         Index(['black', '', 'red', None], dtype='object')
         >>> idx.isna()
-        array([False, False, False,  True], dtype=bool)
+        array([False, False, False,  True])
 
         For datetimes, `NaT` (Not a Time) is considered as an NA value.
 
@@ -2072,7 +2072,7 @@ def isna(self):
         DatetimeIndex(['1940-04-25', 'NaT', 'NaT', 'NaT'],
                       dtype='datetime64[ns]', freq=None)
         >>> idx.isna()
-        array([False,  True,  True,  True], dtype=bool)
+        array([False,  True,  True,  True])
         """
         return self._isnan
 
@@ -4790,8 +4790,9 @@ def isin(self, values, level=None):
         ...                                  ['red', 'blue', 'green']],
         ...                                  names=('number', 'color'))
         >>> midx
-        MultiIndex(levels=[[1, 2, 3], ['blue', 'green', 'red']],
-                   codes=[[0, 1, 2], [2, 0, 1]],
+        MultiIndex([(1,   'red'),
+                    (2,  'blue'),
+                    (3, 'green')],
                    names=['number', 'color'])
 
         Check whether the strings in the 'color' level of the MultiIndex
@@ -4859,11 +4860,11 @@ def slice_indexer(self, start=None, end=None, step=None, kind=None):
 
         >>> idx = pd.Index(list('abcd'))
         >>> idx.slice_indexer(start='b', end='c')
-        slice(1, 3)
+        slice(1, 3, None)
 
         >>> idx = pd.MultiIndex.from_arrays([list('abcd'), list('efgh')])
         >>> idx.slice_indexer(start='b', end=('c', 'g'))
-        slice(1, 3)
+        slice(1, 3, None)
         """
         start_slice, end_slice = self.slice_locs(start, end, step=step, kind=kind)
 
@@ -5434,11 +5435,10 @@ def ensure_index_from_sequences(sequences, names=None):
 
     Examples
     --------
-    >>> ensure_index_from_sequences([[1, 2, 3]], names=['name'])
+    >>> ensure_index_from_sequences([[1, 2, 3]], names=["name"])
     Int64Index([1, 2, 3], dtype='int64', name='name')
 
-    >>> ensure_index_from_sequences([['a', 'a'], ['a', 'b']],
-                                    names=['L1', 'L2'])
+    >>> ensure_index_from_sequences([["a", "a"], ["a", "b"]], names=["L1", "L2"])
     MultiIndex([('a', 'a'),
                 ('a', 'b')],
                names=['L1', 'L2'])
@@ -5471,6 +5471,10 @@ def ensure_index(index_like, copy=False):
     -------
     index : Index or MultiIndex
 
+    See Also
+    --------
+    ensure_index_from_sequences
+
     Examples
     --------
     >>> ensure_index(['a', 'b'])
@@ -5481,13 +5485,8 @@ def ensure_index(index_like, copy=False):
 
     >>> ensure_index([['a', 'a'], ['b', 'c']])
     MultiIndex([('a', 'b'),
-                ('a', 'c')],
-               dtype='object')
-               )
-
-    See Also
-    --------
-    ensure_index_from_sequences
+            ('a', 'c')],
+           )
     """
     if isinstance(index_like, Index):
         if copy:

pandas/core/indexes/category.py

@@ -138,21 +138,25 @@ class CategoricalIndex(ExtensionIndex, accessor.PandasDelegate):
 
     Examples
     --------
-    >>> pd.CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'])
-    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['a', 'b', 'c'], ordered=False, dtype='category')  # noqa
+    >>> pd.CategoricalIndex(["a", "b", "c", "a", "b", "c"])
+    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
+                     categories=['a', 'b', 'c'], ordered=False, dtype='category')
 
     ``CategoricalIndex`` can also be instantiated from a ``Categorical``:
 
-    >>> c = pd.Categorical(['a', 'b', 'c', 'a', 'b', 'c'])
+    >>> c = pd.Categorical(["a", "b", "c", "a", "b", "c"])
     >>> pd.CategoricalIndex(c)
-    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['a', 'b', 'c'], ordered=False, dtype='category')  # noqa
+    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
+                     categories=['a', 'b', 'c'], ordered=False, dtype='category')
 
     Ordered ``CategoricalIndex`` can have a min and max value.
 
-    >>> ci = pd.CategoricalIndex(['a','b','c','a','b','c'], ordered=True,
-    ...                          categories=['c', 'b', 'a'])
+    >>> ci = pd.CategoricalIndex(
+    ...     ["a", "b", "c", "a", "b", "c"], ordered=True, categories=["c", "b", "a"]
+    ... )
     >>> ci
-    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['c', 'b', 'a'], ordered=True, dtype='category')  # noqa
+    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
+                     categories=['c', 'b', 'a'], ordered=True, dtype='category')
     >>> ci.min()
     'c'
     """
@@ -652,7 +656,7 @@ def map(self, mapper):
         >>> idx = pd.CategoricalIndex(['a', 'b', 'c'])
         >>> idx
         CategoricalIndex(['a', 'b', 'c'], categories=['a', 'b', 'c'],
-                         ordered=False, dtype='category')
+                          ordered=False, dtype='category')
         >>> idx.map(lambda x: x.upper())
         CategoricalIndex(['A', 'B', 'C'], categories=['A', 'B', 'C'],
                          ordered=False, dtype='category')