# 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`.

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.