classification
Title: io.BufferReader.read() returns None
Type: behavior Stage:
Components: Documentation, IO Versions: Python 3.7
process
Status: open Resolution:
Dependencies: Superseder: The io module doesn't support non-blocking files
View: 13322
Assigned To: docs@python Nosy List: docs@python, martin.panter, steverpalmer
Priority: normal Keywords:

Created on 2019-01-31 15:21 by steverpalmer, last changed 2019-02-01 08:36 by martin.panter.

Files
File name Uploaded Description Edit
read2.py steverpalmer, 2019-01-31 15:21
Messages (3)
msg334630 - (view) Author: Steve Palmer (steverpalmer) * Date: 2019-01-31 15:21
class io.BufferedIOBase states "In addition, those methods [read(), readinto() and write()] can raise BlockingIOError if the underlying raw stream is in non-blocking mode and cannot take or give enough data; unlike their RawIOBase counterparts, they will never return None."

However, class.io.BufferedReader (inheriting from io.BufferedIOBase) *does* return None in this case.  Admittedly, io.BufferedReader does says it is overriding the inherited method, but I'm surprised that change in behaviour declared for buffered objects, is reverted to the RarIOBase behaviour on a more specific class.

The attached file (a little long - sorry), simulates a slow non-blocking raw file, which it wraps in a BufferReader to test the behaviour defined in BufferedIOBase.
msg334632 - (view) Author: Steve Palmer (steverpalmer) * Date: 2019-01-31 15:56
The description of read in io.BufferedReader.read function states "Read and return size bytes, or if size is not given or negative, until EOF or if the read call would block in non-blocking mode."  This does mention the non-block mode scenario, but I can't parse this sentence.
msg334655 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2019-02-01 08:36
This is covered by Issue 13322. There are a few other BufferedReader methods that contradict the documentation for non-blocking mode.

A while ago I posted a patch to change the implementation to match the documentation, but nobody reviewed it or gave their opinion. These days I would prefer to just documentat the reality: the methods might raise an exception rather than returning None, or perhaps no particular behaviour at all is expected in general in the non-blocking case. But I don’t spend much time on Python now, so you might have to find someone else to move this forward.

Regarding the entry for “BufferedReader.read”, it would make more sense to remove the last “if”: “if ‘size’ is not given . . ., until EOF, or the ‘read’ call would block”. But I don’t think even that is complete, because it should also say the read stops and returns short in the non-blocking case even when “size” is positive.
History
Date User Action Args
2019-02-01 08:36:11martin.pantersetnosy: + docs@python, martin.panter
messages: + msg334655

assignee: docs@python
components: + Documentation, IO
superseder: The io module doesn't support non-blocking files
2019-01-31 15:56:29steverpalmersetmessages: + msg334632
2019-01-31 15:21:50steverpalmercreate