[Twisted-Python] @raise and deferreds
Wilfredo Sánchez Vega
wsanchez at wsanchez.net
Thu Jun 15 19:33:39 EDT 2006
I'm curious about what conventions we have for documenting
exceptions that are raised in deferreds, which turn into errbacks.
Say I have a function which returns a deferred, and several flavors
of Failure might have been raised. I'd like to document that thusly:
Do something fooey.
@raise FooError: if it's too fooey.
@raise BarError: if there is any bar; this is foo, not bar.
@raise HolyCrapError: if your pants are on fire.
@return: a deferred containing a Foo.
This is a little weird, since the exceptions are actually being
raised, but are being delivered in errbacks. The alternative is to
describe all of the possible exceptions in the @return clause, but
that is really clunky. So I'd like to have a convention whereby
everyone knows that if you have a function that returns a deferred,
that the exceptions described in the docstring refer to exceptions
delivered via errbacks rather than via raising.
Is that making any sense? Alternatively, we could make up a new
keyword (@errback?), but I don't know how troublesome doing so is.
If we do that, maybe another keyword (@callback) makes sense as well.
More information about the Twisted-Python