--- rest25/library/tarfile.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/tarfile.rst	2009-04-05 05:02:09.000000000 +0900
@@ -1,93 +1,99 @@
+.. _tarfile-mod:
 
 :mod:`tarfile` --- Read and write tar archive files
 ===================================================
 
 .. module:: tarfile
    :synopsis: Read and write tar-format archive files.
 
 
 .. versionadded:: 2.3
 
 .. moduleauthor:: Lars Gustabel <lars@gustaebel.de>
 .. sectionauthor:: Lars Gustabel <lars@gustaebel.de>
 
 
-The :mod:`tarfile` module makes it possible to read and create tar archives.
+The :mod:`tarfile` module makes it possible to read and write tar
+archives, including those using gzip or bz2 compression.
+(:file:`.zip` files can be read and written using the :mod:`zipfile` module.)
+
 Some facts and figures:
 
-* reads and writes :mod:`gzip` and :mod:`bzip2` compressed archives.
+* reads and writes :mod:`gzip` and :mod:`bz2` compressed archives.
+
+* read/write support for the POSIX.1-1988 (ustar) format.
 
-* creates POSIX 1003.1-1990 compliant or GNU tar compatible archives.
+* read/write support for the GNU tar format including *longname* and *longlink*
+  extensions, read-only support for the *sparse* extension.
 
-* reads GNU tar extensions *longname*, *longlink* and *sparse*.
+* read/write support for the POSIX.1-2001 (pax) format.
 
-* stores pathnames of unlimited length using GNU tar extensions.
+  .. versionadded:: 2.6
 
 * handles directories, regular files, hardlinks, symbolic links, fifos,
   character devices and block devices and is able to acquire and restore file
   information like timestamp, access permissions and owner.
 
-* can handle tape devices.
-
 
-.. function:: open([name[, mode [, fileobj[, bufsize]]]])
+.. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, \*\*kwargs)
 
    Return a :class:`TarFile` object for the pathname *name*. For detailed
-   information on :class:`TarFile` objects, see TarFile Objects (section
-   :ref:`tarfile-objects`).
+   information on :class:`TarFile` objects and the keyword arguments that are
+   allowed, see :ref:`tarfile-objects`.
 
    *mode* has to be a string of the form ``'filemode[:compression]'``, it defaults
    to ``'r'``. Here is a full list of mode combinations:
 
-   +------------------+------------------------------------------+
-   | mode             | action                                   |
-   +==================+==========================================+
-   | ``'r' or 'r:*'`` | Open for reading with transparent        |
-   |                  | compression (recommended).               |
-   +------------------+------------------------------------------+
-   | ``'r:'``         | Open for reading exclusively without     |
-   |                  | compression.                             |
-   +------------------+------------------------------------------+
-   | ``'r:gz'``       | Open for reading with gzip compression.  |
-   +------------------+------------------------------------------+
-   | ``'r:bz2'``      | Open for reading with bzip2 compression. |
-   +------------------+------------------------------------------+
-   | ``'a' or 'a:'``  | Open for appending with no compression.  |
-   +------------------+------------------------------------------+
-   | ``'w' or 'w:'``  | Open for uncompressed writing.           |
-   +------------------+------------------------------------------+
-   | ``'w:gz'``       | Open for gzip compressed writing.        |
-   +------------------+------------------------------------------+
-   | ``'w:bz2'``      | Open for bzip2 compressed writing.       |
-   +------------------+------------------------------------------+
+   +------------------+---------------------------------------------+
+   | mode             | action                                      |
+   +==================+=============================================+
+   | ``'r' or 'r:*'`` | Open for reading with transparent           |
+   |                  | compression (recommended).                  |
+   +------------------+---------------------------------------------+
+   | ``'r:'``         | Open for reading exclusively without        |
+   |                  | compression.                                |
+   +------------------+---------------------------------------------+
+   | ``'r:gz'``       | Open for reading with gzip compression.     |
+   +------------------+---------------------------------------------+
+   | ``'r:bz2'``      | Open for reading with bzip2 compression.    |
+   +------------------+---------------------------------------------+
+   | ``'a' or 'a:'``  | Open for appending with no compression. The |
+   |                  | file is created if it does not exist.       |
+   +------------------+---------------------------------------------+
+   | ``'w' or 'w:'``  | Open for uncompressed writing.              |
+   +------------------+---------------------------------------------+
+   | ``'w:gz'``       | Open for gzip compressed writing.           |
+   +------------------+---------------------------------------------+
+   | ``'w:bz2'``      | Open for bzip2 compressed writing.          |
+   +------------------+---------------------------------------------+
 
    Note that ``'a:gz'`` or ``'a:bz2'`` is not possible. If *mode* is not suitable
    to open a certain (compressed) file for reading, :exc:`ReadError` is raised. Use
    *mode* ``'r'`` to avoid this.  If a compression method is not supported,
    :exc:`CompressionError` is raised.
 
    If *fileobj* is specified, it is used as an alternative to a file object opened
