#!/usr/bin/env python

# -*- coding: iso-8859-1 -*-

#-------------------------------------------------------------------

# tarfile.py

#-------------------------------------------------------------------

# Copyright (C) 2002 Lars Gustäbel <lars@gustaebel.de>

# All rights reserved.

#

# Permission  is  hereby granted,  free  of charge,  to  any person

# obtaining a  copy of  this software  and associated documentation

# files  (the  "Software"),  to   deal  in  the  Software   without

# restriction,  including  without limitation  the  rights to  use,

# copy, modify, merge, publish, distribute, sublicense, and/or sell

# copies  of  the  Software,  and to  permit  persons  to  whom the

# Software  is  furnished  to  do  so,  subject  to  the  following

# conditions:

#

# The above copyright  notice and this  permission notice shall  be

# included in all copies or substantial portions of the Software.

#

# THE SOFTWARE IS PROVIDED "AS  IS", WITHOUT WARRANTY OF ANY  KIND,

# EXPRESS OR IMPLIED, INCLUDING  BUT NOT LIMITED TO  THE WARRANTIES

# OF  MERCHANTABILITY,  FITNESS   FOR  A  PARTICULAR   PURPOSE  AND

# NONINFRINGEMENT.  IN  NO  EVENT SHALL  THE  AUTHORS  OR COPYRIGHT

# HOLDERS  BE LIABLE  FOR ANY  CLAIM, DAMAGES  OR OTHER  LIABILITY,

# WHETHER  IN AN  ACTION OF  CONTRACT, TORT  OR OTHERWISE,  ARISING

# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR

# OTHER DEALINGS IN THE SOFTWARE.

#

"""Read from and write to tar format archives.

"""

__version__ = "$Revision: 65514 $"

# $Source$

version     = "0.9.0"

__author__  = "Lars Gustäbel (lars@gustaebel.de)"

__date__    = "$Date: 2008-08-04 17:23:07 -0400 (Mon, 04 Aug 2008) $"

__cvsid__   = "$Id: tarfile.py 65514 2008-08-04 21:23:07Z brett.cannon $"

__credits__ = "Gustavo Niemeyer, Niels Gustäbel, Richard Townsend."

#---------

# Imports

#---------

import sys

import os

import shutil

import stat

import errno

import time

import struct

import copy

import re

import operator

if sys.platform == 'mac':

    # This module needs work for MacOS9, especially in the area of pathname

    # handling. In many places it is assumed a simple substitution of / by the

    # local os.path.sep is good enough to convert pathnames, but this does not

    # work with the mac rooted:path:name versus :nonrooted:path:name syntax

    raise ImportError, "tarfile does not work for platform==mac"

try:

    import grp, pwd

except ImportError:

    grp = pwd = None

# from tarfile import *

__all__ = ["TarFile", "TarInfo", "is_tarfile", "TarError"]

#---------------------------------------------------------

# tar constants

#---------------------------------------------------------

NUL = "\0"                      # the null character

BLOCKSIZE = 512                 # length of processing blocks

RECORDSIZE = BLOCKSIZE * 20     # length of records

GNU_MAGIC = "ustar  \0"         # magic gnu tar string

POSIX_MAGIC = "ustar\x0000"     # magic posix tar string

LENGTH_NAME = 100               # maximum length of a filename

LENGTH_LINK = 100               # maximum length of a linkname

LENGTH_PREFIX = 155             # maximum length of the prefix field

REGTYPE = "0"                   # regular file

AREGTYPE = "\0"                 # regular file

LNKTYPE = "1"                   # link (inside tarfile)

SYMTYPE = "2"                   # symbolic link

CHRTYPE = "3"                   # character special device

BLKTYPE = "4"                   # block special device

DIRTYPE = "5"                   # directory

FIFOTYPE = "6"                  # fifo special device

CONTTYPE = "7"                  # contiguous file

GNUTYPE_LONGNAME = "L"          # GNU tar longname

GNUTYPE_LONGLINK = "K"          # GNU tar longlink

GNUTYPE_SPARSE = "S"            # GNU tar sparse file

XHDTYPE = "x"                   # POSIX.1-2001 extended header

XGLTYPE = "g"                   # POSIX.1-2001 global header

SOLARIS_XHDTYPE = "X"           # Solaris extended header

USTAR_FORMAT = 0                # POSIX.1-1988 (ustar) format

GNU_FORMAT = 1                  # GNU tar format

