gh-133492: Add readinto to typing.BinaryIO and widen its write signatures

[v0ropaev]

Closes #133492.

typing.BinaryIO has no readinto, though every binary stream open() returns supports it, and its write/writelines are narrower than what those streams accept.

@JelleZijlstra set a condition for the readinto half:

I'd be fine with doing this it can be shown that the method is present on all classes in typeshed that are currently marked as inheriting from BinaryIO.

Seven classes in typeshed are declared that way. FileIO, BytesIO, BufferedReader, BufferedWriter and BufferedRandom get readinto from _RawIOBase or _BufferedIOBase; http.client.HTTPResponse declares it itself. The seventh, codecs.StreamRecoder, does not define it — its __getattr__ forwards every unknown attribute to the wrapped stream:

def __getattr__(self, name, getattr=getattr):
    """ Inherit all other methods from the underlying stream.
    """
    return getattr(self.stream, name)

so a recoder wrapping a binary stream has it and it works:

>>> sr = codecs.StreamRecoder(io.BytesIO(b"abc"), enc, dec, Reader, Writer)
>>> buf = bytearray(3); sr.readinto(buf), bytes(buf)
(3, b'abc')

Worth noting that a class-level hasattr(codecs.StreamRecoder, "readinto") says False and is the wrong probe — it misses the forwarding, which only shows on an instance.

The other half you were fine with outright:

I wouldn't mind a PR updating the typing.py definitions to match those in typeshed better though.

So BinaryIO.write and BinaryIO.writelines now take collections.abc.Buffer instead of bytes | bytearray, and IO.writelines takes an iterable rather than a list. Binary streams accept all of that today; typeshed says the same through overloads a runtime stub cannot spell.

Nothing here affects type checkers, which read typeshed rather than these definitions — this is about the runtime stubs matching what they claim to describe.

./python.exe -m test test_typing is 744 tests passing; reverting Lib/typing.py while keeping the new test fails one. Two news entries, since the two halves stand on their own. Docs get a versionchanged:: next on BinaryIO. main only.

• Issue: "typing.BinaryIO" missing "readinto" method #133492

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34747862 | 📁 Comparing c209802 against main (a5b03fa)

  🔍 Preview build  

2 files changed

± library/typing.html
± whatsnew/changelog.html