-   for *name*.
+   for *name*. It is supposed to be at position 0.
 
    For special purposes, there is a second format for *mode*:
-   ``'filemode|[compression]'``.  :func:`open` will return a :class:`TarFile`
-   object that processes its data as a stream of blocks.  No random seeking will be
-   done on the file. If given, *fileobj* may be any object that has a :meth:`read`
+   ``'filemode|[compression]'``.  :func:`tarfile.open` will return a :class:`TarFile`
+   object that processes its data as a stream of blocks.  No random seeking will
+   be done on the file. If given, *fileobj* may be any object that has a
-   or :meth:`write` method (depending on the *mode*). *bufsize* specifies the
-   blocksize and defaults to ``20 * 512`` bytes. Use this variant in combination
+   :meth:`read` or :meth:`write` method (depending on the *mode*). *bufsize*
+   specifies the blocksize and defaults to ``20 * 512`` bytes. Use this variant
-   with e.g. ``sys.stdin``, a socket file object or a tape device. However, such a
-   :class:`TarFile` object is limited in that it does not allow to be accessed
+   in combination with e.g. ``sys.stdin``, a socket file object or a tape
+   device. However, such a :class:`TarFile` object is limited in that it does
-   randomly, see "Examples" (section :ref:`tar-examples`).  The currently possible
-   modes:
+   not allow to be accessed randomly, see :ref:`tar-examples`.  The currently
+   possible modes:
 
    +-------------+--------------------------------------------+
    | Mode        | Action                                     |
    +=============+============================================+
    | ``'r|*'``   | Open a *stream* of tar blocks for reading  |
    |             | with transparent compression.              |
    +-------------+--------------------------------------------+
    | ``'r|'``    | Open a *stream* of uncompressed tar blocks |
    |             | for reading.                               |
    +-------------+--------------------------------------------+
    | ``'r|gz'``  | Open a gzip compressed *stream* for        |
    |             | reading.                                   |
@@ -99,51 +105,54 @@
    +-------------+--------------------------------------------+
    | ``'w|gz'``  | Open an gzip compressed *stream* for       |
    |             | writing.                                   |
    +-------------+--------------------------------------------+
    | ``'w|bz2'`` | Open an bzip2 compressed *stream* for      |
    |             | writing.                                   |
    +-------------+--------------------------------------------+
 
 
 .. class:: TarFile
 
    Class for reading and writing tar archives. Do not use this class directly,
-   better use :func:`open` instead. See "TarFile Objects" (section
-   :ref:`tarfile-objects`).
+   better use :func:`tarfile.open` instead. See :ref:`tarfile-objects`.
 
 
 .. function:: is_tarfile(name)
 
    Return :const:`True` if *name* is a tar archive file, that the :mod:`tarfile`
    module can read.
 
 
-.. class:: TarFileCompat(filename[, mode[, compression]])
+.. class:: TarFileCompat(filename, mode='r', compression=TAR_PLAIN)
 
    Class for limited access to tar archives with a :mod:`zipfile`\ -like interface.
    Please consult the documentation of the :mod:`zipfile` module for more details.
    *compression* must be one of the following constants:
 
 
    .. data:: TAR_PLAIN
 
       Constant for an uncompressed tar archive.
 
 
    .. data:: TAR_GZIPPED
 
       Constant for a :mod:`gzip` compressed tar archive.
 
 
+   .. deprecated:: 2.6
+      The :class:`TarFileCompat` class has been deprecated for removal in Python 3.0.
+
+
 .. exception:: TarError
 
    Base class for all :mod:`tarfile` exceptions.
 
 
 .. exception:: ReadError
 
    Is raised when a tar archive is opened, that either cannot be handled by the
    :mod:`tarfile` module or is somehow invalid.
 
 
 .. exception:: CompressionError
