REF: clearer construction of Categorical/CategoricalIndex

Author: topper-123

pandas/core/arrays/categorical.py

@@ -200,6 +200,62 @@ def contains(cat, key, container):
         return any(loc_ in container for loc_ in loc)
 
 
+def create_categorical_dtype(values, categories=None, ordered=None,
+                             dtype=None):
+    """
+    Helper function to Construct/return a :class:`CategoricalDtype`.
+
+    Construct the CategoricalDtype from typical inputs to :class:`Categorical`.
+
+    Parameters
+    ----------
+    values : array-like or Categorical, (1-dimensional), optional
+    categories : list-like, optional
+        categories for the CategoricalDtype
+    ordered : bool, optional
+        designating if the categories are ordered
+    dtype : CategoricalDtype, optional
+        Cannot be used in combination with `categories` or `ordered`.
+
+    Returns
+    -------
+    CategoricalDtype
+
+    Examples
+    --------
+    >>> create_categorical_dtype()
+    CategoricalDtype(categories=None, ordered=None)
+    >>> create_categorical_dtype(categories=['a', 'b'], ordered=True)
+    CategoricalDtype(categories=['a', 'b'], ordered=True)
+    >>> dtype = CategoricalDtype(['a', 'b'], ordered=True)
+    >>> c = Categorical([0, 1], dtype=dtype, fastpath=True)
+    >>> create_categorical_dtype(c, ['x', 'y'], True, dtype=dtype)
+    CategoricalDtype(['a', 'b'], ordered=True)
+    """
+    if dtype is not None:
+        # The dtype argument takes precedence over values.dtype (if any)
+        if isinstance(dtype, compat.string_types):
+            if dtype == 'category':
+                dtype = CategoricalDtype(categories, ordered)
+            else:
+                msg = "Unknown dtype {dtype!r}"
+                raise ValueError(msg.format(dtype=dtype))
+        elif categories is not None or ordered is not None:
+            raise ValueError("Cannot specify `categories` or `ordered` "
+                             "together with `dtype`.")
+    elif is_categorical(values):
+        # If no "dtype" was passed, use the one from "values", but honor
+        # the "ordered" and "categories" arguments
+        dtype = values.dtype._from_categorical_dtype(values.dtype,
+                                                     categories, ordered)
+    else:
+        # If dtype=None and values is not categorical, create a new dtype.
+        # Note: This could potentially have categories=None and ordered=None.
+        dtype = CategoricalDtype(categories, ordered)
+
+    return dtype
+
+
 _codes_doc = """\
 The category codes of this categorical.
 
@@ -316,50 +372,18 @@ class Categorical(ExtensionArray, PandasObject):
     def __init__(self, values, categories=None, ordered=None, dtype=None,
                  fastpath=False):
 
-        # Ways of specifying the dtype (prioritized ordered)
-        # 1. dtype is a CategoricalDtype
-        #    a.) with known categories, use dtype.categories
-        #    b.) else with Categorical values, use values.dtype
-        #    c.) else, infer from values
-        #    d.) specifying dtype=CategoricalDtype and categories is an error
-        # 2. dtype is a string 'category'
-        #    a.) use categories, ordered
-        #    b.) use values.dtype
-        #    c.) infer from values
-        # 3. dtype is None
-        #    a.) use categories, ordered
-        #    b.) use values.dtype
-        #    c.) infer from values
-        if dtype is not None:
-            # The dtype argument takes precedence over values.dtype (if any)
-            if isinstance(dtype, compat.string_types):
-                if dtype == 'category':
-                    dtype = CategoricalDtype(categories, ordered)
-                else:
-                    msg = "Unknown `dtype` {dtype}"
-                    raise ValueError(msg.format(dtype=dtype))
-            elif categories is not None or ordered is not None:
-                raise ValueError("Cannot specify both `dtype` and `categories`"
-                                 " or `ordered`.")
-        elif is_categorical(values):
-            # If no "dtype" was passed, use the one from "values", but honor
-            # the "ordered" and "categories" arguments
-            dtype = values.dtype._from_categorical_dtype(values.dtype,
-                                                         categories, ordered)
+        dtype = create_categorical_dtype(values, categories, ordered, dtype)
+        # At this point, dtype is always a CategoricalDtype, but
+        # we may have dtype.categories be None, and we need to
+        # infer categories in a factorization step futher below
 
+        if is_categorical(values):
             # GH23814, for perf, if values._values already an instance of
             # Categorical, set values to codes, and run fastpath
             if (isinstance(values, (ABCSeries, ABCIndexClass)) and
                isinstance(values._values, type(self))):
                 values = values._values.codes.copy()
                 fastpath = True
-        else:
-            # If dtype=None and values is not categorical, create a new dtype
-            dtype = CategoricalDtype(categories, ordered)
-
-        # At this point, dtype is always a CategoricalDtype and you should not
-        # use categories and ordered seperately.
-        # if dtype.categories is None, we are inferring
 
         if fastpath:
             self._codes = coerce_indexer_dtype(values, dtype.categories)
@@ -656,6 +680,8 @@ def from_codes(cls, codes, categories, ordered=False):
             categorical. If not given, the resulting categorical will be
             unordered.
         """
+        dtype = create_categorical_dtype(codes, categories, ordered)
+
         codes = np.asarray(codes)  # #21767
         if not is_integer_dtype(codes):
             msg = "codes need to be array-like integers"
@@ -675,14 +701,12 @@ def from_codes(cls, codes, categories, ordered=False):
             raise ValueError(
                 "codes need to be convertible to an arrays of integers")
 
