python - 记录函数时如何引用 "True-like"和 "False-like"？

Question

Strongly related question .

在 python 中为我的函数编写文档字符串时，有时我想写一些关于参数规范的类似内容:

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

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

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

然而，这并不完全准确，因为在这个例子中 bar 可能返回任何对象，当条件 XXX实现了。这样的可调用对象将是传递给 foo 的完全有效的参数。

我应该如何制定我的文档以反射(reflect) foo 并不严格要求 bar 的输出为 bool 值？

我的第一步是写类似“[...] 必须返回一个对象，如果...，该对象将被评估为 True”，但我发现它很困惑。

Answer 1

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

咳咳。

---

当在 if 语句中使用时，求值为 True 的事物的术语是“truthy”。在 if 语句中使用时评估为 False 的事物的术语是“falsy”或“falsey”。所以，你的文档可以这样写:

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

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

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

“Iff”更像是俚语，这次来自数学世界。它的意思是“当且仅当”。这些词在编程环境中很常用，所以我希望大多数程序员都能理解它们；如果没有，truthy , falsy , falsey和 iff在搜索引擎中搜索时，所有人都会得出各自的正确含义。