Standardize function signatures

Standardize the following function signatures:

1) repeat(reps, *args, **kwargs)
2) searchsorted(key, side='left', sorter=None)

Closes gh-12662.

Author: gfyoung

doc/source/whatsnew/v0.20.0.txt

@@ -54,6 +54,10 @@ Other API Changes
 Deprecations
 ^^^^^^^^^^^^
 
+- ``Series.repeat()`` has deprecated the ``reps`` parameter in favor of ``repeats`` (:issue:`12662`)
+- ``Index.repeat()`` and ``MultiIndex.repeat()`` have deprecated the ``n`` parameter in favor of ``repeats`` (:issue:`12662`)
+- ``Categorical.searchsorted()`` and ``Series.searchsorted()`` have deprecated the ``v`` parameter in favor of ``value`` (:issue:`12662`)
+- ``IndexOpsMixin.searchsorted()``, ``TimedeltaIndex.searchsorted()``, ``DatetimeIndex.searchsorted()``, and ``PeriodIndex.searchsorted()`` have deprecated the ``key`` parameter in favor of ``value`` (:issue:`12662`)
 
 
 

pandas/core/base.py

@@ -1091,12 +1091,12 @@ def factorize(self, sort=False, na_sentinel=-1):
         """Find indices where elements should be inserted to maintain order.
 
         Find the indices into a sorted %(klass)s `self` such that, if the
-        corresponding elements in `v` were inserted before the indices, the
-        order of `self` would be preserved.
+        corresponding elements in `value` were inserted before the indices,
+        the order of `self` would be preserved.
 
         Parameters
         ----------
-        %(value)s : array_like
+        value : array_like
             Values to insert into `self`.
         side : {'left', 'right'}, optional
             If 'left', the index of the first suitable location found is given.
@@ -1109,7 +1109,7 @@ def factorize(self, sort=False, na_sentinel=-1):
         Returns
         -------
         indices : array of ints
-            Array of insertion points with the same shape as `v`.
+            Array of insertion points with the same shape as `value`.
 
         See Also
         --------
@@ -1149,11 +1149,12 @@ def factorize(self, sort=False, na_sentinel=-1):
         array([3, 4])    # eggs before milk
         """)
 
-    @Substitution(klass='IndexOpsMixin', value='key')
+    @Substitution(klass='IndexOpsMixin')
     @Appender(_shared_docs['searchsorted'])
-    def searchsorted(self, key, side='left', sorter=None):
+    @deprecate_kwarg(old_arg_name='key', new_arg_name='value')
+    def searchsorted(self, value, side='left', sorter=None):
         # needs coercion on the key (DatetimeIndex does already)
-        return self.values.searchsorted(key, side=side, sorter=sorter)
+        return self.values.searchsorted(value, side=side, sorter=sorter)
 
     _shared_docs['drop_duplicates'] = (
         """Return %(klass)s with duplicate values removed

pandas/core/categorical.py

@@ -1076,17 +1076,18 @@ def memory_usage(self, deep=False):
         """
         return self._codes.nbytes + self._categories.memory_usage(deep=deep)
 
-    @Substitution(klass='Categorical', value='v')
+    @Substitution(klass='Categorical')
     @Appender(_shared_docs['searchsorted'])
-    def searchsorted(self, v, side='left', sorter=None):
+    @deprecate_kwarg(old_arg_name='v', new_arg_name='value')
+    def searchsorted(self, value, side='left', sorter=None):
         if not self.ordered:
             raise ValueError("Categorical not ordered\nyou can use "
                              ".as_ordered() to change the Categorical to an "
                              "ordered one")
 
         from pandas.core.series import Series
         values_as_codes = self.categories.values.searchsorted(
-            Series(v).values, side=side)
+            Series(value).values, side=side)
 
         return self.codes.searchsorted(values_as_codes, sorter=sorter)
 

pandas/core/series.py

@@ -832,18 +832,19 @@ def _set_values(self, key, value):
         self._data = self._data.setitem(indexer=key, value=value)
         self._maybe_update_cacher()
 
-    def repeat(self, reps, *args, **kwargs):
+    @deprecate_kwarg(old_arg_name='reps', new_arg_name='repeats')
+    def repeat(self, repeats, *args, **kwargs):
         """
         Repeat elements of an Series. Refer to `numpy.ndarray.repeat`
-        for more information about the `reps` argument.
+        for more information about the `repeats` argument.
 
         See also
         --------
         numpy.ndarray.repeat
         """
         nv.validate_repeat(args, kwargs)
-        new_index = self.index.repeat(reps)
-        new_values = self._values.repeat(reps)
+        new_index = self.index.repeat(repeats)
+        new_values = self._values.repeat(repeats)
         return self._constructor(new_values,
                                  index=new_index).__finalize__(self)
 
@@ -1509,12 +1510,13 @@ def dot(self, other):
         else:  # pragma: no cover
             raise TypeError('unsupported type: %s' % type(other))
 
-    @Substitution(klass='Series', value='v')
+    @Substitution(klass='Series')
     @Appender(base._shared_docs['searchsorted'])
-    def searchsorted(self, v, side='left', sorter=None):
+    @deprecate_kwarg(old_arg_name='v', new_arg_name='value')
+    def searchsorted(self, value, side='left', sorter=None):
         if sorter is not None:
             sorter = _ensure_platform_int(sorter)
