如何在Python文档字符串中定义“可调用”参数？

Question

考虑一下如何实现 filterNot 这个功能（基本上是 filter 的反向操作）：

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

这里的参数 f 可以是一个“函数”、一个“方法”、一个 lambda 表达式，甚至是一个定义了 __call__ 的对象。

现在想想这个参数的文档说明中的一行内容：

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

那么，在??? 的位置应该写什么呢——在文档说明中，如何描述参数 f 的类型？callable 是显而易见的选择（如果我来决定的话，我会这么写 :P），但有没有什么固定的写法呢？

Answer 1

没错，这里用“可调用”这个词是最合适的。

在collections.abc中有一个叫Callable的抽象基类——你可以把抽象基类想象成一种接口（虽然它更像是Go语言中的动态接口，而不是Java中的那种）——它定义了一种接口，任何拥有这些特定功能的类都可以被认为是继承了这个抽象基类（无论它们是否明确声明）——这意味着你在这样的函数中可以传入的任何东西，都是Callable的子类，所以在这里使用这个词是完全正确的。就像你可能会提到Iterable一样。

在谈论Python代码时，大多数人确实会使用这个词，任何阅读你代码的人都应该能理解你的意思。

内置的callable()函数（在3.x版本中曾经被移除过，后来又加回来了）可以用来检查那些像函数一样的对象，这进一步证明了“可调用”这个名字是寻找函数类对象时的最佳选择。