DEPR: passing categories or ordered kwargs to Series.astype is deprecated (pandas-dev#17742)

closes pandas-dev#17636

Author: jreback

doc/source/whatsnew/v0.21.0.txt

@@ -606,6 +606,7 @@ Deprecations
 - :func:`DataFrame.as_blocks` is deprecated, as this is exposing the internal implementation (:issue:`17302`)
 - ``pd.TimeGrouper`` is deprecated in favor of :class:`pandas.Grouper` (:issue:`16747`)
 - ``cdate_range`` has been deprecated in favor of :func:`bdate_range`, which has gained ``weekmask`` and ``holidays`` parameters for building custom frequency date ranges. See the :ref:`documentation <timeseries.custom-freq-ranges>` for more details (:issue:`17596`)
+- passing ``categories`` or ``ordered`` kwargs to :func:`Series.astype` is deprecated, in favor of passing a :ref:`CategoricalDtype <whatsnew_0210.enhancements.categorical_dtype>` (:issue:`17636`)
 
 .. _whatsnew_0210.deprecations.argmin_min:
 

pandas/core/internals.py

@@ -1,3 +1,4 @@
+import warnings
 import copy
 from warnings import catch_warnings
 import itertools
@@ -547,12 +548,20 @@ def _astype(self, dtype, copy=False, errors='raise', values=None,
         # may need to convert to categorical
         # this is only called for non-categoricals
         if self.is_categorical_astype(dtype):
-            if (('categories' in kwargs or 'ordered' in kwargs) and
-                    isinstance(dtype, CategoricalDtype)):
-                raise TypeError("Cannot specify a CategoricalDtype and also "
-                                "`categories` or `ordered`. Use "
-                                "`dtype=CategoricalDtype(categories, ordered)`"
-                                " instead.")
+
+            # deprecated 17636
+            if ('categories' in kwargs or 'ordered' in kwargs):
+                if isinstance(dtype, CategoricalDtype):
+                    raise TypeError(
+                        "Cannot specify a CategoricalDtype and also "
+                        "`categories` or `ordered`. Use "
+                        "`dtype=CategoricalDtype(categories, ordered)`"
+                        " instead.")
+                warnings.warn("specifying 'categories' or 'ordered' in "
+                              ".astype() is deprecated; pass a "
+                              "CategoricalDtype instead",
+                              FutureWarning, stacklevel=7)
+
             kwargs = kwargs.copy()
             categories = getattr(dtype, 'categories', None)
             ordered = getattr(dtype, 'ordered', False)

pandas/tests/frame/test_sorting.py

@@ -8,6 +8,7 @@
 
 import pandas as pd
 from pandas.compat import lrange
+from pandas.api.types import CategoricalDtype
 from pandas import (DataFrame, Series, MultiIndex, Timestamp,
                     date_range, NaT, IntervalIndex)
 
@@ -513,7 +514,7 @@ def test_sort_index_categorical_index(self):
 
         df = (DataFrame({'A': np.arange(6, dtype='int64'),
                          'B': Series(list('aabbca'))
-                         .astype('category', categories=list('cab'))})
+                         .astype(CategoricalDtype(list('cab')))})
               .set_index('B'))
 
         result = df.sort_index()

pandas/tests/series/test_dtypes.py

@@ -186,6 +186,16 @@ def test_astype_dict_like(self, dtype_class):
         with pytest.raises(KeyError):
             s.astype(dt5)
 
+    def test_astype_categories_deprecation(self):
+
+        # deprecated 17636
+        s = Series(['a', 'b', 'a'])
+        expected = s.astype(CategoricalDtype(['a', 'b'], ordered=True))
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            result = s.astype('category', categories=['a', 'b'], ordered=True)
+        tm.assert_series_equal(result, expected)
+
     def test_astype_categoricaldtype(self):
         s = Series(['a', 'b', 'a'])
         result = s.astype(CategoricalDtype(['a', 'b'], ordered=True))

pandas/tests/series/test_rank.py

@@ -7,7 +7,8 @@
 from numpy import nan
 import numpy as np
 
-from pandas import (Series, date_range, NaT)
+from pandas import Series, date_range, NaT
+from pandas.api.types import CategoricalDtype
 
 from pandas.compat import product
 from pandas.util.testing import assert_series_equal
@@ -123,50 +124,34 @@ def test_rank_categorical(self):
         exp_desc = Series([6., 5., 4., 3., 2., 1.])
         ordered = Series(
             ['first', 'second', 'third', 'fourth', 'fifth', 'sixth']
-        ).astype(
-            'category',
-            categories=['first', 'second', 'third',
-                        'fourth', 'fifth', 'sixth'],
-            ordered=True
-        )
+        ).astype(CategoricalDtype(categories=['first', 'second', 'third',
+                                              'fourth', 'fifth', 'sixth'],
+                                  ordered=True))
         assert_series_equal(ordered.rank(), exp)
         assert_series_equal(ordered.rank(ascending=False), exp_desc)
 
         # Unordered categoricals should be ranked as objects
-        unordered = Series(
-            ['first', 'second', 'third', 'fourth', 'fifth', 'sixth'],
-        ).astype(
-            'category',
-            categories=['first', 'second', 'third',
-                        'fourth', 'fifth', 'sixth'],
-            ordered=False
-        )
+        unordered = Series(['first', 'second', 'third', 'fourth',
+                            'fifth', 'sixth']).astype(
+            CategoricalDtype(categories=['first', 'second', 'third',
+                                         'fourth', 'fifth', 'sixth'],
+                             ordered=False))
         exp_unordered = Series([2., 4., 6., 3., 1., 5.])
         res = unordered.rank()
         assert_series_equal(res, exp_unordered)
 
         unordered1 = Series(
             [1, 2, 3, 4, 5, 6],
-        ).astype(
-            'category',
-            categories=[1, 2, 3, 4, 5, 6],
-            ordered=False
-        )
+        ).astype(CategoricalDtype([1, 2, 3, 4, 5, 6], False))
         exp_unordered1 = Series([1., 2., 3., 4., 5., 6.])
         res1 = unordered1.rank()
         assert_series_equal(res1, exp_unordered1)
 
         # Test na_option for rank data
         na_ser = Series(
             ['first', 'second', 'third', 'fourth', 'fifth', 'sixth', np.NaN]
-        ).astype(
-            'category',
-            categories=[
-                'first', 'second', 'third', 'fourth',
-                'fifth', 'sixth', 'seventh'
-            ],
-            ordered=True
-        )
+        ).astype(CategoricalDtype(['first', 'second', 'third', 'fourth',
+                                   'fifth', 'sixth', 'seventh'], True))
 
         exp_top = Series([2., 3., 4., 5., 6., 7., 1.])
         exp_bot = Series([1., 2., 3., 4., 5., 6., 7.])
@@ -195,13 +180,8 @@ def test_rank_categorical(self):
         )
 
         # Test with pct=True
-        na_ser = Series(
-            ['first', 'second', 'third', 'fourth', np.NaN],
-        ).astype(
-            'category',
-            categories=['first', 'second', 'third', 'fourth'],
-            ordered=True
-        )
+        na_ser = Series(['first', 'second', 'third', 'fourth', np.NaN]).astype(
+            CategoricalDtype(['first', 'second', 'third', 'fourth'], True))
         exp_top = Series([0.4, 0.6, 0.8, 1., 0.2])
         exp_bot = Series([0.2, 0.4, 0.6, 0.8, 1.])
         exp_keep = Series([0.25, 0.5, 0.75, 1., np.NaN])

pandas/tests/test_categorical.py

@@ -84,17 +84,17 @@ def test_getitem_category_type(self):
 
         # get slice
         result = s.iloc[0:2]
-        expected = pd.Series([1, 2]).astype('category', categories=[1, 2, 3])
+        expected = pd.Series([1, 2]).astype(CategoricalDtype([1, 2, 3]))
         tm.assert_series_equal(result, expected)
 
         # get list of indexes
         result = s.iloc[[0, 1]]
-        expected = pd.Series([1, 2]).astype('category', categories=[1, 2, 3])
+        expected = pd.Series([1, 2]).astype(CategoricalDtype([1, 2, 3]))
         tm.assert_series_equal(result, expected)
 
         # get boolean array
         result = s.iloc[[True, False, False]]
-        expected = pd.Series([1]).astype('category', categories=[1, 2, 3])
+        expected = pd.Series([1]).astype(CategoricalDtype([1, 2, 3]))
         tm.assert_series_equal(result, expected)
 
     def test_setitem(self):
@@ -2076,12 +2076,12 @@ def test_creation_astype(self):
         l = ["a", "b", "c", "a"]
         s = pd.Series(l)
         exp = pd.Series(Categorical(l, ordered=True))
-        res = s.astype('category', ordered=True)
+        res = s.astype(CategoricalDtype(None, ordered=True))
         tm.assert_series_equal(res, exp)
 
         exp = pd.Series(Categorical(
             l, categories=list('abcdef'), ordered=True))
-        res = s.astype('category', categories=list('abcdef'), ordered=True)
+        res = s.astype(CategoricalDtype(list('abcdef'), ordered=True))
         tm.assert_series_equal(res, exp)
 
     def test_construction_series(self):
@@ -4262,11 +4262,11 @@ def test_concat_preserve(self):
         b = Series(list('aabbca'))
 
         df2 = DataFrame({'A': a,
-                         'B': b.astype('category', categories=list('cab'))})
+                         'B': b.astype(CategoricalDtype(list('cab')))})
         res = pd.concat([df2, df2])
-        exp = DataFrame({'A': pd.concat([a, a]),
-                         'B': pd.concat([b, b]).astype(
-            'category', categories=list('cab'))})
+        exp = DataFrame(
+            {'A': pd.concat([a, a]),
+             'B': pd.concat([b, b]).astype(CategoricalDtype(list('cab')))})
         tm.assert_frame_equal(res, exp)
 
     def test_categorical_index_preserver(self):
@@ -4275,13 +4275,13 @@ def test_categorical_index_preserver(self):
         b = Series(list('aabbca'))
 
         df2 = DataFrame({'A': a,
-                         'B': b.astype('category', categories=list('cab'))
+                         'B': b.astype(CategoricalDtype(list('cab')))
                          }).set_index('B')
         result = pd.concat([df2, df2])
-        expected = DataFrame({'A': pd.concat([a, a]),
-                              'B': pd.concat([b, b]).astype(
-                                  'category', categories=list('cab'))
-                              }).set_index('B')
+        expected = DataFrame(
+            {'A': pd.concat([a, a]),
+             'B': pd.concat([b, b]).astype(CategoricalDtype(list('cab')))
+             }).set_index('B')
         tm.assert_frame_equal(result, expected)
 
         # wrong catgories
@@ -4324,7 +4324,7 @@ def test_merge(self):
         cright = right.copy()
         cright['d'] = cright['d'].astype('category')
         result = pd.merge(left, cright, how='left', left_on='b', right_on='c')
-        expected['d'] = expected['d'].astype('category', categories=['null'])
+        expected['d'] = expected['d'].astype(CategoricalDtype(['null']))
         tm.assert_frame_equal(result, expected)
 
         # cat-object