[docs] [issue17811] Improve os.readv() and os.writev() documentation and docstring

[Nikolaus Rath]

New submission from Nikolaus Rath:

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

----------
assignee: docs at python
components: Documentation
messages: 187526
nosy: Nikratio, docs at python
priority: normal
severity: normal
status: open
title: Improve os.readv() and os.writev() documentation and docstring
type: enhancement
versions: Python 3.3, Python 3.4, Python 3.5

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue17811>
_______________________________________