Issue 26050: Add new StreamReader.readuntil() method

See code discussion here:

https://github.com/python/asyncio/pull/297

Sorry, posted my previous message here by mistake (it was for issue #26081).

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

Leaving this issue open until we have the docs committed.

Attached patch, but did not compile documentation until text is validated.

These descriptions are just copies of docstrings of corresponding functions.

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, . . .

Also it looks like the b'\n' default confuses Sphinx. Maybe it needs extra escaping?

Looks like we already have docs for readuntil.  Mark, could you please check if we have some docs missing (or just close the issue)?

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.

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.

nosy: + xtreak
messages: + msg352074

resolution: fixed
stage: patch review -> resolved

assignee: docs@python
components: + Documentation
stage: patch review