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

Question

考虑一个filterNot的实现（基本上是filter的相反操作）：

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

参数f可以是一个"function"(函数)、"method"(方法)或者是lambda(匿名函数)，甚至可以是一个定义了__call__的类的实例。

现在考虑该参数的文档字符串:

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

现在，???应该填什么？-在docstring中如何引用参数f的类型。 callable是显而易见的选择（如果我有决定权，我会这样指示:P），但是否有已经确立的约定？

- Chris W.

---

值得注意的是，函数、方法和lambda表达式都只是通过不同方法产生的函数 - 它们本身并没有什么特别之处。 - Gareth Latty

@200OK 这与问题的要求并不相关。 - Gareth Latty

callable 对我来说很好，可能是最好的选择 - 如果您的文档生成引擎不喜欢它，那么 function 可能是下一个最好的选择。毕竟，在 Python 中，假定对象只需要像函数所记录的类型一样 表现 即可。 - mgilson

@Lattyware 非正式地说，它们都是函数，因为它们是可调用的。然而，有着不同类型的 function（由 lambda 表达式和 def 语句创建）、instancemethod（实例或类方法）和 builtin_function_or_method（直接在 C 中实现，而不是通过 Python 代码）。此外，任何其类型/类定义了 __call__ 方法的对象都是可调用的，而不属于前面提到的任何一种类型。因此，值得拥有一个涵盖所有这些内容的术语。 - chepner

@chepner 哦，确实，我并不是说没有需要一个通用术语，我只是指出函数和lambda是相同的项目，只是通过不同的方式构建而已。（而方法本质上只是装饰过的函数）。这并不是要改变问题，只是一个有趣的注释。 - Gareth Latty

Answer 1

是的，在这里要使用术语“callable”。

抽象基类Callable存在于collections.abc中 - 抽象基类可以最好地被看作为接口（虽然更像是Go中的动态接口而不是Java中的接口）- 它们定义了一个接口，任何具有给定函数的类都被定义为继承自该抽象基类（无论它们是否显式地这样做） - 这意味着您在这样的函数中有用传递任何东西都将是Callable的子类，使得在此处完全正确使用该术语。就像你可能会说的Iterable一样。

这确实是大多数人在谈论Python代码时非正式使用的术语，任何阅读您的代码的人都应该理解您的意思。

内置的callable()（在3.x中有一段时间被删除，然后被添加回来）可以检查类似函数的对象，这进一步强化了该名称作为寻找类似函数的对象的最佳选择。

- Gareth Latty

---

听起来对我来说答案是否定的，但你同意“callable”是最好的术语使用... :-/ - Chris W.

@chrisw。所问的问题是在文档字符串中，当您想要一个类似函数的对象时，可调用对象是正确的选择。 - Gareth Latty

我想问一下是否有“官方”的或标准化的方法来做这件事（例如，在PIP中）...听起来似乎没有。话虽如此，我同意“callable”比“function”或其他任何我能想到的东西更有意义。 - Chris W.

@ChrisW。嗯，你想要一个字符串时并不是一定要使用“str” - 在这种情况下指定类型的名称（在本例中为抽象基类）基本上是假定的用法。 - Gareth Latty