add examples to .get_loc methods

Author: tp

pandas/core/indexes/base.py

@@ -2436,15 +2436,26 @@ def _get_unique_index(self, dropna=False):
             Maximum distance from index value for inexact matches. The value of
             the index at the matching location most satisfy the equation
             ``abs(index[loc] - key) <= tolerance``.
-
             .. versionadded:: 0.17.0
 
         Returns
         -------
-        loc : int if unique index, possibly slice or mask if not
-    """
+        loc : int if unique index, slice if monotonic index, else mask
 
-    @Appender(_index_shared_docs['get_loc'])
+        Examples
+        ---------
+        >>> unique_index = pd.%(klass)s(list('abc'))
+        >>> unique_index.get_loc('b')
+        1
+        >>> monotonic_index = pd.%(klass)s(list('abbc'))
+        >>> monotonic_index.get_loc('b')
+        slice(1, 3, None)
+        >>> non_monotonic_index = pd.%(klass)s(list('abcb'))
+        >>> non_monotonic_index.get_loc('b')
+        array([False,  True, False,  True], dtype=bool)
+        """
+
+    @Appender(_index_shared_docs['get_loc'] % _index_doc_kwargs)
     def get_loc(self, key, method=None, tolerance=None):
         if method is None:
             if tolerance is not None:

pandas/core/indexes/category.py

@@ -354,7 +354,7 @@ def _to_safe_for_reshape(self):
 
     def get_loc(self, key, method=None):
         """
-        Get integer location for requested label
+        Get integer location for requested label.
 
         Parameters
         ----------
@@ -364,7 +364,19 @@ def get_loc(self, key, method=None):
 
         Returns
         -------
-        loc : int if unique index, possibly slice or mask if not
+        loc : int if unique index, slice if monotonic index, else mask
+
+        Examples
+        ---------
+        >>> unique_index = pd.CategoricalIndex(list('abc'))
+        >>> unique_index.get_loc('b')
+        1
+        >>> monotonic_index = pd.CategoricalIndex(list('abbc'))
+        >>> monotonic_index.get_loc('b')
+        slice(1, 3, None)
+        >>> non_monotonic_index = p.dCategoricalIndex(list('abcb'))
+        >>> non_monotonic_index.get_loc('b')
+        array([False,  True, False,  True], dtype=bool)
         """
         codes = self.categories.get_loc(key)
         if (codes == -1):

pandas/core/indexes/interval.py

@@ -689,6 +689,39 @@ def _find_non_overlapping_monotonic_bounds(self, key):
         return start, stop
 
     def get_loc(self, key, method=None):
+        """Get integer location for requested label.
+
+        Parameters
+        ----------
+        key : label
+        method : {None, 'pad'/'ffill', 'backfill'/'bfill', 'nearest'}, optional
+            * default: matches where the label is within an interval only.
+            * the other methods are not currently implemented.
+
+        Returns
+        -------
+        loc : int if unique index, slice if monotonic index, else mask
+
+        Examples
+        ---------
+        >>> i1, i2 = pd.Interval(0, 1), pd.Interval(1, 2)
+        >>> index = pd.IntervalIndex.from_intervals([i1, i2])
+        >>> index.get_loc(1)
+        0
+
+        You can also get the location for a point inside an interval.
+
+        >>> index.get_loc(1.5)
+        1
+
+        If a label is in several intervals, you get the locations of all the
+        relevant intervals.
+
+        >>> i3 = pd.Interval(0, 2)
+        >>> overlapping_index = pd.IntervalIndex.from_intervals([i2, i3])
+        >>> overlapping_index.get_loc(1.5)
+        array([0, 1], dtype=int64)
+        """
         self._check_method(method)
 
         original_key = key

pandas/core/indexes/multi.py

@@ -1966,6 +1966,20 @@ def get_loc(self, key, method=None):
         Returns
         -------
         loc : int, slice object or boolean mask
+
+        Examples
+        ---------
+        >>> mi = pd.MultiIndex.from_arrays([list('abb'), list('def')])
+        >>> mi.get_loc('b')
+        slice(1, 3, None)
+        >>> mi.get_loc(('b', 'e'))
+        1
+
+        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
         """
         if method is not None:
             raise NotImplementedError('only the default get_loc method is '