DEPR: deprecate .get_value and .set_value for Series, DataFrame, Panel, SparseSeries, SparseDataFrame

closes #15269

Author: jreback

doc/source/whatsnew/v0.21.0.txt

@@ -572,6 +572,7 @@ Deprecations
 - :func:`DataFrame.as_blocks` is deprecated, as this is exposing the internal implementation (:issue:`17302`)
 - ``pd.TimeGrouper`` is deprecated in favor of :class:`pandas.Grouper` (:issue:`16747`)
 - ``cdate_range`` has been deprecated in favor of :func:`bdate_range`, which has gained ``weekmask`` and ``holidays`` parameters for building custom frequency date ranges. See the :ref:`documentation <timeseries.custom-freq-ranges>` for more details (:issue:`17596`)
+- ``.get_value`` and ``.set_value`` on ``Series``, ``DataFrame``, ``Panel``, ``SparseSeries``, and ``SparseDataFrame`` are deprecated in favor of using ``.iat[]`` or ``.at[]`` accessors
 
 .. _whatsnew_0210.deprecations.argmin_min:
 

pandas/core/frame.py

@@ -299,7 +299,8 @@ def _constructor(self):
         return DataFrame
 
     _constructor_sliced = Series
-    _deprecations = NDFrame._deprecations | frozenset(['sortlevel'])
+    _deprecations = NDFrame._deprecations | frozenset(
+        ['sortlevel', 'get_value', 'set_value'])
 
     @property
     def _constructor_expanddim(self):
@@ -1920,6 +1921,29 @@ def get_value(self, index, col, takeable=False):
         """
         Quickly retrieve single value at passed column and index
 
+        .. deprecated:: 0.21.0
+
+        Parameters
+        ----------
+        index : row label
+        col : column label
+        takeable : interpret the index/col as indexers, default False
+
+        Returns
+        -------
+        value : scalar value
+        """
+
+        warnings.warn("get_value is deprecated and will be removed "
+                      "in a future release. Please use "
+                      ".at[] or .iat[] accessors instead", FutureWarning,
+                      stacklevel=2)
+        return self._get_value(index, col, takeable=takeable)
+
+    def _get_value(self, index, col, takeable=False):
+        """
+        Quickly retrieve single value at passed column and index
+
         Parameters
         ----------
         index : row label
@@ -1946,12 +1970,37 @@ def get_value(self, index, col, takeable=False):
             # use positional
             col = self.columns.get_loc(col)
             index = self.index.get_loc(index)
-            return self.get_value(index, col, takeable=True)
+            return self._get_value(index, col, takeable=True)
 
     def set_value(self, index, col, value, takeable=False):
         """
         Put single value at passed column and index
 
+        .. deprecated:: 0.21.0
+
+        Parameters
+        ----------
+        index : row label
+        col : column label
+        value : scalar value
+        takeable : interpret the index/col as indexers, default False
+
+        Returns
+        -------
+        frame : DataFrame
+            If label pair is contained, will be reference to calling DataFrame,
+            otherwise a new object
+        """
+        warnings.warn("set_value is deprecated and will be removed "
+                      "in a future release. Please use "
+                      ".at[] or .iat[] accessors instead", FutureWarning,
+                      stacklevel=2)
+        return self._set_value(index, col, value, takeable=takeable)
+
+    def _set_value(self, index, col, value, takeable=False):
+        """
+        Put single value at passed column and index
+
         Parameters
         ----------
         index : row label
@@ -1968,7 +2017,7 @@ def set_value(self, index, col, value, takeable=False):
         try:
             if takeable is True:
                 series = self._iget_item_cache(col)
-                return series.set_value(index, value, takeable=True)
+                return series._set_value(index, value, takeable=True)
 
             series = self._get_item_cache(col)
             engine = self.index._engine
@@ -2787,7 +2836,7 @@ def lookup(self, row_labels, col_labels):
         else:
             result = np.empty(n, dtype='O')
             for i, (r, c) in enumerate(zip(row_labels, col_labels)):
-                result[i] = self.get_value(r, c)
+                result[i] = self._get_value(r, c)
 
         if is_object_dtype(result):
             result = lib.maybe_convert_objects(result)

pandas/core/indexing.py

@@ -109,7 +109,7 @@ def __getitem__(self, key):
         if type(key) is tuple:
             key = tuple(com._apply_if_callable(x, self.obj) for x in key)
             try:
-                values = self.obj.get_value(*key)
+                values = self.obj._get_value(*key)
                 if is_scalar(values):
                     return values
             except Exception:
@@ -1481,7 +1481,7 @@ def _is_scalar_access(self, key):
     def _getitem_scalar(self, key):
         # a fast-path to scalar access
         # if not, raise
-        values = self.obj.get_value(*key)
+        values = self.obj._get_value(*key)
         return values
 
     def _get_partial_string_timestamp_match_key(self, key, labels):
@@ -1637,7 +1637,7 @@ def _is_scalar_access(self, key):
     def _getitem_scalar(self, key):
         # a fast-path to scalar access
         # if not, raise
-        values = self.obj.get_value(*key, takeable=True)
+        values = self.obj._get_value(*key, takeable=True)
         return values
 
     def _is_valid_integer(self, key, axis):
@@ -1794,7 +1794,7 @@ def __getitem__(self, key):
                 raise ValueError('Invalid call for scalar access (getting)!')
 
         key = self._convert_key(key)
-        return self.obj.get_value(*key, takeable=self._takeable)
+        return self.obj._get_value(*key, takeable=self._takeable)
 
     def __setitem__(self, key, value):
         if isinstance(key, tuple):