PAX_FORMAT = 2                  # POSIX.1-2001 (pax) format

DEFAULT_FORMAT = GNU_FORMAT

#---------------------------------------------------------

# tarfile constants

#---------------------------------------------------------

# File types that tarfile supports:

SUPPORTED_TYPES = (REGTYPE, AREGTYPE, LNKTYPE,

                   SYMTYPE, DIRTYPE, FIFOTYPE,

                   CONTTYPE, CHRTYPE, BLKTYPE,

                   GNUTYPE_LONGNAME, GNUTYPE_LONGLINK,

                   GNUTYPE_SPARSE)

# File types that will be treated as a regular file.

REGULAR_TYPES = (REGTYPE, AREGTYPE,

                 CONTTYPE, GNUTYPE_SPARSE)

# File types that are part of the GNU tar format.

GNU_TYPES = (GNUTYPE_LONGNAME, GNUTYPE_LONGLINK,

             GNUTYPE_SPARSE)

# Fields from a pax header that override a TarInfo attribute.

PAX_FIELDS = ("path", "linkpath", "size", "mtime",

              "uid", "gid", "uname", "gname")

# Fields in a pax header that are numbers, all other fields

# are treated as strings.

PAX_NUMBER_FIELDS = {

    "atime": float,

    "ctime": float,

    "mtime": float,

    "uid": int,

    "gid": int,

    "size": int

}

#---------------------------------------------------------

# Bits used in the mode field, values in octal.

#---------------------------------------------------------

S_IFLNK = 0120000        # symbolic link

S_IFREG = 0100000        # regular file

S_IFBLK = 0060000        # block device

S_IFDIR = 0040000        # directory

S_IFCHR = 0020000        # character device

S_IFIFO = 0010000        # fifo

TSUID   = 04000          # set UID on execution

TSGID   = 02000          # set GID on execution

TSVTX   = 01000          # reserved

TUREAD  = 0400           # read by owner

TUWRITE = 0200           # write by owner

TUEXEC  = 0100           # execute/search by owner

TGREAD  = 0040           # read by group

TGWRITE = 0020           # write by group

TGEXEC  = 0010           # execute/search by group

TOREAD  = 0004           # read by other

TOWRITE = 0002           # write by other

TOEXEC  = 0001           # execute/search by other

#---------------------------------------------------------

# initialization

#---------------------------------------------------------

ENCODING = sys.getfilesystemencoding()

if ENCODING is None:

    ENCODING = sys.getdefaultencoding()

#---------------------------------------------------------

# Some useful functions

#---------------------------------------------------------

def stn(s, length):

    """Convert a python string to a null-terminated string buffer.

    """

    return s[:length] + (length - len(s)) * NUL

def nts(s):

    """Convert a null-terminated string field to a python string.

    """

    # Use the string up to the first null char.

    p = s.find("\0")

    if p == -1:

        return s

    return s[:p]

def nti(s):

    """Convert a number field to a python number.

    """

    # There are two possible encodings for a number field, see

    # itn() below.

    if s[0] != chr(0200):

        try:

            n = int(nts(s) or "0", 8)

        except ValueError:

            raise HeaderError("invalid header")

    else:

        n = 0L

        for i in xrange(len(s) - 1):

            n <<= 8

            n += ord(s[i + 1])

    return n

def itn(n, digits=8, format=DEFAULT_FORMAT):

    """Convert a python number to a number field.

    """

    # POSIX 1003.1-1988 requires numbers to be encoded as a string of

    # octal digits followed by a null-byte, this allows values up to

    # (8**(digits-1))-1. GNU tar allows storing numbers greater than

    # that if necessary. A leading 0200 byte indicates this particular

    # encoding, the following digits-1 bytes are a big-endian

    # representation. This allows values up to (256**(digits-1))-1.

    if 0 <= n < 8 ** (digits - 1):

        s = "%0*o" % (digits - 1, n) + NUL

    else:

        if format != GNU_FORMAT or n >= 256 ** (digits - 1):

            raise ValueError("overflow in number field")

        if n < 0:

            # XXX We mimic GNU tar's behaviour with negative numbers,

            # this could raise OverflowError.

            n = struct.unpack("L", struct.pack("l", n))[0]

        s = ""

        for i in xrange(digits - 1):

            s = chr(n & 0377) + s

            n >>= 8

        s = chr(0200) + s

    return s

