fabric/fabric — Issue #515: Improve documentation on Failure handling
Author: jaraco
Created: 2011-12-22 16:10:51+00:00
State: open

The section on Failure handling in usage/Execution does not describe how to signal a failure. Consider for example calling an executable that doesn't give nice return values for errors (i.e. apt-add-repository). A fabric author might write a function like this:

```
@task
def add_repo(repo):
res = sudo('apt-add-repository ' + repo)
# apt-add-repository always returns 0
# check res for the expected output or raise error
```

However, if one raises an exception, a not-so-nice traceback is displayed.

I see in some other tickets there's mention of _handle_failure and abort. I'm going to track those down to find out if they might be of help in this scenario. It would be nice, however, if the documentation made mention of what the recommended technique is to signal a failure as if it had been signaled by fabric.