fixup! ENH: Parametrized CategoricalDtype

Author: TomAugspurger

doc/source/categorical.rst

@@ -152,13 +152,14 @@ CategoricalDtype
 
 A categorical's type is fully described by
 
-1. its categories: a sequence of unique values and no missing values
-2. its orderedness: a boolean
+1. ``categories``: a sequence of unique values and no missing values
+2. ``ordered``: a boolean
 
 This information can be stored in a :class:`~pandas.api.types.CategoricalDtype`.
 The ``categories`` argument is optional, which implies that the actual categories
 should be inferred from whatever is present in the data when the
-:class:`pandas.Categorical` is created.
+:class:`pandas.Categorical` is created. The categories are assumed to be unordered
+by default.      
 
 .. ipython:: python
 
@@ -172,11 +173,13 @@ A :class:`~pandas.api.types.CategoricalDtype` can be used in any place pandas
 expects a `dtype`. For example :func:`pandas.read_csv`,
 :func:`pandas.DataFrame.astype`, or in the Series constructor.
 
-As a convenience, you can use the string ``'category'`` in place of a
-:class:`~pandas.api.types.CategoricalDtype` when you want the default behavior of
-the categories being unordered, and equal to the set values present in the
-array. In other words, ``dtype='category'`` is equivalent to
-``dtype=CategoricalDtype()``.
+.. note::
+
+    As a convenience, you can use the string ``'category'`` in place of a
+    :class:`~pandas.api.types.CategoricalDtype` when you want the default behavior of
+    the categories being unordered, and equal to the set values present in the
+    array. In other words, ``dtype='category'`` is equivalent to
+    ``dtype=CategoricalDtype()``.
 
 Equality Semantics
 ~~~~~~~~~~~~~~~~~~

doc/source/whatsnew/v0.21.0.txt

@@ -11,7 +11,7 @@ Highlights include:
 
 - Integration with `Apache Parquet <https://parquet.apache.org/>`__, including a new top-level :func:`read_parquet` and :func:`DataFrame.to_parquet` method, see :ref:`here <io.parquet>`.
 - New user-facing :class:`pandas.api.types.CategoricalDtype` for specifying
-  categoricals independent of the data (:issue:`14711`, :issue:`15078`)
+  categoricals independent of the data, see :ref:`here <whatsnew_0210.enhancements.categorical_dtype>`.
 
 Check the :ref:`API Changes <whatsnew_0210.api_breaking>` and :ref:`deprecations <whatsnew_0210.deprecations>` before updating.
 
@@ -99,7 +99,7 @@ Setting a list-like data structure into a new attribute now raise a ``UserWarnin
 expanded to include the ``categories`` and ``ordered`` attributes. A
 ``CategoricalDtype`` can be used to specify the set of categories and
 orderedness of an array, independent of the data themselves. This can be useful,
-e.g., when converting string data to a ``Categorical``:
+e.g., when converting string data to a ``Categorical`` (:issue:`14711`, :issue:`15078`):
 
 .. ipython:: python
 

pandas/core/categorical.py

@@ -139,33 +139,6 @@ def maybe_to_categorical(array):
 setter to change values in the categorical.
 """
 
-_categories_doc = """The categories of this categorical.
-
-Setting assigns new values to each category (effectively a rename of
-each individual category).
-
-The assigned value has to be a list-like object. All items must be unique and
-the number of items in the new categories must be the same as the number of
-items in the old categories.
-
-Assigning to `categories` is a inplace operation!
-
-Raises
-------
-ValueError
-    If the new categories do not validate as categories or if the number of new
-    categories is unequal the number of old categories
-
-See also
---------
-rename_categories
-reorder_categories
-add_categories
-remove_categories
-remove_unused_categories
-set_categories
-"""
-
 
 class Categorical(PandasObject):
     """
@@ -192,6 +165,10 @@ class Categorical(PandasObject):
     ordered : boolean, (default False)
         Whether or not this categorical is treated as a ordered categorical.
         If not given, the resulting categorical will not be ordered.
+    dtype : CategoricalDtype
+        An instance of ``CategoricalDtype`` to use for this categorical
+
+        .. versionadded:: 0.21.0
 
     Attributes
     ----------
@@ -203,6 +180,10 @@ class Categorical(PandasObject):
     ordered : boolean
         Whether or not this Categorical is ordered.
     dtype : CategoricalDtype
+        The instance of ``CategoricalDtype`` storing the ``categories``
+        and ``ordered``.
+
+        .. versionadded:: 0.21.0
 
     Raises
     ------
@@ -212,7 +193,6 @@ class Categorical(PandasObject):
         If an explicit ``ordered=True`` is given but no `categories` and the
         `values` are not sortable.
 
-
     Examples
     --------
     >>> from pandas import Categorical
@@ -224,17 +204,17 @@ class Categorical(PandasObject):
     [a, b, c, a, b, c]
     Categories (3, object): [a < b < c]
 
+    Only ordered `Categoricals` can be sorted (according to the order
+    of the categories) and have a min and max value.
+
     >>> a = Categorical(['a','b','c','a','b','c'], ['c', 'b', 'a'],
                         ordered=True)
     >>> a.min()
     'c'
-    """
-    _dtype = CategoricalDtype()
-    """The dtype (always "category")"""
-    """Whether or not this Categorical is ordered.
 
-    Only ordered `Categoricals` can be sorted (according to the order
-    of the categories) and have a min and max value.
+    Notes
+    -----
+    See the :ref:`user guide <categorical>` for more.
 
     See also
     --------
@@ -247,6 +227,7 @@ class Categorical(PandasObject):
     # For comparisons, so that numpy uses our implementation if the compare
     # ops, which raise
     __array_priority__ = 1000
+    _dtype = CategoricalDtype()
     _typ = 'categorical'
 
     def __init__(self, values, categories=None, ordered=None, dtype=None,
@@ -359,6 +340,32 @@ def __init__(self, values, categories=None, ordered=None, dtype=None,
 
     @property
     def categories(self):
+        """The categories of this categorical.
+
+        Setting assigns new values to each category (effectively a rename of
+        each individual category).
+
+        The assigned value has to be a list-like object. All items must be
+        unique and the number of items in the new categories must be the same
+        as the number of items in the old categories.
+
+        Assigning to `categories` is a inplace operation!
+
+        Raises
+        ------
+        ValueError
+            If the new categories do not validate as categories or if the
+            number of new categories is unequal the number of old categories
+
+        See also
+        --------
+        rename_categories
+        reorder_categories
+        add_categories
+        remove_categories
+        remove_unused_categories
+        set_categories
+        """
         return self.dtype.categories
 
     @categories.setter
@@ -372,10 +379,12 @@ def categories(self, categories):
 
     @property
     def ordered(self):
+        """Whether the categories have an ordered relationship"""
         return self.dtype.ordered
 
     @property
     def dtype(self):
+        """The :ref:`~pandas.api.types.CategoricalDtype` for this instance"""
         return self._dtype
 
     def __dir__(self):