Doc update for io module

[pakal]

BPO	7022
Nosy	@birkenfeld, @pitrou, @pakal

^{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 = 'https://github.com/pitrou'
closed_at = <Date 2009-10-01.16:28:04.956>
created_at = <Date 2009-09-30.06:52:40.568>
labels = ['type-bug', 'expert-IO', 'docs']
title = 'Doc update for io module'
updated_at = <Date 2009-10-05.18:01:10.330>
user = 'https://github.com/pakal'

bugs.python.org fields:

activity = <Date 2009-10-05.18:01:10.330>
actor = 'pakal'
assignee = 'pitrou'
closed = True
closed_date = <Date 2009-10-01.16:28:04.956>
closer = 'pitrou'
components = ['Documentation', 'IO']
creation = <Date 2009-09-30.06:52:40.568>
creator = 'pakal'
dependencies = []
files = []
hgrepos = []
issue_num = 7022
keywords = []
message_count = 6.0
messages = ['93352', '93398', '93399', '93410', '93412', '93614']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'pitrou', 'pakal']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue7022'
versions = ['Python 2.6', 'Python 3.1', 'Python 2.7', 'Python 3.2']

[pakal]

*Propositions of doc update*

*RawIOBase*.read(n: int) -> bytes

Read up to n bytes from the object and return them. Fewer than n bytes
may be returned if the operating system call returns fewer than n bytes.
If 0 bytes are returned, and n was not 0, this indicates end of file. If
the object is in non-blocking mode and no bytes are available, the call
returns None.

<warning - this proposition requires patching teh current implementation
as well>:
*RawIOBase*.readinto(b: bytearray, [start: int = None], [end: int =
None]) -> int

start and end are used as slice indexes, so that the bytearray taken
into account is actually range = b[start:end] (or b[start:], b[:end] or
b[:], depending on the arguments which are not None).

Read up to len(range) bytes from the object and store them in b, returning
the number of bytes read. Like .read, fewer than len(range) bytes may be
read, and 0 indicates end of file if len(range) is not 0.
None is returned if a non-blocking object has no bytes available. The
length of b is never changed.

[pitrou]

If you are requesting new start and end arguments to readinto(), the
way to do that today is to use a memoryview:

   # b is your bytearray, f your IO object
   m = memoryview(b)[start:end]
   f.readinto(m)

If you still want that feature, please open a separate bug (doc updates
and feature requests should be open separately) :-)

As for the first part of the report (RawIOBase.read), I'll look into it.

[pitrou]

Actually, I'm not sure what is wrong with the current doc:

read(n=-1)¶
Read and return up to n bytes from the stream. As a convenience, if
n is unspecified or -1, readall() is called. Otherwise, only one system
call is ever made. An empty bytes object is returned on EOF; None is
returned if the object is set not to block and has no data to read.

(http://docs.python.org/dev/py3k/library/io.html)

[pakal]

Thanks for the memoryview tip - I though I was up-to-date with python's
features but obviously I wans't ^^ (I searched through dict views but
that wasn't it...)
It should be exactly what's needed to replace these unnecessary
additional arguments.

As for the simple doc update, I was just pointing out the fact that EOF
is reached if read methods returns an empty bytes AND we didn't ask for
0 bytes. Just to avoid confusing people : file.read(0) will always
return an empty bytes, but it doesnt mean that we're at eof, contarrily
to what the doc currently says B-)

[pitrou]

Ok, I've improved the docs a bit in r75168. Thanks!

[pakal]

Thanks a lot B-)