Advise to use typing.IO sparingly

[srittau]

Documentation

typing.IO and subclasses typing.TextIO and typing.BinaryIO are a bit of a legacy feature and should be used sparingly. We should document better alternatives. I'm preparing a PR with some suggestions.

(Cc @gvanrossum @JelleZijlstra @AlexWaygood)

[srittau]

PR: #92878

[AlexWaygood]

PR: #92877

I think you mean #92878 -- this is #92877 :)

[srittau]

PR: #92877

I think you mean #92878 -- this is #92877 :)

I'm not sure what you mean. 😇

[ambv]

How is IO[Text] a "legacy" feature and why should it be used "sparingly"? In my talk I advise the opposite: that users should typically avoid "FileLike" protocols that specify a subset of functionality. I do it because:

• it's annoying to specify;
• it's cumbersome to read what the specification is due to indirection and it being a non-standard type;
• it's brittle since if in the future your file interface needs grow, now your current FileLike protocol is inadequate (sure, you can always change it at that point but all existing users of your API will be faced with a backwards-incompatible change).

I'm curious whether we can come up with a similar list of arguments against using IO[Text] and in favor of custom protocols.

[srittau]

IO and its subclasses have several, quite major problems:

• It's not a protocol, meaning that ad-hoc file-like objects can't be used in places where IO is expected.
• It's overspecified. It includes everything and the kitchen sink, and writing a class that implements all methods is cumbersome and often not required.
• It doesn't distinguish between readable and writable file-like objects. In probably 95% of cases, you want to either read or write to it.
• The division between IO and BinaryIO/TextIO is a bit arbitrary, and it's often not really clear whether to annotate something with the former or the latter.

All of these things make it quite hard to use custom file-like classes with type checking. Even using file-like objects from libraries becomes hard, because they usually don't implement methods like isatty() or truncate(). Often they are read-only, meaning they won't implement write(). These are some of the reasons why we're moving away from those classes - at least for argument types - in typeshed.

I believe the best way forward is to create two new protocols Reader and Writer (or similar) with a small set of methods that are actually used. I'm thinking along the lines of read()/write(), close(), seek()/tell(), __iter__ and readline() for readers. (List not final.) This would make it easy for application and library authors to use these in type annotations, but has none of the problems above. (Except maybe overspecification.) If the supported methods are chosen carefully, it also allows forward compatibility to a certain degree. More difficult cases could use these protocols as base protocols.