[Python-ideas] collections.abc.Stream

[Guido van Rossum]

I think it may be time to gently phase out "file-like" from the stdlib
documentation, in favor of more precise terms like (text | binary) (input |
output) stream.

There are probably a handful of cases where it's worth restricting the
(duck) type more, e.g. to "an object with a readline() method returning
str". But in most cases for the stdlib I favor specifying a relatively wide
interface so that future evolution of the documented module is not
constrained by old documentation.

For example, an API that takes a writable binary stream might currently
only call .readline() on that stream, but in the future might find it more
convenient to use .readlines() or .read().

As to whether we should just stick with the ABCs from 'io', there are a few
problems with that, so I don't want to go there.

First, these ABCs don't distinguish between input and output. This is
intentional because otherwise there would be a bewildering set of
combinations, since for each form would have to support input, output, or
both -- and we already have more than enough ABCs here (IOBase, RawIOBase,
BufferedIOBase, TextIOBase -- I really don't want to have to remember 12 of
these).

We also need to be sensitive to the use of duck typing (which is
particularly common for I/O streams) -- while it's fine to formally define
an API as taking e.g. a text input stream, it's usually not fine to start
asserting that it must be an instance of TextIOBase -- ABC.register()
notwithstanding, that would break a lot of code. (Type annotations are a
different story -- but except for brand new APIs, the stdlib should not yet
start using those.)

PS. I assume the reference to 'STL' was meant to be 'stdlib', an innocent
mistake by someone more familiar with C++, not something to be picked apart.

-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20160618/f7a88f68/attachment.html>