Comment updates

Author: TomAugspurger

doc/source/whatsnew/v0.21.0.txt

@@ -294,6 +294,8 @@ length 2+ levels, so a :class:`MultiIndex` is always returned from all of the
 
    pd.MultiIndex.from_tuples([('a',), ('b',)])
 
+This affects all the ``MultiIndex`` constructors. (:issue:`17178`)
+
 .. _whatsnew_0210.api:
 
 Other API Changes

pandas/core/indexes/base.py

@@ -4032,6 +4032,10 @@ def _ensure_index_from_sequences(sequences, names=None):
     MultiIndex(levels=[['a'], ['a', 'b']],
                labels=[[0, 0], [0, 1]],
                names=['L1', 'L2'])
+
+    See Also
+    --------
+    _ensure_index
     """
     from .multi import MultiIndex
 
@@ -4068,6 +4072,10 @@ def _ensure_index(index_like, copy=False):
     >>> _ensure_index([['a', 'a'], ['b', 'c']])
     MultiIndex(levels=[['a'], ['b', 'c']],
                labels=[[0, 0], [0, 1]])
+
+    See Also
+    --------
+    _ensure_index_from_sequences
     """
     if isinstance(index_like, Index):
         if copy:

pandas/core/reshape/reshape.py

@@ -450,12 +450,12 @@ def _slow_pivot(index, columns, values):
 
 def unstack(obj, level, fill_value=None):
     if isinstance(level, (tuple, list)):
-        if len(level) == 1:
-            # unstack_multiple only handles MultiIndexes,
+        if len(level) != 1:
+            # _unstack_multiple only handles MultiIndexes,
             # and isn't needed for a single level
-            level = level[0]
-        else:
             return _unstack_multiple(obj, level)
+        else:
+            level = level[0]
 
     if isinstance(obj, DataFrame):
         if isinstance(obj.index, MultiIndex):

pandas/tests/io/parser/dtypes.py

@@ -6,6 +6,7 @@
 """
 
 import pytest
+from textwrap import dedent
 
 import numpy as np
 import pandas as pd
@@ -149,6 +150,19 @@ def test_categorical_dtype_chunksize(self):
         for actual, expected in zip(actuals, expecteds):
             tm.assert_frame_equal(actual, expected)
 
+    def test_categorical_categoricaldtype(self):
+        data = dedent("""\
+            A,B
+            1,a
+            2,b""")
+        dtype = CategoricalDtype(categories=['a', 'b', 'c'])
+        expected = pd.DataFrame({
+            "A": [1, 2],
+            "B": pd.Categorical(['a', 'b'], categories=['a', 'b', 'c'])
+        })[['A', 'B']]
+        result = self.read_csv(StringIO(data), dtype={"B": dtype})
+        tm.assert_frame_equal(result, expected)
+
     def test_empty_pass_dtype(self):
         data = 'one,two'
         result = self.read_csv(StringIO(data), dtype={'one': 'u1'})