.. _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 Gustäbel <lars@gustaebel.de>

.. sectionauthor:: Lars Gustäbel <lars@gustaebel.de>

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:`bz2` compressed archives.

* read/write support for the POSIX.1-1988 (ustar) format.

* read/write support for the GNU tar format including *longname* and *longlink*

  extensions, read-only support for the *sparse* extension.

* read/write support for the POSIX.1-2001 (pax) format.

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

.. 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 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. 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*. It is supposed to be at position 0.

   For special purposes, there is a second format for *mode*:

   ``'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

   :meth:`read` or :meth:`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 :class:`TarFile` object is limited in that it does

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

   +-------------+--------------------------------------------+

   | ``'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 :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='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

   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:`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/Standard.html>`_

      Documentation for tar archive files, including GNU tar extensions.

.. _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

archive several times. Each archive member is represented by a :class:`TarInfo`

object, see :ref:`tarinfo-objects` for details.

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

   *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. *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:`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.

.. method:: TarFile.getmembers()

   Return the members of the archive as a list of :class:`TarInfo` objects. The

   list has the same order as the members in the archive.

.. method:: TarFile.getnames()

   Return the members as a list of their names. It has the same order as the list

   returned by :meth:`getmembers`.

.. 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 :const:`None` if there is no more

   available.

.. 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 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="")

   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::

      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, :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=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`. 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=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=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

   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.pax_headers

   A dictionary containing key-value pairs of pax global headers.

   .. 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="")

   Create a :class:`TarInfo` object.

.. method:: TarInfo.frombuf(buf)

   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(format=DEFAULT_FORMAT, encoding=ENCODING, errors='strict')

   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.

.. attribute:: TarInfo.mtime

   Time of last modification.

.. attribute:: TarInfo.mode

   Permission bits.

.. attribute:: TarInfo.type

   File type.  *type* is usually one of these constants: :const:`REGTYPE`,

   :const:`AREGTYPE`, :const:`LNKTYPE`, :const:`SYMTYPE`, :const:`DIRTYPE`,

   :const:`FIFOTYPE`, :const:`CONTTYPE`, :const:`CHRTYPE`, :const:`BLKTYPE`,

   :const:`GNUTYPE_SPARSE`.  To determine the type of a :class:`TarInfo` object

   more conveniently, use the ``is_*()`` methods below.

.. attribute:: TarInfo.linkname

   Name of the target file name, which is only present in :class:`TarInfo` objects