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:`xxxxx`).
 - 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 the `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 the `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)()

pandas/core/reshape/reshape.py

@@ -446,7 +446,7 @@ def _unstack_extension_series(series, level, fill_value):
     out = []
     values = extract_array(series, extract_numpy=False)
 
-    for col, indices in result.iteritems():
+    for col, indices in result.items():
         out.append(Series(values.take(indices.values,
                                       allow_fill=True,
                                       fill_value=fill_value),
@@ -505,7 +505,7 @@ def factorize(index):
         if is_extension_array_dtype(dtype):
             arr = dtype.construct_array_type()
             new_values = arr._concat_same_type([
-                col._values for _, col in frame.iteritems()
+                col._values for _, col in frame.items()
             ])
             new_values = _reorder_for_extension_array_stack(new_values, N, K)
         else:
@@ -646,7 +646,7 @@ def _convert_level_number(level_num, columns):
                 subset = this[this.columns[loc]]
 
                 value_slice = dtype.construct_array_type()._concat_same_type(
-                    [x._values for _, x in subset.iteritems()]
+                    [x._values for _, x in subset.items()]
                 )
                 N, K = this.shape
                 idx = np.arange(N * K).reshape(K, N).T.ravel()
@@ -849,7 +849,7 @@ def check_len(item, name):
             # columns to prepend to result.
             with_dummies = [data.select_dtypes(exclude=dtypes_to_encode)]
 
-        for (col, pre, sep) in zip(data_to_encode.iteritems(), prefix,
+        for (col, pre, sep) in zip(data_to_encode.items(), prefix,
                                    prefix_sep):
             # col is (column_name, column), use just column data here
             dummy = _get_dummies_1d(col[1], prefix=pre, prefix_sep=sep,

pandas/core/series.py

@@ -1442,13 +1442,12 @@ def to_string(self, buf=None, na_rep='NaN', float_format=None, header=True,
 
     # ----------------------------------------------------------------------
 
-    def iteritems(self):
+    def items(self):
         """
         Lazily iterate over (index, value) tuples.
 
         This method returns an iterable tuple (index, value). This is
-        convienient if you want to create a lazy iterator. Note that the
-        methods Series.items and Series.iteritems are the same methods.
+        convienient if you want to create a lazy iterator.
 
         Returns
         -------
@@ -1458,20 +1457,25 @@ def iteritems(self):
 
         See Also
         --------
-        DataFrame.iteritems : Equivalent to Series.iteritems for DataFrame.
+        DataFrame.items : Equivalent to Series.items for DataFrame.
 
         Examples
         --------
         >>> s = pd.Series(['A', 'B', 'C'])
-        >>> for index, value in s.iteritems():
+        >>> for index, value in s.items():
         ...     print("Index : {}, Value : {}".format(index, value))
         Index : 0, Value : A
         Index : 1, Value : B
         Index : 2, Value : C
         """
         return zip(iter(self.index), iter(self))
 
-    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 the `items` instead.",
+                      FutureWarning, stacklevel=2)
+        return self.items()
 
     # ----------------------------------------------------------------------
     # Misc public methods

pandas/core/sparse/frame.py

@@ -684,7 +684,7 @@ def _reindex_index(self, index, method, copy, level, fill_value=np.nan,
         need_mask = mask.any()
 
         new_series = {}
-        for col, series in self.iteritems():
+        for col, series in self.items():
             if mask.all():
                 continue
 

pandas/core/strings.py

@@ -941,7 +941,7 @@ def str_extractall(arr, pat, flags=0):
     index_list = []
     is_mi = arr.index.nlevels > 1
 
-    for subject_key, subject in arr.iteritems():
+    for subject_key, subject in arr.items():
         if isinstance(subject, str):
 
             if not is_mi:

pandas/core/util/hashing.py

@@ -98,7 +98,7 @@ def hash_pandas_object(obj, index=True, encoding='utf8', hash_key=None,
         h = Series(h, index=obj.index, dtype='uint64', copy=False)
 
     elif isinstance(obj, ABCDataFrame):
-        hashes = (hash_array(series.values) for _, series in obj.iteritems())
+        hashes = (hash_array(series.values) for _, series in obj.items())
         num_items = len(obj.columns)
         if index:
             index_hash_generator = (hash_pandas_object(obj.index,

pandas/io/formats/style.py

@@ -482,7 +482,7 @@ def _update_ctx(self, attrs):
         matter.
         """
         for row_label, v in attrs.iterrows():
-            for col_label, col in v.iteritems():
+            for col_label, col in v.items():
                 i = self.index.get_indexer([row_label])[0]
                 j = self.columns.get_indexer([col_label])[0]
                 for pair in col.rstrip(";").split(";"):

pandas/io/json/json.py

@@ -918,7 +918,7 @@ def _process_converter(self, f, filt=None):
 
         needs_new_obj = False
         new_obj = dict()
-        for i, (col, c) in enumerate(self.obj.iteritems()):
+        for i, (col, c) in enumerate(self.obj.items()):
             if filt(col, c):
                 new_data, result = f(col, c)
                 if result:

pandas/io/json/table_schema.py

@@ -240,7 +240,7 @@ def build_table_schema(data, index=True, primary_key=None, version=True):
             fields.append(convert_pandas_type_to_json_field(data.index))
 
     if data.ndim > 1:
-        for column, s in data.iteritems():
+        for column, s in data.items():
             fields.append(convert_pandas_type_to_json_field(s))
     else:
         fields.append(convert_pandas_type_to_json_field(data))

pandas/io/msgpack/_packer.pyx

@@ -194,7 +194,7 @@ cdef class Packer(object):
                     raise ValueError("dict is too large")
                 ret = msgpack_pack_map(&self.pk, L)
                 if ret == 0:
-                    for k, v in d.iteritems():
+                    for k, v in d.items():
                         ret = self._pack(k, nest_limit - 1)
                         if ret != 0: break
                         ret = self._pack(v, nest_limit - 1)