DEPR: Deprecate Index.set_value

doc/source/reference/indexing.rst

@@ -166,7 +166,6 @@ Selecting
    Index.get_slice_bound
    Index.get_value
    Index.get_values
-   Index.set_value
    Index.isin
    Index.slice_indexer
    Index.slice_locs

doc/source/whatsnew/v1.0.0.rst

@@ -123,7 +123,9 @@ Documentation Improvements
 Deprecations
 ~~~~~~~~~~~~
 
--
+- `Index.set_value` has been deprecated. For a given index ``idx``, array ``arr``,
+  value in ``idx`` of ``idx_val`` and a new value of ``val``, ``idx.set_value(arr, idx_val, val)``
+  is equivalent to ``arr[idx.get_loc(idx_val)] = val``, which should be used instead (:issue:`28621`).
 -
 
 .. _whatsnew_1000.prior_deprecations:

pandas/core/indexes/base.py

@@ -205,7 +205,9 @@ class Index(IndexOpsMixin, PandasObject):
     """
 
     # tolist is not actually deprecated, just suppressed in the __dir__
-    _deprecations = DirNamesMixin._deprecations | frozenset(["tolist", "dtype_str"])
+    _deprecations = DirNamesMixin._deprecations | frozenset(
+        ["tolist", "dtype_str", "set_value"]
+    )
 
     # To hand over control to subclasses
     _join_precedence = 1
@@ -4680,10 +4682,20 @@ def set_value(self, arr, key, value):
         """
         Fast lookup of value from 1-dimensional ndarray.
 
+        .. deprecated:: 1.0
+
         Notes
         -----
         Only use this if you know what you're doing.
         """
+        warnings.warn(
+            (
+                "The 'set_value' method is deprecated, and "
+                "will be removed in a future version."
+            ),
+            FutureWarning,
+            stacklevel=2,
+        )
         self._engine.set_value(
             com.values_from_object(arr), com.values_from_object(key), value
         )

pandas/tests/indexes/test_base.py

@@ -1908,16 +1908,21 @@ def test_is_monotonic_incomparable(self, attr):
         index = Index([5, datetime.now(), 7])
         assert not getattr(index, attr)
 
-    def test_get_set_value(self):
+    def test_set_value_deprecated(self):
+        # GH 28621
+        idx = self.create_index()
+        arr = np.array([1, 2, 3])
+        with tm.assert_produces_warning(FutureWarning):
+            idx.set_value(arr, idx[1], 80)
+        assert arr[1] == 80
+
+    def test_get_value(self):
         # TODO: Remove function? GH 19728
         values = np.random.randn(100)
         date = self.dateIndex[67]
 
         assert_almost_equal(self.dateIndex.get_value(values, date), values[67])
 
-        self.dateIndex.set_value(values, date, 10)
-        assert values[67] == 10
-
     @pytest.mark.parametrize("values", [["foo", "bar", "quux"], {"foo", "bar", "quux"}])
     @pytest.mark.parametrize(
         "index,expected",