How to define the parameter "called" in a Python docstring?

Question

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

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

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

Now consider the docstring line for this parameter:

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

Now, what should go instead ??? - how to specify the type of parameter f in docstring. callable is the obvious choice (and what I would dictate if I would fire the shots: P), but is there an established agreement?

Answer 1

Yes, a term that can be used is one that can be used here.

The Callable abstract base class exists in collections.abc - abstract base classes are best viewed as interfaces (although they are more like dynamic ones in Go than Java, for example) - they define an interface, and any class that has defined functions is defined as inheriting from this abstract base class (regardless of whether they did it explicitly or not) - this means all that you would happily switch to a function like this would be a Callable subclass, which would allow you to fully use the term here. How could you say Iterable .

This is definitely a term used by most people when it informally talks about Python code, and anyone who reads your code should understand what you mean.

The callable() (which was removed in 3.x for a while and then added back) performs a check for objects like functions, and this further strengthens the name as the best choice where you are looking for function-like objects.