classification
Title: Add new StreamReader.readuntil() method
Type: enhancement Stage: resolved
Components: asyncio, Documentation Versions: Python 3.6, Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, gvanrossum, martin.panter, python-dev, socketpair, vstinner, xtreak, yselivanov
Priority: normal Keywords: patch

Created on 2016-01-08 20:37 by socketpair, last changed 2019-09-12 09:29 by xtreak. This issue is now closed.

Files
File name Uploaded Description Edit
asyncio-stream-doc-preliminary.patch socketpair, 2016-01-12 23:48 preliminary patch for docs
Messages (10)
msg257776 - (view) Author: Марк Коренберг (socketpair) * Date: 2016-01-08 20:37
See code discussion here:

https://github.com/python/asyncio/pull/297
msg257985 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2016-01-11 17:24
Sorry, posted my previous message here by mistake (it was for issue #26081).
msg257989 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-01-11 17:33
New changeset db11d0db1598 by Yury Selivanov in branch '3.4':
Issue #26050: Add asyncio.StreamReader.readuntil() method.
https://hg.python.org/cpython/rev/db11d0db1598

New changeset a6288fe5420f by Yury Selivanov in branch '3.5':
Merge 3.4 (Issue #26050)
https://hg.python.org/cpython/rev/a6288fe5420f

New changeset c2cd3b435afe by Yury Selivanov in branch 'default':
Merge 3.5 (issue #26050)
https://hg.python.org/cpython/rev/c2cd3b435afe
msg257990 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2016-01-11 17:33
Leaving this issue open until we have the docs committed.
msg258123 - (view) Author: Марк Коренберг (socketpair) * Date: 2016-01-12 23:50
Attached patch, but did not compile documentation until text is validated.

These descriptions are just copies of docstrings of corresponding functions.
msg273083 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-08-19 06:56
In revision 83450939b106, Yury added some documentation for readuntil(). I am not familiar with this StreamReader class, but maybe Mark or someone else can check if the remaining changes in his patch are still useful.

I can suggest some spelling and wording fixes however. Bits in square brackets are my changes.

## read(n=-1):

If *n* is zero, return [an] empty ``bytes`` object [immediately (single L)].

If *n* is positive, this function [tries] to read *n* bytes, [but may return less]. If EOF was received before any byte is read, this function returns [an] empty [bytes] object[, otherwise it returns at least one byte].

[The] returned value is not limited [by] [*limit* (add asterisks)], . . .

If [the] stream was paused, . . .

## readline():

Read [] from the stream until [a] newline (``b'\n'``) is found.

On success, return [the line, which] ends with [a] newline. If only [a] partial line can be read due to EOF, return [an] incomplete line without terminating newline. When EOF was reached [and] no bytes [were] read, [an] empty ``bytes`` object is returned.

If [*limit* (add asterisks)] is reached, ValueError will be raised. In that case, if [a] newline was found, [the] complete line including newline will be removed from [the] internal buffer. [Otherwise, the] internal buffer will be cleared. [*Limit* (add asterisks)] is compared against [the length] of the line[, not counting the] newline.

If [the] stream was paused, . . .

## readexactly(n):

If *n* is zero, return [an] empty bytes object.

[The] returned value is not limited by [*limit* (add asterisks)], . . .

If [the] stream was paused, . . .

## readuntil(separator=b'\n'):

Read [] from the stream until *separator* is found.

On success, [the] chunk [of data] and its separator will be removed from [the] internal buffer (i.e. consumed). [The] returned chunk will include [the] separator at the end.

[The] configured stream limit is used to [limit the] result. [*Limit* (add asterisks)] means [the maximum] length of [the] chunk . . .

If EOF occurs and [a] complete separator [is] still not found, :exc:`IncompleteReadError`(<partial data>, None) will be raised and [the] internal buffer becomes empty. . . .

If [the] chunk cannot be read due to [the] limit, :exc:`LimitOverrunError` will be raised and data will be left in [the] internal buffer, . . .

If [the] stream was paused, . . .
msg273085 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-08-19 07:33
Also it looks like the b'\n' default confuses Sphinx. Maybe it needs extra escaping?
msg276624 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2016-09-15 21:41
Looks like we already have docs for readuntil.  Mark, could you please check if we have some docs missing (or just close the issue)?
msg276688 - (view) Author: Марк Коренберг (socketpair) * Date: 2016-09-16 09:30
It needs to compare python functoin(s) docstrings with  separate documentation. All information from docstrings should also be written in separate docs. Will compare later.
msg352074 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2019-09-12 09:29
StreamReader and StreamWriter were merged to Stream with issue36889 and there were also docs added for it along with asyncio docs rewritten. I am closing this as fixed. Feel free to reopen if needed. Thanks.
History
Date User Action Args
2019-09-12 09:29:37xtreaksetstatus: open -> closed

nosy: + xtreak
messages: + msg352074

resolution: fixed
stage: patch review -> resolved
2016-09-16 09:30:50socketpairsetmessages: + msg276688
2016-09-15 21:41:15yselivanovsetmessages: + msg276624
2016-08-19 07:33:57martin.pantersetmessages: + msg273085
2016-08-19 06:56:26martin.pantersetnosy: + martin.panter, docs@python
messages: + msg273083

assignee: docs@python
components: + Documentation
stage: patch review
2016-01-13 03:45:42martin.panterlinkissue25752 superseder
2016-01-12 23:50:15socketpairsetmessages: + msg258123
2016-01-12 23:48:48socketpairsetfiles: + asyncio-stream-doc-preliminary.patch
keywords: + patch
2016-01-11 17:33:33yselivanovsetmessages: + msg257990
2016-01-11 17:33:04python-devsetnosy: + python-dev
messages: + msg257989
2016-01-11 17:24:49yselivanovsetmessages: + msg257985
2016-01-11 17:24:01yselivanovsetmessages: - msg257983
2016-01-11 17:23:28yselivanovsetmessages: + msg257983
2016-01-08 20:37:56socketpaircreate