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

[jreback]

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()

[jtratner]

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

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

[jreback]

will do

[jtratner]

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

[jtratner]

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.

[jreback]

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

[jtratner]

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?

[jreback]

@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

[jtratner]

might be nice to split this on to multiple lines. your call.

[jreback]

sure

[jreback]

In [1]: s = Series(1,index=[1,2])

In [2]:  s and s
ValueError: The truth value of an array with more than one element is ambiguous.
            Use a.empty, a.any() or a.all()

[jreback]

@wesm ?

[hayd]

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

[jreback]

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

[hayd]

(missing) is ambiguous

[jreback]

yep..thkxs

[jreback]

any more comments on this before merging?

[jtratner]

Looks good.

[hayd]

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