[docs] [issue27000] improve document of filter

[Franklin? Lee]

Franklin? Lee added the comment:

> Although I still think it's telling readers incorrect info in the second part. For ``bool``, it is not equivalent to ``(item for item in iterable if function(item))`` but ``(item for item in iterable if item)``. For CPython, you are not telling the truth.

What do you mean by, "it is not equivalent"? Are you saying that the first one will give a different result from the second? In general, when interpreting an object in a boolean context, Python will do the "equivalent" of calling ``bool`` on it, where "equivalent" in the docs means "has the same result as". See, for example, the ``itertools`` docs:
https://docs.python.org/3/library/itertools.html#itertools.accumulate

--------

In this case:

If ``filter`` is passed ``None`` or ``bool``, it will call "PyObject_IsTrue" on the object.
    (https://github.com/python/cpython/blob/c750281ef5d8fa89d13990792163605302e972d4/Python/bltinmodule.c#L481)

"PyObject_IsTrue" is defined here:
    https://github.com/python/cpython/blob/6aea3c26a22c5d7e3ffa3d725d8d75dac0e1b83b/Objects/object.c#L1223

On the other hand, ``bool`` is defined here, as "PyBool_Type":
    https://github.com/python/cpython/blob/c750281ef5d8fa89d13990792163605302e972d4/Python/bltinmodule.c#L2686


"PyBool_Type" is defined here, with the ``bool.__new__`` function defined as "bool_new":
    https://github.com/python/cpython/blob/2d264235f6e066611b412f7c2e1603866e0f7f1b/Objects/boolobject.c#L133

"bool_new" is defined here, using "PyObject_IsTrue":
    https://github.com/python/cpython/blob/2d264235f6e066611b412f7c2e1603866e0f7f1b/Objects/boolobject.c#L43

Both "filter_next" and "bool_new" call "PyObject_IsTrue" and take 0 as False, positive as True, and negative as an error. So it's equivalent to calling ``bool``, but the "bool_new" call is sort of inlined.

Does that clear things up?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue27000>
_______________________________________