The file-like object returned by urllib.urlopen() should be documented
like a proper class. The textual description under the urlopen() method
is less approachable and breaks the usual format of a class documentation.

Maybe the return type should be changed to be a httplib.HTTPResponse
object (but that's a separate issue).

I'll let Georg make the final determination about this, but IMO this is
unneeded. File-like objects are so common in Python code, that just
telling what methods are supported should be fine.

I agree with Benjamin on this issue, describing what is a "File like Object" is
so much un-needed in Python and especially at urlopen function. Users have been
able to understand and use it properly from a long time.

Agreed.

On Fri, Aug 8, 2008 at 2:04 AM, Senthil <report@bugs.python.org> wrote:
>
> Senthil <orsenthil@gmail.com> added the comment:
>
> I agree with Benjamin on this issue, describing what is a "File like Object" is
> so much un-needed in Python and especially at urlopen function. Users have been
> able to understand and use it properly from a long time.

If only it were more file-like. But, oh, it adds info() and geturl()
methods which you have to string-search for to find the proper
description in the prose. And, ah, the size argument of the read()
method doesn't quite behave like on other file-like objects, but there
you go. And, uh, by the way, you really can't use it in places "where
a true built-in file object is required" (and I'm sure everybody knows
what that means). - So much for file-like.

I have no doubt that people can get along with the description as it
is, because that's what they always try. My main point was that it is
"less approachable and breaks the usual format of a class
documentation". But I see there is much agreement in keeping the
status quo.

Georg,

you seem like a dedicated person. I'm sure you guys have thought about
documenting return types of methods and functions in a standardized
way, documenting classes so that you could fade in and out inherited
features, and such. Where do you guys discuss general documentation
issues? Is there a mailing list dedicated to Python documentation?!

On Fri, Aug 8, 2008 at 8:43 AM, Georg Brandl <report@bugs.python.org> wrote:
>
> Georg Brandl <georg@python.org> added the comment:
>
> Agreed.
>
> ----------
> resolution:  -> works for me
> status: open -> closed
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue3429>
> _______________________________________
>