@@ -151,71 +160,154 @@
    Is raised when a compression method is not supported or when the data cannot be
    decoded properly.
 
 
 .. exception:: StreamError
 
    Is raised for the limitations that are typical for stream-like :class:`TarFile`
    objects.
 
 
 .. exception:: ExtractError
 
-   Is raised for *non-fatal* errors when using :meth:`extract`, but only if
+   Is raised for *non-fatal* errors when using :meth:`TarFile.extract`, but only if
    :attr:`TarFile.errorlevel`\ ``== 2``.
 
 
+.. exception:: HeaderError
+
+   Is raised by :meth:`TarInfo.frombuf` if the buffer it gets is invalid.
+
+   .. versionadded:: 2.6
+
+
+Each of the following constants defines a tar archive format that the
+:mod:`tarfile` module is able to create. See section :ref:`tar-formats` for
+details.
+
+
+.. data:: USTAR_FORMAT
+
+   POSIX.1-1988 (ustar) format.
+
+
+.. data:: GNU_FORMAT
+
+   GNU tar format.
+
+
+.. data:: PAX_FORMAT
+
+   POSIX.1-2001 (pax) format.
+
+
+.. data:: DEFAULT_FORMAT
+
+   The default format for creating archives. This is currently :const:`GNU_FORMAT`.
+
+
+The following variables are available on module level:
+
+
+.. data:: ENCODING
+
+   The default character encoding i.e. the value from either
+   :func:`sys.getfilesystemencoding` or :func:`sys.getdefaultencoding`.
+
+
 .. seealso::
 
    Module :mod:`zipfile`
       Documentation of the :mod:`zipfile` standard module.
 
-   `GNU tar manual, Basic Tar Format <http://www.gnu.org/software/tar/manual/html_node/tar_134.html#SEC134>`_
+   `GNU tar manual, Basic Tar Format <http://www.gnu.org/software/tar/manual/html_node/Standard.html>`_
       Documentation for tar archive files, including GNU tar extensions.
 
-.. % -----------------
-.. % TarFile Objects
-.. % -----------------
-
 
 .. _tarfile-objects:
 
 TarFile Objects
 ---------------
 
 The :class:`TarFile` object provides an interface to a tar archive. A tar
 archive is a sequence of blocks. An archive member (a stored file) is made up of
-a header block followed by data blocks. It is possible, to store a file in a tar
+a header block followed by data blocks. It is possible to store a file in a tar
 archive several times. Each archive member is represented by a :class:`TarInfo`
-object, see TarInfo Objects (section :ref:`tarinfo-objects`) for details.
+object, see :ref:`tarinfo-objects` for details.
+
+
-.. class:: TarFile([name [, mode[, fileobj]]])
+.. class:: TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors=None, pax_headers=None, debug=0, errorlevel=0)
 
+   All following arguments are optional and can be accessed as instance attributes
+   as well.

-   Open an *(uncompressed)* tar archive *name*. *mode* is either ``'r'`` to read
-   from an existing archive, ``'a'`` to append data to an existing file or ``'w'``
-   to create a new file overwriting an existing one. *mode* defaults to ``'r'``.
 
+   *name* is the pathname of the archive. It can be omitted if *fileobj* is given.
+   In this case, the file object's :attr:`name` attribute is used if it exists.
 
+   *mode* is either ``'r'`` to read from an existing archive, ``'a'`` to append
+   data to an existing file or ``'w'`` to create a new file overwriting an existing
+   one.
 
    If *fileobj* is given, it is used for reading or writing data. If it can be
-   determined, *mode* is overridden by *fileobj*'s mode.
+   determined, *mode* is overridden by *fileobj*'s mode. *fileobj* will be used
+   from position 0.
 
    .. note::
 
       *fileobj* is not closed, when :class:`TarFile` is closed.
 
