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)()

pandas/core/reshape/reshape.py

@@ -478,7 +478,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),
@@ -544,7 +544,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:
@@ -695,7 +695,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()
@@ -909,7 +909,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, prefix_sep):
+        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],

pandas/core/series.py

@@ -1692,13 +1692,12 @@ def to_string(
 
     # ----------------------------------------------------------------------
 
-    def iteritems(self):
+    def items(self):
         """
         Lazily iterate over (index, value) tuples.
 
         This method returns an iterable tuple (index, value). This is
-        convenient if you want to create a lazy iterator. Note that the
-        methods Series.items and Series.iteritems are the same methods.
+        convenient if you want to create a lazy iterator.
 
         Returns
         -------
@@ -1708,20 +1707,22 @@ 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):
+        return self.items()
 
     # ----------------------------------------------------------------------
     # Misc public methods

pandas/core/sparse/frame.py

@@ -695,7 +695,7 @@ def _reindex_index(
         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

@@ -998,7 +998,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

@@ -113,7 +113,7 @@ def hash_pandas_object(
         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 = (

pandas/io/formats/style.py

@@ -538,7 +538,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

@@ -1105,7 +1105,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

@@ -249,7 +249,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:
                     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)

pandas/io/sql.py

@@ -108,7 +108,7 @@ def _parse_date_columns(data_frame, parse_dates):
     # we want to coerce datetime64_tz dtypes for now to UTC
     # we could in theory do a 'nice' conversion from a FixedOffset tz
     # GH11216
-    for col_name, df_col in data_frame.iteritems():
+    for col_name, df_col in data_frame.items():
         if is_datetime64tz_dtype(df_col) or col_name in parse_dates:
             try:
                 fmt = parse_dates[col_name]