DOC: use shared_docs for Index.get_indexer, get_indexer_non_unique (pandas-dev#15411)

* STYLE: flake8 upgraded to 3.3 on conda

fixes for E305, 2 blank lines after a class definition

* DOC: use shared_docs for Index.get_indexer, get_indexer_non_unique

fix non-populated doc-strings for some methods in Index (take)

Author: jreback

pandas/indexes/base.py

@@ -65,6 +65,7 @@
 _unsortable_types = frozenset(('mixed', 'mixed-integer'))
 
 _index_doc_kwargs = dict(klass='Index', inplace='',
+                         target_klass='Index',
                          unique='Index', duplicated='np.ndarray')
 _index_shared_docs = dict()
 
@@ -1605,7 +1606,7 @@ def _append_same_dtype(self, to_concat, name):
         numpy.ndarray.take
         """
 
-    @Appender(_index_shared_docs['take'])
+    @Appender(_index_shared_docs['take'] % _index_doc_kwargs)
     def take(self, indices, axis=0, allow_fill=True,
              fill_value=None, **kwargs):
         nv.validate_take(tuple(), kwargs)
@@ -2350,15 +2351,14 @@ 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.
 
         Parameters
         ----------
-        target : Index
+        target : %(target_klass)s
         method : {None, 'pad'/'ffill', 'backfill'/'bfill', 'nearest'}, optional
             * default: exact matches only.
             * pad / ffill: find the PREVIOUS index value if no exact match.
@@ -2387,6 +2387,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'] % _index_doc_kwargs)
+    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 +2499,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 : %(target_klass)s
+
+        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'] % _index_doc_kwargs)
     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 +2536,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

@@ -18,6 +18,8 @@
 import pandas.core.base as base
 import pandas.core.missing as missing
 import pandas.indexes.base as ibase
+_index_doc_kwargs = dict(ibase._index_doc_kwargs)
+_index_doc_kwargs.update(dict(target_klass='CategoricalIndex'))
 
 
 class CategoricalIndex(Index, base.PandasDelegate):
@@ -289,7 +291,7 @@ def _engine(self):
     def is_unique(self):
         return not self.duplicated().any()
 
-    @Appender(base._shared_docs['unique'] % ibase._index_doc_kwargs)
+    @Appender(base._shared_docs['unique'] % _index_doc_kwargs)
     def unique(self):
         result = base.IndexOpsMixin.unique(self)
         # CategoricalIndex._shallow_copy uses keeps original categories
@@ -299,7 +301,7 @@ def unique(self):
 
     @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
                                                    False: 'first'})
-    @Appender(base._shared_docs['duplicated'] % ibase._index_doc_kwargs)
+    @Appender(base._shared_docs['duplicated'] % _index_doc_kwargs)
     def duplicated(self, keep='first'):
         from pandas.hashtable import duplicated_int64
         codes = self.codes.astype('i8')
@@ -425,34 +427,8 @@ def _reindex_non_unique(self, target):
 
         return new_target, indexer, new_indexer
 
+    @Appender(_index_shared_docs['get_indexer'] % _index_doc_kwargs)
     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 +448,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'] % _index_doc_kwargs)
     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):
@@ -497,7 +471,7 @@ def _convert_list_indexer(self, keyarr, kind=None):
 
         return None
 
-    @Appender(_index_shared_docs['take'])
+    @Appender(_index_shared_docs['take'] % _index_doc_kwargs)
     def take(self, indices, axis=0, allow_fill=True,
              fill_value=None, **kwargs):
         nv.validate_take(tuple(), kwargs)

pandas/indexes/multi.py

@@ -43,6 +43,10 @@
                                  _get_na_value, InvalidIndexError,
                                  _index_shared_docs)
 import pandas.indexes.base as ibase
+_index_doc_kwargs = dict(ibase._index_doc_kwargs)
+_index_doc_kwargs.update(
+    dict(klass='MultiIndex',
+         target_klass='MultiIndex or list of tuples'))
 
 
 class MultiIndex(Index):
@@ -755,7 +759,7 @@ def f(k, stringify):
 
     @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
                                                    False: 'first'})
-    @Appender(base._shared_docs['duplicated'] % ibase._index_doc_kwargs)
+    @Appender(base._shared_docs['duplicated'] % _index_doc_kwargs)
     def duplicated(self, keep='first'):
         from pandas.core.sorting import get_group_index
         from pandas.hashtable import duplicated_int64
@@ -1244,7 +1248,7 @@ def __getitem__(self, key):
                               names=self.names, sortorder=sortorder,
                               verify_integrity=False)
 
-    @Appender(_index_shared_docs['take'])
+    @Appender(_index_shared_docs['take'] % _index_doc_kwargs)
     def take(self, indices, axis=0, allow_fill=True,
              fill_value=None, **kwargs):
         nv.validate_take(tuple(), kwargs)
@@ -1564,34 +1568,8 @@ def sortlevel(self, level=0, ascending=True, sort_remaining=True):
 
         return new_index, indexer
 
+    @Appender(_index_shared_docs['get_indexer'] % _index_doc_kwargs)
     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)
 
@@ -1633,6 +1611,10 @@ def get_indexer(self, target, method=None, limit=None, tolerance=None):
 
         return _ensure_platform_int(indexer)
 
+    @Appender(_index_shared_docs['get_indexer_non_unique'] % _index_doc_kwargs)
+    def get_indexer_non_unique(self, target):
+        return super(MultiIndex, self).get_indexer_non_unique(target)
+
     def reindex(self, target, method=None, level=None, limit=None,
                 tolerance=None):
         """

pandas/tseries/period.py

@@ -44,6 +44,10 @@
 from pandas.lib import infer_dtype
 import pandas.tslib as tslib
 from pandas.compat import zip, u
+import pandas.indexes.base as ibase
+_index_doc_kwargs = dict(ibase._index_doc_kwargs)
+_index_doc_kwargs.update(
+    dict(target_klass='PeriodIndex or list of Periods'))
 
 
 def _field_accessor(name, alias, docstring=None):
@@ -759,6 +763,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'] % _index_doc_kwargs)
     def get_indexer(self, target, method=None, limit=None, tolerance=None):
         target = _ensure_index(target)