Add examples to MultiIndex.get_level_values + related changes

Author: tp

pandas/core/indexes/base.py

@@ -2529,15 +2529,20 @@ def set_value(self, arr, key, value):
     def _get_level_values(self, level):
         """
         Return an Index of values for requested level, equal to the length
-        of the index
+        of the index.
 
         Parameters
         ----------
-        level : int
+        level : int or level name
 
         Returns
         -------
-        values : Index
+        self : Index
+
+        See also
+        ---------
+        pandas.MultiIndex.get_level_values : get values for a level of a
+                                             MultiIndex
         """
 
         self._validate_index_level(level)

pandas/core/indexes/multi.py

@@ -882,7 +882,7 @@ def _get_level_values(self, level):
     def get_level_values(self, level):
         """
         Return vector of label values for requested level,
-        equal to the length of the index
+        equal to the length of the index.
 
         Parameters
         ----------
@@ -891,6 +891,24 @@ def get_level_values(self, level):
         Returns
         -------
         values : Index
+
+        Examples
+        ---------
+
+        Create a MultiIndex:
+
+        >>> i1 = pd.Index(list('abc'), name='level_1')
+        >>> i2 = pd.CategoricalIndex(list('def'), name='level_2')
+        >>> mi = pd.MultiIndex.from_arrays((i1, i2))
+
+        Get level values by supplying level as either integer or name:
+
+        >>> mi.get_level_values(1)
+        CategoricalIndex(['d', 'e', 'f'], categories=['d', 'e', 'f'],
+                         ordered=False, name='level_2',
+                         dtype='category')
+        >>> mi.get_level_values('level_1')
+        Index(['a', 'b', 'c'], dtype='object', name='level_1')
         """
         level = self._get_level_number(level)
         values = self._get_level_values(level)

pandas/tests/indexes/test_base.py

@@ -1438,6 +1438,12 @@ def test_get_level_values(self):
         result = self.strIndex.get_level_values(0)
         tm.assert_index_equal(result, self.strIndex)
 
+        # test with name
+        index_with_name = self.strIndex.copy()
+        index_with_name.name = 'a'
+        result = index_with_name.get_level_values('a')
+        tm.assert_index_equal(result, index_with_name)
+
     def test_slice_keep_name(self):
         idx = Index(['a', 'b'], name='asdf')
         assert idx.name == idx[1:].name