[docs] [issue10589] I/O ABC docs should specify which methods have implementations

Daniel Stutzbach report at bugs.python.org
Tue Nov 30 23:36:27 CET 2010


Daniel Stutzbach <stutzbach at google.com> added the comment:

> What does "unsupported" mean? "Abstract" would look more exact.

It means they raise io.UnsupportedOperation when called (unless the subclass overrides them to do something else).  

They are not marked with @abstractmethod, so "Abstract" would be wrong.

It should be a bit more clear in context.  Here's a link to the point in the documentation where the table would fit:
http://docs.python.org/dev/py3k/library/io.html#class-hierarchy

The most relevant bit is: "implementations are allowed to raise UnsupportedOperation if they do not support a given operation."

> E.g. "readinto" is listed as provided by RawIOBase in the doc text.

The doc text describes the API.  That is, it describes what the readinto method should do if a subclass of RawIOBase decides to implement it.  The existing text doesn't contain any clues as to which methods contain useful implementations versus which will raise io.UnsupportedOperation if not overridden.  Hence the need for the table.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10589>
_______________________________________


More information about the docs mailing list