[Twisted-Python] Interface documentation

Itamar Shtull-Trauring lists at itamarst.org
Wed Oct 3 12:57:43 EDT 2001

Right now, too much of the interface documentation is mixed up with the 
class implementation (if there *is* documentation). I propose making 
separate interface classes used only for documentation purposes. For 
example, in twisted.internet we might have interface.py with the following 
code, which would allow us to remove all the docstrings from 
abstract.FileDescriptor (that class is way too huge anyway), and maybe add a 
__implements__ = (interfaces.IProducer,) to the FileDescriptor class:

class IProducer:
     """A producer produces data for a consumer.

     If this is a streaming producer, it will only be
     asked to resume producing if it has been previously asked to pause.
     Also, if this is a streaming producer, it will ask the producer to
     pause when the buffer has reached a certain size.

     In other words, a streaming producer is expected to produce (write to
     this consumer) data in the main IO thread of some process as the result
     of a read operation, whereas a non-streaming producer is expected to
     produce data each time resumeProducing() is called.

     If this is a non-streaming producer, resumeProducing will be called
     immediately, to start the flow of data.  Otherwise it is assumed that
     the producer starts out life unpaused.

     def resumeProducing(self):
         """Resume producing data.

         This tells a producer to re-add itself to the main loop and produce
         more data for its consumer.

     def pauseProducing(self):
         """Pause producing data.

         Tells a producer that it has produced too much data to process for
         the time being, and to stop until resumeProducing() is called.

     def stopProducing(self):
         """Stop producing data.

         This tells a producer that its consumer has died, so it must stop
         producing data for good.

More information about the Twisted-Python mailing list