Changeset 391 for python/trunk/Doc/library/gzip.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/gzip.rst (modified) (7 diffs)

python/trunk/Doc/library/gzip.rst

@@ -4 +4 @@
 .. module:: gzip
    :synopsis: Interfaces for gzip compression and decompression using file objects.
+
+**Source code:** :source:`Lib/gzip.py`
+
+--------------
 
 This module provides a simple interface to compress and decompress files just
@@ -19 +23 @@
 :program:`compress` and :program:`pack`, are not supported by this module.
 
-For other archive formats, see the :mod:`bz2`, :mod:`zipfile`, and
-:mod:`tarfile` modules.
-
 The module defines the following items:
 
 
-.. class:: GzipFile([filename[, mode[, compresslevel[, fileobj]]]])
+.. class:: GzipFile([filename[, mode[, compresslevel[, fileobj[, mtime]]]]])
 
    Constructor for the :class:`GzipFile` class, which simulates most of the methods
@@ -33 +34 @@
 
    The new class instance is based on *fileobj*, which can be a regular file, a
-   :class:`StringIO` object, or any other object which simulates a file.  It
+   :class:`~StringIO.StringIO` object, or any other object which simulates a file.  It
    defaults to ``None``, in which case *filename* is opened to provide a file
    object.
 
    When *fileobj* is not ``None``, the *filename* argument is only used to be
-   included in the :program:`gzip` file header, which may includes the original
+   included in the :program:`gzip` file header, which may include the original
    filename of the uncompressed file.  It defaults to the filename of *fileobj*, if
    discernible; otherwise, it defaults to the empty string, and in this case the
@@ -49 +50 @@
    in binary mode for cross-platform portability.
 
-   The *compresslevel* argument is an integer from ``1`` to ``9`` controlling the
-   level of compression; ``1`` is fastest and produces the least compression, and
-   ``9`` is slowest and produces the most compression.  The default is ``9``.
+   The *compresslevel* argument is an integer from ``0`` to ``9`` controlling
+   the level of compression; ``1`` is fastest and produces the least
+   compression, and ``9`` is slowest and produces the most compression. ``0``
+   is no compression. The default is ``9``.
+
+   The *mtime* argument is an optional numeric timestamp to be written to
+   the stream when compressing.  All :program:`gzip` compressed streams are
+   required to contain a timestamp.  If omitted or ``None``, the current
+   time is used.  This module ignores the timestamp when decompressing;
+   however, some programs, such as :program:`gunzip`\ , make use of it.
+   The format of the timestamp is the same as that of the return value of
+   ``time.time()`` and of the ``st_mtime`` attribute of the object returned
+   by ``os.stat()``.
 
    Calling a :class:`GzipFile` object's :meth:`close` method does not close
    *fileobj*, since you might wish to append more material after the compressed
-   data.  This also allows you to pass a :class:`StringIO` object opened for
+   data.  This also allows you to pass a :class:`~StringIO.StringIO` object opened for
    writing as *fileobj*, and retrieve the resulting memory buffer using the
-   :class:`StringIO` object's :meth:`getvalue` method.
+   :class:`StringIO` object's :meth:`~StringIO.StringIO.getvalue` method.
+
+   :class:`GzipFile` supports iteration and the :keyword:`with` statement.
+
+   .. versionchanged:: 2.7
+      Support for the :keyword:`with` statement was added.
+
+   .. versionchanged:: 2.7
+      Support for zero-padded files was added.
+
+   .. versionadded:: 2.7
+      The *mtime* argument.
 
 
@@ -75 +97 @@
 
    import gzip
-   f = gzip.open('/home/joe/file.txt.gz', 'rb')
+   f = gzip.open('file.txt.gz', 'rb')
    file_content = f.read()
    f.close()
@@ -83 +105 @@
    import gzip
    content = "Lots of content here"
-   f = gzip.open('/home/joe/file.txt.gz', 'wb')
+   f = gzip.open('file.txt.gz', 'wb')
    f.write(content)
    f.close()
@@ -90 +112 @@
 
    import gzip
-   f_in = open('/home/joe/file.txt', 'rb')
-   f_out = gzip.open('/home/joe/file.txt.gz', 'wb')
+   f_in = open('file.txt', 'rb')
+   f_out = gzip.open('file.txt.gz', 'wb')
    f_out.writelines(f_in)
    f_out.close()