+   *format* controls the archive format. It must be one of the constants
+   :const:`USTAR_FORMAT`, :const:`GNU_FORMAT` or :const:`PAX_FORMAT` that are
+   defined at module level.
+
+   .. versionadded:: 2.6
+
+   The *tarinfo* argument can be used to replace the default :class:`TarInfo` class
+   with a different one.
+
+   .. versionadded:: 2.6
+
+   If *dereference* is :const:`False`, add symbolic and hard links to the archive. If it
+   is :const:`True`, add the content of the target files to the archive. This has no
+   effect on systems that do not support symbolic links.
+
+   If *ignore_zeros* is :const:`False`, treat an empty block as the end of the archive.
+   If it is :const:`True`, skip empty (and invalid) blocks and try to get as many members
+   as possible. This is only useful for reading concatenated or damaged archives.
+
+   *debug* can be set from ``0`` (no debug messages) up to ``3`` (all debug
+   messages). The messages are written to ``sys.stderr``.
+
+   If *errorlevel* is ``0``, all errors are ignored when using :meth:`TarFile.extract`.
+   Nevertheless, they appear as error messages in the debug output, when debugging
+   is enabled.  If ``1``, all *fatal* errors are raised as :exc:`OSError` or
+   :exc:`IOError` exceptions. If ``2``, all *non-fatal* errors are raised as
+   :exc:`TarError` exceptions as well.
+
+   The *encoding* and *errors* arguments control the way strings are converted to
+   unicode objects and vice versa. The default settings will work for most users.
+   See section :ref:`tar-unicode` for in-depth information.
+
+   .. versionadded:: 2.6
+
+   The *pax_headers* argument is an optional dictionary of unicode strings which
+   will be added as a pax global header if *format* is :const:`PAX_FORMAT`.
+
+   .. versionadded:: 2.6
+
 
 .. method:: TarFile.open(...)
 
-   Alternative constructor. The :func:`open` function on module level is actually a
-   shortcut to this classmethod. See section :ref:`module-tarfile` for details.
+   Alternative constructor. The :func:`tarfile.open` function is actually a
+   shortcut to this classmethod.
 
 
 .. method:: TarFile.getmember(name)
 
    Return a :class:`TarInfo` object for member *name*. If *name* can not be found
    in the archive, :exc:`KeyError` is raised.
 
    .. note::
 
       If a member occurs more than once in the archive, its last occurrence is assumed
       to be the most up-to-date version.
 
@@ -233,181 +325,180 @@
 
 
 .. method:: TarFile.list(verbose=True)
 
    Print a table of contents to ``sys.stdout``. If *verbose* is :const:`False`,
    only the names of the members are printed. If it is :const:`True`, output
    similar to that of :program:`ls -l` is produced.
 
 
 .. method:: TarFile.next()
 
    Return the next member of the archive as a :class:`TarInfo` object, when
-   :class:`TarFile` is opened for reading. Return ``None`` if there is no more
+   :class:`TarFile` is opened for reading. Return :const:`None` if there is no more
    available.
 
 
-.. method:: TarFile.extractall([path[, members]])
+.. method:: TarFile.extractall(path=".", members=None)
 
    Extract all members from the archive to the current working directory or
    directory *path*. If optional *members* is given, it must be a subset of the
-   list returned by :meth:`getmembers`. Directory informations like owner,
+   list returned by :meth:`getmembers`. Directory information like owner,
    modification time and permissions are set after all members have been extracted.
    This is done to work around two problems: A directory's modification time is
    reset each time a file is created in it. And, if a directory's permissions do
    not allow writing, extracting files to it will fail.
 
+   .. warning::
+
+      Never extract archives from untrusted sources without prior inspection.
+      It is possible that files are created outside of *path*, e.g. members
+      that have absolute filenames starting with ``"/"`` or filenames with two
+      dots ``".."``.
+
    .. versionadded:: 2.5
 
 
-.. method:: TarFile.extract(member[, path])
+.. method:: TarFile.extract(member, path="")
 
    Extract a member from the archive to the current working directory, using its
    full name. Its file information is extracted as accurately as possible. *member*
    may be a filename or a :class:`TarInfo` object. You can specify a different
    directory using *path*.
 
    .. note::
 
-      Because the :meth:`extract` method allows random access to a tar archive there
-      are some issues you must take care of yourself. See the description for
-      :meth:`extractall` above.
+      The :meth:`extract` method does not take care of several extraction issues.
+      In most cases you should consider using the :meth:`extractall` method.
+
+   .. warning::
+
+      See the warning for :meth:`extractall`.
 
 
 .. method:: TarFile.extractfile(member)
 
    Extract a member from the archive as a file object. *member* may be a filename
    or a :class:`TarInfo` object. If *member* is a regular file, a file-like object
    is returned. If *member* is a link, a file-like object is constructed from the
-   link's target. If *member* is none of the above, ``None`` is returned.
+   link's target. If *member* is none of the above, :const:`None` is returned.
 
    .. note::
 
       The file-like object is read-only and provides the following methods:
       :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`seek`, :meth:`tell`.
 
 
