From 30676a5a6f7206e6d039d11a225d1d009ebf9766 Mon Sep 17 00:00:00 2001 From: mateomramos Date: Wed, 22 Oct 2025 14:50:42 -0400 Subject: [PATCH 1/4] DOC: Replace @Appender decorator with inline docstrings for Index.take, Index.repeat, and Index.get_indexer_non_unique --- pandas/core/indexes/base.py | 54 +++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 30 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index c716bd4e636bd..e71c28f6dc194 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -71,7 +71,7 @@ InvalidIndexError, ) from pandas.util._decorators import ( - Appender, + Appender cache_readonly, doc, set_module, @@ -1170,8 +1170,16 @@ def astype(self, dtype: Dtype, copy: bool = True): result._references.add_index_reference(result) return result - _index_shared_docs["take"] = """ - Return a new %(klass)s of the values selected by the indices. + def take( + self, + indices, + axis: Axis = 0, + allow_fill: bool = True, + fill_value=None, + **kwargs, + ) -> Self: + """ + Return a new Index of the values selected by the indices. For internal compatibility with numpy arrays. @@ -1189,7 +1197,7 @@ def astype(self, dtype: Dtype, copy: bool = True): :func:`numpy.take`. * True: negative values in `indices` indicate - missing values. These values are set to `fill_value`. Any other + missing values. These values are set to `fill_value`. Any other negative values raise a ``ValueError``. fill_value : scalar, default None @@ -1215,16 +1223,6 @@ def astype(self, dtype: Dtype, copy: bool = True): >>> idx.take([2, 2, 1, 2]) Index(['c', 'c', 'b', 'c'], dtype='str') """ - - @Appender(_index_shared_docs["take"] % _index_doc_kwargs) - def take( - self, - indices, - axis: Axis = 0, - allow_fill: bool = True, - fill_value=None, - **kwargs, - ) -> Self: if kwargs: nv.validate_take((), kwargs) if is_scalar(indices): @@ -1272,10 +1270,11 @@ def _maybe_disallow_fill(self, allow_fill: bool, fill_value, indices) -> bool: allow_fill = False return allow_fill - _index_shared_docs["repeat"] = """ - Repeat elements of a %(klass)s. + def repeat(self, repeats, axis: None = None) -> Self: + """ + Repeat elements of a Index. - Returns a new %(klass)s where each element of the current %(klass)s + Returns a new Index where each element of the current Index is repeated consecutively a given number of times. Parameters @@ -1283,15 +1282,15 @@ def _maybe_disallow_fill(self, allow_fill: bool, fill_value, indices) -> bool: repeats : int or array of ints The number of repetitions for each element. This should be a non-negative integer. Repeating 0 times will return an empty - %(klass)s. + Index. axis : None Must be ``None``. Has no effect but is accepted for compatibility with numpy. Returns ------- - %(klass)s - Newly created %(klass)s with repeated elements. + Index + Newly created Index with repeated elements. See Also -------- @@ -1308,9 +1307,6 @@ def _maybe_disallow_fill(self, allow_fill: bool, fill_value, indices) -> bool: >>> idx.repeat([1, 2, 3]) Index(['a', 'b', 'b', 'c', 'c', 'c'], dtype='object') """ - - @Appender(_index_shared_docs["repeat"] % _index_doc_kwargs) - def repeat(self, repeats, axis: None = None) -> Self: repeats = ensure_platform_int(repeats) nv.validate_repeat((), {"axis": axis}) res_values = self._values.repeat(repeats) @@ -5940,7 +5936,10 @@ def _should_fallback_to_positional(self) -> bool: "complex", } - _index_shared_docs["get_indexer_non_unique"] = """ + def get_indexer_non_unique( + self, target + ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: + """ Compute indexer and mask for new index given the current index. The indexer should be then used as an input to ndarray.take to align the @@ -5948,7 +5947,7 @@ def _should_fallback_to_positional(self) -> bool: Parameters ---------- - target : %(target_klass)s + target : Index An iterable containing the values to be used for computing indexer. Returns @@ -5992,11 +5991,6 @@ def _should_fallback_to_positional(self) -> bool: >>> index.get_indexer_non_unique(['f', 'b', 's']) (array([-1, 1, 3, 4, -1]), array([0, 2])) """ - - @Appender(_index_shared_docs["get_indexer_non_unique"] % _index_doc_kwargs) - def get_indexer_non_unique( - self, target - ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: target = self._maybe_cast_listlike_indexer(target) if not self._should_compare(target) and not self._should_partial_index(target): From 77efcd8258a9cb409461065c712140597e66989a Mon Sep 17 00:00:00 2001 From: mateomramos Date: Wed, 22 Oct 2025 14:56:50 -0400 Subject: [PATCH 2/4] DOC: Replace @Appender decorator with inline docstrings for Index.take, Index.repeat, and Index.get_indexer_non_unique --- pandas/core/indexes/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index e71c28f6dc194..80662dd37bb85 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -71,7 +71,7 @@ InvalidIndexError, ) from pandas.util._decorators import ( - Appender + Appender, cache_readonly, doc, set_module, From 9e38e8c6e52ceed3d5a4b6a71e8d3f283ccea69e Mon Sep 17 00:00:00 2001 From: mateomramos Date: Thu, 23 Oct 2025 00:31:09 -0400 Subject: [PATCH 3/4] DOC: Replace @Appender decorator with inline docstrings for Index.take, Index.repeat, and Index.get_indexer_non_unique --- pandas/core/indexes/base.py | 99 +++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 80662dd37bb85..61d74fac926e3 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -1170,6 +1170,52 @@ def astype(self, dtype: Dtype, copy: bool = True): result._references.add_index_reference(result) return result + _index_shared_docs["take"] = """ + Return a new %(klass)s of the values selected by the indices. + + For internal compatibility with numpy arrays. + + Parameters + ---------- + indices : array-like + Indices to be taken. + axis : int, optional + The axis over which to select values, always 0. + allow_fill : bool, default True + How to handle negative values in `indices`. + + * False: negative values in `indices` indicate positional indices + from the right (the default). This is similar to + :func:`numpy.take`. + + * True: negative values in `indices` indicate + missing values. These values are set to `fill_value`. Any other + other negative values raise a ``ValueError``. + + fill_value : scalar, default None + If allow_fill=True and fill_value is not None, indices specified by + -1 are regarded as NA. If Index doesn't hold NA, raise ValueError. + **kwargs + Required for compatibility with numpy. + + Returns + ------- + Index + An index formed of elements at the given indices. Will be the same + type as self, except for RangeIndex. + + See Also + -------- + numpy.ndarray.take: Return an array formed from the + elements of a at the given indices. + + Examples + -------- + >>> idx = pd.Index(['a', 'b', 'c']) + >>> idx.take([2, 2, 1, 2]) + Index(['c', 'c', 'b', 'c'], dtype='str') + """ + def take( self, indices, @@ -5936,6 +5982,59 @@ def _should_fallback_to_positional(self) -> bool: "complex", } + _index_shared_docs["get_indexer_non_unique"] = """ + Compute indexer and mask for new index given the current index. + + The indexer should be then used as an input to ndarray.take to align the + current data to the new index. + + Parameters + ---------- + target : %(target_klass)s + An iterable containing the values to be used for computing indexer. + + Returns + ------- + indexer : np.ndarray[np.intp] + Integers from 0 to n - 1 indicating that the index at these + positions matches the corresponding target values. Missing values + in the target are marked by -1. + missing : np.ndarray[np.intp] + An indexer into the target of the values not found. + These correspond to the -1 in the indexer array. + + See Also + -------- + Index.get_indexer : Computes indexer and mask for new index given + the current index. + Index.get_indexer_for : Returns an indexer even when non-unique. + + Examples + -------- + >>> index = pd.Index(['c', 'b', 'a', 'b', 'b']) + >>> index.get_indexer_non_unique(['b', 'b']) + (array([1, 3, 4, 1, 3, 4]), array([], dtype=int64)) + + In the example below there are no matched values. + + >>> index = pd.Index(['c', 'b', 'a', 'b', 'b']) + >>> index.get_indexer_non_unique(['q', 'r', 't']) + (array([-1, -1, -1]), array([0, 1, 2])) + + For this reason, the returned ``indexer`` contains only integers equal to -1. + It demonstrates that there's no match between the index and the ``target`` + values at these positions. The mask [0, 1, 2] in the return value shows that + the first, second, and third elements are missing. + + Notice that the return value is a tuple contains two items. In the example + below the first item is an array of locations in ``index``. The second + item is a mask shows that the first and third elements are missing. + + >>> index = pd.Index(['c', 'b', 'a', 'b', 'b']) + >>> index.get_indexer_non_unique(['f', 'b', 's']) + (array([-1, 1, 3, 4, -1]), array([0, 2])) + """ + def get_indexer_non_unique( self, target ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: From 77ca6ac597fdd841014e535f6b8dca4ac38bf1cb Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 23 Oct 2025 05:36:48 +0000 Subject: [PATCH 4/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- pandas/core/indexes/base.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 61d74fac926e3..6fafbd9590143 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -1265,7 +1265,7 @@ def take( Examples -------- - >>> idx = pd.Index(['a', 'b', 'c']) + >>> idx = pd.Index(["a", "b", "c"]) >>> idx.take([2, 2, 1, 2]) Index(['c', 'c', 'b', 'c'], dtype='str') """ @@ -1345,7 +1345,7 @@ def repeat(self, repeats, axis: None = None) -> Self: Examples -------- - >>> idx = pd.Index(['a', 'b', 'c']) + >>> idx = pd.Index(["a", "b", "c"]) >>> idx Index(['a', 'b', 'c'], dtype='object') >>> idx.repeat(2) @@ -6067,14 +6067,14 @@ def get_indexer_non_unique( Examples -------- - >>> index = pd.Index(['c', 'b', 'a', 'b', 'b']) - >>> index.get_indexer_non_unique(['b', 'b']) + >>> index = pd.Index(["c", "b", "a", "b", "b"]) + >>> index.get_indexer_non_unique(["b", "b"]) (array([1, 3, 4, 1, 3, 4]), array([], dtype=int64)) In the example below there are no matched values. - >>> index = pd.Index(['c', 'b', 'a', 'b', 'b']) - >>> index.get_indexer_non_unique(['q', 'r', 't']) + >>> index = pd.Index(["c", "b", "a", "b", "b"]) + >>> index.get_indexer_non_unique(["q", "r", "t"]) (array([-1, -1, -1]), array([0, 1, 2])) For this reason, the returned ``indexer`` contains only integers equal to -1. @@ -6086,8 +6086,8 @@ def get_indexer_non_unique( below the first item is an array of locations in ``index``. The second item is a mask shows that the first and third elements are missing. - >>> index = pd.Index(['c', 'b', 'a', 'b', 'b']) - >>> index.get_indexer_non_unique(['f', 'b', 's']) + >>> index = pd.Index(["c", "b", "a", "b", "b"]) + >>> index.get_indexer_non_unique(["f", "b", "s"]) (array([-1, 1, 3, 4, -1]), array([0, 2])) """ target = self._maybe_cast_listlike_indexer(target)