BUG: pivot_table always returns a DataFrame

Before this commit, if

* `values` is not list like
* `columns` is `None`
* `aggfunc` is not instance of `list`

`pivot_table` returns a `Series`.

This commit adds checking for `columns.nlevels` is
greater than 1 to prevent from casting `table` to
a `Series`.

This will fix #4386.

DOC: add docs for #13554

Author: yui-knk

doc/source/whatsnew/v0.20.0.txt

@@ -1287,6 +1287,38 @@ joins, :meth:`DataFrame.join` and :func:`merge`, and the ``.align`` methods.
 
      left.join(right, how='inner')
 
+.. _whatsnew_0200.api_breaking.pivot_table:
+
+Pivot Table always returns a DataFrame
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The documentation for :meth:`pivot_table` states that a ``DataFrame`` is *always* returned. Here a bug
+is fixed that allowed this to return a ``Series`` under a narrow circumstance. (:issue:`4386`)
+
+.. ipython:: python
+
+   df = DataFrame({'col1': [3, 4, 5],
+                   'col2': ['C', 'D', 'E'],
+                   'col3': [1, 3, 9]})
+   df
+
+Previous Behavior:
+
+.. code-block:: ipython
+
+   In [2]: df.pivot_table('col1', index=['col3', 'col2'], aggfunc=np.sum)
+   Out[2]:
+   col3  col2
+   1     C       3
+   3     D       4
+   9     E       5
+   Name: col1, dtype: int64
+
+New Behavior:
+
+.. ipython:: python
+
+   df.pivot_table('col1', index=['col3', 'col2'], aggfunc=np.sum)
 
 .. _whatsnew_0200.api:
 

pandas/core/reshape/pivot.py

@@ -170,7 +170,8 @@ def pivot_table(data, values=None, index=None, columns=None, aggfunc='mean',
                              margins_name=margins_name)
 
     # discard the top level
-    if values_passed and not values_multi and not table.empty:
+    if values_passed and not values_multi and not table.empty and \
+       (table.columns.nlevels > 1):
         table = table[values[0]]
 
     if len(index) == 0 and len(columns) > 0:

pandas/tests/reshape/test_pivot.py

@@ -940,6 +940,44 @@ def test_categorical_pivot_index_ordering(self):
                                 columns=expected_columns)
         tm.assert_frame_equal(result, expected)
 
+    def test_pivot_table_not_series(self):
+        # GH 4386
+        # pivot_table always returns a DataFrame
+        # when values is not list like and columns is None
+        # and aggfunc is not instance of list
+        df = DataFrame({'col1': [3, 4, 5],
+                        'col2': ['C', 'D', 'E'],
+                        'col3': [1, 3, 9]})
+
+        result = df.pivot_table('col1', index=['col3', 'col2'], aggfunc=np.sum)
+        m = MultiIndex.from_arrays([[1, 3, 9],
+                                    ['C', 'D', 'E']],
+                                   names=['col3', 'col2'])
+        expected = DataFrame([3, 4, 5],
+                             index=m, columns=['col1'])
+
+        tm.assert_frame_equal(result, expected)
+
+        result = df.pivot_table(
+            'col1', index='col3', columns='col2', aggfunc=np.sum
+        )
+        expected = DataFrame([[3, np.NaN, np.NaN],
+                              [np.NaN, 4, np.NaN],
+                              [np.NaN, np.NaN, 5]],
+                             index=Index([1, 3, 9], name='col3'),
+                             columns=Index(['C', 'D', 'E'], name='col2'))
+
+        tm.assert_frame_equal(result, expected)
+
+        result = df.pivot_table('col1', index='col3', aggfunc=[np.sum])
+        m = MultiIndex.from_arrays([['sum'],
+                                    ['col1']])
+        expected = DataFrame([3, 4, 5],
+                             index=Index([1, 3, 9], name='col3'),
+                             columns=m)
+
+        tm.assert_frame_equal(result, expected)
+
 
 class TestCrosstab(tm.TestCase):