[Twisted-Python] making twisted provide good feedback (was Re: Having reactor run at the main thread...)

glyph at divmod.com glyph at divmod.com
Thu Nov 6 13:22:53 MST 2008


(Moving this off the twisted-web list because it is of more general 
interest and contains nothing web-specific.)

On 09:48 am, jml at mumak.net wrote:
>On the other hand, there's a related invalid argument that gets used a
>lot by library and framework authors: "if we provide X, people might
>misuse it, so we should not provide X". This argument is also bogus
>(that way lies Java). Provide safe, well-documented alternatives for
>the abusers and let those who want to shoot themselves in the foot do
>so: sometimes they might actually know better than you.

I find it peculiar that you think this is Java's disease.  My 
perspective is that Java is unpleasant because it is remarkably tedious, 
redundant, and inconsistent, not because it lacks functionality.  If 
anything, it's a mess of functionality, and there are too many ways to 
do the same thing.

If you want to shoot yourself in the foot (or face, as the case may be) 
there's always the com.sun hierarchy, which despite being full of 
warnings signs and sparsely documented, is all public (at the language 
level) and accessible from Java programs which wish to go that way.  In 
that sense it's relatively hacker friendly.  For more fun with foot- 
shooting there's also AccessibleObject, which lets you call private 
methods and access private fields.

I think the whole issue here is very complex, and so I'd like to repeat 
and perhaps more clearly explain my own views.

I work at the bleeding edge of lots of software and am frequently 
frustrated when the authors of libraries that I use don't bother with 
"edge" cases that are necessary to the applications that I write. 
Twisted should provide excellent support for valid use-cases, no matter 
how obscure.

On the other hand, it's equally frustrating to use a library where the 
incredibly obscure "you probably don't need this" and the 99%-of-the- 
time positive-path APIs are listed, without any particular ordering, in 
one giant flat list.  It's particularly frustrating to google for "How 
do I (X)" and get a solution which uses an apparently reasonable API to 
do (X), only to discover months after using it that it's actually 
unsupported and you're not supposed to touch it and now your program is 
going to break horribly with the next minor version of the library.

This isn't just a problem with documentation, because in reality nobody 
reads documentation.  If you're writing a program, you're going to read 
_just_ enough of the API doc and do just enough groveling around with 
dir() and pydoc to get yourself to the point where something works. 
When it works, you will probably consider that sufficient proof that you 
used the APIs correctly, unless you had to type something that _looked_ 
particularly gross in the course of doing it, or you got a bunch of 
warnings out of your program when you ran it.  This is the whole point 
of DeprecationWarning: somehow, your library code itself has to 
communicate with the the developer who is invoking it and tell them 
useful things about their use or misuse.

I feel like Twisted has more of the latter problem than the former. 
There are a lot of methods which aren't really private 
(addReader/removeReader) that don't differentiate themselves as more or 
less private or refer you to the more portable and general APIs that you 
probably want (pauseProducing/resumeProducing).  However, (modulo global 
reactors, of course) Twisted does support a lot of edge cases very 
nicely.

Speaking from personal experience, there are a lot of people who show up 
in #twisted looking at 
<http://twistedmatrix.com/documents/8.1.0/api/twisted.internet._sslverify.html> 
when they should be looking at 
<http://twistedmatrix.com/documents/8.1.0/api/twisted.internet.ssl.html>, 
or 
<http://twistedmatrix.com/documents/8.1.0/api/twisted.internet.iocpreactor.tcp.Server.html> 
when they should be looking at 
<http://twistedmatrix.com/documents/8.1.0/api/twisted.internet.interfaces.IReactorTCP.html>. 
In the long term, we need to write both better documentation and more 
code that gets these people back onto the right track.

I know I've used a few libraries which provided exactly this kind of 
feedback and it was very satisfying and educational.  It's really an 
art, one that's difficult to master, and I don't know that I really know 
the right way to do it in the general case.  The danger that comes along 
with doing it wrong is very nicely explained here: 
http://blogs.msdn.com/oldnewthing/archive/2008/10/06/8969399.aspx - if 
you make an API which doesn't work except for the "special" cases, then 
everyone just starts using the "special" version.




More information about the Twisted-Python mailing list