def uts(s, encoding, errors):

    """Convert a unicode object to a string.

    """

    if errors == "utf-8":

        # An extra error handler similar to the -o invalid=UTF-8 option

        # in POSIX.1-2001. Replace untranslatable characters with their

        # UTF-8 representation.

        try:

            return s.encode(encoding, "strict")

        except UnicodeEncodeError:

            x = []

            for c in s:

                try:

                    x.append(c.encode(encoding, "strict"))

                except UnicodeEncodeError:

                    x.append(c.encode("utf8"))

            return "".join(x)

    else:

        return s.encode(encoding, errors)

def calc_chksums(buf):

    """Calculate the checksum for a member's header by summing up all

       characters except for the chksum field which is treated as if

       it was filled with spaces. According to the GNU tar sources,

       some tars (Sun and NeXT) calculate chksum with signed char,

       which will be different if there are chars in the buffer with

       the high bit set. So we calculate two checksums, unsigned and

       signed.

    """

    unsigned_chksum = 256 + sum(struct.unpack("148B", buf[:148]) + struct.unpack("356B", buf[156:512]))

    signed_chksum = 256 + sum(struct.unpack("148b", buf[:148]) + struct.unpack("356b", buf[156:512]))

    return unsigned_chksum, signed_chksum

def copyfileobj(src, dst, length=None):

    """Copy length bytes from fileobj src to fileobj dst.

       If length is None, copy the entire content.

    """

    if length == 0:

        return

    if length is None:

        shutil.copyfileobj(src, dst)

        return

    BUFSIZE = 16 * 1024

    blocks, remainder = divmod(length, BUFSIZE)

    for b in xrange(blocks):

        buf = src.read(BUFSIZE)

        if len(buf) < BUFSIZE:

            raise IOError("end of file reached")

        dst.write(buf)

    if remainder != 0:

        buf = src.read(remainder)

        if len(buf) < remainder:

            raise IOError("end of file reached")

        dst.write(buf)

    return

filemode_table = (

    ((S_IFLNK,      "l"),

     (S_IFREG,      "-"),

     (S_IFBLK,      "b"),

     (S_IFDIR,      "d"),

     (S_IFCHR,      "c"),

     (S_IFIFO,      "p")),

    ((TUREAD,       "r"),),

    ((TUWRITE,      "w"),),

    ((TUEXEC|TSUID, "s"),

     (TSUID,        "S"),

     (TUEXEC,       "x")),

    ((TGREAD,       "r"),),

    ((TGWRITE,      "w"),),

    ((TGEXEC|TSGID, "s"),

     (TSGID,        "S"),

     (TGEXEC,       "x")),

    ((TOREAD,       "r"),),

    ((TOWRITE,      "w"),),

    ((TOEXEC|TSVTX, "t"),

     (TSVTX,        "T"),

     (TOEXEC,       "x"))

)

def filemode(mode):

    """Convert a file's mode to a string of the form

       -rwxrwxrwx.

       Used by TarFile.list()

    """

    perm = []

    for table in filemode_table:

        for bit, char in table:

            if mode & bit == bit:

                perm.append(char)

                break

        else:

            perm.append("-")

    return "".join(perm)

if os.sep != "/":

    normpath = lambda path: os.path.normpath(path).replace(os.sep, "/")

else:

    normpath = os.path.normpath

class TarError(Exception):

    """Base exception."""

    pass

class ExtractError(TarError):

    """General exception for extract errors."""

    pass

class ReadError(TarError):

    """Exception for unreadble tar archives."""

    pass

class CompressionError(TarError):

    """Exception for unavailable compression methods."""

    pass

class StreamError(TarError):

    """Exception for unsupported operations on stream-like TarFiles."""

    pass

class HeaderError(TarError):

    """Exception for invalid headers."""

    pass

#---------------------------

# internal stream interface

#---------------------------

class _LowLevelFile:

    """Low-level file object. Supports reading and writing.

       It is used instead of a regular file object for streaming

       access.

    """

    def __init__(self, name, mode):

        mode = {

            "r": os.O_RDONLY,

            "w": os.O_WRONLY | os.O_CREAT | os.O_TRUNC,

        }[mode]

        if hasattr(os, "O_BINARY"):

            mode |= os.O_BINARY

        self.fd = os.open(name, mode)

    def close(self):

        os.close(self.fd)

    def read(self, size):

        return os.read(self.fd, size)

    def write(self, s):

        os.write(self.fd, s)

