[issue11203] gzip doc is behind
New submission from K Richard Pixley rich@noir.com:
The documentation for gzip should include the "close" method.
It's use in the 2.7 documentation implies it's existence but it should also be stated explicitly that it exists.
In the 3.x documentation, the use of "close" not in the examples since the examples use context manager. For 3.x documentation there should be both an explicit mention of the "close" method as well as an explicit mention that GzipFile supports the context manager protocol.
Yes, the use of the context manager in the examples implies that this is true but documentation on other modules states so explicitly so this module should too.
---------- assignee: docs@python components: Documentation messages: 128460 nosy: docs@python, teamnoir priority: normal severity: normal status: open title: gzip doc is behind type: feature request versions: Python 2.7, Python 3.3
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
Thanks for the report. Would you like to propose a patch?
---------- nosy: +eric.araujo versions: +Python 3.1, Python 3.2
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
Changes by Adam Woodbeck adam.woodbeck@gmail.com:
---------- nosy: +adam.woodbeck
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
Antoine Pitrou pitrou@free.fr added the comment:
The 3.x doc states that "GzipFile supports the io.BufferedIOBase interface, including iteration and the with statement. Only the truncate() method isn’t implemented". This implies that it also supports close().
---------- nosy: +pitrou versions: -Python 3.1, Python 3.2, Python 3.3
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
This implies that it also supports close().
One has to follow the link to BufferedIOBase and then to IOBase, but I think it’s okay.
Richard: Does that address your issue?
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
K Richard Pixley rich@noir.com added the comment:
My point was for python-2.7. I haven't stumbled into the buffer protocol yet. So no, it doesn't really.
I still think the documentation, especially the 2.7 doc, could be more explicit.
My concern here is with the use of close() becoming obscure, a second class citizen, or an afterthought. While I greatly appreciate the context manager, there are times when I want an enduring open channel for which the context manager just isn't appropriate. Even in a world with context manager, open and close need to be available and presented as a pair.
It isn't clear to me from reading the doc or looking at the examples that gzip is expected to support a close call. Yes, I concur that there is an implication, but I would prefer to see it stated explicitly along with the explicit statement that it supports an open call.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
In 2.7, while there is no index-generating entry for the close method, it is mentioned: “Calling a GzipFile object’s close() method [...]”.
Yes, I concur that there is an implication, but I would prefer to see it stated explicitly along with the explicit statement that it supports an open call.
I wouldn’t like to see the docs for int, float, complex, Decimal, Fraction, GzipFile, BZ2File, BytesIO, StringIO and all others having duplicated lists of methods and attributes that are already documented in the doc of the ABC.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
K Richard Pixley rich@noir.com added the comment:
An interesting point, although I think that's only relevant if the documentation lists the ABC and a reference to it. (python-3 doc essentially does this.)
I see no such reference in the 2.7 gzipfile doc, which leads me to believe, (from the doc alone), that it's an independent implementation of a "file like object".
This may not be important enough to even merit the time we've already put into it. Please feel free to close this ticket without change if you prefer.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
I see no such reference in the 2.7 gzipfile doc
Did you miss the first part of my previous message? The 2.7 docs for GzipFile do not link to the ABC, but they mention the close method in plain text.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
K Richard Pixley rich@noir.com added the comment:
I didn't miss it.
I think the close call needs equal treatment to the open call. The mention is certainly present, but seems implicit to me. I would prefer to see it listed explicitly.
But I also don't think it's important enough in the 2.7 docs to discuss it much further. You've convinced me that it's not worth fixing. Let's drop it.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
K Richard Pixley rich@noir.com added the comment:
I'm now convinced this isn't worth fixing in 2.x.
---------- resolution: -> wont fix status: open -> closed
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
Just one thing:
I think the close call needs equal treatment to the open call.
The open call is a module-level functions; the close method of GzipFile cannot be equally treated, as it is in the doc of the class, where no methods are given special treatment :)
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11203 _______________________________________
participants (4)
-
Adam Woodbeck -
Antoine Pitrou
-
K Richard Pixley
-
Éric Araujo