diff --git a/pandas/core/indexing.py b/pandas/core/indexing.py index 0896339bc28c7..a9269a5e0efa1 100755 --- a/pandas/core/indexing.py +++ b/pandas/core/indexing.py @@ -212,18 +212,18 @@ def _validate_key(self, key, axis: int): Parameters ---------- key : scalar, slice or list-like - The key requested + Key requested. axis : int - Dimension on which the indexing is being made + Dimension on which the indexing is being made. Raises ------ TypeError - If the key (or some element of it) has wrong type + If the key (or some element of it) has wrong type. IndexError - If the key (or some element of it) is out of bounds + If the key (or some element of it) is out of bounds. KeyError - If the key was not found + If the key was not found. """ raise AbstractMethodError(self) @@ -243,6 +243,11 @@ def _has_valid_tuple(self, key: Tuple): ) def _is_nested_tuple_indexer(self, tup: Tuple) -> bool: + """ + Returns + ------- + bool + """ if any(isinstance(ax, ABCMultiIndex) for ax in self.obj.axes): return any(is_nested_tuple(tup, ax) for ax in self.obj.axes) return False @@ -279,8 +284,13 @@ def _has_valid_setitem_indexer(self, indexer) -> bool: return True def _has_valid_positional_setitem_indexer(self, indexer) -> bool: - """ validate that an positional indexer cannot enlarge its target - will raise if needed, does not modify the indexer externally + """ + Validate that a positional indexer cannot enlarge its target + will raise if needed, does not modify the indexer externally. + + Returns + ------- + bool """ if isinstance(indexer, dict): raise IndexError("{0} cannot enlarge its target object".format(self.name)) @@ -656,10 +666,9 @@ def _align_series(self, indexer, ser: ABCSeries, multiindex_indexer: bool = Fals Parameters ---------- indexer : tuple, slice, scalar - The indexer used to get the locations that will be set to - `ser` + Indexer used to get the locations that will be set to `ser`. ser : pd.Series - The values to assign to the locations specified by `indexer` + Values to assign to the locations specified by `indexer`. multiindex_indexer : boolean, optional Defaults to False. Should be set to True if `indexer` was from a `pd.MultiIndex`, to avoid unnecessary broadcasting. @@ -818,20 +827,23 @@ def _getitem_tuple(self, tup: Tuple): return retval - def _multi_take_opportunity(self, tup: Tuple): + def _multi_take_opportunity(self, tup: Tuple) -> bool: """ Check whether there is the possibility to use ``_multi_take``. - Currently the limit is that all axes being indexed must be indexed with + + Currently the limit is that all axes being indexed, must be indexed with list-likes. Parameters ---------- tup : tuple - Tuple of indexers, one per axis + Tuple of indexers, one per axis. Returns ------- - boolean: Whether the current indexing can be passed through _multi_take + bool + Whether the current indexing, + can be passed through `_multi_take`. """ if not all(is_list_like_indexer(x) for x in tup): return False @@ -844,14 +856,15 @@ def _multi_take_opportunity(self, tup: Tuple): def _multi_take(self, tup: Tuple): """ - Create the indexers for the passed tuple of keys, and execute the take - operation. This allows the take operation to be executed all at once - - rather than once for each dimension - improving efficiency. + Create the indexers for the passed tuple of keys, and + executes the take operation. This allows the take operation to be + executed all at once, rather than once for each dimension. + Improving efficiency. Parameters ---------- tup : tuple - Tuple of indexers, one per axis + Tuple of indexers, one per axis. Returns ------- @@ -1033,13 +1046,13 @@ def _get_listlike_indexer(self, key, axis: int, raise_missing: bool = False): Parameters ---------- key : list-like - Target labels + Targeted labels. axis: int - Dimension on which the indexing is being made - raise_missing: bool - Whether to raise a KeyError if some labels are not found. Will be - removed in the future, and then this method will always behave as - if raise_missing=True. + Dimension on which the indexing is being made. + raise_missing: bool, default False + Whether to raise a KeyError if some labels were not found. + Will be removed in the future, and then this method will always behave as + if ``raise_missing=True``. Raises ------ @@ -1050,9 +1063,9 @@ def _get_listlike_indexer(self, key, axis: int, raise_missing: bool = False): Returns ------- keyarr: Index - New index (coinciding with 'key' if the axis is unique) + New index (coinciding with 'key' if the axis is unique). values : array-like - An indexer for the return object; -1 denotes keys not found + Indexer for the return object, -1 denotes keys not found. """ o = self.obj ax = o._get_axis(axis) @@ -1082,15 +1095,16 @@ def _get_listlike_indexer(self, key, axis: int, raise_missing: bool = False): def _getitem_iterable(self, key, axis: int): """ - Index current object with an an iterable key (which can be a boolean - indexer, or a collection of keys). + Index current object with an an iterable key. + + The iterable key can be a boolean indexer or a collection of keys. Parameters ---------- key : iterable - Target labels, or boolean indexer + Targeted labels or boolean indexer. axis: int - Dimension on which the indexing is being made + Dimension on which the indexing is being made. Raises ------ @@ -1103,7 +1117,7 @@ def _getitem_iterable(self, key, axis: int): Returns ------- - scalar, DataFrame, or Series: indexed value(s), + scalar, DataFrame, or Series: indexed value(s). """ # caller is responsible for ensuring non-None axis self._validate_key(key, axis) @@ -1126,17 +1140,20 @@ def _validate_read_indexer( self, key, indexer, axis: int, raise_missing: bool = False ): """ - Check that indexer can be used to return a result (e.g. at least one - element was found, unless the list of keys was actually empty). + Check that indexer can be used to return a result. + + e.g. at least one element was found, + unless the list of keys was actually empty. Parameters ---------- key : list-like - Target labels (only used to show correct error message) + Targeted labels (only used to show correct error message). indexer: array-like of booleans - Indices corresponding to the key (with -1 indicating not found) + Indices corresponding to the key, + (with -1 indicating not found). axis: int - Dimension on which the indexing is being made + Dimension on which the indexing is being made. raise_missing: bool Whether to raise a KeyError if some labels are not found. Will be removed in the future, and then this method will always behave as @@ -1148,7 +1165,6 @@ def _validate_read_indexer( If at least one key was requested but none was found, and raise_missing=True. """ - ax = self.obj._get_axis(axis) if len(key) == 0: @@ -1186,7 +1202,7 @@ def _validate_read_indexer( def _convert_to_indexer(self, obj, axis: int, raise_missing: bool = False): """ Convert indexing key into something we can use to do actual fancy - indexing on an ndarray + indexing on a ndarray. Examples ix[:5] -> slice(0, 5) @@ -1315,6 +1331,11 @@ def __init__(self, name, obj): @Appender(_NDFrameIndexer._validate_key.__doc__) def _validate_key(self, key, axis: int) -> bool: + """ + Returns + ------- + bool + """ if isinstance(key, slice): return True @@ -1338,13 +1359,13 @@ def _convert_for_reindex(self, key, axis: int): Parameters ---------- key : list-like - Target labels + Targeted labels. axis: int - Where the indexing is being made + Where the indexing is being made. Returns ------- - list-like of labels + list-like of labels. """ labels = self.obj._get_axis(axis) @@ -1405,7 +1426,9 @@ def _getbool_axis(self, key, axis: int): return self.obj.take(inds, axis=axis) def _get_slice_axis(self, slice_obj: slice, axis: int): - """ this is pretty simple as we just have to deal with labels """ + """ + This is pretty simple as we just have to deal with labels. + """ # caller is responsible for ensuring non-None axis obj = self.obj if not need_slice(slice_obj): @@ -1451,8 +1474,8 @@ class _LocIndexer(_LocationIndexer): Raises ------ - KeyError: - when any items are not found + KeyError + If any items are not found. See Also -------- @@ -1686,6 +1709,11 @@ def _validate_key(self, key, axis: int): self._convert_scalar_indexer(key, axis) def _is_scalar_access(self, key: Tuple) -> bool: + """ + Returns + ------- + bool + """ # this is a shortcut accessor to both .loc and .iloc # that provide the equivalent access of .at and .iat # a) avoid getting things via sections and (to minimize dtype changes) @@ -1718,8 +1746,12 @@ def _getitem_scalar(self, key): return values def _get_partial_string_timestamp_match_key(self, key, labels): - """Translate any partial string timestamp matches in key, returning the - new key (GH 10331)""" + """ + Translate any partial string timestamp matches in key, returning the + new key. + + (GH 10331) + """ if isinstance(labels, ABCMultiIndex): if ( isinstance(key, str) @@ -1999,6 +2031,11 @@ def _has_valid_setitem_indexer(self, indexer): self._has_valid_positional_setitem_indexer(indexer) def _is_scalar_access(self, key: Tuple) -> bool: + """ + Returns + ------- + bool + """ # this is a shortcut accessor to both .loc and .iloc # that provide the equivalent access of .at and .iat # a) avoid getting things via sections and (to minimize dtype changes) @@ -2029,20 +2066,15 @@ def _validate_integer(self, key: int, axis: int) -> None: Parameters ---------- key : int - Requested position + Requested position. axis : int - Desired axis - - Returns - ------- - None + Desired axis. Raises ------ IndexError - If 'key' is not a valid position in axis 'axis' + If 'key' is not a valid position in axis 'axis'. """ - len_axis = len(self.obj._get_axis(axis)) if key >= len_axis or key < -len_axis: raise IndexError("single positional indexer is out-of-bounds") @@ -2077,16 +2109,20 @@ def _getitem_tuple(self, tup: Tuple): def _get_list_axis(self, key, axis: int): """ - Return Series values by list or array of integers + Return Series values by list or array of integers. Parameters ---------- key : list-like positional indexer - axis : int (can only be zero) + axis : int Returns ------- Series object + + Notes + ----- + `axis` can only be zero. """ try: return self.obj.take(key, axis=axis) @@ -2122,8 +2158,9 @@ def _getitem_axis(self, key, axis: int): # raise_missing is included for compat with the parent class signature def _convert_to_indexer(self, obj, axis: int, raise_missing: bool = False): - """ much simpler as we only have to deal with our valid types """ - + """ + Much simpler as we only have to deal with our valid types. + """ # make need to convert a float key if isinstance(obj, slice): return self._convert_slice_indexer(obj, axis) @@ -2142,7 +2179,9 @@ def _convert_to_indexer(self, obj, axis: int, raise_missing: bool = False): class _ScalarAccessIndexer(_NDFrameIndexerBase): - """ access scalars quickly """ + """ + Access scalars quickly. + """ def _convert_key(self, key, is_setter: bool = False): raise AbstractMethodError(self) @@ -2186,7 +2225,7 @@ class _AtIndexer(_ScalarAccessIndexer): Raises ------ KeyError - When label does not exist in DataFrame + If 'label' does not exist in DataFrame. See Also -------- @@ -2225,10 +2264,10 @@ class _AtIndexer(_ScalarAccessIndexer): _takeable = False def _convert_key(self, key, is_setter: bool = False): - """ require they keys to be the same type as the index (so we don't + """ + Require they keys to be the same type as the index. (so we don't fallback) """ - # allow arbitrary setting if is_setter: return list(key) @@ -2261,7 +2300,7 @@ class _iAtIndexer(_ScalarAccessIndexer): Raises ------ IndexError - When integer position is out of bounds + When integer position is out of bounds. See Also -------- @@ -2299,7 +2338,9 @@ class _iAtIndexer(_ScalarAccessIndexer): _takeable = True def _convert_key(self, key, is_setter: bool = False): - """ require integer args (and convert to label arguments) """ + """ + Require integer args. (and convert to label arguments) + """ for a, i in zip(self.obj.axes, key): if not is_integer(i): raise ValueError("iAt based indexing can only have integer indexers") @@ -2327,7 +2368,7 @@ def _tuplify(ndim: int, loc) -> tuple: def convert_to_index_sliceable(obj, key): """ - if we are index sliceable, then return my slicer, otherwise return None + If we are index sliceable, then return my slicer, otherwise return None. """ idx = obj.index if isinstance(key, slice): @@ -2360,23 +2401,21 @@ def check_bool_indexer(index: Index, key) -> np.ndarray: Parameters ---------- index : Index - Index of the object on which the indexing is done + Index of the object on which the indexing is done. key : list-like - Boolean indexer to check + Boolean indexer to check. Returns ------- - result: np.array - Resulting key + np.array + Resulting key. Raises ------ IndexError - If the key does not have the same length as index - + If the key does not have the same length as index. IndexingError - If the index of the key is unalignable to index - + If the index of the key is unalignable to index. """ result = key if isinstance(key, ABCSeries) and not key.index.equals(index): @@ -2405,10 +2444,9 @@ def check_bool_indexer(index: Index, key) -> np.ndarray: def convert_missing_indexer(indexer): """ - reverse convert a missing indexer, which is a dict + Reverse convert a missing indexer, which is a dict return the scalar indexer and a boolean indicating if we converted """ - if isinstance(indexer, dict): # a missing key (but not a tuple indexer) @@ -2423,7 +2461,7 @@ def convert_missing_indexer(indexer): def convert_from_missing_indexer_tuple(indexer, axes): """ - create a filtered indexer that doesn't have any missing indexers + Create a filtered indexer that doesn't have any missing indexers. """ def get_indexer(_i, _idx): @@ -2434,9 +2472,8 @@ def get_indexer(_i, _idx): def maybe_convert_ix(*args): """ - We likely want to take the cross-product + We likely want to take the cross-product. """ - ixify = True for arg in args: if not isinstance(arg, (np.ndarray, list, ABCSeries, Index)): @@ -2449,6 +2486,11 @@ def maybe_convert_ix(*args): def is_nested_tuple(tup, labels) -> bool: + """ + Returns + ------- + bool + """ # check for a compatible nested tuple and multiindexes among the axes if not isinstance(tup, tuple): return False @@ -2462,11 +2504,21 @@ def is_nested_tuple(tup, labels) -> bool: def is_label_like(key) -> bool: + """ + Returns + ------- + bool + """ # select a label or row return not isinstance(key, slice) and not is_list_like_indexer(key) def need_slice(obj) -> bool: + """ + Returns + ------- + bool + """ return ( obj.start is not None or obj.stop is not None @@ -2488,6 +2540,13 @@ def _non_reducing_slice(slice_): slice_ = IndexSlice[:, slice_] def pred(part) -> bool: + """ + Returns + ------- + bool + True if slice does *not* reduce, + False if `part` is a tuple. + """ # true when slice does *not* reduce, False when part is a tuple, # i.e. MultiIndex slice return (isinstance(part, slice) or is_list_like(part)) and not isinstance( @@ -2508,7 +2567,7 @@ def pred(part) -> bool: def _maybe_numeric_slice(df, slice_, include_bool=False): """ - want nice defaults for background_gradient that don't break + Want nice defaults for background_gradient that don't break with non-numeric data. But if slice_ is passed go with that. """ if slice_ is None: @@ -2520,7 +2579,12 @@ def _maybe_numeric_slice(df, slice_, include_bool=False): def _can_do_equal_len(labels, value, plane_indexer, lplane_indexer, obj) -> bool: - """ return True if we have an equal len settable """ + """ + Returns + ------- + bool + True if we have an equal len settable. + """ if not len(labels) == 1 or not np.iterable(value) or is_scalar(plane_indexer[0]): return False