-.. method:: TarFile.add(name[, arcname[, recursive]])
+.. method:: TarFile.add(name, arcname=None, recursive=True, exclude=None)
 
    Add the file *name* to the archive. *name* may be any type of file (directory,
    fifo, symbolic link, etc.). If given, *arcname* specifies an alternative name
    for the file in the archive. Directories are added recursively by default. This
-   can be avoided by setting *recursive* to :const:`False`; the default is
-   :const:`True`.
+   can be avoided by setting *recursive* to :const:`False`. If *exclude* is given
+   it must be a function that takes one filename argument and returns a boolean
+   value. Depending on this value the respective file is either excluded
+   (:const:`True`) or added (:const:`False`).
+
+   .. versionchanged:: 2.6
+      Added the *exclude* parameter.
 
 
-.. method:: TarFile.addfile(tarinfo[, fileobj])
+.. method:: TarFile.addfile(tarinfo, fileobj=None)
 
    Add the :class:`TarInfo` object *tarinfo* to the archive. If *fileobj* is given,
    ``tarinfo.size`` bytes are read from it and added to the archive.  You can
    create :class:`TarInfo` objects using :meth:`gettarinfo`.
 
    .. note::
 
       On Windows platforms, *fileobj* should always be opened with mode ``'rb'`` to
       avoid irritation about the file size.
 
 
-.. method:: TarFile.gettarinfo([name[, arcname[, fileobj]]])
+.. method:: TarFile.gettarinfo(name=None, arcname=None, fileobj=None)
 
    Create a :class:`TarInfo` object for either the file *name* or the file object
    *fileobj* (using :func:`os.fstat` on its file descriptor).  You can modify some
    of the :class:`TarInfo`'s attributes before you add it using :meth:`addfile`.
    If given, *arcname* specifies an alternative name for the file in the archive.
 
 
 .. method:: TarFile.close()
 
    Close the :class:`TarFile`. In write mode, two finishing zero blocks are
    appended to the archive.
 
 
 .. attribute:: TarFile.posix
 
-   If true, create a POSIX 1003.1-1990 compliant archive. GNU extensions are not
-   used, because they are not part of the POSIX standard.  This limits the length
-   of filenames to at most 256, link names to 100 characters and the maximum file
-   size to 8 gigabytes. A :exc:`ValueError` is raised if a file exceeds this limit.
-   If false, create a GNU tar compatible archive.  It will not be POSIX compliant,
-   but can store files without any of the above restrictions.
+   Setting this to :const:`True` is equivalent to setting the :attr:`format`
+   attribute to :const:`USTAR_FORMAT`, :const:`False` is equivalent to
+   :const:`GNU_FORMAT`.
 
    .. versionchanged:: 2.4
       *posix* defaults to :const:`False`.
 
+   .. deprecated:: 2.6
+      Use the :attr:`format` attribute instead.
 
-.. attribute:: TarFile.dereference
-
-   If false, add symbolic and hard links to archive. If true, add the content of
-   the target files to the archive.  This has no effect on systems that do not
-   support symbolic links.
-
-
-.. attribute:: TarFile.ignore_zeros
 
-   If false, treat an empty block as the end of the archive. If true, skip empty
-   (and invalid) blocks and try to get as many members as possible. This is only
-   useful for concatenated or damaged archives.
+.. attribute:: TarFile.pax_headers
 
+   A dictionary containing key-value pairs of pax global headers.
 
-.. attribute:: TarFile.debug=0
-
-   To be set from ``0`` (no debug messages; the default) up to ``3`` (all debug
-   messages). The messages are written to ``sys.stderr``.
-
-
-.. attribute:: TarFile.errorlevel
-
-   If ``0`` (the default), all errors are ignored when using :meth:`extract`.
-   Nevertheless, they appear as error messages in the debug output, when debugging
-   is enabled.  If ``1``, all *fatal* errors are raised as :exc:`OSError` or
-   :exc:`IOError` exceptions.  If ``2``, all *non-fatal* errors are raised as
-   :exc:`TarError` exceptions as well.
-
-.. % -----------------
-.. % TarInfo Objects
-.. % -----------------
+   .. versionadded:: 2.6
 
 
 .. _tarinfo-objects:
 
 TarInfo Objects
 ---------------
 
 A :class:`TarInfo` object represents one member in a :class:`TarFile`. Aside
 from storing all required attributes of a file (like file type, size, time,
 permissions, owner etc.), it provides some useful methods to determine its type.
 It does *not* contain the file's data itself.
 
 :class:`TarInfo` objects are returned by :class:`TarFile`'s methods
 :meth:`getmember`, :meth:`getmembers` and :meth:`gettarinfo`.
 
 
