clarifies input to get_loc is sequence

Author: tp

pandas/core/categorical.py

@@ -223,7 +223,7 @@ class Categorical(PandasObject):
 
  See also
  --------
- pandas.api.types.CategoricalDtype
+ CategoricalDtype : Type for categorical data
  CategoricalIndex : An Index with an underlying ``Categorical``
  """
 

pandas/core/indexes/multi.py

@@ -72,8 +72,8 @@ class MultiIndex(Index):
  Examples
  ---------
  A new ``MultiIndex`` is typically constructed using one of the helper
- methods :meth:`MultiIndex.from_arrays``, :meth:`MultiIndex.from_product``
- and :meth:`MultiIndex.from_tuples``. For example (using ``.from_arrays``):
+ methods :meth:`MultiIndex.from_arrays`, :meth:`MultiIndex.from_product`
+ and :meth:`MultiIndex.from_tuples`. For example (using ``.from_arrays``):
 
  >>> arrays = [[1, 1, 2, 2], ['red', 'blue', 'red', 'blue']]
  >>> pd.MultiIndex.from_arrays(arrays, names=('number', 'color'))
@@ -1985,13 +1985,9 @@ def get_loc(self, key, method=None):
  Get location for a label or a tuple of labels as an integer, slice or
  boolean mask.
 
- Note that the key cannot be a slice, list of same-level labels,
- a boolean mask, or a sequence of such. If you want that, use
- :meth:`get_locs` instead.
-
  Parameters
  ----------
- key : label or tuple of labels
+ key : label or tuple of labels (one for each level)
  method : None
 
  Returns
@@ -2003,17 +1999,24 @@ def get_loc(self, key, method=None):
  Examples
  ---------
  >>> mi = pd.MultiIndex.from_arrays([list('abb'), list('def')])
+
  >>> mi.get_loc('b')
  slice(1, 3, None)
+
  >>> mi.get_loc(('b', 'e'))
  1
 
+ Notes
+ ------
+ The key cannot be a slice, list of same-level labels, a boolean mask,
+ or a sequence of such. If you want to use those, use :meth:`get_locs`
+ instead.
+
  See also
  --------
  Index.get_loc : get_loc method for (single-level) index.
- get_locs : Given a tuple of slices/lists/labels/boolean indexer to a
- level-wise spec, produce an indexer to extract those
- locations.
+ get_locs : Get location for a label/slice/list/mask or a sequence of
+ such.
  """
  if method is not None:
  raise NotImplementedError('only the default get_loc method is '
@@ -2122,7 +2125,9 @@ def get_loc_level(self, key, level=0, drop_level=True):
 
  See Also
  ---------
- MultiIndex.get_loc : Get location for a label or a tuple of labels.
+ MultiIndex.get_loc : Get location for a label or a tuple of labels.
+ MultiIndex.get_locs : Get location for a label/slice/list/mask or a
+ sequence of such
  """
 
  def maybe_droplevels(indexer, levels, drop_level):
@@ -2332,14 +2337,14 @@ def convert_indexer(start, stop, step, indexer=indexer, labels=labels):
  j = labels.searchsorted(loc, side='right')
  return slice(i, j)
 
- def get_locs(self, tup):
+ def get_locs(self, seq):
  """
  Get location for a given label/slice/list/mask or a sequence of such as
  a integer, slice or boolean mask.
 
  Parameters
  ----------
- key : label/slice/list/mask or a sequence of such.
+ seq : label/slice/list/mask or a sequence of such.
 
  Returns
  -------
@@ -2365,7 +2370,7 @@ def get_locs(self, tup):
  """
 
  # must be lexsorted to at least as many levels
- true_slices = [i for (i, s) in enumerate(is_true_slices(tup)) if s]
+ true_slices = [i for (i, s) in enumerate(is_true_slices(seq)) if s]
  if true_slices and true_slices[-1] >= self.lexsort_depth:
  raise UnsortedIndexError('MultiIndex slicing requires the index '
  'to be lexsorted: slicing on levels {0}, '
@@ -2398,7 +2403,7 @@ def _update_indexer(idxr, indexer=indexer):
  return indexer
  return indexer & idxr
 
- for i, k in enumerate(tup):
+ for i, k in enumerate(seq):
 
  if is_bool_indexer(k):
  # a boolean indexer, must be the same length!