> Apparently, they are specified to, even for blocking streams (which 
> I find a bit weird, and the language in the docs seems deliberately
> vague). 

"""
As an additional convenience, it attempts to read as many bytes as possible by repeatedly invoking the read method of the underlying stream. This iterated read continues until one of the following conditions becomes true:

The specified number of bytes have been read,
The read method of the underlying stream returns -1, indicating end-of-file, or
The available method of the underlying stream returns zero, indicating that further input requests would block.
"""

As I understand it, it will return the number of bytes asked, unless EOF or EAGAIN/EWOULDBLOCK. It would seem reasonable to me to add the same note for non-blocking FDs to Python's read().

>> But what about the buggy readline() behaviour?
> Just tell people that if the return value is a string which does not 
> end in '\n' then it might caused by EOF or EAGAIN.  They can just call 
> readline() again to check which.

Sounds reasonable.

> No one has suggested raising BlockingIOError and DISCARDING the data 
> when a partial read has occurred.

The problem is that if we raise BlockingIOError, we can only buffer a limited amount of data.

> The docs seem to imply that the partially read data should be returned 
> since they only say that BlockingIOError should be raised if there is 
> NOTHING to read.  Clearly this should all be spelt out properly.

Agreed.

> That leaves the question of whether, when there is NOTHING to 
> read, BlockingIOError should be raised (as the docs say) or None
> should be returned (as is done now).

I don't have a string feeling: if we don't raise BlockingIOError on partial reads, then it probably makes sense to keep None.