Categorical: Thanks for Jan Schulz for much of the work on Categoricals

Doc: Add Release notes for #7217

DOC: update v0.15.0 notes

Categorical: .codes should be immutable

ERR: codes modification raises ValueError always

Categorical: use Categorical.from_codes() in a few places

Categorical: Fix assigning a Categorical to an existing string column

CLN: CategoricalDtype repr now yields category
DISPLAY: show dtype when displaying Categorical series (for consistency)

BUG: fix groupby with multiple non-compressed categoricals

Categorical: minor doc cleanups

ENH: add a metaclass to CategoricalDtype to provide issubclass support (for select_dtypes)

TST: io/pytables.py tests now raise NotImplementedError for dtype==category

DOC: document the new category dtype in select_dtypes

Author: jankatins

doc/source/api.rst

@@ -485,18 +485,26 @@ and has the following usable methods and properties (all available as
    :toctree: generated/
 
    Categorical
+   Categorical.from_codes
    Categorical.levels
    Categorical.ordered
    Categorical.reorder_levels
    Categorical.remove_unused_levels
    Categorical.min
    Categorical.max
    Categorical.mode
+   Categorical.describe
+
+``np.asarray(categorical)`` works by implementing the array interface. Be aware, that this converts
+the Categorical back to a numpy array, so levels and order information is not preserved!
+
+.. autosummary::
+   :toctree: generated/
+
+   Categorical.__array__
 
 To create compatibility with `pandas.Series` and `numpy` arrays, the following (non-API) methods
-are also introduced. Apart from these methods, ``np.asarray(categorical)`` works by implementing the
-array interface (`Categorical.__array__()`). Be aware, that this converts the
-Categorical back to a numpy array, so levels and order information is not preserved!
+are also introduced.
 
 .. autosummary::
    :toctree: generated/
@@ -507,13 +515,11 @@ Categorical back to a numpy array, so levels and order information is not preser
    Categorical.dtype
    Categorical.ndim
    Categorical.sort
-   Categorical.describe
    Categorical.equals
    Categorical.unique
    Categorical.order
    Categorical.argsort
    Categorical.fillna
-   Categorical.__array__
 
 
 Plotting

doc/source/basics.rst

@@ -1574,7 +1574,8 @@ dtypes:
                    'float64': np.arange(4.0, 7.0),
                    'bool1': [True, False, True],
                    'bool2': [False, True, False],
-                   'dates': pd.date_range('now', periods=3).values})
+                   'dates': pd.date_range('now', periods=3).values}),
+                   'category': pd.Categorical(list("ABC))
    df['tdeltas'] = df.dates.diff()
    df['uint64'] = np.arange(3, 6).astype('u8')
    df['other_dates'] = pd.date_range('20130101', periods=3).values
@@ -1630,6 +1631,11 @@ All numpy dtypes are subclasses of ``numpy.generic``:
 
     subdtypes(np.generic)
 
+.. note::
+
+    Pandas also defines an additional ``category`` dtype, which is not integrated into the normal
+    numpy hierarchy and wont show up with the above function.
+
 .. note::
 
    The ``include`` and ``exclude`` parameters must be non-string sequences.