12.5 tarfile -- Read and write tar archive files

New in version 2.3.

The tarfile module makes it possible to read and create tar archives. Some facts and figures:

open( [name[, mode [, fileobj[, bufsize]]]])
Return a TarFile object for the pathname name. For detailed information on TarFile objects, see TarFile Objects (section 12.5.1).

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.

Note that 'a:gz' or 'a:bz2' is not possible. If mode is not suitable to open a certain (compressed) file for reading, ReadError is raised. Use mode 'r' to avoid this. If a compression method is not supported, CompressionError is raised.

If fileobj is specified, it is used as an alternative to a file object opened for name.

For special purposes, there is a second format for mode: 'filemode|[compression]'. open() will return a 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 read() or write() method (depending on the mode). bufsize specifies the blocksize and defaults to 20 * 512 bytes. Use this variant in combination with e.g. sys.stdin, a socket file object or a tape device. However, such a TarFile object is limited in that it does not allow to be accessed randomly, see ``Examples'' (section 12.5.3). 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.
'r|bz2' Open a bzip2 compressed stream for reading.
'w|' Open an uncompressed stream for writing.
'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 open() instead. See ``TarFile Objects'' (section 12.5.1).

is_tarfile( name)
Return True if name is a tar archive file, that the tarfile module can read.

class TarFileCompat( filename[, mode[, compression]])
Class for limited access to tar archives with a zipfile-like interface. Please consult the documentation of the zipfile module for more details. compression must be one of the following constants:
TAR_PLAIN
Constant for an uncompressed tar archive.
TAR_GZIPPED
Constant for a gzip compressed tar archive.

exception TarError
Base class for all tarfile exceptions.

exception ReadError
Is raised when a tar archive is opened, that either cannot be handled by the tarfile module or is somehow invalid.

exception CompressionError
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 TarFile objects.

exception ExtractError
Is raised for non-fatal errors when using extract(), but only if TarFile.errorlevel == 2.

See Also:

Module zipfile:
Documentation of the zipfile standard module.

GNU tar manual, Basic Tar Format
Documentation for tar archive files, including GNU tar extensions.



Subsections
See About this document... for information on suggesting changes.