[Twisted-Python] @raise and deferreds

[David Reid]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Wilfredo Sánchez Vega wrote:
>   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.

A couple of quick greps seem to indicate that @raise is used sometimes,
but mostly that the errbacks are documented in @return which may be
unattractive is quite clear.  @raise is very confusing and I had to
check the actual implementations of the interfaces which brought up this
issue to see where the 'raise' actually took place.  So I'm still in
favor of the interfaces being changed to include the errback information
in the @return.  However it can probably be put off until the next web2
release.

>   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.

I think that would be good, we should ask mwh to do that.

- -David


- --
"Usually the protocol is this: I appoint someone for a task,
which they are not qualified to do.  Then, they have to fight
a bear if they don't want to do it." -- Glyph Lefkowitz
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFEkvBMrsrO6aeULcgRAjkCAJoDsfNOgTd8jM+JPa3jMdIJeX5OMQCeKpyK
hLiNeAHwmKSoOItnX6wC7sA=
=Gn0G
-----END PGP SIGNATURE-----