DEPR: deprecate DataFrame.iteritems and Series.iteritems

Author: topper-123

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 item, frame in df.iteritems():
+   for item, frame in df.items():
        print(item)
        print(frame)
 

doc/source/reference/frame.rst

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

doc/source/reference/series.rst

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

doc/source/whatsnew/v0.25.0.rst

@@ -224,6 +224,7 @@ Other API Changes
 Deprecations
 ~~~~~~~~~~~~
 
+- ``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`).
 - Deprecated the `M (months)` and `Y (year)` `units` parameter of :func: `pandas.to_timedelta`, :func: `pandas.Timedelta` and :func: `pandas.TimedeltaIndex` (:issue:`16344`)
 - The functions :func:`pandas.to_datetime` and :func:`pandas.to_timedelta` have deprecated the ``box`` keyword. Instead, use :meth:`to_numpy` or :meth:`Timestamp.to_datetime64`/:meth:`Timedelta.to_timedelta64`. (:issue:`24416`)
 

pandas/core/frame.py

@@ -72,7 +72,7 @@
     ABCSeries, ABCDataFrame, ABCIndexClass, ABCMultiIndex)
 from pandas.core.dtypes.missing import isna, notna
 
-from pandas.core import algorithms
+from pandas.core import algorithms, generic
 from pandas.core import common as com
 from pandas.core import nanops
 from pandas.core import ops
@@ -720,7 +720,7 @@ def style(self):
         from pandas.io.formats.style import Styler
         return Styler(self)
 
-    def iteritems(self):
+    def items(self):
         r"""
         Iterator over (column name, Series) pairs.
 
@@ -751,7 +751,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')
         ...
@@ -792,7 +792,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
         -----
@@ -850,7 +850,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
         -----
@@ -907,7 +907,12 @@ def itertuples(self, index=True, name="Pandas"):
         # fallback to regular tuples
         return zip(*arrays)
 
-    items = iteritems
+    @Appender(generic._shared_docs["iteritems"] % _shared_doc_kwargs)
+    def iteritems(self):
+        warnings.warn("'iteritems' is deprecated and will be removed in a "
+                      "future version. Please use `items` instead.",
+                      FutureWarning, stacklevel=2)
+        return self.items()
 
     def __len__(self):
         """
@@ -2528,7 +2533,7 @@ def memory_usage(self, index=True, deep=False):
         5168
         """
         result = Series([c.memory_usage(index=False, deep=deep)
-                         for col, c in self.iteritems()], index=self.columns)
+                         for col, c in self.items()], index=self.columns)
         if index:
             result = Series(self.index.memory_usage(deep=deep),
                             index=['Index']).append(result)
@@ -4723,7 +4728,7 @@ def f(vals):
         if not diff.empty:
             raise KeyError(diff)
 
-        vals = (col.values for name, col in self.iteritems()
+        vals = (col.values for name, col in self.items()
                 if name in subset)
         labels, shape = map(list, zip(*map(f, vals)))
 
@@ -6987,7 +6992,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:
@@ -7008,7 +7013,7 @@ def _series_round(s, decimals):
         elif is_integer(decimals):
             # Dispatch to Series.round
             new_cols = [_series_round(v, decimals)
-                        for _, v in self.iteritems()]
+                        for _, v in self.items()]
         else:
             raise TypeError("decimals must be an integer, a dict-like or a "
                             "Series")

pandas/core/generic.py

@@ -430,7 +430,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()}
+                in self.items()}
 
     @property
     def _info_axis(self):
@@ -1857,15 +1857,27 @@ def keys(self):
         """
         return self._info_axis
 
-    def iteritems(self):
+    def items(self):
         """Iterate over (label, values) on info axis
 
-        This is index for Series, columns for DataFrame, major_axis for Panel,
-        and so on.
+        This is index for Series and columns for DataFrame.
         """
         for h in self._info_axis:
             yield h, self[h]
 
+    _shared_docs['iteritems'] = ("""Iterate over (label, values) on info axis
+
+        .. deprecated :: 0.25.0
+            Use :attr:`%(klass)s.items` instead.
+        """)
+
+    @Appender(_shared_docs["iteritems"] % _shared_doc_kwargs)
+    def iteritems(self):
+        warnings.warn("'iteritems' is deprecated and will be removed in a "
+                      "future version. Please use `items` instead.",
+                      FutureWarning, stacklevel=2)
+        return self.items()
+
     def __len__(self):
         """Returns length of info axis"""
         return len(self._info_axis)
@@ -5706,7 +5718,7 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs):
                     raise KeyError('Only a column name can be used for the '
                                    '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(dtype=dtype[col_name], copy=copy,
                                               errors=errors, **kwargs))
@@ -6110,7 +6122,7 @@ def fillna(self, value=None, method=None, axis=None, inplace=False,
             elif self.ndim == 3:
                 # fill in 2d chunks
                 result = {col: s.fillna(method=method, value=value)
-                          for col, s in self.iteritems()}
+                          for col, s in self.items()}
                 prelim_obj = self._constructor.from_dict(result)
                 new_obj = prelim_obj.__finalize__(self)
                 new_data = new_obj._data
@@ -9861,7 +9873,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

@@ -511,7 +511,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 = lzip(*df.iteritems())
+        column_names, columns = lzip(*df.items())
         names = column_names if names is None else names
         return cls.from_arrays(columns, sortorder=sortorder, names=names)
 

pandas/core/panel.py

@@ -452,7 +452,7 @@ def to_excel(self, path, na_rep='', engine=None, **kwargs):
             writer = path
         kwargs['na_rep'] = na_rep
 
-        for item, df in self.iteritems():
+        for item, df in self.items():
             name = str(item)
             df.to_excel(writer, name, **kwargs)
         writer.save()

pandas/core/reshape/pivot.py

@@ -223,7 +223,7 @@ def _compute_grand_margin(data, values, aggfunc,
 
     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)()