@@ -1810,7 +1810,7 @@ def __setitem__(self, key, value):
                              '(setting)!')
         key = list(self._convert_key(key, is_setter=True))
         key.append(value)
-        self.obj.set_value(*key, takeable=self._takeable)
+        self.obj._set_value(*key, takeable=self._takeable)
 
 
 class _AtIndexer(_ScalarAccessIndexer):

pandas/core/panel.py

@@ -471,6 +471,29 @@ def get_value(self, *args, **kwargs):
         """
         Quickly retrieve single value at (item, major, minor) location
 
+        .. deprecated:: 0.21.0
+
+        Parameters
+        ----------
+        item : item label (panel item)
+        major : major axis label (panel item row)
+        minor : minor axis label (panel item column)
+        takeable : interpret the passed labels as indexers, default False
+
+        Returns
+        -------
+        value : scalar value
+        """
+        warnings.warn("get_value is deprecated and will be removed "
+                      "in a future release. Please use "
+                      ".at[] or .iat[] accessors instead", FutureWarning,
+                      stacklevel=2)
+        return self._get_value(*args, **kwargs)
+
+    def _get_value(self, *args, **kwargs):
+        """
+        Quickly retrieve single value at (item, major, minor) location
+
         Parameters
         ----------
         item : item label (panel item)
@@ -501,12 +524,38 @@ def get_value(self, *args, **kwargs):
         else:
             lower = self._get_item_cache(args[0])
 
-        return lower.get_value(*args[1:], takeable=takeable)
+        return lower._get_value(*args[1:], takeable=takeable)
 
     def set_value(self, *args, **kwargs):
         """
         Quickly set single value at (item, major, minor) location
 
+        .. deprecated:: 0.21.0
+
+        Parameters
+        ----------
+        item : item label (panel item)
+        major : major axis label (panel item row)
+        minor : minor axis label (panel item column)
+        value : scalar
+        takeable : interpret the passed labels as indexers, default False
+
+        Returns
+        -------
+        panel : Panel
+            If label combo is contained, will be reference to calling Panel,
+            otherwise a new object
+        """
+        warnings.warn("set_value is deprecated and will be removed "
+                      "in a future release. Please use "
+                      ".at[] or .iat[] accessors instead", FutureWarning,
+                      stacklevel=2)
+        return self._set_value(*args, **kwargs)
+
+    def _set_value(self, *args, **kwargs):
+        """
+        Quickly set single value at (item, major, minor) location
+
         Parameters
         ----------
         item : item label (panel item)
@@ -541,7 +590,7 @@ def set_value(self, *args, **kwargs):
             else:
                 lower = self._get_item_cache(args[0])
 
-            lower.set_value(*args[1:], takeable=takeable)
+            lower._set_value(*args[1:], takeable=takeable)
             return self
         except KeyError:
             axes = self._expand_axes(args)
@@ -554,7 +603,7 @@ def set_value(self, *args, **kwargs):
             if made_bigger:
                 maybe_cast_item(result, args[0], likely_dtype)
 
-            return result.set_value(*args)
+            return result._set_value(*args)
 
     def _box_item_values(self, key, values):
         if self.ndim == values.ndim:

pandas/core/series.py

@@ -147,7 +147,7 @@ class Series(base.IndexOpsMixin, generic.NDFrame):
     _metadata = ['name']
     _accessors = frozenset(['dt', 'cat', 'str'])
     _deprecations = generic.NDFrame._deprecations | frozenset(
-        ['sortlevel', 'reshape'])
+        ['sortlevel', 'reshape', 'get_value', 'set_value'])
     _allow_index_ops = True
 
     def __init__(self, data=None, index=None, dtype=None, name=None,
@@ -902,6 +902,27 @@ def get_value(self, label, takeable=False):
         """
         Quickly retrieve single value at passed index label
 
+        .. deprecated:: 0.21.0
+
+        Parameters
+        ----------
+        index : label
+        takeable : interpret the index as indexers, default False
+
+        Returns
+        -------
+        value : scalar value
+        """
+        warnings.warn("get_value is deprecated and will be removed "
+                      "in a future release. Please use "
+                      ".at[] or .iat[] accessors instead", FutureWarning,
+                      stacklevel=2)
+        return self._get_value(label, takeable=takeable)
+
+    def _get_value(self, label, takeable=False):
+        """
+        Quickly retrieve single value at passed index label
+
         Parameters
         ----------
         index : label
@@ -921,6 +942,34 @@ def set_value(self, label, value, takeable=False):
         new object is created with the label placed at the end of the result
         index
 
+        .. deprecated:: 0.21.0
+
+        Parameters
+        ----------
+        label : object
+            Partial indexing with MultiIndex not allowed
+        value : object
+            Scalar value
+        takeable : interpret the index as indexers, default False
+
+        Returns
+        -------
+        series : Series
+            If label is contained, will be reference to calling Series,
+            otherwise a new object
+        """
+        warnings.warn("set_value is deprecated and will be removed "
+                      "in a future release. Please use "
+                      ".at[] or .iat[] accessors instead", FutureWarning,
+                      stacklevel=2)
+        return self._set_value(label, value, takeable=takeable)
+
+    def _set_value(self, label, value, takeable=False):
+        """
+        Quickly set single value at passed label. If label is not contained, a
+        new object is created with the label placed at the end of the result
+        index
+
         Parameters
         ----------
         label : object
@@ -940,12 +989,12 @@ def set_value(self, label, value, takeable=False):
                 self._values[label] = value
             else:
                 self.index._engine.set_value(self._values, label, value)
-            return self
         except KeyError:
 
             # set using a non-recursive method
             self.loc[label] = value
-            return self
+
+        return self
 
     def reset_index(self, level=None, drop=False, name=None, inplace=False):
         """