diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 3927b91fe05c0..3958b3fedb6b8 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -145,13 +145,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.util.hash_pandas_object \ pandas_object \ pandas.api.interchange.from_dataframe \ - pandas.Index.asof_locs \ - pandas.Index.get_slice_bound \ - pandas.RangeIndex \ - pandas.RangeIndex.start \ - pandas.RangeIndex.stop \ - pandas.RangeIndex.step \ - pandas.RangeIndex.from_range \ pandas.CategoricalIndex.codes \ pandas.CategoricalIndex.categories \ pandas.CategoricalIndex.ordered \ diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index d10a3888c5f75..f72c7b9512126 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -5670,14 +5670,14 @@ def asof_locs( """ Return the locations (indices) of labels in the index. - As in the `asof` function, if the label (a particular entry in - `where`) is not in the index, the latest index label up to the + As in the :meth:`pandas.Index.asof`, if the label (a particular entry in + ``where``) is not in the index, the latest index label up to the passed label is chosen and its index returned. - If all of the labels in the index are later than a label in `where`, + If all of the labels in the index are later than a label in ``where``, -1 is returned. - `mask` is used to ignore NA values in the index during calculation. + ``mask`` is used to ignore ``NA`` values in the index during calculation. Parameters ---------- @@ -5685,14 +5685,34 @@ def asof_locs( An Index consisting of an array of timestamps. mask : np.ndarray[bool] Array of booleans denoting where values in the original - data are not NA. + data are not ``NA``. Returns ------- np.ndarray[np.intp] - An array of locations (indices) of the labels from the Index - which correspond to the return values of the `asof` function - for every element in `where`. + An array of locations (indices) of the labels from the index + which correspond to the return values of :meth:`pandas.Index.asof` + for every element in ``where``. + + See Also + -------- + Index.asof : Return the label from the index, or, if not present, the + previous one. + + Examples + -------- + >>> idx = pd.date_range('2023-06-01', periods=3, freq='D') + >>> where = pd.DatetimeIndex(['2023-05-30 00:12:00', '2023-06-01 00:00:00', + ... '2023-06-02 23:59:59']) + >>> mask = np.ones(3, dtype=bool) + >>> idx.asof_locs(where, mask) + array([-1, 0, 1]) + + We can use ``mask`` to ignore certain values in the index during calculation. + + >>> mask[1] = False + >>> idx.asof_locs(where, mask) + array([-1, 0, 0]) """ # error: No overload variant of "searchsorted" of "ndarray" matches argument # types "Union[ExtensionArray, ndarray[Any, Any]]", "str" @@ -6627,6 +6647,27 @@ def get_slice_bound(self, label, side: Literal["left", "right"]) -> int: ------- int Index of label. + + See Also + -------- + Index.get_loc : Get integer location, slice or boolean mask for requested + label. + + Examples + -------- + >>> idx = pd.RangeIndex(5) + >>> idx.get_slice_bound(3, 'left') + 3 + + >>> idx.get_slice_bound(3, 'right') + 4 + + If ``label`` is non-unique in the index, an error will be raised. + + >>> idx_duplicate = pd.Index(['a', 'b', 'a', 'c', 'd']) + >>> idx_duplicate.get_slice_bound('a', 'left') + Traceback (most recent call last): + KeyError: Cannot get left slice bound for non-unique label: 'a' """ if side not in ("left", "right"): diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 8f50788604da0..2b0dc53a736ea 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -95,6 +95,26 @@ class RangeIndex(Index): See Also -------- Index : The base pandas Index type. + + Examples + -------- + >>> list(pd.RangeIndex(5)) + [0, 1, 2, 3, 4] + + >>> list(pd.RangeIndex(-2, 4)) + [-2, -1, 0, 1, 2, 3] + + >>> list(pd.RangeIndex(0, 10, 2)) + [0, 2, 4, 6, 8] + + >>> list(pd.RangeIndex(2, -10, -3)) + [2, -1, -4, -7] + + >>> list(pd.RangeIndex(0)) + [] + + >>> list(pd.RangeIndex(1, 0)) + [] """ _typ = "rangeindex" @@ -148,11 +168,19 @@ def __new__( @classmethod def from_range(cls, data: range, name=None, dtype: Dtype | None = None) -> Self: """ - Create RangeIndex from a range object. + Create :class:`pandas.RangeIndex` from a ``range`` object. Returns ------- RangeIndex + + Examples + -------- + >>> pd.RangeIndex.from_range(range(5)) + RangeIndex(start=0, stop=5, step=1) + + >>> pd.RangeIndex.from_range(range(2, -10, -3)) + RangeIndex(start=2, stop=-10, step=-3) """ if not isinstance(data, range): raise TypeError( @@ -252,6 +280,16 @@ def _format_with_header(self, header: list[str], na_rep: str) -> list[str]: def start(self) -> int: """ The value of the `start` parameter (``0`` if this was not supplied). + + Examples + -------- + >>> idx = pd.RangeIndex(5) + >>> idx.start + 0 + + >>> idx = pd.RangeIndex(2, -10, -3) + >>> idx.start + 2 """ # GH 25710 return self._range.start @@ -260,6 +298,16 @@ def start(self) -> int: def stop(self) -> int: """ The value of the `stop` parameter. + + Examples + -------- + >>> idx = pd.RangeIndex(5) + >>> idx.stop + 5 + + >>> idx = pd.RangeIndex(2, -10, -3) + >>> idx.stop + -10 """ return self._range.stop @@ -267,6 +315,23 @@ def stop(self) -> int: def step(self) -> int: """ The value of the `step` parameter (``1`` if this was not supplied). + + Examples + -------- + >>> idx = pd.RangeIndex(5) + >>> idx.step + 1 + + >>> idx = pd.RangeIndex(2, -10, -3) + >>> idx.step + -3 + + Even if :class:`pandas.RangeIndex` is empty, ``step`` is still ``1`` if + not supplied. + + >>> idx = pd.RangeIndex(1, 0) + >>> idx.step + 1 """ # GH 25710 return self._range.step