← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/library/gzip.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/gzip.rst
 
1
:mod:`gzip` --- Support for :program:`gzip` files
 
2
=================================================
 
3
 
 
4
.. module:: gzip
 
5
   :synopsis: Interfaces for gzip compression and decompression using file objects.
 
6
 
 
7
This module provides a simple interface to compress and decompress files just
 
8
like the GNU programs :program:`gzip` and :program:`gunzip` would.
 
9
 
 
10
The data compression is provided by the :mod:``zlib`` module.
 
11
 
 
12
The :mod:`gzip` module provides the :class:`GzipFile` class which is modeled
 
13
after Python's File Object. The :class:`GzipFile` class reads and writes
 
14
:program:`gzip`\ -format files, automatically compressing or decompressing the
 
15
data so that it looks like an ordinary file object.
 
16
 
 
17
Note that additional file formats which can be decompressed by the
 
18
:program:`gzip` and :program:`gunzip` programs, such  as those produced by
 
19
:program:`compress` and :program:`pack`, are not supported by this module.
 
20
 
 
21
For other archive formats, see the :mod:`bz2`, :mod:`zipfile`, and
 
22
:mod:`tarfile` modules.
 
23
 
 
24
The module defines the following items:
 
25
 
 
26
 
 
27
.. class:: GzipFile([filename[, mode[, compresslevel[, fileobj]]]])
 
28
 
 
29
   Constructor for the :class:`GzipFile` class, which simulates most of the methods
 
30
   of a file object, with the exception of the :meth:`readinto` and
 
31
   :meth:`truncate` methods.  At least one of *fileobj* and *filename* must be
 
32
   given a non-trivial value.
 
33
 
 
34
   The new class instance is based on *fileobj*, which can be a regular file, a
 
35
   :class:`StringIO` object, or any other object which simulates a file.  It
 
36
   defaults to ``None``, in which case *filename* is opened to provide a file
 
37
   object.
 
38
 
 
39
   When *fileobj* is not ``None``, the *filename* argument is only used to be
 
40
   included in the :program:`gzip` file header, which may includes the original
 
41
   filename of the uncompressed file.  It defaults to the filename of *fileobj*, if
 
42
   discernible; otherwise, it defaults to the empty string, and in this case the
 
43
   original filename is not included in the header.
 
44
 
 
45
   The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, ``'w'``,
 
46
   or ``'wb'``, depending on whether the file will be read or written.  The default
 
47
   is the mode of *fileobj* if discernible; otherwise, the default is ``'rb'``. If
 
48
   not given, the 'b' flag will be added to the mode to ensure the file is opened
 
49
   in binary mode for cross-platform portability.
 
50
 
 
51
   The *compresslevel* argument is an integer from ``1`` to ``9`` controlling the
 
52
   level of compression; ``1`` is fastest and produces the least compression, and
 
53
   ``9`` is slowest and produces the most compression.  The default is ``9``.
 
54
 
 
55
   Calling a :class:`GzipFile` object's :meth:`close` method does not close
 
56
   *fileobj*, since you might wish to append more material after the compressed
 
57
   data.  This also allows you to pass a :class:`StringIO` object opened for
 
58
   writing as *fileobj*, and retrieve the resulting memory buffer using the
 
59
   :class:`StringIO` object's :meth:`getvalue` method.
 
60
 
 
61
 
 
62
.. function:: open(filename[, mode[, compresslevel]])
 
63
 
 
64
   This is a shorthand for ``GzipFile(filename,`` ``mode,`` ``compresslevel)``.
 
65
   The *filename* argument is required; *mode* defaults to ``'rb'`` and
 
66
   *compresslevel* defaults to ``9``.
 
67
 
 
68
 
 
69
.. _gzip-usage-examples:
 
70
 
 
71
Examples of usage
 
72
-----------------
 
73
 
 
74
Example of how to read a compressed file::
 
75
 
 
76
   import gzip
 
77
   f = gzip.open('/home/joe/file.txt.gz', 'rb')
 
78
   file_content = f.read()
 
79
   f.close()
 
80
 
 
81
Example of how to create a compressed GZIP file::
 
82
 
 
83
   import gzip
 
84
   content = "Lots of content here"
 
85
   f = gzip.open('/home/joe/file.txt.gz', 'wb')
 
86
   f.write(content)
 
87
   f.close()
 
88
 
 
89
Example of how to GZIP compress an existing file::
 
90
 
 
91
   import gzip
 
92
   f_in = open('/home/joe/file.txt', 'rb')
 
93
   f_out = gzip.open('/home/joe/file.txt.gz', 'wb')
 
94
   f_out.writelines(f_in)
 
95
   f_out.close()
 
96
   f_in.close()
 
97
 
 
98
 
 
99
.. seealso::
 
100
 
 
101
   Module :mod:`zlib`
 
102
      The basic data compression module needed to support the :program:`gzip` file
 
103
      format.
 
104