From f3028a815f9aad82de8709b78fbaee7d86eb363a Mon Sep 17 00:00:00 2001 From: Charlie-XIAO Date: Thu, 29 Jun 2023 09:52:51 +0800 Subject: [PATCH 01/11] Example for pd.Index.asof_locs --- pandas/core/indexes/base.py | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index d10a3888c5f75..29ee58816f18a 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,30 @@ 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``. + + Examples + -------- + >>> import numpy as np + >>> 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], dtype=int64) + + 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], dtype=int64) """ # error: No overload variant of "searchsorted" of "ndarray" matches argument # types "Union[ExtensionArray, ndarray[Any, Any]]", "str" From 18b109afd92fceca664b014f71b0ac60eb13fc10 Mon Sep 17 00:00:00 2001 From: Charlie-XIAO Date: Thu, 29 Jun 2023 10:27:18 +0800 Subject: [PATCH 02/11] Example for pd.Index.get_slice_bound --- ci/code_checks.sh | 2 -- pandas/core/indexes/base.py | 32 ++++++++++++++++++++++++++++---- 2 files changed, 28 insertions(+), 6 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 3927b91fe05c0..97b89dd214588 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -145,8 +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 \ diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 29ee58816f18a..ee86a579df93e 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -5694,12 +5694,16 @@ def asof_locs( 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 -------- - >>> import numpy as np - >>> 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"]) + >>> 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], dtype=int64) @@ -6643,6 +6647,26 @@ 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"): From 737a9036983fa0e49bd066cf794d75d31117f070 Mon Sep 17 00:00:00 2001 From: Charlie-XIAO Date: Thu, 29 Jun 2023 10:39:32 +0800 Subject: [PATCH 03/11] Example for pd.RangeIndex --- pandas/core/indexes/base.py | 1 + pandas/core/indexes/range.py | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index ee86a579df93e..262760805fee0 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -6658,6 +6658,7 @@ def get_slice_bound(self, label, side: Literal["left", "right"]) -> int: >>> idx = pd.RangeIndex(5) >>> idx.get_slice_bound(3, 'left') 3 + >>> idx.get_slice_bound(3, 'right') 4 diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 8f50788604da0..deaf38af65e62 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" From 0cc88672907588b8d666500e4e5fba6ad55a3aae Mon Sep 17 00:00:00 2001 From: Charlie-XIAO Date: Thu, 29 Jun 2023 10:48:30 +0800 Subject: [PATCH 04/11] Example for pd.RangeIndex.start/stop/step --- ci/code_checks.sh | 4 ---- pandas/core/indexes/range.py | 37 ++++++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 4 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 97b89dd214588..733d7f9cacf2d 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -145,10 +145,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.util.hash_pandas_object \ pandas_object \ pandas.api.interchange.from_dataframe \ - pandas.RangeIndex \ - pandas.RangeIndex.start \ - pandas.RangeIndex.stop \ - pandas.RangeIndex.step \ pandas.RangeIndex.from_range \ pandas.CategoricalIndex.codes \ pandas.CategoricalIndex.categories \ diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index deaf38af65e62..7f8314809ab1c 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -272,6 +272,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 @@ -280,6 +290,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 @@ -287,6 +307,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 From e3bdf0d33c10155b8df6d37cb4f9fcb332c98662 Mon Sep 17 00:00:00 2001 From: Charlie-XIAO Date: Thu, 29 Jun 2023 10:54:13 +0800 Subject: [PATCH 05/11] Example for pd.RangeIndex.from_range --- pandas/core/indexes/range.py | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 7f8314809ab1c..75b126faf8611 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -168,11 +168,22 @@ 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(range(start, stop[, step]))`` is equivalent to + ``pd.RangeIndex(start, stop[, step])``. + + >>> pd.RangeIndex(range(5)) + RangeIndex(start=0, stop=5, step=1) + + >>> pd.RangeIndex(range(2, -10, -3)) + RangeIndex(start=2, stop=-10, step=-3) """ if not isinstance(data, range): raise TypeError( From 78490db4458c5bd8ad5a15900d0a62c3906f7bd6 Mon Sep 17 00:00:00 2001 From: Charlie-XIAO Date: Thu, 29 Jun 2023 10:55:11 +0800 Subject: [PATCH 06/11] cleanup for now --- ci/code_checks.sh | 1 - 1 file changed, 1 deletion(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 733d7f9cacf2d..3958b3fedb6b8 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -145,7 +145,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.util.hash_pandas_object \ pandas_object \ pandas.api.interchange.from_dataframe \ - pandas.RangeIndex.from_range \ pandas.CategoricalIndex.codes \ pandas.CategoricalIndex.categories \ pandas.CategoricalIndex.ordered \ From ee57857227ce6841b7adcb2626c027915a2ab712 Mon Sep 17 00:00:00 2001 From: Charlie-XIAO Date: Thu, 29 Jun 2023 12:35:01 +0800 Subject: [PATCH 07/11] fix doctest --- pandas/core/indexes/base.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 262760805fee0..f72c7b9512126 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -5706,13 +5706,13 @@ def asof_locs( ... '2023-06-02 23:59:59']) >>> mask = np.ones(3, dtype=bool) >>> idx.asof_locs(where, mask) - array([-1, 0, 1], dtype=int64) + 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], dtype=int64) + array([-1, 0, 0]) """ # error: No overload variant of "searchsorted" of "ndarray" matches argument # types "Union[ExtensionArray, ndarray[Any, Any]]", "str" From 2e901f202f887ba61f2887eaa1730a671205f241 Mon Sep 17 00:00:00 2001 From: Charlie-XIAO Date: Thu, 29 Jun 2023 14:21:58 +0800 Subject: [PATCH 08/11] example for RangeIndex.from_range is wrong --- pandas/core/indexes/range.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 75b126faf8611..2b0dc53a736ea 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -176,13 +176,10 @@ def from_range(cls, data: range, name=None, dtype: Dtype | None = None) -> Self: Examples -------- - ``pd.RangeIndex(range(start, stop[, step]))`` is equivalent to - ``pd.RangeIndex(start, stop[, step])``. - - >>> pd.RangeIndex(range(5)) + >>> pd.RangeIndex.from_range(range(5)) RangeIndex(start=0, stop=5, step=1) - >>> pd.RangeIndex(range(2, -10, -3)) + >>> pd.RangeIndex.from_range(range(2, -10, -3)) RangeIndex(start=2, stop=-10, step=-3) """ if not isinstance(data, range): From a317b5b5d2b498e182df6c5def3929cb2ca8fd5b Mon Sep 17 00:00:00 2001 From: Charlie-XIAO Date: Thu, 29 Jun 2023 14:30:12 +0800 Subject: [PATCH 09/11] retrigger checks From 46cb303e427b2c71ad567850cf4c3f9ed06eaf70 Mon Sep 17 00:00:00 2001 From: Charlie-XIAO Date: Thu, 29 Jun 2023 15:15:58 +0800 Subject: [PATCH 10/11] retrigger checks From 6f216c1bad12a54387d69608fef7c75d673c1179 Mon Sep 17 00:00:00 2001 From: Charlie-XIAO Date: Thu, 29 Jun 2023 17:34:15 +0800 Subject: [PATCH 11/11] retrigger checks