classification
Title: Doc update for io module
Type: behavior Stage:
Components: Documentation, IO Versions: Python 3.1, Python 3.2, Python 2.7, Python 2.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: pitrou Nosy List: georg.brandl, pakal, pitrou
Priority: normal Keywords:

Created on 2009-09-30 06:52 by pakal, last changed 2009-10-05 18:01 by pakal. This issue is now closed.

Messages (6)
msg93352 - (view) Author: Pascal Chambon (pakal) * Date: 2009-09-30 06:52
*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.
msg93398 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2009-10-01 10:55
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.
msg93399 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2009-10-01 10:58
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)
msg93410 - (view) Author: Pascal Chambon (pakal) * Date: 2009-10-01 15:59
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-)
msg93412 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2009-10-01 16:28
Ok, I've improved the docs a bit in r75168. Thanks!
msg93614 - (view) Author: Pascal Chambon (pakal) * Date: 2009-10-05 18:01
Thanks a lot B-)
History
Date User Action Args
2009-10-05 18:01:10pakalsetmessages: + msg93614
2009-10-01 16:28:04pitrousetstatus: open -> closed
resolution: fixed
messages: + msg93412
2009-10-01 15:59:09pakalsetmessages: + msg93410
2009-10-01 10:59:10pitrousetpriority: normal
type: enhancement -> behavior
versions: + Python 2.6, Python 2.7
2009-10-01 10:58:51pitrousetmessages: + msg93399
2009-10-01 10:55:03pitrousetmessages: + msg93398
2009-10-01 07:57:52georg.brandlsetassignee: georg.brandl -> pitrou

nosy: + pitrou
2009-09-30 06:52:40pakalcreate