Title: Documentation of asyncio.StreamWriter.drain()
Type: behavior Stage: resolved
Components: asyncio Versions: Python 3.4
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: gvanrossum, martius, python-dev, vstinner, yselivanov
Priority: normal Keywords: patch

Created on 2014-09-06 12:53 by martius, last changed 2014-11-28 16:47 by vstinner. This issue is now closed.

File name Uploaded Description Edit
asyncio-streams-drain-doc.patch martius, 2014-09-06 12:53 Documentation for StreamWriter.drain() review
asyncio-streams-drain-doc-water-limits.patch martius, 2014-09-12 08:42 review
Messages (5)
msg226487 - (view) Author: Martin Richard (martius) * Date: 2014-09-06 12:53

Following the discussion on the python-tulip group, I'd like to propose a patch for the documentation of StreamWriter.drain().

This patch aims to give a better description of what drain() is intended to do, and when to use it. In particular, it highlights the fact that calling drain() does not mean that any write operation will be performed, nor is required to be called.
msg226813 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2014-09-12 07:49
IMO we should mention the write buffer limits ("high- and low-water limits for write flow control"). get_write_buffer_limits() and set_write_buffer_limits() methods of the transport are public, there is no reason to "hide" them.
msg226815 - (view) Author: Martin Richard (martius) * Date: 2014-09-12 08:42
Here is an other patch which mentions high and low water limits. I think it's better to talk about it, since it tells extactly what a "full buffer" and "partially drained" means.

On the other hand, StreamWriter wraps the transport but does not expose the set/get_write_buffer_limits() directly, you reach then through stream_writer.transport (which makes sense, StreamWriter is here to help writing, not to do plumbery) - so I did not mention the functions.
msg231817 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-11-28 16:46
New changeset 8224253ef4b7 by Victor Stinner in branch '3.4':
Closes #22348: Rephrase asyncio.StreamWriter.drain() documentation

New changeset 1cad9e4bba40 by Victor Stinner in branch 'default':
(Merge 3.4) Closes #22348: Rephrase asyncio.StreamWriter.drain() documentation
msg231818 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2014-11-28 16:47
Sorry for the delay, I pushed asyncio-streams-drain-doc-water-limits.patch, thanks for your contribution Martin.
Date User Action Args
2014-11-28 16:47:04vstinnersetmessages: + msg231818
2014-11-28 16:46:37python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg231817

resolution: fixed
stage: resolved
2014-09-12 08:42:32martiussetfiles: + asyncio-streams-drain-doc-water-limits.patch

messages: + msg226815
2014-09-12 07:49:54vstinnersetmessages: + msg226813
2014-09-06 12:54:18martiussethgrepos: - hgrepo273
2014-09-06 12:53:47martiuscreate