[Python-checkins] cpython (3.4): Closes #22348: Rephrase asyncio.StreamWriter.drain() documentation

[victor.stinner]

https://hg.python.org/cpython/rev/8224253ef4b7
changeset:   93645:8224253ef4b7
branch:      3.4
parent:      93643:c90fe355ac43
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Fri Nov 28 17:45:41 2014 +0100
summary:
  Closes #22348: Rephrase asyncio.StreamWriter.drain() documentation
Patch written by Martin Richard.

files:
  Doc/library/asyncio-stream.rst |  14 ++++++++++----
  Misc/ACKS                      |   1 +
  2 files changed, 11 insertions(+), 4 deletions(-)


diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -170,16 +170,22 @@
 
    .. method:: drain()
 
-      Wait until the write buffer of the underlying transport is flushed.
+      Let the write buffer of the underlying transport a chance to be flushed.
 
       The intended use is to write::
 
           w.write(data)
           yield from w.drain()
 
-      When the transport buffer is full (the protocol is paused), block until
-      the buffer is (partially) drained and the protocol is resumed. When there
-      is nothing to wait for, the yield-from continues immediately.
+      When the size of the transport buffer reaches the high-water limit (the
+      protocol is paused), block until the size of the buffer is drained down
+      to the low-water limit and the protocol is resumed. When there is nothing
+      to wait for, the yield-from continues immediately.
+
+      Yielding from :meth:`drain` gives the opportunity for the loop to
+      schedule the write operation and flush the buffer. It should especially
+      be used when a possibly large amount of data is written to the transport,
+      and the coroutine does not yield-from between calls to :meth:`write`.
 
       This method is a :ref:`coroutine <coroutine>`.
 
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1125,6 +1125,7 @@
 Tim Rice
 Jan Pieter Riegel
 Armin Rigo
+Martin Richard
 Arc Riley
 Nicholas Riley
 Jean-Claude Rimbault

-- 
Repository URL: https://hg.python.org/cpython