The doc of `itertools.filterfalse()` shows `predicate` argument but the docstring shows `function` argument

[hyperkai]

The doc of itertools.filterfalse() shows predicate argument as shown below:

itertools.filterfalse(predicate, iterable)

But the docstring of itertools.filterfalse() shows function argument instead of predicate argument as shown below:

from itertools import filterfalse

print(help(filterfalse))
# class filterfalse(builtins.object)
#  |  filterfalse(function, iterable, /)
# ...

So the docstring of itertools.filterfalse() should show predicate argument instead of function argument for consistency as shown below:

from itertools import filterfalse

print(help(filterfalse))
# class filterfalse(builtins.object)
#  |  filterfalse(predicate, iterable, /)
# ...

In addition, both the doc and docstring of itertools.takewhile() properly show predicate argument as shown below:

itertools.takewhile(predicate, iterable)

from itertools import takewhile

print(help(takewhile))
# class takewhile(builtins.object)
#  |  takewhile(predicate, iterable, /)
#  ...

And, both the doc and docstring of itertools.dropwhile() properly show predicate argument as shown below:

itertools.dropwhile(predicate, iterable)

from itertools import dropwhile

print(help(dropwhile))
# class dropwhile(builtins.object)
#  |  dropwhile(predicate, iterable, /)
# ...

[skirpichev]

In both cases arguments are positional-only (we have an issue for this: #131885). Naming doesn't make any sense.

[terryjreedy]

I believe @serhiy-storchaka has some interest in consistency between doc and docstring. What does @rhettinger think for itertools? He might want to change when making other changes.
EDIT: a 'predicate' is a function that returns a boolean, so I prefer it here.

[serhiy-storchaka]

This is positional-only parameter, so we can change its name without breaking user code.

The filter() signature is filter(function, iterable, /). itertools.filterfalse() should have the same signature. If use predicate, it should be used in both signatures and documentations. callable is technically more correct than function, although predicate is more semantically precise.

[mpkocher]

I believe @serhiy-storchaka has some interest in consistency between doc and docstring. What does @rhettinger think for itertools? He might want to change when making other changes.
EDIT: a 'predicate' is a function that returns a boolean, so I prefer it here.

While it's useful to improve the naming consistency, I'm not sure this is moving the needle forward in a meaningful way.

The lack of type hints/annotations integrated into the stdlib docs is a notable friction point. The current docs have a very 2.7 era approach (which was a great quality for that era).

It's useful to consider LLM approaches to fill in the gap. Here's an example of itertools.filterfalse with type hints/annotations.

https://gist.github.com/mpkocher/2e8eef3d52c67b4de2447e8624c863ce

[terryjreedy]

Problems with typing annotations:

1. Understanding and using the typing annotations was promised to be OPTIONAL. I am pretty sure that for most users, they are just mostly distracting noise. For instance, callable(obj)' returns whether an object is callable, whether obj()will execute and return a value for some set of proper argument structures. typing.Callable[x,y]` looks similar but is quite different. x and y must be typing expressions and the result is a typing expression representing Callables that take x's as input and return y's.

2. Even ignoring value restrictions like Real > 0 (for log) or Real >= 0 for sqrt, the system is incomplete in it cannot define all in-practice input domains. The LLM example, function: Callable[[T], bool] | None is wrong in being too restrictive. The intended return type for filter functions in not bool, but 'objects which have a boolean value', which is to say, 'objects x for which bool(x) returns True or False', which is to say, 'objects x for which x.__boo__() returns True or False'. (But see Notes 2 & 3 below for the sense in which even this is too restrictive.) Since a predicate is usually defined as returning False/True, I retract my vote above for 'predicate' as the name of the parameter.)

3. The 'proper' annotation for any parameter is partly a matter of opinion and goal. For function, I think Callable[[T], any would be better, even if looser than the intention. Note 2 below suggests Callable(any, any). It is not required that the filter function only apply to items in the iterable and not checkable that it does before one iterates. Note 3 suggests that any is the current (possibly buggy) truth.

The problem with LLMs is that they are statistical regurgitator programs, tuned to produce plausible and engaging text, but with no sense of correctness of said text. The current docstring for itertools.filterfalse starts with "'Return those items of iterable for which function(item) is false." Here, false means bool(function(item)) == False, as explained above. The LLM changes 'false' to 'False', which is wrong. There follows some slightly garbled text using 'falsey that would need to be edited or deleted.

Recent studies have shown that using LLMs for programming often save little to no time because carefully checking, editing, and correcting takes about or almost as much time as the LLM otherwise saves. Using a tool that ignores or degrads existing carefully written text is dubious.

Note 1. Both doc strings are deficient in not noting that rejected items must be true, in that bool(f(item)) must return True rather than a non-bool and must not raise. Whether this needs to be said is a judgment call.

Note 2. Now that filter and filterfalse, in Python 3, return an iterator instead iterating and returning a list, there is no restriction on the function in order for either to return an iterator. The restriction is only needed to allow the iterator to work correctly. filter (and I presume filterfalse) checks that the iterable is an iterable by calling iter(iterable) to the the iterator used in the filter iterator.

Note 3. Currently, filter does not even check that the 'function' is callable(). The corresponding annotation for function would be any. filter(1, 'ab') returns an iterator that fails immediately. A bug to be fixed? Raymond?