[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:

	def foo():
		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 mailing list