From 28c9c89e8ea1232070519dca2adf2b6b78f5ec1f Mon Sep 17 00:00:00 2001
From: tp <terji78@yaho.com>
Date: Sun, 17 Sep 2017 17:06:01 +0100
Subject: [PATCH] add examples to .get_loc methods

---
 pandas/core/indexes/base.py     | 20 ++++++++++++++++---
 pandas/core/indexes/category.py | 18 +++++++++++++++--
 pandas/core/indexes/interval.py | 35 +++++++++++++++++++++++++++++++++
 pandas/core/indexes/multi.py    | 15 ++++++++++++++
 4 files changed, 83 insertions(+), 5 deletions(-)

diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py
index 008828cf4f309..ca145eeaaa7b8 100644
--- a/pandas/core/indexes/base.py
+++ b/pandas/core/indexes/base.py
@@ -2421,7 +2421,7 @@ def _get_unique_index(self, dropna=False):
         return self._shallow_copy(values)
 
     _index_shared_docs['get_loc'] = """
-        Get integer location for requested label.
+        Get integer location, slice or boolean mask for requested label.
 
         Parameters
         ----------
@@ -2441,8 +2441,22 @@ def _get_unique_index(self, dropna=False):
 
         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.Index(list('abc'))
+        >>> unique_index.get_loc('b')
+        1
+
+        >>> monotonic_index = pd.Index(list('abbc'))
+        >>> monotonic_index.get_loc('b')
+        slice(1, 3, None)
+
+        >>> non_monotonic_index = pd.Index(list('abcb'))
+        >>> non_monotonic_index.get_loc('b')
+        array([False,  True, False,  True], dtype=bool)
+        """
 
     @Appender(_index_shared_docs['get_loc'])
     def get_loc(self, key, method=None, tolerance=None):
diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py
index ef1dc4d971f37..447087d3c7563 100644
--- a/pandas/core/indexes/category.py
+++ b/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, slice or boolean mask for requested label.
 
         Parameters
         ----------
@@ -364,7 +364,21 @@ 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):
diff --git a/pandas/core/indexes/interval.py b/pandas/core/indexes/interval.py
index c0a9c139722f5..8120c93ad3364 100644
--- a/pandas/core/indexes/interval.py
+++ b/pandas/core/indexes/interval.py
@@ -689,6 +689,41 @@ def _find_non_overlapping_monotonic_bounds(self, key):
         return start, stop
 
     def get_loc(self, key, method=None):
+        """Get integer location, slice or boolean mask for requested label.
+
+        Parameters
+        ----------
+        key : label
+        method : {None}, optional
+            * default: matches where the label is within an interval only.
+
+        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 supply an interval or an location for a point inside an
+        interval.
+
+        >>> index.get_loc(pd.Interval(0, 2))
+        array([0, 1], dtype=int64)
+        >>> 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
diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py
index ea613a27b6521..66209ecd3a030 100644
--- a/pandas/core/indexes/multi.py
+++ b/pandas/core/indexes/multi.py
@@ -1967,6 +1967,21 @@ 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 '