12.5 tarfile -- Read and write tar archive files

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:

reads and writes gzip and bzip2 compressed archives.
creates POSIX 1003.1-1990 compliant or GNU tar compatible archives.
reads GNU tar extensions longname, longlink and sparse.
stores pathnames of unlimited length using GNU tar extensions.
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.

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.