#!/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: 60730 $"

# $Source$

version     = "0.8.0"

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

__date__    = "$Date: 2008-02-11 19:36:07 +0100 (Mo, 11 Feb 2008) $"

__cvsid__   = "$Id: tarfile.py 60730 2008-02-11 18:36:07Z lars.gustaebel $"

__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

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

MAGIC      = "ustar"            # magic tar string

VERSION    = "00"               # version number

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

MAXSIZE_MEMBER = 077777777777L  # maximum size of a file (11 octal digits)

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 extension for longnames

GNUTYPE_LONGLINK = "K"          # GNU tar extension for longlink

GNUTYPE_SPARSE   = "S"          # GNU tar extension for sparse file

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

# tarfile constants

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

SUPPORTED_TYPES = (REGTYPE, AREGTYPE, LNKTYPE,  # file types that tarfile

                   SYMTYPE, DIRTYPE, FIFOTYPE,  # can cope with.

                   CONTTYPE, CHRTYPE, BLKTYPE,

                   GNUTYPE_LONGNAME, GNUTYPE_LONGLINK,

                   GNUTYPE_SPARSE)

REGULAR_TYPES = (REGTYPE, AREGTYPE,             # file types that somehow

                 CONTTYPE, GNUTYPE_SPARSE)      # represent regular files

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

# 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

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

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

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

    else:

        n = 0L

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

            n <<= 8

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

    return n

def itn(n, digits=8, posix=False):

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

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

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

# 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("")

            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)

        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:

            while True:

                s = self.__read(1)

                if not s or s == NUL:

                    break

        if flag & 2:

            self.__read(2)

    def tell(self):

        """Return the stream's file pointer position.

        """

        return self.pos

    def seek(self, pos=0):

        """Set the stream's file pointer to pos. Negative seeking

           is forbidden.

        """

        if pos - self.pos >= 0:

            blocks, remainder = divmod(pos - self.pos, self.bufsize)

            for i in xrange(blocks):

                self.read(self.bufsize)

            self.read(remainder)

        else:

            raise StreamError("seeking backwards is not allowed")

        return self.pos

    def read(self, size=None):

        """Return the next size number of bytes from the stream.

           If size is not defined, return all bytes of the stream

           up to EOF.

        """

        if size is None:

            t = []

            while True:

                buf = self._read(self.bufsize)

                if not buf:

                    break

                t.append(buf)

            buf = "".join(t)

        else:

            buf = self._read(size)

        self.pos += len(buf)

        return buf

    def _read(self, size):

        """Return size bytes from the stream.

        """

        if self.comptype == "tar":

            return self.__read(size)

        c = len(self.dbuf)

        t = [self.dbuf]

        while c < size:

            buf = self.__read(self.bufsize)

            if not buf:

                break

            buf = self.cmp.decompress(buf)

            t.append(buf)

            c += len(buf)

        t = "".join(t)

        self.dbuf = t[size:]

        return t[:size]

    def __read(self, size):

        """Return size bytes from stream. If internal buffer is empty,