[Twisted-Python] newbie confusion - puzzling reactor response

[K. Richard Pixley]

exarkun at twistedmatrix.com wrote:
> It isn't `doRead`'s job to close the file descriptor.  At most, it's 
> `doRead`'s job to signal that the descriptor is no longer worth keeping 
> open by returning something like an instance of ConnectionDone or 
> ConnectionLost.  Then the reactor will call connectionLost on your 
> object and you can close the file descriptor there.
>   
Thank you!  That's the info I was looking for.
> The documentation for how this all works could probably be improved. 
> Once you figure it out, would you mind submitting a patch?
>   
I don't think I've even seen mention of ConnectionDone in the doc yet.

I think there's a design decision here about the doc.  It seems to me 
that the return codes are part of the interface and as such should 
probably be documented in twisted.internet.interfaces.py whereas there's 
almost nothing there now.  Instead, some of this is in 
twisted.internet.abstract.  Granted, the distinction between an abstract 
class and a "zope.interface.Interface" is subtle.

As a newbie, the interface is the thing I find first and most easily.  
I'm directed there by the doc and by the reference material.  I have to 
dig around to even notice that the abstract class exists.
> Also, you won't accomplish much by adding a file descriptor for a normal 
> file to the reactor.  Select, poll, etc, will always indicate that such 
> descriptors are both readable and writeable.
I could swear that wasn't true when I first mucked about with select, 
but that was a couple decades ago.  Thanks for the update.

In any case, my point was more about illustration and testing.

--rich