classification
Title: detach method has no docstring
Type: Stage:
Components: IO Versions: Python 3.1
process
Status: closed Resolution: works for me
Dependencies: Superseder:
Assigned To: Nosy List: amcnabb, benjamin.peterson
Priority: normal Keywords:

Created on 2010-02-18 00:53 by amcnabb, last changed 2010-02-19 00:58 by benjamin.peterson. This issue is now closed.

Messages (7)
msg99486 - (view) Author: Andrew McNabb (amcnabb) Date: 2010-02-18 00:53
The detach() method has no docstring, so it's impossible to find out about it with pydoc or help().  It would be great if the description were copied from the io library documentation.

For BufferedIOBase:

"""Separate the underlying raw stream from the buffer and return it.

After the raw stream has been detached, the buffer is in an unusable state."""

For TextIOBase:

"""Separate the underlying binary buffer from the TextIOBase and return it.

After the underlying buffer has been detached, the TextIOBase is in an unusable state."""

By the way, it's odd that detaching
msg99488 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2010-02-18 01:01
There are docstrings in the "abstract" methods on BufferedIOBase and TextIOBase.
msg99489 - (view) Author: Andrew McNabb (amcnabb) Date: 2010-02-18 01:22
Oops.  I had run "pydoc" instead of "pydoc3", so I was getting the 2.6 version of the io docstrings instead of the 3.1 version.

By the way, it took about an hour to find out how to get Python 3 to treat stdin as bytes instead of unicode.  Now that I know what I was looking for, the documentation for the io library seems fine.  However, since Python 3 uptake is still a little slow, it's really hard to search for good information out there.

Would it be possible to some tutorial-style information to the io library documentation?  Stuff like switching stdin and stdout to bytes mode seem like they will be common problems, and it's a bit overwhelming to sort through 14 pages of documentation.  I think for most readers, it would be helpful to start with a brief tutorial before lunging into the hierarchy of abstract classes.

Overall, the documentation is great; it's detailed and complete.  If there's one weakness, it's the overview.

Thanks.
msg99490 - (view) Author: Andrew McNabb (amcnabb) Date: 2010-02-18 01:25
Oh, and I realized that even "pydoc3 sys.stdin" doesn't have any of the docstrings.  Would it be possible to have the method docstrings show up for the TextIOWrapper instance?
msg99491 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2010-02-18 01:27
2010/2/17 Andrew McNabb <report@bugs.python.org>:
>
> Andrew McNabb <amcnabb@mcnabbs.org> added the comment:
>
> Oops.  I had run "pydoc" instead of "pydoc3", so I was getting the 2.6 version of the io docstrings instead of the 3.1 version.
>
> By the way, it took about an hour to find out how to get Python 3 to treat stdin as bytes instead of unicode.  Now that I know what I was looking for, the documentation for the io library seems fine.  However, since Python 3 uptake is still a little slow, it's really hard to search for good information out there.

There's a note here: http://docs.python.org/py3k/library/sys#sys.stdin

>
> Would it be possible to some tutorial-style information to the io library documentation?  Stuff like switching stdin and stdout to bytes mode seem like they will be common problems, and it's a bit overwhelming to sort through 14 pages of documentation.  I think for most readers, it would be helpful to start with a brief tutorial before lunging into the hierarchy of abstract classes.
>
> Overall, the documentation is great; it's detailed and complete.  If there's one weakness, it's the overview.

Yes, but that's another issue. :)
msg99495 - (view) Author: Andrew McNabb (amcnabb) Date: 2010-02-18 04:17
I followed your link to http://docs.python.org/py3k/library/sys#sys.stdin and that looks really good.  Can there be a link to this at the beginning of the documentation for the io library?
msg99550 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2010-02-19 00:58
2010/2/17 Andrew McNabb <report@bugs.python.org>:
>
> Andrew McNabb <amcnabb@mcnabbs.org> added the comment:
>
> I followed your link to http://docs.python.org/py3k/library/sys#sys.stdin and that looks really good.  Can there be a link to this at the beginning of the documentation for the io library?

r78230
History
Date User Action Args
2010-02-19 00:58:44benjamin.petersonsetmessages: + msg99550
2010-02-18 04:17:53amcnabbsetmessages: + msg99495
2010-02-18 01:27:12benjamin.petersonsetmessages: + msg99491
2010-02-18 01:25:06amcnabbsetmessages: + msg99490
2010-02-18 01:22:46amcnabbsetmessages: + msg99489
2010-02-18 01:01:47benjamin.petersonsetstatus: open -> closed

nosy: + benjamin.peterson
messages: + msg99488

resolution: works for me
2010-02-18 00:53:41amcnabbcreate