DEPR: deprecate .get_value and .set_value for Series, DataFrame, Panel, SparseSeries, SparseDataFrame (#17739)

closes #15269

Author: jreback

doc/source/whatsnew/v0.21.0.txt

@@ -666,7 +666,8 @@ Deprecations
 - ``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`)
 - passing ``categories`` or ``ordered`` kwargs to :func:`Series.astype` is deprecated, in favor of passing a :ref:`CategoricalDtype <whatsnew_0210.enhancements.categorical_dtype>` (:issue:`17636`)
-- Passing a non-existant column in ``.to_excel(..., columns=)`` is deprecated and will raise a ``KeyError`` in the future (:issue:`17295`)
+- Passing a non-existent column in ``.to_excel(..., columns=)`` is deprecated and will raise a ``KeyError`` in the future (:issue:`17295`)
+- ``.get_value`` and ``.set_value`` on ``Series``, ``DataFrame``, ``Panel``, ``SparseSeries``, and ``SparseDataFrame`` are deprecated in favor of using ``.iat[]`` or ``.at[]`` accessors (:issue:`15269`)
 
 .. _whatsnew_0210.deprecations.select:
 

pandas/core/frame.py

@@ -297,7 +297,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):
@@ -1922,6 +1923,10 @@ def get_value(self, index, col, takeable=False):
         """
         Quickly retrieve single value at passed column and index
 
+        .. deprecated:: 0.21.0
+
+        Please use .at[] or .iat[] accessors.
+
         Parameters
         ----------
         index : row label
@@ -1933,6 +1938,14 @@ def get_value(self, index, col, takeable=False):
         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):
+
         if takeable:
             series = self._iget_item_cache(col)
             return _maybe_box_datetimelike(series._values[index])
@@ -1948,12 +1961,17 @@ 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)
+    _get_value.__doc__ = get_value.__doc__
 
     def set_value(self, index, col, value, takeable=False):
         """
         Put single value at passed column and index
 
+        .. deprecated:: 0.21.0
+
+        Please use .at[] or .iat[] accessors.
+
         Parameters
         ----------
         index : row label
@@ -1967,10 +1985,17 @@ def set_value(self, index, col, value, takeable=False):
             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):
         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
@@ -1983,6 +2008,7 @@ def set_value(self, index, col, value, takeable=False):
             self._item_cache.pop(col, None)
 
             return self
+    _set_value.__doc__ = set_value.__doc__
 
     def _ixs(self, i, axis=0):
         """
@@ -2791,7 +2817,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

@@ -112,7 +112,7 @@ def __getitem__(self, key):
             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:
@@ -1542,7 +1542,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):
@@ -1701,7 +1701,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):
@@ -1866,7 +1866,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):
@@ -1883,7 +1883,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

@@ -470,6 +470,10 @@ def get_value(self, *args, **kwargs):
         """
         Quickly retrieve single value at (item, major, minor) location
 
+        .. deprecated:: 0.21.0
+
+        Please use .at[] or .iat[] accessors.
+
         Parameters
         ----------
         item : item label (panel item)
@@ -481,6 +485,13 @@ def get_value(self, *args, **kwargs):
         -------
         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):
         nargs = len(args)
         nreq = self._AXIS_LEN
 
@@ -500,12 +511,17 @@ 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)
+    _get_value.__doc__ = get_value.__doc__
 
     def set_value(self, *args, **kwargs):
         """
         Quickly set single value at (item, major, minor) location
 
+        .. deprecated:: 0.21.0
+
+        Please use .at[] or .iat[] accessors.
+
         Parameters
         ----------
         item : item label (panel item)
@@ -520,6 +536,13 @@ def set_value(self, *args, **kwargs):
             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):
         # require an arg for each axis and the value
         nargs = len(args)
         nreq = self._AXIS_LEN + 1
@@ -540,7 +563,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)
@@ -553,7 +576,8 @@ 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)
+    _set_value.__doc__ = set_value.__doc__
 
     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,10 @@ def get_value(self, label, takeable=False):
         """
         Quickly retrieve single value at passed index label
 
+        .. deprecated:: 0.21.0
+
+        Please use .at[] or .iat[] accessors.
+
         Parameters
         ----------
         index : label
@@ -911,16 +915,28 @@ def get_value(self, label, takeable=False):
         -------
         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):
         if takeable is True:
             return _maybe_box_datetimelike(self._values[label])
         return self.index.get_value(self._values, label)
+    _get_value.__doc__ = get_value.__doc__
 
     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
 
+        .. deprecated:: 0.21.0
+
+        Please use .at[] or .iat[] accessors.
+
         Parameters
         ----------
         label : object
@@ -935,17 +951,25 @@ def set_value(self, label, value, takeable=False):
             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):
         try:
             if takeable:
                 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
+    _set_value.__doc__ = set_value.__doc__
 
     def reset_index(self, level=None, drop=False, name=None, inplace=False):
         """

pandas/core/sparse/frame.py

@@ -5,6 +5,7 @@
 from __future__ import division
 # pylint: disable=E1101,E1103,W0231,E0202
 
+import warnings
 from pandas.compat import lmap
 from pandas import compat
 import numpy as np
@@ -430,19 +431,47 @@ def __getitem__(self, key):
         else:
             return self._get_item_cache(key)
 
-    @Appender(DataFrame.get_value.__doc__, indents=0)
     def get_value(self, index, col, takeable=False):
+        """
+        Quickly retrieve single value at passed column and index
+
+        .. deprecated:: 0.21.0
+
+        Please use .at[] or .iat[] accessors.
+
+        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):
         if takeable is True:
             series = self._iget_item_cache(col)
         else:
             series = self._get_item_cache(col)
 
-        return series.get_value(index, takeable=takeable)
+        return series._get_value(index, takeable=takeable)
+    _get_value.__doc__ = get_value.__doc__
 
     def set_value(self, index, col, value, takeable=False):
         """
         Put single value at passed column and index
 
+        .. deprecated:: 0.21.0
+
+        Please use .at[] or .iat[] accessors.
+
         Parameters
         ----------
         index : row label
@@ -460,9 +489,18 @@ def set_value(self, index, col, value, takeable=False):
         -------
         frame : DataFrame
         """
-        dense = self.to_dense().set_value(index, col, value, takeable=takeable)
+        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):
+        dense = self.to_dense()._set_value(
+            index, col, value, takeable=takeable)
         return dense.to_sparse(kind=self._default_kind,
                                fill_value=self._default_fill_value)
+    _set_value.__doc__ = set_value.__doc__
 
     def _slice(self, slobj, axis=0, kind=None):
         if axis == 0: