DEPR: Deprecate ordered=None for CategoricalDtype

Author: jschendel

doc/source/whatsnew/v0.25.0.rst

@@ -257,6 +257,7 @@ Deprecations
 
 - Deprecated the ``units=M`` (months) and ``units=Y`` (year) parameters for ``units`` 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` or :meth:`Timedelta.to_timedelta64`. (:issue:`24416`)
+- 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`)
 
 .. _whatsnew_0250.prior_deprecations:
 

pandas/core/dtypes/dtypes.py

@@ -550,8 +550,15 @@ def update_dtype(self, dtype):
             new_categories = self.categories
 
         new_ordered = dtype.ordered
+
+        # TODO(GH26336): remove this if block when ordered=None is removed
         if new_ordered is None:
             new_ordered = self.ordered
+            if self.ordered:
+                msg = ("ordered=None is deprecated and will default to False "
+                       "in a future version; ordered=True must be explicitly "
+                       "passed in order to be retained")
+                warnings.warn(msg, FutureWarning, stacklevel=2)
 
         return CategoricalDtype(new_categories, new_ordered)
 

pandas/tests/arrays/categorical/test_dtypes.py

@@ -160,6 +160,14 @@ def test_astype_category(self, dtype_ordered, cat_ordered):
             expected = cat
             tm.assert_categorical_equal(result, expected)
 
+    def test_astype_category_ordered_none_deprecated(self):
+        # GH 26336
+        cdt1 = CategoricalDtype(categories=list('cdab'), ordered=True)
+        cdt2 = CategoricalDtype(categories=list('cedafb'))
+        cat = Categorical(list('abcdaba'), dtype=cdt1)
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            cat.astype(cdt2)
+
     def test_iter_python_types(self):
         # GH-19909
         cat = Categorical([1, 2])

pandas/tests/dtypes/test_dtypes.py

@@ -817,7 +817,13 @@ def test_update_dtype(self, ordered_fixture, new_categories, new_ordered):
         if expected_ordered is None:
             expected_ordered = dtype.ordered
 
-        result = dtype.update_dtype(new_dtype)
+        # GH 26336
+        if new_ordered is None and ordered_fixture is True:
+            with tm.assert_produces_warning(FutureWarning):
+                result = dtype.update_dtype(new_dtype)
+        else:
+            result = dtype.update_dtype(new_dtype)
+
         tm.assert_index_equal(result.categories, expected_categories)
         assert result.ordered is expected_ordered
 

pandas/tests/indexes/test_category.py

@@ -490,6 +490,14 @@ def test_astype_category(self, name, dtype_ordered, index_ordered):
             expected = index
             tm.assert_index_equal(result, expected)
 
+    def test_astype_category_ordered_none_deprecated(self):
+        # GH 26336
+        cdt1 = CategoricalDtype(categories=list('cdab'), ordered=True)
+        cdt2 = CategoricalDtype(categories=list('cedafb'))
+        idx = CategoricalIndex(list('abcdaba'), dtype=cdt1)
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            idx.astype(cdt2)
+
     def test_reindex_base(self):
         # Determined by cat ordering.
         idx = CategoricalIndex(list("cab"), categories=list("cab"))

pandas/tests/series/test_dtypes.py

@@ -227,6 +227,14 @@ def test_astype_categories_deprecation(self):
             result = s.astype('category', categories=['a', 'b'], ordered=True)
         tm.assert_series_equal(result, expected)
 
+    def test_astype_category_ordered_none_deprecated(self):
+        # GH 26336
+        cdt1 = CategoricalDtype(categories=list('cdab'), ordered=True)
+        cdt2 = CategoricalDtype(categories=list('cedafb'))
+        s = Series(list('abcdaba'), dtype=cdt1)
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            s.astype(cdt2)
+
     def test_astype_from_categorical(self):
         items = ["a", "b", "c", "a"]
         s = Series(items)