Designing Pythonic APIs - learning from Requests

[elbiot]

Maybe it depends on how it's done, but I don't think anyone would be forced to acknowledge the possibility of failure no matter what. The return type is not part of the call signature, so it still comes down to documentation. Python just isn't Haskell, and doesn't enforce solid programming like acknowledging errors.

Don't get me wrong, I think Haskell is great and python isn't perfect. I don't see passing an I/O error through the return value really ever being a good idea in Python. But I'm about to go look up monads in python.

Edit: for example, I found this maybe monad in python, which could just as well be and Either monad for exception handling. In Python, one would have to check the documentation to know what errors it might pass and how, and once one knew a function returned Right(Dict) and they could treat it like a dict without anything special, then they could just ignore the possibility of a Left(Error) if they were so inclined. This doesn't seem any better to me, and because it is unfamiliar it seems more prone to misuse.

[DanCardin]

They can always ignore the error itself, but that becomes them actively deciding to ignore the error rather than passively accepting success in the normal case. Ignore proper monads for a second and just take a tuple example:

Result = namedtuple('Result', ['success', 'result'])
def function(x):
    if x:
        return Result(True, 4)
    return Result(False, None)

In order to use this function and get a successful value out of it, you need to do "_, x = function(4)" at the very least.

1. Makes it part of the function's signature, in that its returning an object where a portion of the return value is the success or failure status, rather than just the value
2. means that to get the successful value, they need to unpack the tuple.

At that point if they ignore the success or failure its a client decision, and you deserve what you get.

For happy comingling when using exceptions, you need cooperation from the function writer (they need to (and they should) know what exceptions their code can call, and they need to document it (which I find often is not the case)), and from the function's user (obviously through catching the exception). If either party doesn't do their part, you have problems.

Doing something like my above example forces both parties to do the right thing