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.<div>




<br></div><div>I&#39;m working on a similar table for the I/O ABCs (<a href="http://bugs.python.org/issue10589" target="_blank">http://bugs.python.org/issue10589</a>).  The existing documentation [2] describes the methods of each class but doesn&#39;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.</div>




<div><br></div><div>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].</div>




<div><br></div><div>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.</div>

<div><br></div><meta http-equiv="content-type" content="text/html; charset=utf-8"><div>Does anyone have any categorical objections?</div>


<div><br></div><div>[1]: <a href="http://docs.python.org/py3k/library/collections.html#abcs-abstract-base-classes" target="_blank">http://docs.python.org/py3k/library/collections.html#abcs-abstract-base-classes</a></div>



<div>
[2]: <a href="http://docs.python.org/py3k/library/io.html#class-hierarchy" target="_blank">http://docs.python.org/py3k/library/io.html#class-hierarchy</a></div><div>[3]: Possibly hurting performance by forcing .readinto() to perform the extra allocations, copies, and deallocations required by .read().</div>




<div>[4]: <a href="http://www.google.com/codesearch?hl=en&amp;sa=N&amp;q=BufferedIOBase++lang:python&amp;ct=rr&amp;cs_r=lang:python" target="_blank">http://www.google.com/codesearch?hl=en&amp;sa=N&amp;q=BufferedIOBase++lang:python&amp;ct=rr&amp;cs_r=lang:python</a><br clear="all">




<br>-- <br>Daniel Stutzbach<br>
</div>