fixup! ENH: Parametrized CategoricalDtype

Author: TomAugspurger

doc/source/api.rst

@@ -637,7 +637,10 @@ strings and apply several methods to it. These can be accessed like
 Categorical
 ~~~~~~~~~~~
 
-If the Series is of dtype ``category``, ``Series.cat`` can be used to change the the categorical
+.. autoclass:: api.types.CategoricalDtype
+   :members: categories, ordered
+
+If the Series is of dtype ``CategoricalDtype``, ``Series.cat`` can be used to change the categorical
 data. This accessor is similar to the ``Series.dt`` or ``Series.str`` and has the
 following usable methods and properties:
 

doc/source/categorical.rst

@@ -99,9 +99,11 @@ of :class:`~pd.api.types.CategoricalDtype`.
 
 .. ipython:: python
 
+    from pandas.api.types import CategoricalDtype
+
     s = pd.Series(["a", "b", "c", "a"])
-    cat_type = pd.api.types.CategoricalDtype(categories=["b", "c", "d"],
-                                             ordered=False)
+    cat_type = CategoricalDtype(categories=["b", "c", "d"],
+                                ordered=False)
     s_cat = s.astype(cat_type)
     s_cat
 
@@ -141,33 +143,40 @@ constructor to save the factorize step during normal constructor mode:
     splitter = np.random.choice([0,1], 5, p=[0.5,0.5])
     s = pd.Series(pd.Categorical.from_codes(splitter, categories=["train", "test"]))
 
+.. _categorical.categoricaldtype:
+
 CategoricalDtype
 ----------------
 
 .. versionchanged:: 0.21.0
 
-A categorical's type is fully described by 1.) its categories (an iterable with
-unique values and no missing values), and 2.) its orderedness (a boolean).
+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
+
 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.
 
 .. ipython:: python
 
-   pd.api.types.CategoricalDtype(['a', 'b', 'c'])
-   pd.api.types.CategoricalDtype(['a', 'b', 'c'], ordered=True)
-   pd.api.types.CategoricalDtype()
+   from pandas.api.types import CategoricalDtype
+
+   CategoricalDtype(['a', 'b', 'c'])
+   CategoricalDtype(['a', 'b', 'c'], ordered=True)
+   CategoricalDtype()
 
 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 the Series constructor.
+:func:`pandas.DataFrame.astype`, or in the Series constructor.
 
-As a convenience, you can use the string `'category'` in place of a
+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. On other words, ``dtype='category'`` is equivalent to
-``dtype=pd.api.types.CategoricalDtype()``.
+array. In other words, ``dtype='category'`` is equivalent to
+``dtype=CategoricalDtype()``.
 
 Equality Semantics
 ~~~~~~~~~~~~~~~~~~
@@ -178,19 +187,20 @@ order of the ``categories`` is not considered
 
 .. ipython:: python
 
-   c1 = pd.api.types.CategoricalDtype(['a', 'b', 'c'], ordered=False)
+   c1 = CategoricalDtype(['a', 'b', 'c'], ordered=False)
+
    # Equal, since order is not considered when ordered=False
-   c1 == pd.api.types.CategoricalDtype(['b', 'c', 'a'], ordered=False)
+   c1 == CategoricalDtype(['b', 'c', 'a'], ordered=False)
+
    # Unequal, since the second CategoricalDtype is ordered
-   c1 == pd.api.types.CategoricalDtype(['a',  'b', 'c'], ordered=True)
+   c1 == CategoricalDtype(['a',  'b', 'c'], ordered=True)
 
 All instances of ``CategoricalDtype`` compare equal to the string ``'category'``
 
 .. ipython:: python
 
    c1 == 'category'
 
-
 .. warning::
 
    Since ``dtype='category'`` is essentially ``CategoricalDtype(None, False)``,
@@ -246,9 +256,7 @@ It's also possible to pass in the categories in a specific order:
 
     .. ipython:: python
 
-         s = pd.Series(list('babc')).astype(
-             pd.api.types.CategoricalDtype(list('abcd'))
-         )
+         s = pd.Series(list('babc')).astype(CategoricalDtype(list('abcd')))
          s
 
          # categories
@@ -362,7 +370,7 @@ meaning and certain operations are possible. If the categorical is unordered, ``
     s = pd.Series(pd.Categorical(["a","b","c","a"], ordered=False))
     s.sort_values(inplace=True)
     s = pd.Series(["a","b","c","a"]).astype(
-        pd.api.types.CategoricalDtype(ordered=True)
+        CategoricalDtype(ordered=True)
     )
     s.sort_values(inplace=True)
     s
@@ -464,13 +472,13 @@ categories or a categorical with any list-like object, will raise a TypeError.
 .. ipython:: python
 
     cat = pd.Series([1,2,3]).astype(
-        pd.api.types.CategoricalDtype([3, 2, 1], ordered=True)
+        CategoricalDtype([3, 2, 1], ordered=True)
     )
     cat_base = pd.Series([2,2,2]).astype(
-        pd.api.types.CategoricalDtype([3, 2, 1], ordered=True)
+        CategoricalDtype([3, 2, 1], ordered=True)
     )
     cat_base2 = pd.Series([2,2,2]).astype(
-        pd.api.types.CategoricalDtype(ordered=True)
+        CategoricalDtype(ordered=True)
     )
 
     cat

doc/source/whatsnew/v0.21.0.txt

@@ -10,6 +10,8 @@ users upgrade to this version.
 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`)
 
 Check the :ref:`API Changes <whatsnew_0210.api_breaking>` and :ref:`deprecations <whatsnew_0210.deprecations>` before updating.
 
@@ -22,8 +24,6 @@ Check the :ref:`API Changes <whatsnew_0210.api_breaking>` and :ref:`deprecations
 New features
 ~~~~~~~~~~~~
 
-- New user-facing :class:`pandas.api.types.CategoricalDtype` for specifying
-  categoricals independent of the data (:issue:`14711`, :issue:`15078`)
 - Support for `PEP 519 -- Adding a file system path protocol
   <https://www.python.org/dev/peps/pep-0519/>`_ on most readers and writers (:issue:`13823`)
 - Added ``__fspath__`` method to :class:`~pandas.HDFStore`, :class:`~pandas.ExcelFile`,