clarifies input to get_loc is sequence

Author: tp

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!