Add new StreamReader.readuntil() method

[socketpair]

BPO	26050
Nosy	@gvanrossum, @vstinner, @socketpair, @vadmium, @1st1, @tirkarthi
Files	asyncio-stream-doc-preliminary.patch: preliminary patch for docs

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2019-09-12.09:29:37.095>
created_at = <Date 2016-01-08.20:37:56.026>
labels = ['type-feature', 'docs', 'expert-asyncio']
title = 'Add new StreamReader.readuntil() method'
updated_at = <Date 2019-09-12.09:29:37.092>
user = 'https://github.com/socketpair'

bugs.python.org fields:

activity = <Date 2019-09-12.09:29:37.092>
actor = 'xtreak'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-09-12.09:29:37.095>
closer = 'xtreak'
components = ['Documentation', 'asyncio']
creation = <Date 2016-01-08.20:37:56.026>
creator = 'socketpair'
dependencies = []
files = ['41595']
hgrepos = []
issue_num = 26050
keywords = ['patch']
message_count = 10.0
messages = ['257776', '257985', '257989', '257990', '258123', '273083', '273085', '276624', '276688', '352074']
nosy_count = 8.0
nosy_names = ['gvanrossum', 'vstinner', 'docs@python', 'socketpair', 'python-dev', 'martin.panter', 'yselivanov', 'xtreak']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue26050'
versions = ['Python 3.4', 'Python 3.5', 'Python 3.6']

[socketpair]

See code discussion here:

python/asyncio#297

[1st1]

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

[python-dev]

New changeset db11d0db1598 by Yury Selivanov in branch '3.4':
Issue bpo-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 bpo-26050)
https://hg.python.org/cpython/rev/a6288fe5420f

New changeset c2cd3b435afe by Yury Selivanov in branch 'default':
Merge 3.5 (issue bpo-26050)
https://hg.python.org/cpython/rev/c2cd3b435afe

[1st1]

Leaving this issue open until we have the docs committed.

[socketpair]

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

These descriptions are just copies of docstrings of corresponding functions.

[vadmium]

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

[vadmium]

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

[1st1]

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

[socketpair]

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.

[tirkarthi]

StreamReader and StreamWriter were merged to Stream with bpo-36889 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.