Improvement suggestions for the gzip module documentation

[madarche]

BPO	2406
Nosy	@birkenfeld, @ned-deily
Files	gzip.rst.diff idiomatic-gzip.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/birkenfeld'
closed_at = <Date 2008-03-28.08:07:04.166>
created_at = <Date 2008-03-18.20:29:42.761>
labels = ['docs']
title = 'Improvement suggestions for the gzip module documentation'
updated_at = <Date 2015-06-24.03:42:11.274>
user = 'https://bugs.python.org/madarche'

bugs.python.org fields:

activity = <Date 2015-06-24.03:42:11.274>
actor = 'ned.deily'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2008-03-28.08:07:04.166>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2008-03-18.20:29:42.761>
creator = 'madarche'
dependencies = []
files = ['9876', '39790']
hgrepos = []
issue_num = 2406
keywords = ['patch']
message_count = 8.0
messages = ['63981', '64580', '64587', '64598', '64601', '64621', '245693', '245709']
nosy_count = 5.0
nosy_names = ['georg.brandl', 'madarche', 'gpolo', 'ned.deily', 'FrostyX']
pr_nums = []
priority = 'normal'
resolution = 'accepted'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue2406'
versions = []

[madarche]

The documentation for the gzip python module as found at
http://docs.python.org/lib/module-gzip.html could be improved by code
examples. Those examples are really lacking.

Here below are the code snippets I propose. This is inspired by
http://xahlee.org/perl-python/python_doc_gzip.html but done with respect
and with another useful (I think) example.

# Example of how to decompress a file
import gzip
file_obj = gzip.GzipFile('/home/joe/file.txt.gz', 'rb');
file_content = file_obj.read()
file_obj.close()

# Example of how to create a compressed GZIP file
import gzip
file_content = "Lots of content here"
file_obj = gzip.GzipFile('/home/joe/file.txt.gz', 'wb');
file_obj.write(file_content)
file_content.close()

# Example of how to compress an existing file
import shutil
import gzip
file_obj_in = file('/home/joe/file.txt', 'rb')
file_obj_out = gzip.GzipFile('/home/joe/file.txt.gz', 'wb');
shutil.copyfileobj(file_obj_in, file_obj_out)
file_obj_out.close()

Best regards.

[gpolo]

Hello,

(some comments)

What about using gzip.open instead of GzipFile ? It is just a shorthand,
but I prefer it (just my opinion). Also, remove those semicolons.

At the second example you called close on the string object, I guess you
intended to do file_obj.close()

In the third example you used "file", please change that to "open". In
this sample example, you don't need to use shutil. I suggest changing it to:

import gzip
f_in = open('/home/joe/file.txt', 'rb')
f_out = gzip.open('/home/joe/file.txt.gz', 'wb');
f_out.writelines(f_in)
file_obj_out.close()
f_out.close()

Finally, consider doing these changes against Doc/library/gzip.rst and
sending the diff

[madarche]

Thanks Guilherme (I hope Guilherme is your first name) for your very
constructive answer. I'll do exactly as you suggest.

Regards

[madarche]

Here is the diff of the suggested modifications, which include Guilherme
remarks.

This is the kind of doc I would have like to read when I needed it.

Regards.

[gpolo]

If I could I would commit it, but you have my support on this one
nevertheless ;)

[birkenfeld]

Committed patch in r61999. Thanks!

[FrostyX]

Hello, I think the example code snippets are awesome and no doubts, they helped me a lot.

The only problem is that they are not idiomatic. They look like C more than Python.

I suggest following patch

[ned-deily]

Jakub, thanks for your suggested changes. But this issue was closed and the documentation updated many years ago. Please open a new issue with your suggested changes, otherwise they will likely be forgotten and ignored.