classification
Title: Improvement suggestions for the gzip module documentation
Type: Stage:
Components: Documentation Versions:
process
Status: closed Resolution: accepted
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: georg.brandl, gpolo, madarche
Priority: normal Keywords: patch

Created on 2008-03-18 20:29 by madarche, last changed 2008-03-28 08:07 by georg.brandl. This issue is now closed.

Files
File name Uploaded Description Edit
gzip.rst.diff madarche, 2008-03-27 16:16
Messages (6)
msg63981 - (view) Author: M.-A. DARCHE (madarche) Date: 2008-03-18 20:29
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.
msg64580 - (view) Author: Guilherme Polo (gpolo) * (Python committer) Date: 2008-03-27 11:22
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
msg64587 - (view) Author: M.-A. DARCHE (madarche) Date: 2008-03-27 12:59
Thanks Guilherme (I hope Guilherme is your first name) for your very
constructive answer. I'll do exactly as you  suggest.

Regards
msg64598 - (view) Author: M.-A. DARCHE (madarche) Date: 2008-03-27 16:16
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.
msg64601 - (view) Author: Guilherme Polo (gpolo) * (Python committer) Date: 2008-03-27 16:23
If I could I would commit it, but you have my support on this one
nevertheless ;)
msg64621 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-03-28 08:07
Committed patch in r61999. Thanks!
History
Date User Action Args
2008-03-28 08:07:04georg.brandlsetstatus: open -> closed
resolution: accepted
messages: + msg64621
2008-03-27 16:23:04gpolosetmessages: + msg64601
2008-03-27 16:16:53madarchesetfiles: + gzip.rst.diff
keywords: + patch
messages: + msg64598
2008-03-27 12:59:54madarchesetmessages: + msg64587
2008-03-27 11:22:30gpolosetnosy: + gpolo
messages: + msg64580
2008-03-18 20:29:42madarchecreate