DEPR: deprecate (DataFrame|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

@@ -1474,7 +1474,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:
@@ -1523,10 +1523,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
@@ -1536,7 +1536,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

@@ -762,6 +762,8 @@ Other deprecations
 - :meth:`Series.put` is deprecated. (:issue:`18262`)
 - :meth:`Index.item` and :meth:`Series.item` is deprecated. (:issue:`18262`)
 - :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`).
+
 
 .. _whatsnew_0250.prior_deprecations:
 

pandas/core/frame.py

@@ -689,7 +689,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.
 
@@ -720,7 +720,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')
         ...
@@ -761,7 +761,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
         -----
@@ -819,7 +819,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
         -----
@@ -876,7 +876,12 @@ def itertuples(self, index=True, name="Pandas"):
         # fallback to regular tuples
         return zip(*arrays)
 
-    items = iteritems
+    @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):
         """
@@ -2437,7 +2442,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()], 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)
@@ -4640,7 +4645,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)))
 
@@ -6913,7 +6918,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:
@@ -6934,7 +6939,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

@@ -437,7 +437,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):
@@ -1838,15 +1838,27 @@ 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]
 
+    _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)
@@ -5581,7 +5593,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))
@@ -9697,7 +9709,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

@@ -566,7 +566,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/panel.py

@@ -451,7 +451,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)()