-        categories = CategoricalDtype.validate_categories(categories)
-
-        if len(codes) and (codes.max() >= len(categories) or codes.min() < -1):
+        if len(codes) and (
+                codes.max() >= len(dtype.categories) or codes.min() < -1):
             raise ValueError("codes need to be between -1 and "
                              "len(categories)-1")
 
-        return cls(codes, categories=categories, ordered=ordered,
-                   fastpath=True)
+        return cls(codes, dtype=dtype, fastpath=True)
 
     _codes = None
 

pandas/core/indexes/category.py

@@ -17,7 +17,8 @@
 
 from pandas.core import accessor
 from pandas.core.algorithms import take_1d
-from pandas.core.arrays.categorical import Categorical, contains
+from pandas.core.arrays.categorical import (
+    Categorical, contains, create_categorical_dtype)
 import pandas.core.common as com
 from pandas.core.config import get_option
 import pandas.core.indexes.base as ibase
@@ -107,29 +108,22 @@ def __new__(cls, data=None, categories=None, ordered=None, dtype=None,
             if fastpath:
                 return cls._simple_new(data, name=name, dtype=dtype)
 
+        dtype = create_categorical_dtype(data, categories, ordered, dtype)
+
         if name is None and hasattr(data, 'name'):
             name = data.name
 
-        if isinstance(data, ABCCategorical):
-            data = cls._create_categorical(data, categories, ordered,
-                                           dtype)
-        elif isinstance(data, CategoricalIndex):
-            data = data._data
-            data = cls._create_categorical(data, categories, ordered,
-                                           dtype)
-        else:
-
+        if not is_categorical_dtype(data):
             # don't allow scalars
             # if data is None, then categories must be provided
             if is_scalar(data):
                 if data is not None or categories is None:
                     cls._scalar_data_error(data)
                 data = []
-            data = cls._create_categorical(data, categories, ordered,
-                                           dtype)
 
-        if copy:
-            data = data.copy()
+        data = cls._create_categorical(data, dtype=dtype)
+
+        data = data.copy() if copy else data
 
         return cls._simple_new(data, name=name)
 
@@ -159,8 +153,7 @@ def _create_from_codes(self, codes, dtype=None, name=None):
         return CategoricalIndex(cat, name=name)
 
     @classmethod
-    def _create_categorical(cls, data, categories=None, ordered=None,
-                            dtype=None):
+    def _create_categorical(cls, data, dtype=None):
         """
         *this is an internal non-public method*
 
@@ -169,8 +162,6 @@ def _create_categorical(cls, data, categories=None, ordered=None,
         Parameters
         ----------
         data : data for new Categorical
-        categories : optional categories, defaults to existing
-        ordered : optional ordered attribute, defaults to existing
         dtype : CategoricalDtype, defaults to existing
 
         Returns
@@ -182,18 +173,11 @@ def _create_categorical(cls, data, categories=None, ordered=None,
             data = data.values
 
         if not isinstance(data, ABCCategorical):
-            if ordered is None and dtype is None:
-                ordered = False
-            data = Categorical(data, categories=categories, ordered=ordered,
-                               dtype=dtype)
-        else:
-            if categories is not None:
-                data = data.set_categories(categories, ordered=ordered)
-            elif ordered is not None and ordered != data.ordered:
-                data = data.set_ordered(ordered)
-            if isinstance(dtype, CategoricalDtype) and dtype != data.dtype:
-                # we want to silently ignore dtype='category'
-                data = data._set_dtype(dtype)
+            return Categorical(data, dtype=dtype)
+
+        if isinstance(dtype, CategoricalDtype) and dtype != data.dtype:
+            # we want to silently ignore dtype='category'
+            data = data._set_dtype(dtype)
         return data
 
     @classmethod

pandas/tests/arrays/categorical/test_constructors.py

@@ -368,7 +368,7 @@ def test_constructor_str_category(self, categories, ordered):
         tm.assert_categorical_equal(result, expected)
 
     def test_constructor_str_unknown(self):
-        with pytest.raises(ValueError, match="Unknown `dtype`"):
+        with pytest.raises(ValueError, match="Unknown dtype"):
             Categorical([1, 2], dtype="foo")
 
     def test_constructor_from_categorical_with_dtype(self):

pandas/tests/dtypes/test_dtypes.py

@@ -94,7 +94,7 @@ def test_construction_from_string(self):
             TypeError, lambda: CategoricalDtype.construct_from_string('foo'))
 
     def test_constructor_invalid(self):
-        msg = "categories must be list-like"
+        msg = "Parameter 'categories' must be list-like"
         with pytest.raises(TypeError, match=msg):
             CategoricalDtype("category")
 
@@ -710,7 +710,7 @@ def test_invalid_raises(self):
         with pytest.raises(TypeError, match='ordered'):
             CategoricalDtype(['a', 'b'], ordered='foo')
 
-        with pytest.raises(TypeError, match='categories must be list-like'):
+        with pytest.raises(TypeError, match="'categories' must be list-like"):
             CategoricalDtype('category')
 
     def test_mixed(self):

pandas/tests/indexes/test_category.py

@@ -156,7 +156,7 @@ def test_construction_with_categorical_dtype(self):
         tm.assert_index_equal(result, expected, exact=True)
 
         # error when combining categories/ordered and dtype kwargs
-        msg = 'Cannot specify both `dtype` and `categories` or `ordered`.'
+        msg = 'Cannot specify `categories` or `ordered` together with `dtype`.'
         with pytest.raises(ValueError, match=msg):
             CategoricalIndex(data, categories=cats, dtype=dtype)