[Python-Dev] I/O ABCs

[Daniel Stutzbach]

The documentation for the collections Abstract Base Classes (ABCs) [1]
contains a table listing all of the collections ABCs, their parent classes,
their abstract methods, and the methods they provide.  This table makes it
very easy to figure out which methods I must override when I derive from one
of the ABCs, as well as which methods will be provided for me.

I'm working on a similar table for the I/O ABCs (
http://bugs.python.org/issue10589).  The existing documentation [2]
describes the methods of each class but doesn't describe which methods
provide a meaningful implementation and which methods a user should
override.  If I want to inherit from one of the I/O ABCs, I have to go
poking into Lib/_pyio.py to figure out which methods I need to override.

While starting to examine the I/O ABCs, I discovered that there are
some inconsistencies.  For example, RawIOBase provides .read() if the
subclass provides .readinto().  BufferedIOBase does the opposite; it
provides .readinto() if the subclass provides .read() [3].

I would like to fix some of these inconsistencies.  However, this will be a
backwards-incompatible change.  A Google Code Search suggests that the ABCs
are currently only used within the standard library [4].  Just to be clear,
the changes would NOT impact code that merely uses I/O objects; they would
only impact code that implements I/O by subclassing one of the I/O ABCs and
depending on features that are currently undocumented.

Does anyone have any categorical objections?

[1]:
http://docs.python.org/py3k/library/collections.html#abcs-abstract-base-classes
 [2]: http://docs.python.org/py3k/library/io.html#class-hierarchy
[3]: Possibly hurting performance by forcing .readinto() to perform the
extra allocations, copies, and deallocations required by .read().
[4]:
http://www.google.com/codesearch?hl=en&sa=N&q=BufferedIOBase++lang:python&ct=rr&cs_r=lang:python

-- 
Daniel Stutzbach
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20101130/a216d560/attachment.html>