BinaryIO does not have peek method

[vegarsti]

When opening a file with binary mode, typing.BinaryIO is inferred.
This type should have the https://docs.python.org/3/library/io.html#io.BufferedReader.peek method.
It looks like this is known, judging by the TODO on this line in the typing.pyi stub:

typeshed/stdlib/3/typing.pyi

Line 509 in bc90043

# TODO peek?

(There are also other TODOs there for BinaryIO - if those should be added, I could of course do those in the same change if that's not a problem.)

A reproducible example:

with open("some-file", 'rb') as f:
    f.peek()

Running mypy on this results in error: "BinaryIO" has no attribute "peek".

This issue has also been reported earlier in mypy.

I'd be glad to submit a PR for this. Is it as simple as adding peek to BinaryIO in typing.pyi? Or should there also be tests for these changes?

[JelleZijlstra]

This is probably fine to add. The trouble with the IO protocols is that they are fairly ill-defined, in that there are lots of variations in exactly what methods different IO classes have, so it's tricky to say exactly which methods should be on each IO protocol. However, given that this method exists on the return type of open(), I agree we should add it.

No tests are necessary.

[vegarsti]

I see. Thanks for the quick reply!

[vegarsti]

@JelleZijlstra FYI, I opened a PR (sorry if you already got a notification from the mention there)

[srittau]

I didn't see this discussion here, so I answered in the PR. But quickly: I don't think we should add BinaryIO.peek() as the "implementation" in typing.BinaryIO does not have it. Also, open() in the stubs returns an IO[Any] for Python 3. Maybe it's time we added a custom sub-type to be returned by open() (deriving from IO/BinaryIO)?

[JelleZijlstra]

I feel like the right solution is to make the open() stubs reflect the types that open() actually returns, which are various classes in io:

In [13]: type(open('/dev/null', 'w'))                                                                                                                                                
Out[13]: _io.TextIOWrapper

In [14]: type(open('/dev/null', 'wb'))                                                                                                                                               
Out[14]: _io.BufferedWriter

In [15]: type(open('/dev/null', 'r+'))                                                                                                                                               
Out[15]: _io.TextIOWrapper

In [16]: type(open('/dev/null', 'rb+'))                                                                                                                                              
Out[16]: _io.BufferedRandom

In [17]: type(open('/dev/null', 'w+'))                                                                                                                                               
Out[17]: _io.TextIOWrapper

This would require making these classes inherit from TextIO or BinaryIO, which they currently don't do.

I can look into this after #3371 and #4082 (which touch some of the same code) are merged.

[vegarsti]

Agreed, that sounds like a much better solution! Let me know if I can be of help!

[JelleZijlstra]

Here's what open() returns:

• If text mode, always TextIOWrapper
• If unbuffered, FileIO. This appears to map directly to the buffering= keyword argument to open() but the logic is fairly complicated.
• Else BufferedReader, BufferedWriter or BufferedRandom depending on mode.

The code is at https://github.com/python/cpython/blob/master/Modules/_io/_iomodule.c#L231.