API: Make Series.searchsorted return a scalar, when supplied a scalar

Author: topper-123

doc/source/whatsnew/v0.24.0.rst

@@ -1008,6 +1008,7 @@ Other API Changes
 - Slicing a single row of a DataFrame with multiple ExtensionArrays of the same type now preserves the dtype, rather than coercing to object (:issue:`22784`)
 - :class:`DateOffset` attribute `_cacheable` and method `_should_cache` have been removed (:issue:`23118`)
 - Comparing :class:`Timedelta` to be less or greater than unknown types now raises a ``TypeError`` instead of returning ``False`` (:issue:`20829`)
+- :meth:`Series.searchsorted`, when supplied a scalar value to search for, now returns a scalar instead of an array (:issue:`xxxxx`).
 - :meth:`Categorical.searchsorted`, when supplied a scalar value to search for, now returns a scalar instead of an array (:issue:`23466`).
 - :meth:`Categorical.searchsorted` now raises a ``KeyError`` rather that a ``ValueError``, if a searched for key is not found in its categories (:issue:`23466`).
 - :meth:`Index.hasnans` and :meth:`Series.hasnans` now always return a python boolean. Previously, a python or a numpy boolean could be returned, depending on circumstances (:issue:`23294`).

pandas/core/base.py

@@ -1195,8 +1195,8 @@ def factorize(self, sort=False, na_sentinel=-1):
 
         Parameters
         ----------
-        value : array_like
-            Values to insert into `self`.
+        value : scalar or array_like
+            Value(s) to insert into `self`.
         side : {'left', 'right'}, optional
             If 'left', the index of the first suitable location found is given.
             If 'right', return the last such index.  If there is no suitable
@@ -1207,8 +1207,14 @@ def factorize(self, sort=False, na_sentinel=-1):
 
         Returns
         -------
-        indices : array of ints
-            Array of insertion points with the same shape as `value`.
+        int or array of ints
+            A scalar or array of insertion points with the
+            same shape as `value`.
+            
+            .. versionchanged :: 0.24.0
+                Ìf `value`is a scalar, an int is now always returned.
+                Previously, scalar inputs returned an 1-item array for
+                :class:`Series` and :class:`Categorical`.
 
         See Also
         --------
@@ -1229,7 +1235,7 @@ def factorize(self, sort=False, na_sentinel=-1):
         dtype: int64
 
         >>> x.searchsorted(4)
-        array([3])
+        3
 
         >>> x.searchsorted([0, 4])
         array([0, 3])
@@ -1246,7 +1252,7 @@ def factorize(self, sort=False, na_sentinel=-1):
         Categories (4, object): [apple < bread < cheese < milk]
 
         >>> x.searchsorted('bread')
-        array([1])     # Note: an array, not a scalar
+        1
 
         >>> x.searchsorted(['bread'], side='right')
         array([3])

pandas/core/series.py

@@ -2149,8 +2149,10 @@ def __rmatmul__(self, other):
     def searchsorted(self, value, side='left', sorter=None):
         if sorter is not None:
             sorter = ensure_platform_int(sorter)
-        return self._values.searchsorted(Series(value)._values,
-                                         side=side, sorter=sorter)
+        result = self._values.searchsorted(Series(value)._values,
+                                           side=side, sorter=sorter)
+
+        return result[0] if is_scalar(value) else result
 
     # -------------------------------------------------------------------
     # Combination

pandas/tests/arrays/categorical/test_analytics.py

@@ -86,9 +86,11 @@ def test_searchsorted(self):
         # Searching for single item argument, side='left' (default)
         res_cat = c1.searchsorted('apple')
         assert res_cat == 2
+        assert tm.is_scalar(res_cat)
 
         res_ser = s1.searchsorted('apple')
         assert res_ser == 2
+        assert tm.is_scalar(res_ser)
 
         # Searching for single item array, side='left' (default)
         res_cat = c1.searchsorted(['bread'])

pandas/tests/series/test_analytics.py

@@ -1398,17 +1398,19 @@ def test_numpy_repeat(self):
     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))
+        result = s.searchsorted(1, side='left')
+        assert tm.is_scalar(result)
+        assert result == 0
 
-        idx = s.searchsorted(1, side='right')
-        tm.assert_numpy_array_equal(idx, np.array([1], dtype=np.intp))
+        result = s.searchsorted(1, side='right')
+        assert tm.is_scalar(result)
+        assert result == 1
 
     def test_searchsorted_numeric_dtypes_scalar(self):
         s = Series([1, 2, 90, 1000, 3e9])
         r = s.searchsorted(30)
-        e = 2
-        assert r == e
+        assert tm.is_scalar(r)
+        assert r == 2
 
         r = s.searchsorted([30])
         e = np.array([2], dtype=np.intp)
@@ -1424,8 +1426,8 @@ def test_search_sorted_datetime64_scalar(self):
         s = Series(pd.date_range('20120101', periods=10, freq='2D'))
         v = pd.Timestamp('20120102')
         r = s.searchsorted(v)
-        e = 1
-        assert r == e
+        assert tm.is_scalar(r)
+        assert r == 1
 
     def test_search_sorted_datetime64_list(self):
         s = Series(pd.date_range('20120101', periods=10, freq='2D'))

pandas/util/testing.py

@@ -27,7 +27,8 @@
     is_bool, is_categorical_dtype, is_datetime64_dtype, is_datetime64tz_dtype,
     is_datetimelike_v_numeric, is_datetimelike_v_object,
     is_extension_array_dtype, is_interval_dtype, is_list_like, is_number,
-    is_period_dtype, is_sequence, is_timedelta64_dtype, needs_i8_conversion)
+    is_period_dtype, is_scalar, is_sequence, is_timedelta64_dtype,
+    needs_i8_conversion)  # noqa
 from pandas.core.dtypes.missing import array_equivalent
 
 import pandas as pd