DOC: use shared_docs for Index.get_indexer, get_indexer_non_unique

Author: jreback

pandas/indexes/base.py

@@ -2350,8 +2350,7 @@ def get_level_values(self, level):
         self._validate_index_level(level)
         return self
 
-    def get_indexer(self, target, method=None, limit=None, tolerance=None):
-        """
+    _index_shared_docs['get_indexer'] = """
         Compute indexer and mask for new index given the current index. The
         indexer should be then used as an input to ndarray.take to align the
         current data to the new index.
@@ -2387,6 +2386,9 @@ def get_indexer(self, target, method=None, limit=None, tolerance=None):
             positions matches the corresponding target values. Missing values
             in the target are marked by -1.
         """
+
+    @Appender(_index_shared_docs['get_indexer'])
+    def get_indexer(self, target, method=None, limit=None, tolerance=None):
         method = missing.clean_reindex_fill_method(method)
         target = _ensure_index(target)
         if tolerance is not None:
@@ -2496,11 +2498,28 @@ def _filter_indexer_tolerance(self, target, indexer, tolerance):
         indexer = np.where(distance <= tolerance, indexer, -1)
         return indexer
 
+    _index_shared_docs['get_indexer_non_unique'] = """
+        Compute indexer and mask for new index given the current index. The
+        indexer should be then used as an input to ndarray.take to align the
+        current data to the new index.
+
+        Parameters
+        ----------
+        target : Index
+
+        Returns
+        -------
+        indexer : ndarray of int
+            Integers from 0 to n - 1 indicating that the index at these
+            positions matches the corresponding target values. Missing values
+            in the target are marked by -1.
+        missing : ndarray of int
+            An indexer into the target of the values not found.
+            These correspond to the -1 in the indexer array
+        """
+
+    @Appender(_index_shared_docs['get_indexer_non_unique'])
     def get_indexer_non_unique(self, target):
-        """ return an indexer suitable for taking from a non unique index
-            return the labels in the same order as the target, and
-            return a missing indexer into the target (missing are marked as -1
-            in the indexer); target must be an iterable """
         target = _ensure_index(target)
         pself, ptarget = self._possibly_promote(target)
         if pself is not self or ptarget is not target:
@@ -2516,7 +2535,10 @@ def get_indexer_non_unique(self, target):
         return Index(indexer), missing
 
     def get_indexer_for(self, target, **kwargs):
-        """ guaranteed return of an indexer even when non-unique """
+        """
+        guaranteed return of an indexer even when non-unique
+        This dispatches to get_indexer or get_indexer_nonunique as appropriate
+        """
         if self.is_unique:
             return self.get_indexer(target, **kwargs)
         indexer, _ = self.get_indexer_non_unique(target, **kwargs)

pandas/indexes/category.py

@@ -425,34 +425,8 @@ def _reindex_non_unique(self, target):
 
         return new_target, indexer, new_indexer
 
+    @Appender(_index_shared_docs['get_indexer'])
     def get_indexer(self, target, method=None, limit=None, tolerance=None):
-        """
-        Compute indexer and mask for new index given the current index. The
-        indexer should be then used as an input to ndarray.take to align the
-        current data to the new index. The mask determines whether labels are
-        found or not in the current index
-
-        Parameters
-        ----------
-        target : MultiIndex or Index (of tuples)
-        method : {'pad', 'ffill', 'backfill', 'bfill'}
-            pad / ffill: propagate LAST valid observation forward to next valid
-            backfill / bfill: use NEXT valid observation to fill gap
-
-        Notes
-        -----
-        This is a low-level method and probably should be used at your own risk
-
-        Examples
-        --------
-        >>> indexer, mask = index.get_indexer(new_index)
-        >>> new_values = cur_values.take(indexer)
-        >>> new_values[-mask] = np.nan
-
-        Returns
-        -------
-        (indexer, mask) : (ndarray, ndarray)
-        """
         method = missing.clean_reindex_fill_method(method)
         target = ibase._ensure_index(target)
 
@@ -472,10 +446,8 @@ def get_indexer(self, target, method=None, limit=None, tolerance=None):
 
         return _ensure_platform_int(indexer)
 
+    @Appender(_index_shared_docs['get_indexer_non_unique'])
     def get_indexer_non_unique(self, target):
-        """ this is the same for a CategoricalIndex for get_indexer; the API
-        returns the missing values as well
-        """
         target = ibase._ensure_index(target)
 
         if isinstance(target, CategoricalIndex):

pandas/indexes/multi.py

@@ -1564,34 +1564,8 @@ def sortlevel(self, level=0, ascending=True, sort_remaining=True):
 
         return new_index, indexer
 
+    @Appender(_index_shared_docs['get_indexer'])
     def get_indexer(self, target, method=None, limit=None, tolerance=None):
-        """
-        Compute indexer and mask for new index given the current index. The
-        indexer should be then used as an input to ndarray.take to align the
-        current data to the new index. The mask determines whether labels are
-        found or not in the current index
-
-        Parameters
-        ----------
-        target : MultiIndex or Index (of tuples)
-        method : {'pad', 'ffill', 'backfill', 'bfill'}
-            pad / ffill: propagate LAST valid observation forward to next valid
-            backfill / bfill: use NEXT valid observation to fill gap
-
-        Notes
-        -----
-        This is a low-level method and probably should be used at your own risk
-
-        Examples
-        --------
-        >>> indexer, mask = index.get_indexer(new_index)
-        >>> new_values = cur_values.take(indexer)
-        >>> new_values[-mask] = np.nan
-
-        Returns
-        -------
-        (indexer, mask) : (ndarray, ndarray)
-        """
         method = missing.clean_reindex_fill_method(method)
         target = _ensure_index(target)
 

pandas/tseries/period.py

@@ -759,6 +759,7 @@ def get_value(self, series, key):
             return com._maybe_box(self, self._engine.get_value(s, key),
                                   series, key)
 
+    @Appender(_index_shared_docs['get_indexer'])
     def get_indexer(self, target, method=None, limit=None, tolerance=None):
         target = _ensure_index(target)