The os.writev and os.readv functions are currently documented as:

os.writev(fd, buffers)

    Write the contents of buffers to file descriptor fd, where buffers is an arbitrary sequence of buffers. Returns the total number of bytes written.

os.readv(fd, buffers)

    Read from a file descriptor into a number of writable buffers. buffers is an arbitrary sequence of writable buffers. Returns the total number of bytes read.


This is rather confusing, mostly because it's not clear what can be passed as *buffer* (since buffer objects don't exist in Python 3 anymore), and (as a consequence) how the input will be distributed among the list of buffers.

Reading the code, it seems to me that any object that implements the buffer protocol would be fine, but that still doesn't help much in practice. From the memoryview documentation, I can infer that `bytes` implements the buffer protocol, but is also immutable, so how can something be written into it?

I'd be happy to write a patch to the documentation, but someone would need to explain to me first what kind of buffers are actually acceptable (and I suspect this will be different for readv and writev).

Here's a first attempt at improvement based on my guess:

os.writev(fd, buffers)

    Write the contents of buffers to file descriptor fd, where buffers is an arbitrary sequence of buffers. In this context, a buffer may be any Python object that provides a Memory View, i.e. that may be used to instantiate a `memoryview` object (e.g. a bytes or bytearray object). writev writes the contents of each memory view to the file descriptor and returns the total number of bytes written.

os.readv(fd, buffers)

    Read from a file descriptor into a number of writable buffers. buffers is an arbitrary sequence of writable buffers. In this context, a buffer may be any Python object that provides a writeable Memory View, i.e. that may be used to instantiate a `memoryview` object whose `read_only` attribute is false (for example, a bytearray object). Writeable memory views have a fixed size, and readv will transfer data into each buffer until it is full and then move on to the next buffer in the sequence to hold the rest of the data. readv returns the total number of bytes read (which may be less than the total capacity of all the buffers).

Well, the documentation is technically precise.  I'd even managed to forget that buffer objects existed in Python2 :)

As you observed, in Python3 a buffer is something that implements the buffer protocol.  What I would do is link the word 'buffer' to http://docs.python.org/3/c-api/buffer.html.  Perhaps mentioning bytes and bytearray as examples of read-only and writeable buffers would be worthwhile, but they are mentioned in the first paragraph of that section so it may not be necessary.

What section do you mean? bytearray is not mentioned anywhere in
http://docs.python.org/3.4/library/os.html.

I think the problem with just linking to the C API section is that it doesn't help people that are only using pure Python. You can't look at a Python object and tell whether it implements the buffer protocol or not. Therefore, I think it would be important to give at least a reference to memoryview as the Python equivalent of the buffer protocol.

I have attached a patch that takes into account your comments. Would this be suitable for inclusion?

IMO, it should just refer to the glossary entry for "bytes-like object".

Indeed, this makes most sense. I didn't know that glossary entry existed. I have attached an updated patch. Thanks for reviewing!

New changeset 8b413f813a13 by Benjamin Peterson in branch '3.3':
improve description of buffers argument for readv/writev (closes #17811)
http://hg.python.org/cpython/rev/8b413f813a13

New changeset 4d56006133f1 by Benjamin Peterson in branch 'default':
merge 3.3 (#17811)
http://hg.python.org/cpython/rev/4d56006133f1