classification
Title: I/O ABC docs should specify which methods have implementations
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: asvetlov Nosy List: asvetlov, benjamin.peterson, daniel.urban, docs@python, ezio.melotti, fdrake, georg.brandl, pitrou, stutzbach
Priority: normal Keywords: patch

Created on 2010-11-30 19:05 by stutzbach, last changed 2012-12-06 10:24 by asvetlov. This issue is now closed.

Files
File name Uploaded Description Edit
io-abc.diff stutzbach, 2010-11-30 22:15
issue10589.diff asvetlov, 2012-11-30 16:26
Messages (10)
msg122930 - (view) Author: Daniel Stutzbach (stutzbach) (Python committer) Date: 2010-11-30 19:05
The I/O ABC documentation has a blanket disclaimer at the top:

    "The abstract base classes also provide default implementations of some methods in order to help implementation of concrete stream classes. For example, BufferedIOBase provides unoptimized implementations of readinto() and readline()."

Which effectively means that to subclass one of them requires digging into Lib/_pyio.py to figure out which methods provide useful implementations.

It would be handy to have a table, similar to the one for the collections ABCs [1], that spells out which methods are provided.

[1]: http://docs.python.org/py3k/library/collections.html#abcs-abstract-base-classes

I hope to have a patch ready sometime within the next week.
msg122940 - (view) Author: Daniel Stutzbach (stutzbach) (Python committer) Date: 2010-11-30 22:15
+io and doc people

Attached is a simple patch to add a table to the documentation summarizing the I/O ABCs.
msg122943 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2010-11-30 22:26
What does "unsupported" mean? "Abstract" would look more exact.
msg122944 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-11-30 22:28
Not sure what "unsupported methods" means.  E.g. "readinto" is listed as provided by RawIOBase in the doc text.
msg122948 - (view) Author: Daniel Stutzbach (stutzbach) (Python committer) Date: 2010-11-30 22:36
> 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.
msg122949 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2010-11-30 22:40
> > 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.

Except that "unsupported" is even more wrong, because it makes it look
like that these methods are not supported by the respective ABCs.
Actually, what happens is that the default implementations are stubs. If
those methods weren't "supported" at all they wouldn't be defined in the
first place.
msg122951 - (view) Author: Daniel Stutzbach (stutzbach) (Python committer) Date: 2010-11-30 22:44
Other suggestions for a better name for that column are certainly welcome. :-)

"Stub Methods"?
msg122952 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2010-11-30 22:45
> Other suggestions for a better name for that column are certainly welcome. :-)
> 
> "Stub Methods"?

Fine with me.
msg176692 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-11-30 16:26
Updated the patch. Is it ok now?
msg177034 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-12-06 10:24
Fixed in a58204570a7c, 3cb85250a0a3, 93742b046519.
History
Date User Action Args
2012-12-06 10:24:00asvetlovsetstatus: open -> closed
messages: + msg177034

assignee: stutzbach -> asvetlov
resolution: fixed
stage: patch review -> resolved
2012-11-30 16:26:45asvetlovsetfiles: + issue10589.diff
nosy: + asvetlov
messages: + msg176692

2012-11-08 08:29:46ezio.melottisetstage: needs patch -> patch review
versions: + Python 3.3, Python 3.4
2010-12-01 17:02:09daniel.urbansetnosy: + daniel.urban
2010-11-30 22:45:11pitrousetmessages: + msg122952
2010-11-30 22:44:25stutzbachsetmessages: + msg122951
2010-11-30 22:40:04pitrousetmessages: + msg122949
2010-11-30 22:36:23stutzbachsetmessages: + msg122948
2010-11-30 22:28:00georg.brandlsetmessages: + msg122944
2010-11-30 22:26:17pitrousetmessages: + msg122943
2010-11-30 22:24:33fdrakesetnosy: + fdrake, docs@python
2010-11-30 22:15:36stutzbachsetfiles: + io-abc.diff

nosy: + georg.brandl, benjamin.peterson, ezio.melotti
messages: + msg122940

keywords: + patch
2010-11-30 19:08:02pitrousetnosy: + pitrou
2010-11-30 19:05:51stutzbachcreate