如何定义"可调用" Python文档字符串中的参数?

时间:2014-05-09 18:03:57

标签: python types documentation docstring function-declaration

考虑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

现在,应该取代 ??? - 如何在docstring中引用参数f类型callable是显而易见的选择(如果我发号施令,我会指示:P)但是有一个既定的惯例吗?

1 个答案:

答案 0 :(得分:9)

是的,可调用术语是在这里使用的术语。

collections.abc中存在

The abstract base class Callable - 抽象基类可以最好地被视为接口(例如,更像是Go中的动态接口,而不是Java中的动态接口) - 它们定义了接口,并且任何具有给定函数的类被定义为从该抽象基类继承(无论它们是否明确地这样做) - 这意味着你将有用地传递给像这样的函数的任何东西都是Callable的子类,这里使用的术语完全正确。正如您可能会说Iterable

这绝对是大多数人在非正式地讨论Python代码时使用的术语,任何阅读代码的人都应该理解你的意思。

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