4

Strongly related question.

When writing docstrings for my functions in python, I sometimes want to write something like this about argument specifications:

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

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

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

However, this is not perfectly precise, because in this example bar could be returning any object that will be evaluated to True in the if-statement when the conditions XXX is fulfilled. Such a callable would be a perfectly valid argument to pass to foo.

How should I formulate my documentation to reflect that foo does not strictly requires bar's output to be a boolean?

My first move was to write something like "[...] must return an object that will be evaluated to True if ...", but I find it obfuscated.

Alexis
  • 337
  • 1
  • 12
  • 6
    A common way to refer to this is _truthy_ and _falsey_. However, this is really no requirement at all, because _any_ value returned by `bar()` will be either truthy or falsey. – John Gordon Nov 23 '18 at 19:31
  • 1
    How objects evaluate to true or false is often called "truthiness". Also, [falsey is often spelled falsy](https://english.stackexchange.com/questions/109996/is-it-falsy-or-falsey). – gilch Nov 23 '18 at 19:35
  • @JohnGordon there are exceptions like numpy arrays. See [this](https://stackoverflow.com/questions/52862526/can-the-python-bool-function-raise-an-exception-for-an-invalid-argument) for further context. – timgeb Nov 23 '18 at 19:40
  • @timgeb Fair enough. – John Gordon Nov 23 '18 at 19:41
  • Another (strange) case would be if foo makes assumptions about bar returning only bools, by computing x = 5 * bar(...), to obtain 5 or 0. Then bar could return a truthy or falsy but create unexpected behavior. – Alexis Nov 23 '18 at 19:42
  • 2
    You can say `bool(bar())` must evaluate to `True` or `False`? – r.ook Nov 23 '18 at 19:42

3 Answers3

4

This is a slang question! I've always wanted to answer one of these!

Ahem.

The term for something that evaluates to True when used in an if statement is "truthy". The term for something that evaluates to False when used in an if statement is "falsy" or "falsey". So, your documentation can be written like this:

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

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

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

"Iff" is more slang, this time from the mathematical world. It means "if and only if". These words are commonly used in programming contexts, so I expect most programmers will understand them; if not, truthy, falsy, falsey and iff all come up with their respective correct meanings when searched in a search engine.

wizzwizz4
  • 6,140
  • 2
  • 26
  • 62
2

I'm not sure if there's a standard for this, but based on python's Truth Value Testing you would probably be safe writing something like

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
andersource
  • 799
  • 3
  • 9
1

I would suggest that is is just fine to say "must return True if XXX and False otherwise." Because of duck typing, I read this the way you intend. Further, this seems to be standard in how the Python standard library documents things.

In fact, if you do strictly require the value to be True or False and use this language, I will have a very bad day tracking down this bug!

As others have said, "truthy" and "falsy" are fine, well-understood alternatives if you are still concerned.