API: GH4633, bool(obj) behavior, raise on __nonzero__ always
State: closed

closes #4633

this is a revert to #1073/#1069

now a call to `__nonzero__` raises `ValueError` ALWAYS

The following is the behavior

```
In [17]: s = Series(randn(4))

In [18]: df = DataFrame(randn(10,2))

In [19]: s_empty = Series()

In [20]: df_empty = DataFrame()

In [5]: bool(s)
Out[5]: ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

In [6]: bool(s_empty)
Out[6]:  ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

In [7]: bool(df)
Out[7]:  ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

In [8]: bool(df_empty)
Out[8]:  ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()
```

And prevents these fun ones (same for Series/Panel)

```
In [4]: df1 = DataFrame(np.ones((4,4)))

In [5]: df2 = DataFrame(np.zeros((4,4)))

In [6]: df1 and df2
 ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

In [7]: df1 or df2
 ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

In [8]: not df1
 ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

In [9]: def f():
   ...:     if df1:
   ...:         print("this is cool")
   ...:         

In [10]: f()
 ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()


```


Labels:

Comments:
The only change I might make is to include the note you had previously about using 'empty', so maybe:

``` python
ValueError: The truth value of an array with more than one element is ambiguous. Use a.empty(), a.any() or a.all().
```

will do

@jreback sorry, missed your earlier comment - anyways looks good though!

The one nice thing to do would be to add something  to the docs that specifically quotes this exception so that someone using pandas for the first time can search for it. Either with this PR or as a todo for later on. 

sure....where do you think should go? boolean indexing (maybe a mention of NOT using and and using '&' instead)
where else?

I think that's a good place - caveats and gotchas probably is another good place - http://pandas.pydata.org/pandas-docs/dev/gotchas.html . I'm thinking something like:

```
Using If/Truth Statements with Pandas
=============================

Pandas follows the numpy convention of raising an error when you try to convert something to a `bool`, (which is what happens in an `if` statement or when using `and` or `or`).  It's not clear what the result of

.. code-block:: python
    if Series([False, True, False]):

should be. Should it be `True` because it's not zero-length? False because there are False values? It's unclear, so instead, pandas raises a ValueError:

.. code-block:: python
    >>> if pd.Series([False, True, False]): print("I was true")
    Traceback
        ...
    ValueError: The truth value of an array with more than one element is ambiguous. Use a.empty(), a.any() or a.all().


If you see that, you need to explicitly choose what you want to do with it (e.g., use `any()`, `all()` or `empty`).  Often you might want to compare against `None`.

Note that comparison operators like `==` and `!=` will also return arrays (which is almost always what you want anyways):

.. code-block:: python
   >>> s = pd.Series(range(5))
   >>> s == 4
   0    False
   1    False
   2    False
   3    False
   4     True
   dtype: bool

```

And maybe link to docs on any, all, empty?

@jtratner 
that was a nice explanation....it went in (in gotchase), with an expanded comparison section (for all/any/empty) in basics and links around

@wesm ?

ValueError: The truth value of an array ~~with more than one element~~ is ambiguous. Use a.any() or a.all()

@wesm this going back to a more natural, less error prone API (that we did have in 0.11)

any more comments on this before merging?

Looks good.

discussion: https://groups.google.com/forum/#!topic/pydata/XzSHSLlTSZ8