-        return self._values.searchsorted(Series(v)._values,
+        return self._values.searchsorted(Series(value)._values,
                                          side=side, sorter=sorter)
 
     # -------------------------------------------------------------------

pandas/indexes/base.py

@@ -535,17 +535,18 @@ def tolist(self):
         """
         return list(self.values)
 
-    def repeat(self, n, *args, **kwargs):
+    @deprecate_kwarg(old_arg_name='n', new_arg_name='repeats')
+    def repeat(self, repeats, *args, **kwargs):
         """
         Repeat elements of an Index. Refer to `numpy.ndarray.repeat`
-        for more information about the `n` argument.
+        for more information about the `repeats` argument.
 
         See also
         --------
         numpy.ndarray.repeat
         """
         nv.validate_repeat(args, kwargs)
-        return self._shallow_copy(self._values.repeat(n))
+        return self._shallow_copy(self._values.repeat(repeats))
 
     def where(self, cond, other=None):
         """

pandas/indexes/multi.py

@@ -1166,10 +1166,11 @@ def append(self, other):
     def argsort(self, *args, **kwargs):
         return self.values.argsort(*args, **kwargs)
 
-    def repeat(self, n, *args, **kwargs):
+    @deprecate_kwarg(old_arg_name='n', new_arg_name='repeats')
+    def repeat(self, repeats, *args, **kwargs):
         nv.validate_repeat(args, kwargs)
         return MultiIndex(levels=self.levels,
-                          labels=[label.view(np.ndarray).repeat(n)
+                          labels=[label.view(np.ndarray).repeat(repeats)
                                   for label in self.labels], names=self.names,
                           sortorder=self.sortorder, verify_integrity=False)
 

pandas/tests/indexes/test_base.py

@@ -17,6 +17,7 @@
                     Float64Index, Int64Index,
                     CategoricalIndex, DatetimeIndex, TimedeltaIndex,
                     PeriodIndex)
+from pandas.core.index import _get_combined_index
 from pandas.util.testing import assert_almost_equal
 from pandas.compat.numpy import np_datetime64_compat
 
@@ -1976,8 +1977,19 @@ def test_dropna(self):
         with tm.assertRaisesRegexp(ValueError, msg):
             pd.Index([1, 2, 3]).dropna(how='xxx')
 
+    def test_get_combined_index(self):
+        result = _get_combined_index([])
+        tm.assert_index_equal(result, Index([]))
 
-def test_get_combined_index():
-    from pandas.core.index import _get_combined_index
-    result = _get_combined_index([])
-    tm.assert_index_equal(result, Index([]))
+    def test_repeat(self):
+        repeats = 2
+        idx = pd.Index([1, 2, 3])
+        expected = pd.Index([1, 1, 2, 2, 3, 3])
+
+        result = idx.repeat(repeats)
+        tm.assert_index_equal(result, expected)
+
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            result = idx.repeat(n=repeats)
+            tm.assert_index_equal(result, expected)

pandas/tests/indexes/test_multi.py

@@ -97,6 +97,10 @@ def test_repeat(self):
             numbers, names.repeat(reps)], names=names)
         tm.assert_index_equal(m.repeat(reps), expected)
 
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            tm.assert_index_equal(m.repeat(n=reps), expected)
+
     def test_numpy_repeat(self):
         reps = 2
         numbers = [1, 2, 3]

pandas/tests/series/test_analytics.py

@@ -1363,6 +1363,11 @@ def test_repeat(self):
         exp = Series(s.values.repeat(5), index=s.index.values.repeat(5))
         assert_series_equal(reps, exp)
 
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            result = s.repeat(reps=5)
+            assert_series_equal(result, exp)
+
         to_rep = [2, 3, 4]
         reps = s.repeat(to_rep)
         exp = Series(s.values.repeat(to_rep),
@@ -1378,6 +1383,20 @@ def test_numpy_repeat(self):
         msg = "the 'axis' parameter is not supported"
         tm.assertRaisesRegexp(ValueError, msg, np.repeat, s, 2, axis=0)
 
+    def test_searchsorted(self):
+        s = Series([1, 2, 3])
+
+        idx = s.searchsorted(1, side='left')
+        tm.assert_numpy_array_equal(idx, np.array([0], dtype=np.intp))
+
+        idx = s.searchsorted(1, side='right')
+        tm.assert_numpy_array_equal(idx, np.array([1], dtype=np.intp))
+
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            idx = s.searchsorted(v=1, side='left')
+            tm.assert_numpy_array_equal(idx, np.array([0], dtype=np.intp))
+
     def test_searchsorted_numeric_dtypes_scalar(self):
         s = Series([1, 2, 90, 1000, 3e9])
         r = s.searchsorted(30)

pandas/tests/test_categorical.py

@@ -1593,6 +1593,12 @@ def test_searchsorted(self):
         self.assert_numpy_array_equal(res, exp)
         self.assert_numpy_array_equal(res, chk)
 
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            res = c1.searchsorted(v=['bread'])
+            exp = np.array([1], dtype=np.intp)
+            tm.assert_numpy_array_equal(res, exp)
+
     def test_deprecated_labels(self):
         # TODO: labels is deprecated and should be removed in 0.18 or 2017,
         # whatever is earlier