DEPR: deprecate (DataFrame|Series).iteritems

Author: topper-123

asv_bench/benchmarks/frame_methods.py

@@ -115,15 +115,15 @@ def setup(self):
         )
         self.df4 = DataFrame(np.random.randn(N * 1000, 10))
 
-    def time_iteritems(self):
+    def time_items(self):
         # (monitor no-copying behaviour)
         if hasattr(self.df, "_item_cache"):
             self.df._item_cache.clear()
-        for name, col in self.df.iteritems():
+        for name, col in self.df.items():
             pass
 
-    def time_iteritems_cached(self):
-        for name, col in self.df.iteritems():
+    def time_items_cached(self):
+        for name, col in self.df.items():
             pass
 
     def time_iteritems_indexing(self):

doc/source/development/contributing_docstring.rst

@@ -522,7 +522,7 @@ examples:
 * ``loc`` and ``iloc``, as they do the same, but in one case providing indices
   and in the other positions
 * ``max`` and ``min``, as they do the opposite
-* ``iterrows``, ``itertuples`` and ``iteritems``, as it is easy that a user
+* ``iterrows``, ``itertuples`` and ``items``, as it is easy that a user
   looking for the method to iterate over columns ends up in the method to
   iterate over rows, and vice-versa
 * ``fillna`` and ``dropna``, as both methods are used to handle missing values

doc/source/getting_started/basics.rst

@@ -1475,7 +1475,7 @@ Thus, for example, iterating over a DataFrame gives you the column names:
        print(col)
 
 
-Pandas objects also have the dict-like :meth:`~DataFrame.iteritems` method to
+Pandas objects also have the dict-like :meth:`~DataFrame.items` method to
 iterate over the (key, value) pairs.
 
 To iterate over the rows of a DataFrame, you can use the following methods:
@@ -1524,10 +1524,10 @@ To iterate over the rows of a DataFrame, you can use the following methods:
 
     df
 
-iteritems
+items
 ~~~~~~~~~
 
-Consistent with the dict-like interface, :meth:`~DataFrame.iteritems` iterates
+Consistent with the dict-like interface, :meth:`~DataFrame.items` iterates
 through key-value pairs:
 
 * **Series**: (index, scalar value) pairs
@@ -1537,7 +1537,7 @@ For example:
 
 .. ipython:: python
 
-   for label, ser in df.iteritems():
+   for label, ser in df.items():
        print(label)
        print(ser)
 

doc/source/reference/frame.rst

@@ -68,7 +68,7 @@ Indexing, iteration
    DataFrame.__iter__
    DataFrame.items
    DataFrame.keys
-   DataFrame.iteritems
+   DataFrame.items
    DataFrame.iterrows
    DataFrame.itertuples
    DataFrame.lookup

doc/source/reference/series.rst

@@ -76,7 +76,6 @@ Indexing, iteration
    Series.loc
    Series.iloc
    Series.__iter__
-   Series.iteritems
    Series.items
    Series.keys
    Series.pop

doc/source/whatsnew/v0.25.0.rst

@@ -886,9 +886,11 @@ Other deprecations
 - :meth:`Index.item` and :meth:`Series.item` is deprecated. (:issue:`18262`)
 - The default value ``ordered=None`` in :class:`~pandas.api.types.CategoricalDtype` has been deprecated in favor of ``ordered=False``. When converting between categorical types ``ordered=True`` must be explicitly passed in order to be preserved. (:issue:`26336`)
 - :meth:`Index.contains` is deprecated. Use ``key in index`` (``__contains__``) instead (:issue:`17753`).
+- ``DataFrame.iteritems`` and ``Series.iteritems`` have been deprecated. :attr:`DataFrame.items` and :attr:`Series.items` provide the exact same functionality and should be used instead (:issue:`26114`).
 - :meth:`DataFrame.get_dtype_counts` is deprecated. (:issue:`18262`)
 - :meth:`Categorical.ravel` will return a :class:`Categorical` instead of a ``np.ndarray`` (:issue:`27199`)
 
+
 .. _whatsnew_0250.prior_deprecations:
 
 Removal of prior version deprecations/changes

pandas/core/frame.py

@@ -771,7 +771,7 @@ def style(self):
 
         return Styler(self)
 
-    def iteritems(self):
+    def items(self):
         r"""
         Iterator over (column name, Series) pairs.
 
@@ -802,7 +802,7 @@ def iteritems(self):
         panda 	bear 	  1864
         polar 	bear 	  22000
         koala 	marsupial 80000
-        >>> for label, content in df.iteritems():
+        >>> for label, content in df.items():
         ...     print('label:', label)
         ...     print('content:', content, sep='\n')
         ...
@@ -826,6 +826,10 @@ def iteritems(self):
             for i, k in enumerate(self.columns):
                 yield k, self._ixs(i, axis=1)
 
+    @Appender(items.__doc)
+    def iteritems(self):
+        return self.items()
+
     def iterrows(self):
         """
         Iterate over DataFrame rows as (index, Series) pairs.
