How to define a "callable" parameter in a Python docstring?

Question

Consider an implementation of filterNot (basically the opposite of filter):

def filterNot(f, sequence):
    return filter(lambda x: not f(x), sequence)

The parameter f can be a "function" or a "method" or a lambda -- or even an object whose class defines __call__.

Now consider a line of docstring for this parameter:

:param ??? f: Should return True for each element to be abandoned

Now, what should go in place of ??? -- how should the type of parameter f be referred to in a docstring. callable is the obvious choice (and what I would dictate if I were calling the shots :P) but is there an established convention?

Answer 1

Yes, the term callable is the one to use here.

The abstract base class Callable exists in collections.abc - abstract base classes can be best thought of as interfaces (although more like they dynamic ones in Go than those in Java, for example) - they define an interface, and any class that has the given functions is defined as inheriting from that abstract base class (whether they did so explicitly or not) - this means anything you would usefully pass into a function like this would be a subclass of Callable, making the use of the term completely correct here. Just as you might say Iterable.

It is definitely the term used by most people in when talking informally about Python code, and anyone reading your code should understand what you mean.

The callable() built-in (that got removed for a while in 3.x, then added back) does the check for function-like objects, and this further reinforces the name as the best choice where you are looking for function-like objects.