DOC/ENH: Deprecate iterkv + add docs

Author: jtratner

doc/source/release.rst

@@ -47,6 +47,21 @@ pandas 0.13
 
 **API Changes**
 
+  - ``pandas`` now is Python 2/3 compatible without the need for 2to3 thanks to
+    @jtratner. As a result, pandas now uses iterators more extensively. This
+    also led to the introduction of substantive parts of the Benjamin
+    Peterson's ``six`` library into compat. (:issue:`4384`, :issue:`4375`,
+    :issue:`4372`)
+  - ``pandas.util.py3compat`` has been merged into ``pandas.util.compat`` and
+    removed from pandas. It contains both list and iterator versions of range,
+    filter, map and zip, plus other necessary elements for Python 3
+    compatibility. ``lmap``, ``lzip``, ``lrange`` and ``lfilter`` all produce
+    lists instead of iterators, for compatibility with ``numpy``, subscripting
+    and ``pandas`` constructors.(:issue:`4384`, :issue:`4375`, :issue:`4372`)
+  - deprecated ``iterkv``, which will be removed in a future release (was just
+    an alias of iteritems used to get around ``2to3``'s changes).
+    (:issue:`4384`, :issue:`4375`, :issue:`4372`)
+
 **Experimental Features**
 
 **Bug Fixes**

doc/source/v0.13.0.txt

@@ -12,8 +12,22 @@ API changes
   - ``read_excel`` now supports an integer in its ``sheetname`` argument giving
     the index of the sheet to read in (:issue:`4301`).
   - Text parser now treats anything that reads like inf ("inf", "Inf", "-Inf",
-    "iNf", etc.) to infinity. (:issue:`4220`, :issue:`4219`), affecting
+    "iNf", etc.) as infinity. (:issue:`4220`, :issue:`4219`), affecting
     ``read_table``, ``read_csv``, etc.
