API: allow single element boolean Series to mimic numpy behavior( related GH4657)

TST: test for single element with null-like

DOC: deprecation message for using bool(Series([True]))

Author: jreback

doc/source/release.rst

@@ -241,7 +241,8 @@ API Changes
 
   - Infer and downcast dtype if ``downcast='infer'`` is passed to ``fillna/ffill/bfill`` (:issue:`4604`)
   - ``__nonzero__`` for all NDFrame objects, will now raise a ``ValueError``, this reverts back to (:issue:`1073`, :issue:`4633`)
-    behavior.
+    behavior (except for a single-element boolean Series, which mimics ``numpy`` behavior and will evaluate
+    to the bool of the element)
   - ``DataFrame.update()`` no longer raises a ``DataConflictError``, it now
     will raise a ``ValueError`` instead (if necessary) (:issue:`4732`)
   - ``Series.isin()`` and ``DataFrame.isin()``  now raise a ``TypeError`` when

doc/source/v0.13.0.txt

@@ -56,9 +56,10 @@ API changes
 
   - Infer and downcast dtype if ``downcast='infer'`` is passed to ``fillna/ffill/bfill`` (:issue:`4604`)
   - ``__nonzero__`` for all NDFrame objects, will now raise a ``ValueError``, this reverts back to (:issue:`1073`, :issue:`4633`)
-    behavior. See :ref:`gotchas<gotchas.truth>` for a more detailed discussion.
+    behavior (except for a single-element boolean Series, which mimics ``numpy`` behavior and will evaluate
+    to the bool of the element). See :ref:`gotchas<gotchas.truth>` for a more detailed discussion.
 
-    This prevent behaviors like (which will now all raise ``ValueError``)
+    This prevents behaviors like (which will now all raise ``ValueError``)
 
     .. code-block:: python
 

pandas/core/generic.py

@@ -596,7 +596,8 @@ def empty(self):
         return not all(len(self._get_axis(a)) > 0 for a in self._AXIS_ORDERS)
 
     def __nonzero__(self):
-        raise ValueError("The truth value of an array is ambiguous. Use a.empty, a.item(), a.any() or a.all().")
+        raise ValueError("The truth value of a {0} is ambiguous. "
+                         "Use a.empty, a.item(), a.any() or a.all().".format(self.__class__.__name__))
 
     __bool__ = __nonzero__
 

pandas/core/series.py

@@ -7,6 +7,7 @@
 
 import operator
 import types
+import warnings
 
 from numpy import nan, ndarray
 import numpy as np
@@ -364,6 +365,17 @@ def imag(self, v):
     __long__ = _coerce_method(int)
     __int__ = _coerce_method(int)
 
+    def __nonzero__(self):
+        if len(self) == 1 and self.dtype == np.bool_:
+            warnings.warn("bool on a single-element boolean dtyped Series is deprecated,\n"
+                          " please use a.empty, a.item(), a.any(), or a.all() instead\n",
+                          UserWarning)
+            return bool(self.iloc[0])
+        raise ValueError("The truth value of a {0} is ambiguous.\n"
+                         "Use a.empty, a.item(), a.any() or a.all().\n"
+                         "Currently, a boolean Series of length 1 is the exception\n".format(self.__class__.__name__))
+    __bool__ = __nonzero__
+
     # we are preserving name here
     def __getstate__(self):
         return dict(_data=self._data, name=self.name)
@@ -913,7 +925,6 @@ def to_string(self, buf=None, na_rep='NaN', float_format=None,
         """
 
         if nanRep is not None:  # pragma: no cover
-            import warnings
             warnings.warn("nanRep is deprecated, use na_rep", FutureWarning)
             na_rep = nanRep
 

pandas/tests/test_generic.py

@@ -205,11 +205,26 @@ def test_get_numeric_data_preserve_dtype(self):
 
     def test_nonzero_single_element(self):
 
+        # single item to follow numpy
         s = Series([True])
-        self.assertRaises(ValueError, lambda : bool(s))
+        self.assert_(bool(s) == True)
 
         s = Series([False])
-        self.assertRaises(ValueError, lambda : bool(s))
+        self.assert_(bool(s) == False)
+
+        # single item nan to raise
+        for s in [ Series([np.nan]), Series([pd.NaT]) ]:
+            self.assertRaises(ValueError, lambda : bool(s))
+
+        # multiple bool are still an error
+        for s in [Series([True,True]), Series([False, False])]:
+            self.assertRaises(ValueError, lambda : bool(s))
+
+        # single non-bool are an error
+        for s in [Series([1]), Series([0]),
+                  Series(['a']), Series([0.0])]:
+                self.assertRaises(ValueError, lambda : bool(s))
+
 
 class TestDataFrame(unittest.TestCase, Generic):
     _typ = DataFrame