-.. class:: TarInfo([name])
+.. class:: TarInfo(name="")
 
    Create a :class:`TarInfo` object.
 
 
-.. method:: TarInfo.frombuf()
+.. method:: TarInfo.frombuf(buf)
 
-   Create and return a :class:`TarInfo` object from a string buffer.
+   Create and return a :class:`TarInfo` object from string buffer *buf*.
 
+   .. versionadded:: 2.6
+      Raises :exc:`HeaderError` if the buffer is invalid..
 
+.. method:: TarInfo.fromtarfile(tarfile)
 
+   Read the next member from the :class:`TarFile` object *tarfile* and return it as
+   a :class:`TarInfo` object.
+
+   .. versionadded:: 2.6
+
+
-.. method:: TarInfo.tobuf(posix)
+.. method:: TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='strict')
 
-   Create a string buffer from a :class:`TarInfo` object. See :class:`TarFile`'s
-   :attr:`posix` attribute for information on the *posix* argument. It defaults to
-   :const:`False`.
-   .. versionadded:: 2.5
-      The *posix* parameter.
+
+   Create a string buffer from a :class:`TarInfo` object. For information on the
+   arguments see the constructor of the :class:`TarFile` class.
+
+   .. versionchanged:: 2.6
+      The arguments were added.
 
 A ``TarInfo`` object has the following public data attributes:
 
 
 .. attribute:: TarInfo.name
 
    Name of the archive member.
 
 
 .. attribute:: TarInfo.size
 
    Size in bytes.
@@ -448,24 +539,31 @@
    Group ID of the user who originally stored this member.
 
 
 .. attribute:: TarInfo.uname
 
    User name.
 
 
 .. attribute:: TarInfo.gname
 
    Group name.
 
+
+.. attribute:: TarInfo.pax_headers
+
+   A dictionary containing key-value pairs of an associated pax extended header.
+
+   .. versionadded:: 2.6
+
 A :class:`TarInfo` object also provides some convenient query methods:
 
 
 .. method:: TarInfo.isfile()
 
    Return :const:`True` if the :class:`Tarinfo` object is a regular file.
 
 
 .. method:: TarInfo.isreg()
 
    Same as :meth:`isfile`.
 
@@ -495,73 +593,143 @@
    Return :const:`True` if it is a block device.
 
 
 .. method:: TarInfo.isfifo()
 
    Return :const:`True` if it is a FIFO.
 
 
 .. method:: TarInfo.isdev()
 
    Return :const:`True` if it is one of character device, block device or FIFO.
 
-.. % ------------------------
-.. % Examples
-.. % ------------------------
-
 
 .. _tar-examples:
 
 Examples
 --------
 
 How to extract an entire tar archive to the current working directory::
 
    import tarfile
    tar = tarfile.open("sample.tar.gz")
    tar.extractall()
    tar.close()
 
+How to extract a subset of a tar archive with :meth:`TarFile.extractall` using
+a generator function instead of a list::
+
+   import os
+   import tarfile
+
+   def py_files(members):
+       for tarinfo in members:
+           if os.path.splitext(tarinfo.name)[1] == ".py":
+               yield tarinfo
+
+   tar = tarfile.open("sample.tar.gz")
+   tar.extractall(members=py_files(tar))
+   tar.close()
+
 How to create an uncompressed tar archive from a list of filenames::
 
    import tarfile
    tar = tarfile.open("sample.tar", "w")
    for name in ["foo", "bar", "quux"]:
        tar.add(name)
    tar.close()
 
 How to read a gzip compressed tar archive and display some member information::
 
    import tarfile
    tar = tarfile.open("sample.tar.gz", "r:gz")
    for tarinfo in tar:
        print tarinfo.name, "is", tarinfo.size, "bytes in size and is",
        if tarinfo.isreg():
            print "a regular file."
        elif tarinfo.isdir():
            print "a directory."
        else:
            print "something else."
    tar.close()
 
-How to create a tar archive with faked information::
 