+  - ``pandas`` now is Python 2/3 compatible without the need for 2to3 thanks to
+    @jtratner. As a result, pandas now uses iterators more extensively. This
+    also led to the introduction of substantive parts of the Benjamin
+    Peterson's ``six`` library into compat. (:issue:`4384`, :issue:`4375`,
+    :issue:`4372`)
+  - ``pandas.util.py3compat`` has been merged into ``pandas.util.compat`` and
+    removed from pandas. It contains both list and iterator versions of range,
+    filter, map and zip, plus other necessary elements for Python 3
+    compatibility. ``lmap``, ``lzip``, ``lrange`` and ``lfilter`` all produce
+    lists instead of iterators, for compatibility with ``numpy``, subscripting
+    and ``pandas`` constructors.(:issue:`4384`, :issue:`4375`, :issue:`4372`)
+  - deprecated ``iterkv``, which will be removed in a future release (was just
+    an alias of iteritems used to get around ``2to3``'s changes).
+    (:issue:`4384`, :issue:`4375`, :issue:`4372`)
 
 Enhancements
 ~~~~~~~~~~~~

pandas/core/frame.py

@@ -17,6 +17,7 @@
 import operator
 import sys
 import collections
+import warnings
 
 from numpy import nan as NA
 import numpy as np
@@ -564,14 +565,12 @@ def _wrap_array(self, arr, axes, copy=False):
 
     @property
     def _verbose_info(self):
-        import warnings
         warnings.warn('The _verbose_info property will be removed in version '
                       '0.13. please use "max_info_rows"', FutureWarning)
         return get_option('display.max_info_rows') is None
 
     @_verbose_info.setter
     def _verbose_info(self, value):
-        import warnings
         warnings.warn('The _verbose_info property will be removed in version '
                       '0.13. please use "max_info_rows"', FutureWarning)
 
@@ -786,7 +785,6 @@ def itertuples(self, index=True):
         arrays.extend(self.iloc[:, k] for k in range(len(self.columns)))
         return zip(*arrays)
 
-    iterkv = iteritems
     if compat.PY3:  # pragma: no cover
         items = iteritems
 
@@ -976,7 +974,6 @@ def to_dict(self, outtype='dict'):
         -------
         result : dict like {column -> {index -> value}}
         """
-        import warnings
         if not self.columns.is_unique:
             warnings.warn("DataFrame columns are not unique, some "
                           "columns will be omitted.", UserWarning)
@@ -1391,7 +1388,6 @@ def to_csv(self, path_or_buf, sep=",", na_rep='', float_format=None,
             or new (expanded format) if False)
         """
         if nanRep is not None:  # pragma: no cover
-            import warnings
             warnings.warn("nanRep is deprecated, use na_rep",
                           FutureWarning)
             na_rep = nanRep
@@ -1527,7 +1523,6 @@ def to_string(self, buf=None, columns=None, col_space=None, colSpace=None,
         """
         Render a DataFrame to a console-friendly tabular output.
         """
-        import warnings
         if force_unicode is not None:  # pragma: no cover
             warnings.warn("force_unicode is deprecated, it will have no "
                           "effect", FutureWarning)
@@ -1576,7 +1571,6 @@ def to_html(self, buf=None, columns=None, col_space=None, colSpace=None,
         Render a DataFrame as an HTML table.
         """
 
-        import warnings
         if force_unicode is not None:  # pragma: no cover
             warnings.warn("force_unicode is deprecated, it will have no "
                           "effect", FutureWarning)
@@ -1615,7 +1609,6 @@ def to_latex(self, buf=None, columns=None, col_space=None, colSpace=None,
         You can splice this into a LaTeX document.
         """
 
-        import warnings
         if force_unicode is not None:  # pragma: no cover
             warnings.warn("force_unicode is deprecated, it will have no "
                           "effect", FutureWarning)
@@ -2014,7 +2007,6 @@ def _getitem_array(self, key):
             # go with the __setitem__ behavior since that is more consistent
             # with all other indexing behavior
             if isinstance(key, Series) and not key.index.equals(self.index):
-                import warnings
                 warnings.warn("Boolean Series key will be reindexed to match "
                               "DataFrame index.", UserWarning)
             elif len(key) != len(self.index):
@@ -3194,7 +3186,6 @@ def sort(self, columns=None, column=None, axis=0, ascending=True,
         sorted : DataFrame
         """
         if column is not None:  # pragma: no cover
-            import warnings
             warnings.warn("column is deprecated, use columns", FutureWarning)
             columns = column
         return self.sort_index(by=columns, axis=axis, ascending=ascending,
@@ -3576,13 +3567,11 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
             raise AssertionError("'to_replace' must be 'None' if 'regex' is "
                                  "not a bool")
         if method is not None:
-            from warnings import warn
-            warn('the "method" argument is deprecated and will be removed in'
+            warnings.warn('the "method" argument is deprecated and will be removed in'
                  'v0.13; this argument has no effect')
 
         if axis is not None:
-            from warnings import warn
-            warn('the "axis" argument is deprecated and will be removed in'
+            warnings.warn('the "axis" argument is deprecated and will be removed in'
                  'v0.13; this argument has no effect')
 
         self._consolidate_inplace()
@@ -3717,7 +3706,6 @@ def interpolate(self, to_replace, method='pad', axis=0, inplace=False,
         --------
         reindex, replace, fillna
         """
-        from warnings import warn
         warn('DataFrame.interpolate will be removed in v0.13, please use '
              'either DataFrame.fillna or DataFrame.replace instead',
              FutureWarning)
@@ -3867,7 +3855,6 @@ def _combine_series_infer(self, other, func, fill_value=None):
 
         # teeny hack because one does DataFrame + TimeSeries all the time
         if self.index.is_all_dates and other.index.is_all_dates:
-            import warnings
             warnings.warn(("TimeSeries broadcasting along DataFrame index "
                            "by default is deprecated. Please use "
                            "DataFrame.<op> to explicitly broadcast arithmetic "

pandas/core/generic.py

@@ -1,5 +1,5 @@
 # pylint: disable=W0231,E1101
-
+import warnings
 from pandas.util import compat
 import numpy as np
 import pandas.lib as lib
@@ -40,13 +40,11 @@ def to_pickle(self, path):
         return to_pickle(self, path)
 
     def save(self, path):  # TODO remove in 0.13
-        import warnings
         from pandas.io.pickle import to_pickle
         warnings.warn("save is deprecated, use to_pickle", FutureWarning)
         return to_pickle(self, path)
 
     def load(self, path):  # TODO remove in 0.13
-        import warnings
         from pandas.io.pickle import read_pickle
         warnings.warn("load is deprecated, use pd.read_pickle", FutureWarning)
         return read_pickle(path)
@@ -717,6 +715,13 @@ def __delitem__(self, key):
         except KeyError:
             pass
 
+    # originally used to get around 2to3's changes to iteritems.
+    # Now unnecessary.
+    def iterkv(self, *args, **kwargs):
+        warnings.warn("iterkv is deprecated and will be removed in a future "
+                      "release, use ``iteritems`` instead.", DeprecationWarning)
+        return self.iteritems(*args, **kwargs)
+
     def get_dtype_counts(self):
         """ return the counts of dtypes in this frame """
         from pandas import Series

pandas/core/panel.py

@@ -496,10 +496,6 @@ def iteritems(self):
         for h in getattr(self, self._info_axis):
             yield h, self[h]
 
-    # Name that won't get automatically converted to items by 2to3. items is
-    # already in use for the first axis.
-    iterkv = iteritems
-
     def _get_plane_axes(self, axis):
         """
         Get my plane axes: these are already

pandas/core/series.py

@@ -9,6 +9,7 @@
 import operator
 from distutils.version import LooseVersion
 import types
+import warnings
 
 from numpy import nan, ndarray
 import numpy as np
@@ -1219,7 +1220,11 @@ def iteritems(self):
         """
         return lzip(iter(self.index), iter(self))
 
-    iterkv = iteritems
+    def iterkv(self):
+        warnings.warn("iterkv is deprecated and will be removed in a future "
+                      "release. Use ``iteritems`` instead", DeprecationWarning)
+        return self.iteritems()
+
     if compat.PY3:  # pragma: no cover
         items = iteritems
 

pandas/tests/test_frame.py

@@ -10305,6 +10305,10 @@ def test_take(self):
             expected = df.ix[:, ['B', 'C', 'A', 'D']]
             assert_frame_equal(result, expected)
 
+    def test_iterkv_deprecation(self):
+        with tm.assert_produces_warning(DeprecationWarning):
+            self.mixed_float.iterkv()
+
     def test_iterkv_names(self):
         for k, v in compat.iteritems(self.mixed_frame):
             self.assertEqual(v.name, k)