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

【问题标题】：How to define a "callable" parameter in a Python docstring?如何在 Python 文档字符串中定义“可调用”参数？
【发布时间】：2014-06-27 14:03:18
【问题描述】：

考虑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 的type 应该如何在文档字符串中引用。 callable 是显而易见的选择（如果我发号施令，我会发号施令：P），但是否有既定惯例？

【问题讨论】：

值得注意的是，函数、方法和 lambda 都只是通过不同方法生成的函数——它们本身并没有什么特别之处。
@200OK 这与问题所问的内容无关。
callable 对我来说似乎很好，并且可能是最好的——如果您的文档生成引擎不喜欢这样，function 可能是下一个最好的选择。毕竟，在 python 中，假设对象只需要表现就像函数记录的任何类型一样。
@Lattyware 非正式地，它们都是函数，因为它们是可调用的。但是，有不同的类型 function（由 lambda 表达式和 def 语句创建）、instancemethod（实例或类方法）和 builtin_function_or_method（直接在 C 中实现，而不是通过 Python 代码实现））。此外，其类型/类定义了__call__ 方法的任何对象都是可调用的，而不是前面提到的任何类型。因此，值得有一个包含所有的术语。
@chepner 哦，事实上，我并不是说不需要一个通用术语，我只是指出函数和 lambda 是相同的项目，只是通过不同的方式构造。（并且方法本质上只是修饰函数）。它不是用来改变问题的，只是一个感兴趣的说明。

标签： python types documentation docstring function-declaration

【解决方案1】：

是的，这里使用的术语可调用。

The abstract base class Callable 存在于collections.abc 中——抽象基类最好被认为是接口（尽管它们在 Go 中更像是动态的，而不是在 Java 中）——它们定义了一个接口，以及任何具有给定的函数被定义为从该抽象基类继承（无论它们是否明确地这样做） - 这意味着您将有用地传递给这样的函数的任何东西都将是Callable 的子类，完全使用该术语在这里正确。正如你可能会说的Iterable。

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

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

【讨论】：

在我看来答案是“否”，但您同意“可调用”是最好的用语... :-/
@chrisw。所问的问题是你想要一个类似函数的对象的文档字符串或文档字符串中的什么 - 可调用是正确的。
我在问是否有“官方”或标准化的方式来执行此操作（例如，在 PIP 中）......听起来好像没有。也就是说，我同意“可调用”比“函数”或我能想到的任何其他东西更有意义。
@ChrisW。好吧，当你想要一个字符串时，你应该使用“str”并不是“官方”的——给出类型的名称（在这种情况下是抽象基类），几乎是这里假设的用途。