Merge pull request twisted#1060 from wiml/more-doc-nits

Author: wiml Reviewer: twm Fixes: ticket:2546 Improve producer and consumer documentation
ultimatecoder · Oct 15, 2018 · ba0703c · ba0703c
2 parents 3c88cc4 + ee08d86
commit ba0703c
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 7 deletions.
diff --git a/src/twisted/internet/interfaces.py b/src/twisted/internet/interfaces.py
@@ -1855,7 +1855,9 @@ def registerProducer(producer, streaming):
 
         For L{IPushProducer} providers, C{pauseProducing} will be called
         whenever the write buffer fills up and C{resumeProducing} will only be
-        called when it empties.
+        called when it empties.  The consumer will only call C{resumeProducing}
+        to balance a previous C{pauseProducing} call; the producer is assumed
+        to start in an un-paused state.
 
         @type producer: L{IProducer} provider
 
@@ -1891,7 +1893,7 @@ class IProducer(Interface):
     """
     A producer produces data for a consumer.
 
-    Typically producing is done by calling the write method of a class
+    Typically producing is done by calling the C{write} method of a class
     implementing L{IConsumer}.
     """
 
@@ -1909,7 +1911,7 @@ class IPushProducer(IProducer):
     A push producer, also known as a streaming producer is expected to
     produce (write to this consumer) data on a continuous basis, unless
     it has been paused. A paused push producer will resume producing
-    after its resumeProducing() method is called.   For a push producer
+    after its C{resumeProducing()} method is called.   For a push producer
     which is not pauseable, these functions may be noops.
     """
 
@@ -1918,7 +1920,7 @@ def pauseProducing():
         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.
+        the time being, and to stop until C{resumeProducing()} is called.
         """
     def resumeProducing():
         """
@@ -1928,10 +1930,12 @@ def resumeProducing():
         more data for its consumer.
         """
 
+
+
 class IPullProducer(IProducer):
     """
     A pull producer, also known as a non-streaming producer, is
-    expected to produce data each time resumeProducing() is called.
+    expected to produce data each time L{resumeProducing()} is called.
     """
 
     def resumeProducing():
@@ -1940,10 +1944,14 @@ def resumeProducing():
 
         This tells a producer to produce data for the consumer once
         (not repeatedly, once only). Typically this will be done
-        by calling the consumer's write() method a single time with
-        produced data.
+        by calling the consumer's C{write} method a single time with
+        produced data. The producer should produce data before returning
+        from C{resumeProducing()}, that is, it should not schedule a deferred
+        write.
         """
 
+
+
 class IProtocol(Interface):
 
     def dataReceived(data):

diff --git a/src/twisted/newsfragments/2546.doc b/src/twisted/newsfragments/2546.doc
@@ -0,0 +1 @@
+The documentation for the the twisted.internet.interfaces.IConsumer, IProducer, and IPullProducer interfaces is more detailed.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		The documentation for the the twisted.internet.interfaces.IConsumer, IProducer, and IPullProducer interfaces is more detailed.