@@ -843,7 +847,7 @@ def iterrows(self):
         See Also
         --------
         itertuples : Iterate over DataFrame rows as namedtuples of the values.
-        iteritems : Iterate over (column name, Series) pairs.
+        items : Iterate over (column name, Series) pairs.
 
         Notes
         -----
@@ -901,7 +905,7 @@ def itertuples(self, index=True, name="Pandas"):
         --------
         DataFrame.iterrows : Iterate over DataFrame rows as (index, Series)
             pairs.
-        DataFrame.iteritems : Iterate over (column name, Series) pairs.
+        DataFrame.items : Iterate over (column name, Series) pairs.
 
         Notes
         -----
@@ -958,8 +962,6 @@ def itertuples(self, index=True, name="Pandas"):
         # fallback to regular tuples
         return zip(*arrays)
 
-    items = iteritems
-
     def __len__(self):
         """
         Returns length of info axis, but here we use the index.
@@ -2634,7 +2636,7 @@ def memory_usage(self, index=True, deep=False):
         5216
         """
         result = Series(
-            [c.memory_usage(index=False, deep=deep) for col, c in self.iteritems()],
+            [c.memory_usage(index=False, deep=deep) for col, c in self.items()],
             index=self.columns,
         )
         if index:
@@ -4955,7 +4957,7 @@ def f(vals):
         if not diff.empty:
             raise KeyError(diff)
 
-        vals = (col.values for name, col in self.iteritems() if name in subset)
+        vals = (col.values for name, col in self.items() if name in subset)
         labels, shape = map(list, zip(*map(f, vals)))
 
         ids = get_group_index(labels, shape, sort=False, xnull=False)
@@ -7343,7 +7345,7 @@ def round(self, decimals=0, *args, **kwargs):
         from pandas.core.reshape.concat import concat
 
         def _dict_round(df, decimals):
-            for col, vals in df.iteritems():
+            for col, vals in df.items():
                 try:
                     yield _series_round(vals, decimals[col])
                 except KeyError:
@@ -7363,7 +7365,7 @@ def _series_round(s, decimals):
             new_cols = [col for col in _dict_round(self, decimals)]
         elif is_integer(decimals):
             # Dispatch to Series.round
-            new_cols = [_series_round(v, decimals) for _, v in self.iteritems()]
+            new_cols = [_series_round(v, decimals) for _, v in self.items()]
         else:
             raise TypeError("decimals must be an integer, a dict-like or a " "Series")
 

pandas/core/generic.py

@@ -494,7 +494,7 @@ def _get_space_character_free_column_resolvers(self):
         """
         from pandas.core.computation.common import _remove_spaces_column_name
 
-        return {_remove_spaces_column_name(k): v for k, v in self.iteritems()}
+        return {_remove_spaces_column_name(k): v for k, v in self.items()}
 
     @property
     def _info_axis(self):
@@ -1936,15 +1936,18 @@ def keys(self):
         """
         return self._info_axis
 
-    def iteritems(self):
-        """
-        Iterate over (label, values) on info axis
+    def items(self):
+        """Iterate over (label, values) on info axis
 
-        This is index for Series, columns for DataFrame and so on.
+        This is index for Series and columns for DataFrame.
         """
         for h in self._info_axis:
             yield h, self[h]
 
+    @Appender(items.__doc__)
+    def iteritems(self):
+        return self.items()
+
     def __len__(self):
         """Returns length of info axis"""
         return len(self._info_axis)
@@ -5912,7 +5915,7 @@ def astype(self, dtype, copy=True, errors="raise", **kwargs):
                         "key in a dtype mappings argument."
                     )
             results = []
-            for col_name, col in self.iteritems():
+            for col_name, col in self.items():
                 if col_name in dtype:
                     results.append(
                         col.astype(
@@ -10328,7 +10331,7 @@ def describe_1d(data):
         else:
             data = self.select_dtypes(include=include, exclude=exclude)
 
-        ldesc = [describe_1d(s) for _, s in data.iteritems()]
+        ldesc = [describe_1d(s) for _, s in data.items()]
         # set a convenient order for rows
         names = []
         ldesc_indexes = sorted((x.index for x in ldesc), key=len)

pandas/core/indexes/multi.py

@@ -601,7 +601,7 @@ def from_frame(cls, df, sortorder=None, names=None):
         if not isinstance(df, ABCDataFrame):
             raise TypeError("Input must be a DataFrame")
 
-        column_names, columns = zip(*df.iteritems())
+        column_names, columns = zip(*df.items())
         names = column_names if names is None else names
         return cls.from_arrays(columns, sortorder=sortorder, names=names)
 

pandas/core/reshape/pivot.py

@@ -272,7 +272,7 @@ def _compute_grand_margin(data, values, aggfunc, margins_name="All"):
 
     if values:
         grand_margin = {}
-        for k, v in data[values].iteritems():
+        for k, v in data[values].items():
             try:
                 if isinstance(aggfunc, str):
                     grand_margin[k] = getattr(v, aggfunc)()