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-clas... [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
participants (1)
-
Daniel Stutzbach