Как ссылаться на «True-like» и «False-like» при документировании функции?

Question

Сильно связанный вопрос .

При написании строк документации для моих функций в python я иногда хочу написать что-то вроде этого о спецификациях аргументов:

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

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

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

Однакоэто не совсем точно, потому что в этом примере bar может возвращать любой объект, который будет оцениваться как True в операторе if, когда выполнены условия XXX.Такой вызываемый объект будет вполне допустимым аргументом для передачи foo.

Как мне сформулировать мою документацию, чтобы отразить, что foo не требует строго, чтобы вывод bar былboolean?

Моим первым шагом было написать что-то вроде "[...] должен вернуть объект, который будет оценен как True, если ...", но я нахожу его запутанным.

Answer 1

Это жаргонный вопрос!Я всегда хотел ответить на один из них!

Гм.

---

Термин для чего-то, что оценивается как True при использовании в выражении if, "правдив",Термин для чего-то, что оценивается как False при использовании в выражении if, является «ложным» или «ложным».Итак, ваша документация может быть написана так:

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

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

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

«Iff» - больше сленга, на этот раз из математического мира.Это означает «если и только если».Эти слова обычно используются в контексте программирования, поэтому я ожидаю, что большинство программистов поймут их;если нет, то truey , falsy , falsey и iff все найдут свои правильные значения при поиске в поисковой системе.

Answer 2

Я бы предположил, что это просто замечательно сказать: «должен вернуть True, если XXX, и False в противном случае».Из-за утки, я читаю это так, как ты намереваешься.Кроме того, это кажется стандартным в том, как стандартная библиотека Python документирует вещи.

Фактически, если вы do строго требуете, чтобы значение было True или False и использовали этоязыком, у меня будет очень плохой день, чтобы выследить эту ошибку!

Как уже говорили другие, «правдивые» и «ложные» - это хорошие, хорошо понятые альтернативы, если вы все еще обеспокоены.

Answer 3

Я не уверен, есть ли стандарт для этого, но на основе Проверка истинности значения 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