class _Stream:

    """Class that serves as an adapter between TarFile and

       a stream-like object.  The stream-like object only

       needs to have a read() or write() method and is accessed

       blockwise.  Use of gzip or bzip2 compression is possible.

       A stream-like object could be for example: sys.stdin,

       sys.stdout, a socket, a tape device etc.

       _Stream is intended to be used only internally.

    """

    def __init__(self, name, mode, comptype, fileobj, bufsize):

        """Construct a _Stream object.

        """

        self._extfileobj = True

        if fileobj is None:

            fileobj = _LowLevelFile(name, mode)

            self._extfileobj = False

        if comptype == '*':

            # Enable transparent compression detection for the

            # stream interface

            fileobj = _StreamProxy(fileobj)

            comptype = fileobj.getcomptype()

        self.name     = name or ""

        self.mode     = mode

        self.comptype = comptype

        self.fileobj  = fileobj

        self.bufsize  = bufsize

        self.buf      = ""

        self.pos      = 0L

        self.closed   = False

        if comptype == "gz":

            try:

                import zlib

            except ImportError:

                raise CompressionError("zlib module is not available")

            self.zlib = zlib

            self.crc = zlib.crc32("") & 0xffffffffL

            if mode == "r":

                self._init_read_gz()

            else:

                self._init_write_gz()

        if comptype == "bz2":

            try:

                import bz2

            except ImportError:

                raise CompressionError("bz2 module is not available")

            if mode == "r":

                self.dbuf = ""

                self.cmp = bz2.BZ2Decompressor()

            else:

                self.cmp = bz2.BZ2Compressor()

    def __del__(self):

        if hasattr(self, "closed") and not self.closed:

            self.close()

    def _init_write_gz(self):

        """Initialize for writing with gzip compression.

        """

        self.cmp = self.zlib.compressobj(9, self.zlib.DEFLATED,

                                            -self.zlib.MAX_WBITS,

                                            self.zlib.DEF_MEM_LEVEL,

                                            0)

        timestamp = struct.pack("<L", long(time.time()))

        self.__write("\037\213\010\010%s\002\377" % timestamp)

        if self.name.endswith(".gz"):

            self.name = self.name[:-3]

        self.__write(self.name + NUL)

    def write(self, s):

        """Write string s to the stream.

        """

        if self.comptype == "gz":

            self.crc = self.zlib.crc32(s, self.crc) & 0xffffffffL

        self.pos += len(s)

        if self.comptype != "tar":

            s = self.cmp.compress(s)

        self.__write(s)

    def __write(self, s):

        """Write string s to the stream if a whole new block

           is ready to be written.

        """

        self.buf += s

        while len(self.buf) > self.bufsize:

            self.fileobj.write(self.buf[:self.bufsize])

            self.buf = self.buf[self.bufsize:]

    def close(self):

        """Close the _Stream object. No operation should be

           done on it afterwards.

        """

        if self.closed:

            return

        if self.mode == "w" and self.comptype != "tar":

            self.buf += self.cmp.flush()

        if self.mode == "w" and self.buf:

            self.fileobj.write(self.buf)

            self.buf = ""

            if self.comptype == "gz":

                # The native zlib crc is an unsigned 32-bit integer, but

                # the Python wrapper implicitly casts that to a signed C

                # long.  So, on a 32-bit box self.crc may "look negative",

                # while the same crc on a 64-bit box may "look positive".

                # To avoid irksome warnings from the `struct` module, force

                # it to look positive on all boxes.

                self.fileobj.write(struct.pack("<L", self.crc & 0xffffffffL))

                self.fileobj.write(struct.pack("<L", self.pos & 0xffffFFFFL))

        if not self._extfileobj:

            self.fileobj.close()

        self.closed = True

    def _init_read_gz(self):

        """Initialize for reading a gzip compressed fileobj.

        """

        self.cmp = self.zlib.decompressobj(-self.zlib.MAX_WBITS)

        self.dbuf = ""

        # taken from gzip.GzipFile with some alterations

        if self.__read(2) != "\037\213":

            raise ReadError("not a gzip file")

        if self.__read(1) != "\010":

            raise CompressionError("unsupported compression method")

        flag = ord(self.__read(1))

        self.__read(6)

        if flag & 4:

            xlen = ord(self.__read(1)) + 256 * ord(self.__read(1))

            self.read(xlen)

        if flag & 8:

            while True:

                s = self.__read(1)

                if not s or s == NUL:

                    break

        if flag & 16: