DOC: .get_slice_bound in MultiIndex needs documentation. (#29967)

Author: proost

pandas/_typing.py

@@ -4,9 +4,11 @@
     TYPE_CHECKING,
     AnyStr,
     Dict,
+    Hashable,
     Iterable,
     List,
     Optional,
+    Sequence,
     TypeVar,
     Union,
 )
@@ -36,6 +38,7 @@
 Axis = Union[str, int]
 Ordered = Optional[bool]
 JSONSerializable = Union[Scalar, List, Dict]
+OneOrMoreObjects = Union[Hashable, Sequence[Hashable]]
 
 # use Collection after we drop support for py35
 Axes = Iterable

pandas/core/indexes/multi.py

@@ -30,6 +30,7 @@
 from pandas.core.dtypes.generic import ABCDataFrame
 from pandas.core.dtypes.missing import array_equivalent, isna
 
+from pandas._typing import OneOrMoreObjects
 import pandas.core.algorithms as algos
 from pandas.core.arrays import Categorical
 from pandas.core.arrays.categorical import factorize_from_iterables
@@ -2441,7 +2442,51 @@ def reindex(self, target, method=None, level=None, limit=None, tolerance=None):
 
         return target, indexer
 
-    def get_slice_bound(self, label, side, kind):
+    def get_slice_bound(self, label: OneOrMoreObjects, side: str, kind: str) -> int:
+        """
+        For an ordered MultiIndex, compute slice bound
+        that corresponds to given label.
+
+        Returns leftmost (one-past-the-rightmost if `side=='right') position
+        of given label.
+
+        Parameters
+        ----------
+        label : object or tuple of objects
+        side : {'left', 'right'}
+        kind : {'ix', 'loc', 'getitem'}
+
+        Returns
+        -------
+        int
+            Index of label.
+
+        Notes
+        -----
+        This method only works if level 0 index of the MultiIndex is lexsorted.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([list('abbc'), list('gefd')])
+
+        Get the locations from the leftmost 'b' in the first level
+        until the end of the multiindex:
+
+        >>> mi.get_slice_bound('b', side="left", kind="ix")
+        1
+
+        Like above, but if you get the locations from the rightmost
+        'b' in the first level and 'f' in the second level:
+
+        >>> mi.get_slice_bound(('b','f'), side="right", kind="ix")
+        3
+
+        See Also
+        --------
+        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.
+        """
 
         if not isinstance(label, tuple):
             label = (label,)