typing: Add peek method to BinaryIO (#3951)

[vegarsti]

Issue.

In the below example, f is of type BinaryIO and has method peek (docs), but mypy doesn't know this.

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

The size parameter to peek is optional. Is size: int = ... the correct way to indicate that? That's what I saw other places in the code base.

[vegarsti]

I see that it's failing in CI, I'll try to find out why. EDIT: Fixed.

[srittau]

Thank you for the PR. IO types are currently a bit of a mess. The long term plan is to have concrete classes returned from functions. Currently, open() returns IO[Any] in Python 3 and BinaryIO in Python 2.

The implementation of typing.BinaryIO does not have a peek() method, so we should not add it to our stubs. But of course since the object returned by open() does have peek() we should represent this in the stubs somehow. Maybe it's time to create a custom file type for open(), deriving from IO/BinaryIO in typeshed. @JelleZijlstra what do you think?

[vegarsti]

Ah, I see! Makes sense not to add this, then. Let me know how I can help with this!

[vegarsti]

@JelleZijlstra a friendly ping

[JelleZijlstra]

I guess we can try returning custom types from open(). I'm worried that something will break just because it is so widely used, but we'll see.

[srittau]

Yes, something breaking is a real danger, we certainly need to test this change.

[JelleZijlstra]

Let's close this because BinaryIO.peek should not exist, and discuss next steps in the issue.