Python 如何参考；真像；及；假像；在记录函数时？

在用python为我的函数编写docstring时，有时我想写一些关于参数规范的类似内容：

def foo(bar):
    """
    Do some stuff.

    bar : callable
        must return True if XXX and False otherwise.
    """

    if bar(...):
        ...  # code goes here

但是，这并不十分精确，因为在本例中，当满足条件XXX时，

bar

可能会返回在if语句中计算为

True

的任何对象。这样一个可调用的参数可以传递给

foo

我应该如何制定文档以反映

foo

并不严格要求

bar

的输出为布尔值？

---

我的第一步是编写类似“[…]必须返回一个对象，如果…”则该对象将被求值为True”，但我发现它被混淆了。

我不确定是否有这样的标准，但基于python的，您可能可以安全地编写类似的内容

def foo(bar):
    """
    Do some stuff.

    bar : callable
        when tested for truth value, return value should evaluate to True if and only if XXX.
    """

    if bar(...):
        ...  # code goes here

---

这是个俚语问题！我一直想回答其中一个问题

啊哼

---

当在

if

语句中使用时，对某事物求值为

True

的术语是“truthy”。当在

if

语句中使用时，计算结果为

False

的术语是“falsy”或“falsy”。因此，您的文档可以这样编写：

def foo(bar):
    """
    Do some stuff.

    bar : callable
        must return a truthy value iff XXX.
    """

    if bar(...):
        ...  # code goes here

---

“Iff”更像是俚语，这次来自数学界。它的意思是“当且仅当”。这些词通常在编程环境中使用，所以我希望大多数程序员都能理解它们；如果不是，则在搜索引擎中搜索时，、和都会给出各自正确的含义。

我建议说“如果XXX必须返回True，否则返回False”就可以了。因为duck类型，所以我按照您的意思阅读。此外，这似乎是Python标准库记录事物的标准方式

事实上，如果您确实严格要求值为

True

或

False

，并使用这种语言，那么我追踪这个bug的日子将非常糟糕

---

正如其他人所说，“真实”和“虚假”都是很好的、很好理解的替代品，如果你仍然担心的话。

一种常见的说法是真实和虚假。然而，这实际上根本不是必需的，因为

bar（）

返回的任何值都是真实的或虚假的。对象如何计算为真或假通常称为“真实性”。另外，.@JohnGordon还有一些例外，比如numpy数组。有关详细内容，请参阅。@timgeb。您可以说

bool（bar（））

必须计算为

True

或

False

？@John Gordon:我确实看到了您的评论，但我很高兴将问题标记为已解决。详细，但安全。在某些情况下很好。“评估为真（假）”也是我的答案