Python Library Reference

Previous: 7.18.3 ZipInfo Objects Up: 7. Optional Operating System Next: 7.19.1 TarFile Objects

---

7.19 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 7.19.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'	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() resp. write() method. 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 7.19.3). The currently possible modes:

mode	action
'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 7.19.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 zipfile 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.

---

Python Library Reference

Previous: 7.18.3 ZipInfo Objects Up: 7. Optional Operating System Next: 7.19.1 TarFile Objects

---

Release 2.3.3, documentation updated on December 19, 2003.