Merged revisions 61981,61984-61987,61992-61993,61997-62000 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r61981 | amaury.forgeotdarc | 2008-03-28 01:21:34 +0100 (Fri, 28 Mar 2008) | 2 lines

  test_future3.py is a regular test file, and should be part of the test suite
........
  r61984 | jeffrey.yasskin | 2008-03-28 05:11:18 +0100 (Fri, 28 Mar 2008) | 6 lines

  Kill a race in test_threading in which the exception info in a thread finishing
  up after it was joined had a traceback pointing to that thread's (deleted)
  target attribute, while the test was trying to check that the target was
  destroyed. Big thanks to Antoine Pitrou for diagnosing the race and pointing
  out sys.exc_clear() to kill the exception early. This fixes issue 2496.
........
  r61985 | neal.norwitz | 2008-03-28 05:41:34 +0100 (Fri, 28 Mar 2008) | 1 line

  Allow use of other ports so the test can pass if 9091 is in use
........
  r61986 | jeffrey.yasskin | 2008-03-28 05:53:10 +0100 (Fri, 28 Mar 2008) | 2 lines

  Print more information the next time test_socket throws the wrong exception.
........
  r61987 | neal.norwitz | 2008-03-28 05:58:51 +0100 (Fri, 28 Mar 2008) | 5 lines

  Revert r61969 which added casts to Py_CHARMASK to avoid compiler warnings.
  Rather than sprinkle casts throughout the code, change Py_CHARMASK to
  always cast it's result to an unsigned char.  This should ensure we
  do the right thing when accessing an array with the result.
........
  r61992 | neal.norwitz | 2008-03-28 06:34:59 +0100 (Fri, 28 Mar 2008) | 2 lines

  Fix compiler warning about finite() missing on Solaris.
........
  r61993 | neal.norwitz | 2008-03-28 07:34:03 +0100 (Fri, 28 Mar 2008) | 11 lines

  Bug 1503: Get the test to pass on OSX.  This should make the test more
  reliable, but I'm not convinced it is the right solution.  We need
  to determine if this causes the test to hang on any platforms or do
  other bad things.

  Even if it gets the test to pass reliably, it might be that we want
  to fix this in socket.  The socket returned from accept() is different
  on different platforms (inheriting attributes or not) and we might
  want to ensure that the attributes (at least blocking) is the same
  across all platforms.
........
  r61997 | neal.norwitz | 2008-03-28 08:36:31 +0100 (Fri, 28 Mar 2008) | 1 line

  Name the main method correctly so the test is run
........
  r61998 | gregory.p.smith | 2008-03-28 09:00:44 +0100 (Fri, 28 Mar 2008) | 7 lines

  This patch moves some tests from test_urllib2_net to test_urllib2_localnet.
  The moved tests use a local server rather than going out to external servers.

  Accepts patch from issue2429.

  Contributed by Jerry Seutter & Michael Foord (fuzzyman) at PyCon 2008.
........
  r61999 | georg.brandl | 2008-03-28 09:06:56 +0100 (Fri, 28 Mar 2008) | 2 lines

  #2406: add examples to gzip docs.
........
  r62000 | gregory.p.smith | 2008-03-28 09:32:09 +0100 (Fri, 28 Mar 2008) | 4 lines

  Accept patch issue2426 by Paul Kippes (kippesp).

  Adds sqlite3.Connection.iterdump to allow dumping of databases.
........

1 files changed, 41 insertions, 8 deletions

diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
index d298f88..86be3cd 100644
--- a/Doc/library/gzip.rst
+++ b/Doc/library/gzip.rst
@@ -1,19 +1,22 @@
-
 :mod:`gzip` --- Support for :program:`gzip` files
 =================================================
 
 .. module:: gzip
    :synopsis: Interfaces for gzip compression and decompression using file objects.
 
+This module provides a simple interface to compress and decompress files just
+like the GNU programs :program:`gzip` and :program:`gunzip` would.
+
+The data compression is provided by the :mod:``zlib`` module.
 
-The data compression provided by the ``zlib`` module is compatible with that
-used by the GNU compression program :program:`gzip`. Accordingly, the
-:mod:`gzip` module provides the :class:`GzipFile` class to read and write
+The :mod:`gzip` module provides the :class:`GzipFile` class which is modeled
+after Python's File Object. The :class:`GzipFile` class reads and writes
 :program:`gzip`\ -format files, automatically compressing or decompressing the
-data so it looks like an ordinary file object.  Note that additional file
-formats which can be decompressed by the :program:`gzip` and :program:`gunzip`
-programs, such  as those produced by :program:`compress` and :program:`pack`,
-are not supported by this module.
+data so that it looks like an ordinary file object.
+
+Note that additional file formats which can be decompressed by the
+:program:`gzip` and :program:`gunzip` programs, such  as those produced by
+: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.
@@ -63,6 +66,36 @@ The module defines the following items:
    *compresslevel* defaults to ``9``.
 
 
+.. _gzip-usage-examples:
+
+Examples of usage
+-----------------
+
+Example of how to read a compressed file::
+
+   import gzip
+   f = gzip.open('/home/joe/file.txt.gz', 'rb')
+   file_content = f.read()
+   f.close()
+
+Example of how to create a compressed GZIP file::
+
+   import gzip
+   content = "Lots of content here"
+   f = gzip.open('/home/joe/file.txt.gz', 'wb')
+   f.write(content)
+   f.close()
+
+Example of how to GZIP compress an existing file::
+
+   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)
+   f_out.close()
+   f_in.close()
+
+
 .. seealso::
 
    Module :mod:`zlib`