DEPR: Series.item and Index.item (#27112)

* Deprecate item

* Add whatsnew

* Use assert_produces_warning instead

doc/source/whatsnew/v0.25.0.rst

@@ -608,6 +608,7 @@ Other deprecations
 - :attr:`Index.dtype_str` is deprecated. (:issue:`18262`)
 - :attr:`Series.imag` and :attr:`Series.real` are deprecated. (:issue:`18262`)
 - :meth:`Series.put` is deprecated. (:issue:`18262`)
+- :meth:`Index.item` and :meth:`Series.item` is deprecated. (:issue:`18262`)
 
 .. _whatsnew_0250.prior_deprecations:
 

pandas/core/base.py

@@ -693,11 +693,15 @@ def item(self):
         """
         Return the first element of the underlying data as a python scalar.
 
+        .. deprecated 0.25.0
+
         Returns
         -------
         scalar
             The first element of %(klass)s.
         """
+        warnings.warn('`item` has been deprecated and will be removed in a '
+                      'future version', FutureWarning, stacklevel=2)
         return self.values.item()
 
     @property

pandas/core/indexes/base.py

@@ -57,13 +57,6 @@
 _index_shared_docs = dict()
 
 
-def _try_get_item(x):
-    try:
-        return x.item()
-    except AttributeError:
-        return x
-
-
 def _make_comparison_op(op, cls):
     def cmp_method(self, other):
         if isinstance(other, (np.ndarray, Index, ABCSeries)):

pandas/core/indexes/numeric.py

@@ -16,7 +16,6 @@
 
 from pandas.core import algorithms
 import pandas.core.common as com
-import pandas.core.indexes.base as ibase
 from pandas.core.indexes.base import (
     Index, InvalidIndexError, _index_shared_docs)
 from pandas.core.ops import get_op_result_name
@@ -442,7 +441,9 @@ def __contains__(self, other):
             return np.isnan(other) and self.hasnans
         except ValueError:
             try:
-                return len(other) <= 1 and ibase._try_get_item(other) in self
+                return len(other) <= 1 and other.item() in self
+            except AttributeError:
+                return len(other) <= 1 and other in self
             except TypeError:
                 pass
         except TypeError:
@@ -457,9 +458,7 @@ def get_loc(self, key, method=None, tolerance=None):
                 nan_idxs = self._nan_idxs
                 try:
                     return nan_idxs.item()
-                except (ValueError, IndexError):
-                    # should only need to catch ValueError here but on numpy
-                    # 1.7 .item() can raise IndexError when NaNs are present
+                except ValueError:
                     if not len(nan_idxs):
                         raise KeyError(key)
                     return nan_idxs

pandas/core/indexes/period.py

@@ -874,7 +874,12 @@ def item(self):
         """
         return the first element of the underlying data as a python
         scalar
+
+        .. deprecated 0.25.0
+
         """
+        warnings.warn('`item` has been deprecated and will be removed in a '
+                      'future version', FutureWarning, stacklevel=2)
         # TODO(DatetimeArray): remove
         if len(self) == 1:
             return self[0]

pandas/tests/series/test_api.py

@@ -419,10 +419,11 @@ def f(x):
         tm.assert_series_equal(result, expected)
 
         # .item()
-        s = Series([1])
-        result = s.item()
-        assert result == 1
-        assert s.item() == s.iloc[0]
+        with tm.assert_produces_warning(FutureWarning):
+            s = Series([1])
+            result = s.item()
+            assert result == 1
+            assert s.item() == s.iloc[0]
 
         # using an ndarray like function
         s = Series(np.random.randn(10))

pandas/tests/test_base.py

@@ -326,13 +326,15 @@ def test_ndarray_compat_properties(self):
                 pass
 
             with pytest.raises(ValueError):
-                o.item()  # len > 1
+                with tm.assert_produces_warning(FutureWarning):
+                    o.item()  # len > 1
 
             assert o.ndim == 1
             assert o.size == len(o)
 
-        assert Index([1]).item() == 1
-        assert Series([1]).item() == 1
+        with tm.assert_produces_warning(FutureWarning):
+            assert Index([1]).item() == 1
+            assert Series([1]).item() == 1
 
     def test_value_counts_unique_nunique(self):
         for orig in self.objs: