io.BufferReader.read() returns None

[steverpalmer]

BPO	35869
Nosy	@vadmium, @steverpalmer
Superseder	bpo-13322: The io module doesn't support non-blocking files
Files	read2.py

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-01-31.15:21:50.213>
labels = ['type-bug', '3.7', 'expert-IO', 'docs']
title = 'io.BufferReader.read() returns None'
updated_at = <Date 2019-02-01.08:36:11.123>
user = 'https://github.com/steverpalmer'

bugs.python.org fields:

activity = <Date 2019-02-01.08:36:11.123>
actor = 'martin.panter'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'IO']
creation = <Date 2019-01-31.15:21:50.213>
creator = 'steverpalmer'
dependencies = []
files = ['48091']
hgrepos = []
issue_num = 35869
keywords = []
message_count = 3.0
messages = ['334630', '334632', '334655']
nosy_count = 3.0
nosy_names = ['docs@python', 'martin.panter', 'steverpalmer']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = '13322'
type = 'behavior'
url = 'https://bugs.python.org/issue35869'
versions = ['Python 3.7']

[steverpalmer]

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.

[steverpalmer]

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.

[vadmium]

This is covered by bpo-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.