-   import tarfile
-   tar = tarfile.open("sample.tar.gz", "w:gz")
-   for name in namelist:
-       tarinfo = tar.gettarinfo(name, "fakeproj-1.0/" + name)
-       tarinfo.uid = 123
-       tarinfo.gid = 456
-       tarinfo.uname = "johndoe"
-       tarinfo.gname = "fake"
-       tar.addfile(tarinfo, file(name))
-   tar.close()
+.. _tar-formats:
 
-The *only* way to extract an uncompressed tar stream from ``sys.stdin``::
+Supported tar formats
+---------------------
 
-   import sys
-   import tarfile
-   tar = tarfile.open(mode="r|", fileobj=sys.stdin)
-   for tarinfo in tar:
-       tar.extract(tarinfo)
-   tar.close()
+There are three tar formats that can be created with the :mod:`tarfile` module:
+
+* The POSIX.1-1988 ustar format (:const:`USTAR_FORMAT`). It supports filenames
+  up to a length of at best 256 characters and linknames up to 100 characters. The
+  maximum file size is 8 gigabytes. This is an old and limited but widely
+  supported format.
+
+* The GNU tar format (:const:`GNU_FORMAT`). It supports long filenames and
+  linknames, files bigger than 8 gigabytes and sparse files. It is the de facto
+  standard on GNU/Linux systems. :mod:`tarfile` fully supports the GNU tar
+  extensions for long names, sparse file support is read-only.
+
+* The POSIX.1-2001 pax format (:const:`PAX_FORMAT`). It is the most flexible
+  format with virtually no limits. It supports long filenames and linknames, large
+  files and stores pathnames in a portable way. However, not all tar
+  implementations today are able to handle pax archives properly.
+
+  The *pax* format is an extension to the existing *ustar* format. It uses extra
+  headers for information that cannot be stored otherwise. There are two flavours
+  of pax headers: Extended headers only affect the subsequent file header, global
+  headers are valid for the complete archive and affect all following files. All
+  the data in a pax header is encoded in *UTF-8* for portability reasons.
+
+There are some more variants of the tar format which can be read, but not
+created:
+
+* The ancient V7 format. This is the first tar format from Unix Seventh Edition,
+  storing only regular files and directories. Names must not be longer than 100
+  characters, there is no user/group name information. Some archives have
+  miscalculated header checksums in case of fields with non-ASCII characters.
+
+* The SunOS tar extended format. This format is a variant of the POSIX.1-2001
+  pax format, but is not compatible.
+
+.. _tar-unicode:
+
+Unicode issues
+--------------
+
+The tar format was originally conceived to make backups on tape drives with the
+main focus on preserving file system information. Nowadays tar archives are
+commonly used for file distribution and exchanging archives over networks. One
+problem of the original format (that all other formats are merely variants of)
+is that there is no concept of supporting different character encodings. For
+example, an ordinary tar archive created on a *UTF-8* system cannot be read
+correctly on a *Latin-1* system if it contains non-ASCII characters. Names (i.e.
+filenames, linknames, user/group names) containing these characters will appear
+damaged.  Unfortunately, there is no way to autodetect the encoding of an
+archive.
+
+The pax format was designed to solve this problem. It stores non-ASCII names
+using the universal character encoding *UTF-8*. When a pax archive is read,
+these *UTF-8* names are converted to the encoding of the local file system.
+
+The details of unicode conversion are controlled by the *encoding* and *errors*
+keyword arguments of the :class:`TarFile` class.
+
+The default value for *encoding* is the local character encoding. It is deduced
+from :func:`sys.getfilesystemencoding` and :func:`sys.getdefaultencoding`. In
+read mode, *encoding* is used exclusively to convert unicode names from a pax
+archive to strings in the local character encoding. In write mode, the use of
+*encoding* depends on the chosen archive format. In case of :const:`PAX_FORMAT`,
+input names that contain non-ASCII characters need to be decoded before being
+stored as *UTF-8* strings. The other formats do not make use of *encoding*
+unless unicode objects are used as input names. These are converted to 8-bit
+character strings before they are added to the archive.
+
+The *errors* argument defines how characters are treated that cannot be
+converted to or from *encoding*. Possible values are listed in section
+:ref:`codec-base-classes`. In read mode, there is an additional scheme
+``'utf-8'`` which means that bad characters are replaced by their *UTF-8*
+representation. This is the default scheme. In write mode the default value for
+*errors* is ``'strict'`` to ensure that name information is not altered
+unnoticed.
 
