readinto should accept any bytes-like object not just memoryview

[hXtreme]

typeshed/stdlib/_io.pyi

Lines 126 to 140 in a3568ac

	@type_check_only
	class _BufferedReaderStream(Protocol):
	def read(self, n: int = ..., /) -> bytes: ...
	# Optional: def readall(self) -> bytes: ...
	def readinto(self, b: memoryview, /) -> int | None: ...
	def seek(self, pos: int, whence: int, /) -> int: ...
	def tell(self) -> int: ...
	def truncate(self, size: int, /) -> int: ...
	def flush(self) -> object: ...
	def close(self) -> object: ...
	@property
	def closed(self) -> bool: ...
	def readable(self) -> bool: ...
	def seekable(self) -> bool: ...

From python docs:
https://docs.python.org/3/library/io.html#io.RawIOBase.readinto

Read bytes into a pre-allocated, writable bytes-like object b

Where bytes-like objects can be any of:

object that supports the Buffer Protocol and can export a C-contiguous buffer. This includes all bytes, bytearray, and array.array objects, as well as many common memoryview objects. ...

And more relevant to BufferReaderStream would be the read-write variant of bytes-like object https://docs.python.org/3/glossary.html#term-bytes-like-object

Some operations need the binary data to be mutable. The documentation often refers to these as “read-write bytes-like objects”. Example mutable buffer objects include bytearray and a memoryview of a bytearray.

---

Not having bytearray as a possible type for b makes it so that urllib3's BaseHTTPResponse.readinto fails typechecking when you do something like:

import io
import requests
from urllib3.response import HTTPResponse

with requests.get(url, stream=True) as response:
        data_stream = response.raw
        assert isinstance(data_stream, HTTPResponse)
        _ = io.BufferedReader(data_stream)

error: Argument 1 to "BufferedReader" has incompatible type "HTTPResponse"; expected "_BufferedReaderStream"  [arg-type]
note: Following member(s) of "HTTPResponse" have conflicts:
note:     Expected:
note:         def readinto(self, memoryview[int], /) -> int | None
note:     Got:
note:         def readinto(self, b: bytearray) -> int

---

Will also be filing a issue with the urllib3 repo, since I believe that they should also be accepting more types in their readinto method implementation
urllib3/urllib3#3764

[srittau]

I don't think the typeshed stubs need changing. RawIOBase.readinto is already correctly annotated as taking a WriteableBuffer (via its _RawIOBase base class):

typeshed/stdlib/_io.pyi

Line 86 in 5c49b1f

def readinto(self, buffer: WriteableBuffer, /) -> int | MaybeNone: ...

The _BufferedReaderStream protocol is narrow and only represents what BufferedReader (and BufferedRWPair) needs of the raw argument provided to it. And BufferedReader provides it with a memoryview:

https://github.com/python/cpython/blob/f3dd0cae6cea38b15b42b20d39c7142a4a0f716e/Lib/_pyio.py#L1202

https://github.com/python/cpython/blob/f3dd0cae6cea38b15b42b20d39c7142a4a0f716e/Modules/_io/bufferedio.c#L1638

Widening the interface would actually be counter-productive as now users that constructing a BufferedReader need to support more types for the object provided as a raw object. The problem here is that urllib3 should annotate their readinto() method as accepting memoryview (or WritableBuffer) as well, since they do supports it and since that's what they are provided with when it's wrapped in a BufferedReader.