Back to index

python3.2  3.2.2
Public Member Functions | Public Attributes | Static Public Attributes | Private Member Functions | Private Attributes
tarfile.TarFile Class Reference
Inheritance diagram for tarfile.TarFile:
Inheritance graph
[legend]
Collaboration diagram for tarfile.TarFile:
Collaboration graph
[legend]

List of all members.

Public Member Functions

def __init__
def open
def taropen
def gzopen
def bz2open
def close
def getmember
def getmembers
def getnames
def gettarinfo
def list
def add
def addfile
def extractall
def extract
def extractfile
def makedir
def makefile
def makeunknown
def makefifo
def makedev
def makelink
def chown
def chmod
def utime
def next
def __iter__
def __enter__
def __exit__

Public Attributes

 mode
 name
 fileobj
 pax_headers
 debug
 errorlevel
 closed
 members
 offset
 inodes
 firstmember
_PyObject_HEAD_EXTRA Py_ssize_t ob_refcnt
struct _typeobjectob_type

Static Public Attributes

int debug = 0
 dereference = False
 ignore_zeros = False
int errorlevel = 1
 format = DEFAULT_FORMAT
 encoding = ENCODING
 errors = None
 tarinfo = TarInfo
 fileobject = ExFileObject
dictionary OPEN_METH

Private Member Functions

def _extract_member
def _getmember
def _load
def _check
def _find_link_target
def _dbg

Private Attributes

 _mode
 _extfileobj
 _loaded

Detailed Description

The TarFile Class provides an interface to tar archives.

Definition at line 1571 of file tarfile.py.


Constructor & Destructor Documentation

def tarfile.TarFile.__init__ (   self,
  name = None,
  mode = "r",
  fileobj = None,
  format = None,
  tarinfo = None,
  dereference = None,
  ignore_zeros = None,
  encoding = None,
  errors = "surrogateescape",
  pax_headers = None,
  debug = None,
  errorlevel = None 
)
Open an (uncompressed) tar archive `name'. `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. `mode'
   defaults to 'r'.
   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' is not closed, when TarFile is closed.

Definition at line 1599 of file tarfile.py.

01599 
01600             errors="surrogateescape", pax_headers=None, debug=None, errorlevel=None):
01601         """Open an (uncompressed) tar archive `name'. `mode' is either 'r' to
01602            read from an existing archive, 'a' to append data to an existing
01603            file or 'w' to create a new file overwriting an existing one. `mode'
01604            defaults to 'r'.
01605            If `fileobj' is given, it is used for reading or writing data. If it
01606            can be determined, `mode' is overridden by `fileobj's mode.
01607            `fileobj' is not closed, when TarFile is closed.
01608         """
01609         if len(mode) > 1 or mode not in "raw":
01610             raise ValueError("mode must be 'r', 'a' or 'w'")
01611         self.mode = mode
01612         self._mode = {"r": "rb", "a": "r+b", "w": "wb"}[mode]
01613 
01614         if not fileobj:
01615             if self.mode == "a" and not os.path.exists(name):
01616                 # Create nonexistent files in append mode.
01617                 self.mode = "w"
01618                 self._mode = "wb"
01619             fileobj = bltn_open(name, self._mode)
01620             self._extfileobj = False
01621         else:
01622             if name is None and hasattr(fileobj, "name"):
01623                 name = fileobj.name
01624             if hasattr(fileobj, "mode"):
01625                 self._mode = fileobj.mode
01626             self._extfileobj = True
01627         self.name = os.path.abspath(name) if name else None
01628         self.fileobj = fileobj
01629 
01630         # Init attributes.
01631         if format is not None:
01632             self.format = format
01633         if tarinfo is not None:
01634             self.tarinfo = tarinfo
01635         if dereference is not None:
01636             self.dereference = dereference
01637         if ignore_zeros is not None:
01638             self.ignore_zeros = ignore_zeros
01639         if encoding is not None:
01640             self.encoding = encoding
01641         self.errors = errors
01642 
01643         if pax_headers is not None and self.format == PAX_FORMAT:
01644             self.pax_headers = pax_headers
01645         else:
01646             self.pax_headers = {}
01647 
01648         if debug is not None:
01649             self.debug = debug
01650         if errorlevel is not None:
01651             self.errorlevel = errorlevel
01652 
01653         # Init datastructures.
01654         self.closed = False
01655         self.members = []       # list of members as TarInfo objects
01656         self._loaded = False    # flag if all members have been read
01657         self.offset = self.fileobj.tell()
01658                                 # current position in the archive file
01659         self.inodes = {}        # dictionary caching the inodes of
01660                                 # archive members already added
01661 
01662         try:
01663             if self.mode == "r":
01664                 self.firstmember = None
01665                 self.firstmember = self.next()
01666 
01667             if self.mode == "a":
01668                 # Move to the end of the archive,
01669                 # before the first empty block.
01670                 while True:
01671                     self.fileobj.seek(self.offset)
01672                     try:
01673                         tarinfo = self.tarinfo.fromtarfile(self)
01674                         self.members.append(tarinfo)
01675                     except EOFHeaderError:
01676                         self.fileobj.seek(self.offset)
01677                         break
01678                     except HeaderError as e:
01679                         raise ReadError(str(e))
01680 
01681             if self.mode in "aw":
01682                 self._loaded = True
01683 
01684                 if self.pax_headers:
01685                     buf = self.tarinfo.create_pax_global_header(self.pax_headers.copy())
01686                     self.fileobj.write(buf)
01687                     self.offset += len(buf)
01688         except:
01689             if not self._extfileobj:
01690                 self.fileobj.close()
01691             self.closed = True
01692             raise

Here is the caller graph for this function:


Member Function Documentation

def tarfile.TarFile.__enter__ (   self)

Definition at line 2535 of file tarfile.py.

02535 
02536     def __enter__(self):
02537         self._check()
02538         return self

Here is the call graph for this function:

def tarfile.TarFile.__exit__ (   self,
  type,
  value,
  traceback 
)

Definition at line 2539 of file tarfile.py.

02539 
02540     def __exit__(self, type, value, traceback):
02541         if type is None:
02542             self.close()
02543         else:
02544             # An exception occurred. We must not call close() because
02545             # it would try to write end-of-archive blocks and padding.
02546             if not self._extfileobj:
02547                 self.fileobj.close()
02548             self.closed = True
02549 # class TarFile

Here is the caller graph for this function:

def tarfile.TarFile.__iter__ (   self)
Provide an iterator object.

Definition at line 2521 of file tarfile.py.

02521 
02522     def __iter__(self):
02523         """Provide an iterator object.
02524         """
02525         if self._loaded:
02526             return iter(self.members)
02527         else:
02528             return TarIter(self)

def tarfile.TarFile._check (   self,
  mode = None 
) [private]
Check if TarFile is still open, and if the operation's mode
   corresponds to TarFile's mode.

Definition at line 2493 of file tarfile.py.

02493 
02494     def _check(self, mode=None):
02495         """Check if TarFile is still open, and if the operation's mode
02496            corresponds to TarFile's mode.
02497         """
02498         if self.closed:
02499             raise IOError("%s is closed" % self.__class__.__name__)
02500         if mode is not None and self.mode not in mode:
02501             raise IOError("bad operation for mode %r" % self.mode)

Here is the caller graph for this function:

def tarfile.TarFile._dbg (   self,
  level,
  msg 
) [private]
Write debugging output to sys.stderr.

Definition at line 2529 of file tarfile.py.

02529 
02530     def _dbg(self, level, msg):
02531         """Write debugging output to sys.stderr.
02532         """
02533         if level <= self.debug:
02534             print(msg, file=sys.stderr)

Here is the caller graph for this function:

def tarfile.TarFile._extract_member (   self,
  tarinfo,
  targetpath,
  set_attrs = True 
) [private]
Extract the TarInfo object tarinfo to a physical
   file called targetpath.

Definition at line 2228 of file tarfile.py.

02228 
02229     def _extract_member(self, tarinfo, targetpath, set_attrs=True):
02230         """Extract the TarInfo object tarinfo to a physical
02231            file called targetpath.
02232         """
02233         # Fetch the TarInfo object for the given name
02234         # and build the destination pathname, replacing
02235         # forward slashes to platform specific separators.
02236         targetpath = targetpath.rstrip("/")
02237         targetpath = targetpath.replace("/", os.sep)
02238 
02239         # Create all upper directories.
02240         upperdirs = os.path.dirname(targetpath)
02241         if upperdirs and not os.path.exists(upperdirs):
02242             # Create directories that are not part of the archive with
02243             # default permissions.
02244             os.makedirs(upperdirs)
02245 
02246         if tarinfo.islnk() or tarinfo.issym():
02247             self._dbg(1, "%s -> %s" % (tarinfo.name, tarinfo.linkname))
02248         else:
02249             self._dbg(1, tarinfo.name)
02250 
02251         if tarinfo.isreg():
02252             self.makefile(tarinfo, targetpath)
02253         elif tarinfo.isdir():
02254             self.makedir(tarinfo, targetpath)
02255         elif tarinfo.isfifo():
02256             self.makefifo(tarinfo, targetpath)
02257         elif tarinfo.ischr() or tarinfo.isblk():
02258             self.makedev(tarinfo, targetpath)
02259         elif tarinfo.islnk() or tarinfo.issym():
02260             self.makelink(tarinfo, targetpath)
02261         elif tarinfo.type not in SUPPORTED_TYPES:
02262             self.makeunknown(tarinfo, targetpath)
02263         else:
02264             self.makefile(tarinfo, targetpath)
02265 
02266         if set_attrs:
02267             self.chown(tarinfo, targetpath)
02268             if not tarinfo.issym():
02269                 self.chmod(tarinfo, targetpath)
02270                 self.utime(tarinfo, targetpath)

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile._find_link_target (   self,
  tarinfo 
) [private]
Find the target member of a symlink or hardlink member in the
   archive.

Definition at line 2502 of file tarfile.py.

02502 
02503     def _find_link_target(self, tarinfo):
02504         """Find the target member of a symlink or hardlink member in the
02505            archive.
02506         """
02507         if tarinfo.issym():
02508             # Always search the entire archive.
02509             linkname = os.path.dirname(tarinfo.name) + "/" + tarinfo.linkname
02510             limit = None
02511         else:
02512             # Search the archive before the link, because a hard link is
02513             # just a reference to an already archived file.
02514             linkname = tarinfo.linkname
02515             limit = tarinfo
02516 
02517         member = self._getmember(linkname, tarinfo=limit, normalize=True)
02518         if member is None:
02519             raise KeyError("linkname %r not found" % linkname)
02520         return member

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile._getmember (   self,
  name,
  tarinfo = None,
  normalize = False 
) [private]
Find an archive member by name from bottom to top.
   If tarinfo is given, it is used as the starting point.

Definition at line 2460 of file tarfile.py.

02460 
02461     def _getmember(self, name, tarinfo=None, normalize=False):
02462         """Find an archive member by name from bottom to top.
02463            If tarinfo is given, it is used as the starting point.
02464         """
02465         # Ensure that all members have been loaded.
02466         members = self.getmembers()
02467 
02468         # Limit the member search list up to tarinfo.
02469         if tarinfo is not None:
02470             members = members[:members.index(tarinfo)]
02471 
02472         if normalize:
02473             name = os.path.normpath(name)
02474 
02475         for member in reversed(members):
02476             if normalize:
02477                 member_name = os.path.normpath(member.name)
02478             else:
02479                 member_name = member.name
02480 
02481             if name == member_name:
02482                 return member

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile._load (   self) [private]
Read through the entire archive file and look for readable
   members.

Definition at line 2483 of file tarfile.py.

02483 
02484     def _load(self):
02485         """Read through the entire archive file and look for readable
02486            members.
02487         """
02488         while True:
02489             tarinfo = self.next()
02490             if tarinfo is None:
02491                 break
02492         self._loaded = True

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.add (   self,
  name,
  arcname = None,
  recursive = True,
  exclude = None,
  filter = 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 False. `exclude' is a function that should
   return True for each filename to be excluded. `filter' is a function
   that expects a TarInfo object argument and returns the changed
   TarInfo object, if it returns None the TarInfo object will be
   excluded from the archive.

Definition at line 2029 of file tarfile.py.

02029 
02030     def add(self, name, arcname=None, recursive=True, exclude=None, *, filter=None):
02031         """Add the file `name' to the archive. `name' may be any type of file
02032            (directory, fifo, symbolic link, etc.). If given, `arcname'
02033            specifies an alternative name for the file in the archive.
02034            Directories are added recursively by default. This can be avoided by
02035            setting `recursive' to False. `exclude' is a function that should
02036            return True for each filename to be excluded. `filter' is a function
02037            that expects a TarInfo object argument and returns the changed
02038            TarInfo object, if it returns None the TarInfo object will be
02039            excluded from the archive.
02040         """
02041         self._check("aw")
02042 
02043         if arcname is None:
02044             arcname = name
02045 
02046         # Exclude pathnames.
02047         if exclude is not None:
02048             import warnings
02049             warnings.warn("use the filter argument instead",
02050                     DeprecationWarning, 2)
02051             if exclude(name):
02052                 self._dbg(2, "tarfile: Excluded %r" % name)
02053                 return
02054 
02055         # Skip if somebody tries to archive the archive...
02056         if self.name is not None and os.path.abspath(name) == self.name:
02057             self._dbg(2, "tarfile: Skipped %r" % name)
02058             return
02059 
02060         self._dbg(1, name)
02061 
02062         # Create a TarInfo object from the file.
02063         tarinfo = self.gettarinfo(name, arcname)
02064 
02065         if tarinfo is None:
02066             self._dbg(1, "tarfile: Unsupported type %r" % name)
02067             return
02068 
02069         # Change or exclude the TarInfo object.
02070         if filter is not None:
02071             tarinfo = filter(tarinfo)
02072             if tarinfo is None:
02073                 self._dbg(2, "tarfile: Excluded %r" % name)
02074                 return
02075 
02076         # Append the tar header and data to the archive.
02077         if tarinfo.isreg():
02078             f = bltn_open(name, "rb")
02079             self.addfile(tarinfo, f)
02080             f.close()
02081 
02082         elif tarinfo.isdir():
02083             self.addfile(tarinfo)
02084             if recursive:
02085                 for f in os.listdir(name):
02086                     self.add(os.path.join(name, f), os.path.join(arcname, f),
02087                             recursive, exclude, filter=filter)
02088 
02089         else:
02090             self.addfile(tarinfo)

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.addfile (   self,
  tarinfo,
  fileobj = None 
)
Add the 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 TarInfo objects using gettarinfo().
   On Windows platforms, `fileobj' should always be opened with mode
   'rb' to avoid irritation about the file size.

Definition at line 2091 of file tarfile.py.

02091 
02092     def addfile(self, tarinfo, fileobj=None):
02093         """Add the TarInfo object `tarinfo' to the archive. If `fileobj' is
02094            given, tarinfo.size bytes are read from it and added to the archive.
02095            You can create TarInfo objects using gettarinfo().
02096            On Windows platforms, `fileobj' should always be opened with mode
02097            'rb' to avoid irritation about the file size.
02098         """
02099         self._check("aw")
02100 
02101         tarinfo = copy.copy(tarinfo)
02102 
02103         buf = tarinfo.tobuf(self.format, self.encoding, self.errors)
02104         self.fileobj.write(buf)
02105         self.offset += len(buf)
02106 
02107         # If there's data to follow, append it.
02108         if fileobj is not None:
02109             copyfileobj(fileobj, self.fileobj, tarinfo.size)
02110             blocks, remainder = divmod(tarinfo.size, BLOCKSIZE)
02111             if remainder > 0:
02112                 self.fileobj.write(NUL * (BLOCKSIZE - remainder))
02113                 blocks += 1
02114             self.offset += blocks * BLOCKSIZE
02115 
02116         self.members.append(tarinfo)

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.bz2open (   cls,
  name,
  mode = "r",
  fileobj = None,
  compresslevel = 9,
  kwargs 
)
Open bzip2 compressed tar archive name for reading or writing.
   Appending is not allowed.

Definition at line 1820 of file tarfile.py.

01820 
01821     def bz2open(cls, name, mode="r", fileobj=None, compresslevel=9, **kwargs):
01822         """Open bzip2 compressed tar archive name for reading or writing.
01823            Appending is not allowed.
01824         """
01825         if len(mode) > 1 or mode not in "rw":
01826             raise ValueError("mode must be 'r' or 'w'.")
01827 
01828         try:
01829             import bz2
01830         except ImportError:
01831             raise CompressionError("bz2 module is not available")
01832 
01833         if fileobj is not None:
01834             fileobj = _BZ2Proxy(fileobj, mode)
01835         else:
01836             fileobj = bz2.BZ2File(name, mode, compresslevel=compresslevel)
01837 
01838         try:
01839             t = cls.taropen(name, mode, fileobj, **kwargs)
01840         except (IOError, EOFError):
01841             fileobj.close()
01842             raise ReadError("not a bzip2 file")
01843         t._extfileobj = False
01844         return t

def tarfile.TarFile.chmod (   self,
  tarinfo,
  targetpath 
)
Set file permissions of targetpath according to tarinfo.

Definition at line 2391 of file tarfile.py.

02391 
02392     def chmod(self, tarinfo, targetpath):
02393         """Set file permissions of targetpath according to tarinfo.
02394         """
02395         if hasattr(os, 'chmod'):
02396             try:
02397                 os.chmod(targetpath, tarinfo.mode)
02398             except EnvironmentError as e:
02399                 raise ExtractError("could not change mode")

Here is the caller graph for this function:

def tarfile.TarFile.chown (   self,
  tarinfo,
  targetpath 
)
Set owner of targetpath according to tarinfo.

Definition at line 2363 of file tarfile.py.

02363 
02364     def chown(self, tarinfo, targetpath):
02365         """Set owner of targetpath according to tarinfo.
02366         """
02367         if pwd and hasattr(os, "geteuid") and os.geteuid() == 0:
02368             # We have to be root to do so.
02369             try:
02370                 g = grp.getgrnam(tarinfo.gname)[2]
02371             except KeyError:
02372                 try:
02373                     g = grp.getgrgid(tarinfo.gid)[2]
02374                 except KeyError:
02375                     g = os.getgid()
02376             try:
02377                 u = pwd.getpwnam(tarinfo.uname)[2]
02378             except KeyError:
02379                 try:
02380                     u = pwd.getpwuid(tarinfo.uid)[2]
02381                 except KeyError:
02382                     u = os.getuid()
02383             try:
02384                 if tarinfo.issym() and hasattr(os, "lchown"):
02385                     os.lchown(targetpath, u, g)
02386                 else:
02387                     if sys.platform != "os2emx":
02388                         os.chown(targetpath, u, g)
02389             except EnvironmentError as e:
02390                 raise ExtractError("could not change owner")

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.close (   self)
Close the TarFile. In write-mode, two finishing zero blocks are
   appended to the archive.

Definition at line 1855 of file tarfile.py.

01855 
01856     def close(self):
01857         """Close the TarFile. In write-mode, two finishing zero blocks are
01858            appended to the archive.
01859         """
01860         if self.closed:
01861             return
01862 
01863         if self.mode in "aw":
01864             self.fileobj.write(NUL * (BLOCKSIZE * 2))
01865             self.offset += (BLOCKSIZE * 2)
01866             # fill up the end with zero-blocks
01867             # (like option -b20 for tar does)
01868             blocks, remainder = divmod(self.offset, RECORDSIZE)
01869             if remainder > 0:
01870                 self.fileobj.write(NUL * (RECORDSIZE - remainder))
01871 
01872         if not self._extfileobj:
01873             self.fileobj.close()
01874         self.closed = True

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.extract (   self,
  member,
  path = "",
  set_attrs = True 
)
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 TarInfo object. You can
   specify a different directory using `path'. File attributes (owner,
   mtime, mode) are set unless `set_attrs' is False.

Definition at line 2155 of file tarfile.py.

02155 
02156     def extract(self, member, path="", set_attrs=True):
02157         """Extract a member from the archive to the current working directory,
02158            using its full name. Its file information is extracted as accurately
02159            as possible. `member' may be a filename or a TarInfo object. You can
02160            specify a different directory using `path'. File attributes (owner,
02161            mtime, mode) are set unless `set_attrs' is False.
02162         """
02163         self._check("r")
02164 
02165         if isinstance(member, str):
02166             tarinfo = self.getmember(member)
02167         else:
02168             tarinfo = member
02169 
02170         # Prepare the link target for makelink().
02171         if tarinfo.islnk():
02172             tarinfo._link_target = os.path.join(path, tarinfo.linkname)
02173 
02174         try:
02175             self._extract_member(tarinfo, os.path.join(path, tarinfo.name),
02176                                  set_attrs=set_attrs)
02177         except EnvironmentError as e:
02178             if self.errorlevel > 0:
02179                 raise
02180             else:
02181                 if e.filename is None:
02182                     self._dbg(1, "tarfile: %s" % e.strerror)
02183                 else:
02184                     self._dbg(1, "tarfile: %s %r" % (e.strerror, e.filename))
02185         except ExtractError as e:
02186             if self.errorlevel > 1:
02187                 raise
02188             else:
02189                 self._dbg(1, "tarfile: %s" % e)

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.extractall (   self,
  path = ".",
  members = None 
)
Extract all members from the archive to the current working
   directory and set owner, modification time and permissions on
   directories afterwards. `path' specifies a different directory
   to extract to. `members' is optional and must be a subset of the
   list returned by getmembers().

Definition at line 2117 of file tarfile.py.

02117 
02118     def extractall(self, path=".", members=None):
02119         """Extract all members from the archive to the current working
02120            directory and set owner, modification time and permissions on
02121            directories afterwards. `path' specifies a different directory
02122            to extract to. `members' is optional and must be a subset of the
02123            list returned by getmembers().
02124         """
02125         directories = []
02126 
02127         if members is None:
02128             members = self
02129 
02130         for tarinfo in members:
02131             if tarinfo.isdir():
02132                 # Extract directories with a safe mode.
02133                 directories.append(tarinfo)
02134                 tarinfo = copy.copy(tarinfo)
02135                 tarinfo.mode = 0o700
02136             # Do not set_attrs directories, as we will do that further down
02137             self.extract(tarinfo, path, set_attrs=not tarinfo.isdir())
02138 
02139         # Reverse sort directories.
02140         directories.sort(key=lambda a: a.name)
02141         directories.reverse()
02142 
02143         # Set correct owner, mtime and filemode on directories.
02144         for tarinfo in directories:
02145             dirpath = os.path.join(path, tarinfo.name)
02146             try:
02147                 self.chown(tarinfo, dirpath)
02148                 self.utime(tarinfo, dirpath)
02149                 self.chmod(tarinfo, dirpath)
02150             except ExtractError as e:
02151                 if self.errorlevel > 1:
02152                     raise
02153                 else:
02154                     self._dbg(1, "tarfile: %s" % e)

Here is the call graph for this function:

def tarfile.TarFile.extractfile (   self,
  member 
)
Extract a member from the archive as a file object. `member' may be
   a filename or a 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, None is returned.
   The file-like object is read-only and provides the following
   methods: read(), readline(), readlines(), seek() and tell()

Definition at line 2190 of file tarfile.py.

02190 
02191     def extractfile(self, member):
02192         """Extract a member from the archive as a file object. `member' may be
02193            a filename or a TarInfo object. If `member' is a regular file, a
02194            file-like object is returned. If `member' is a link, a file-like
02195            object is constructed from the link's target. If `member' is none of
02196            the above, None is returned.
02197            The file-like object is read-only and provides the following
02198            methods: read(), readline(), readlines(), seek() and tell()
02199         """
02200         self._check("r")
02201 
02202         if isinstance(member, str):
02203             tarinfo = self.getmember(member)
02204         else:
02205             tarinfo = member
02206 
02207         if tarinfo.isreg():
02208             return self.fileobject(self, tarinfo)
02209 
02210         elif tarinfo.type not in SUPPORTED_TYPES:
02211             # If a member's type is unknown, it is treated as a
02212             # regular file.
02213             return self.fileobject(self, tarinfo)
02214 
02215         elif tarinfo.islnk() or tarinfo.issym():
02216             if isinstance(self.fileobj, _Stream):
02217                 # A small but ugly workaround for the case that someone tries
02218                 # to extract a (sym)link as a file-object from a non-seekable
02219                 # stream of tar blocks.
02220                 raise StreamError("cannot extract (sym)link as file object")
02221             else:
02222                 # A (sym)link's file object is its target's file object.
02223                 return self.extractfile(self._find_link_target(tarinfo))
02224         else:
02225             # If there's no data associated with the member (directory, chrdev,
02226             # blkdev, etc.), return None instead of a file object.
02227             return None

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.getmember (   self,
  name 
)
Return a TarInfo object for member `name'. If `name' can not be
   found in the archive, KeyError is raised. If a member occurs more
   than once in the archive, its last occurrence is assumed to be the
   most up-to-date version.

Definition at line 1875 of file tarfile.py.

01875 
01876     def getmember(self, name):
01877         """Return a TarInfo object for member `name'. If `name' can not be
01878            found in the archive, KeyError is raised. If a member occurs more
01879            than once in the archive, its last occurrence is assumed to be the
01880            most up-to-date version.
01881         """
01882         tarinfo = self._getmember(name)
01883         if tarinfo is None:
01884             raise KeyError("filename %r not found" % name)
01885         return tarinfo

Here is the call graph for this function:

Here is the caller graph for this function:

Return the members of the archive as a list of TarInfo objects. The
   list has the same order as the members in the archive.

Definition at line 1886 of file tarfile.py.

01886 
01887     def getmembers(self):
01888         """Return the members of the archive as a list of TarInfo objects. The
01889            list has the same order as the members in the archive.
01890         """
01891         self._check()
01892         if not self._loaded:    # if we want to obtain a list of
01893             self._load()        # all members, we first have to
01894                                 # scan the whole archive.
01895         return self.members

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.getnames (   self)
Return the members of the archive as a list of their names. It has
   the same order as the list returned by getmembers().

Definition at line 1896 of file tarfile.py.

01896 
01897     def getnames(self):
01898         """Return the members of the archive as a list of their names. It has
01899            the same order as the list returned by getmembers().
01900         """
01901         return [tarinfo.name for tarinfo in self.getmembers()]

Here is the call graph for this function:

def tarfile.TarFile.gettarinfo (   self,
  name = None,
  arcname = None,
  fileobj = None 
)
Create a TarInfo object for either the file `name' or the file
   object `fileobj' (using os.fstat on its file descriptor). You can
   modify some of the TarInfo's attributes before you add it using
   addfile(). If given, `arcname' specifies an alternative name for the
   file in the archive.

Definition at line 1902 of file tarfile.py.

01902 
01903     def gettarinfo(self, name=None, arcname=None, fileobj=None):
01904         """Create a TarInfo object for either the file `name' or the file
01905            object `fileobj' (using os.fstat on its file descriptor). You can
01906            modify some of the TarInfo's attributes before you add it using
01907            addfile(). If given, `arcname' specifies an alternative name for the
01908            file in the archive.
01909         """
01910         self._check("aw")
01911 
01912         # When fileobj is given, replace name by
01913         # fileobj's real name.
01914         if fileobj is not None:
01915             name = fileobj.name
01916 
01917         # Building the name of the member in the archive.
01918         # Backward slashes are converted to forward slashes,
01919         # Absolute paths are turned to relative paths.
01920         if arcname is None:
01921             arcname = name
01922         drv, arcname = os.path.splitdrive(arcname)
01923         arcname = arcname.replace(os.sep, "/")
01924         arcname = arcname.lstrip("/")
01925 
01926         # Now, fill the TarInfo object with
01927         # information specific for the file.
01928         tarinfo = self.tarinfo()
01929         tarinfo.tarfile = self
01930 
01931         # Use os.stat or os.lstat, depending on platform
01932         # and if symlinks shall be resolved.
01933         if fileobj is None:
01934             if hasattr(os, "lstat") and not self.dereference:
01935                 statres = os.lstat(name)
01936             else:
01937                 statres = os.stat(name)
01938         else:
01939             statres = os.fstat(fileobj.fileno())
01940         linkname = ""
01941 
01942         stmd = statres.st_mode
01943         if stat.S_ISREG(stmd):
01944             inode = (statres.st_ino, statres.st_dev)
01945             if not self.dereference and statres.st_nlink > 1 and \
01946                     inode in self.inodes and arcname != self.inodes[inode]:
01947                 # Is it a hardlink to an already
01948                 # archived file?
01949                 type = LNKTYPE
01950                 linkname = self.inodes[inode]
01951             else:
01952                 # The inode is added only if its valid.
01953                 # For win32 it is always 0.
01954                 type = REGTYPE
01955                 if inode[0]:
01956                     self.inodes[inode] = arcname
01957         elif stat.S_ISDIR(stmd):
01958             type = DIRTYPE
01959         elif stat.S_ISFIFO(stmd):
01960             type = FIFOTYPE
01961         elif stat.S_ISLNK(stmd):
01962             type = SYMTYPE
01963             linkname = os.readlink(name)
01964         elif stat.S_ISCHR(stmd):
01965             type = CHRTYPE
01966         elif stat.S_ISBLK(stmd):
01967             type = BLKTYPE
01968         else:
01969             return None
01970 
01971         # Fill the TarInfo object with all
01972         # information we can get.
01973         tarinfo.name = arcname
01974         tarinfo.mode = stmd
01975         tarinfo.uid = statres.st_uid
01976         tarinfo.gid = statres.st_gid
01977         if type == REGTYPE:
01978             tarinfo.size = statres.st_size
01979         else:
01980             tarinfo.size = 0
01981         tarinfo.mtime = statres.st_mtime
01982         tarinfo.type = type
01983         tarinfo.linkname = linkname
01984         if pwd:
01985             try:
01986                 tarinfo.uname = pwd.getpwuid(tarinfo.uid)[0]
01987             except KeyError:
01988                 pass
01989         if grp:
01990             try:
01991                 tarinfo.gname = grp.getgrgid(tarinfo.gid)[0]
01992             except KeyError:
01993                 pass
01994 
01995         if type in (CHRTYPE, BLKTYPE):
01996             if hasattr(os, "major") and hasattr(os, "minor"):
01997                 tarinfo.devmajor = os.major(statres.st_rdev)
01998                 tarinfo.devminor = os.minor(statres.st_rdev)
01999         return tarinfo

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.gzopen (   cls,
  name,
  mode = "r",
  fileobj = None,
  compresslevel = 9,
  kwargs 
)
Open gzip compressed tar archive name for reading or writing.
   Appending is not allowed.

Definition at line 1789 of file tarfile.py.

01789 
01790     def gzopen(cls, name, mode="r", fileobj=None, compresslevel=9, **kwargs):
01791         """Open gzip compressed tar archive name for reading or writing.
01792            Appending is not allowed.
01793         """
01794         if len(mode) > 1 or mode not in "rw":
01795             raise ValueError("mode must be 'r' or 'w'")
01796 
01797         try:
01798             import gzip
01799             gzip.GzipFile
01800         except (ImportError, AttributeError):
01801             raise CompressionError("gzip module is not available")
01802 
01803         extfileobj = fileobj is not None
01804         try:
01805             fileobj = gzip.GzipFile(name, mode + "b", compresslevel, fileobj)
01806             t = cls.taropen(name, mode, fileobj, **kwargs)
01807         except IOError:
01808             if not extfileobj and fileobj is not None:
01809                 fileobj.close()
01810             if fileobj is None:
01811                 raise
01812             raise ReadError("not a gzip file")
01813         except:
01814             if not extfileobj and fileobj is not None:
01815                 fileobj.close()
01816             raise
01817         t._extfileobj = extfileobj
01818         return t

def tarfile.TarFile.list (   self,
  verbose = True 
)
Print a table of contents to sys.stdout. If `verbose' is False, only
   the names of the members are printed. If it is True, an `ls -l'-like
   output is produced.

Definition at line 2000 of file tarfile.py.

02000 
02001     def list(self, verbose=True):
02002         """Print a table of contents to sys.stdout. If `verbose' is False, only
02003            the names of the members are printed. If it is True, an `ls -l'-like
02004            output is produced.
02005         """
02006         self._check()
02007 
02008         for tarinfo in self:
02009             if verbose:
02010                 print(filemode(tarinfo.mode), end=' ')
02011                 print("%s/%s" % (tarinfo.uname or tarinfo.uid,
02012                                  tarinfo.gname or tarinfo.gid), end=' ')
02013                 if tarinfo.ischr() or tarinfo.isblk():
02014                     print("%10s" % ("%d,%d" \
02015                                     % (tarinfo.devmajor, tarinfo.devminor)), end=' ')
02016                 else:
02017                     print("%10d" % tarinfo.size, end=' ')
02018                 print("%d-%02d-%02d %02d:%02d:%02d" \
02019                       % time.localtime(tarinfo.mtime)[:6], end=' ')
02020 
02021             print(tarinfo.name + ("/" if tarinfo.isdir() else ""), end=' ')
02022 
02023             if verbose:
02024                 if tarinfo.issym():
02025                     print("->", tarinfo.linkname, end=' ')
02026                 if tarinfo.islnk():
02027                     print("link to", tarinfo.linkname, end=' ')
02028             print()

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.makedev (   self,
  tarinfo,
  targetpath 
)
Make a character or block device called targetpath.

Definition at line 2319 of file tarfile.py.

02319 
02320     def makedev(self, tarinfo, targetpath):
02321         """Make a character or block device called targetpath.
02322         """
02323         if not hasattr(os, "mknod") or not hasattr(os, "makedev"):
02324             raise ExtractError("special devices not supported by system")
02325 
02326         mode = tarinfo.mode
02327         if tarinfo.isblk():
02328             mode |= stat.S_IFBLK
02329         else:
02330             mode |= stat.S_IFCHR
02331 
02332         os.mknod(targetpath, mode,
02333                  os.makedev(tarinfo.devmajor, tarinfo.devminor))

Here is the caller graph for this function:

def tarfile.TarFile.makedir (   self,
  tarinfo,
  targetpath 
)
Make a directory called targetpath.

Definition at line 2276 of file tarfile.py.

02276 
02277     def makedir(self, tarinfo, targetpath):
02278         """Make a directory called targetpath.
02279         """
02280         try:
02281             # Use a safe mode for the directory, the real mode is set
02282             # later in _extract_member().
02283             os.mkdir(targetpath, 0o700)
02284         except EnvironmentError as e:
02285             if e.errno != errno.EEXIST:
02286                 raise

Here is the caller graph for this function:

def tarfile.TarFile.makefifo (   self,
  tarinfo,
  targetpath 
)
Make a fifo called targetpath.

Definition at line 2311 of file tarfile.py.

02311 
02312     def makefifo(self, tarinfo, targetpath):
02313         """Make a fifo called targetpath.
02314         """
02315         if hasattr(os, "mkfifo"):
02316             os.mkfifo(targetpath)
02317         else:
02318             raise ExtractError("fifo not supported by system")

Here is the caller graph for this function:

def tarfile.TarFile.makefile (   self,
  tarinfo,
  targetpath 
)
Make a file called targetpath.

Definition at line 2287 of file tarfile.py.

02287 
02288     def makefile(self, tarinfo, targetpath):
02289         """Make a file called targetpath.
02290         """
02291         source = self.fileobj
02292         source.seek(tarinfo.offset_data)
02293         target = bltn_open(targetpath, "wb")
02294         if tarinfo.sparse is not None:
02295             for offset, size in tarinfo.sparse:
02296                 target.seek(offset)
02297                 copyfileobj(source, target, size)
02298         else:
02299             copyfileobj(source, target, tarinfo.size)
02300         target.seek(tarinfo.size)
02301         target.truncate()
02302         target.close()

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.makelink (   self,
  tarinfo,
  targetpath 
)
Make a (symbolic) link called targetpath. If it cannot be created
  (platform limitation), we try to make a copy of the referenced file
  instead of a link.

Definition at line 2334 of file tarfile.py.

02334 
02335     def makelink(self, tarinfo, targetpath):
02336         """Make a (symbolic) link called targetpath. If it cannot be created
02337           (platform limitation), we try to make a copy of the referenced file
02338           instead of a link.
02339         """
02340         try:
02341             # For systems that support symbolic and hard links.
02342             if tarinfo.issym():
02343                 os.symlink(tarinfo.linkname, targetpath)
02344             else:
02345                 # See extract().
02346                 if os.path.exists(tarinfo._link_target):
02347                     os.link(tarinfo._link_target, targetpath)
02348                 else:
02349                     self._extract_member(self._find_link_target(tarinfo),
02350                                          targetpath)
02351         except symlink_exception:
02352             if tarinfo.issym():
02353                 linkpath = os.path.join(os.path.dirname(tarinfo.name),
02354                                         tarinfo.linkname)
02355             else:
02356                 linkpath = tarinfo.linkname
02357         else:
02358             try:
02359                 self._extract_member(self._find_link_target(tarinfo),
02360                                      targetpath)
02361             except KeyError:
02362                 raise ExtractError("unable to resolve link inside archive")

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.makeunknown (   self,
  tarinfo,
  targetpath 
)
Make a file from a TarInfo object with an unknown type
   at targetpath.

Definition at line 2303 of file tarfile.py.

02303 
02304     def makeunknown(self, tarinfo, targetpath):
02305         """Make a file from a TarInfo object with an unknown type
02306            at targetpath.
02307         """
02308         self.makefile(tarinfo, targetpath)
02309         self._dbg(1, "tarfile: Unknown file type %r, " \
02310                      "extracted as regular file." % tarinfo.type)

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.next (   self)
Return the next member of the archive as a TarInfo object, when
   TarFile is opened for reading. Return None if there is no more
   available.

Definition at line 2411 of file tarfile.py.

02411 
02412     def next(self):
02413         """Return the next member of the archive as a TarInfo object, when
02414            TarFile is opened for reading. Return None if there is no more
02415            available.
02416         """
02417         self._check("ra")
02418         if self.firstmember is not None:
02419             m = self.firstmember
02420             self.firstmember = None
02421             return m
02422 
02423         # Read the next block.
02424         self.fileobj.seek(self.offset)
02425         tarinfo = None
02426         while True:
02427             try:
02428                 tarinfo = self.tarinfo.fromtarfile(self)
02429             except EOFHeaderError as e:
02430                 if self.ignore_zeros:
02431                     self._dbg(2, "0x%X: %s" % (self.offset, e))
02432                     self.offset += BLOCKSIZE
02433                     continue
02434             except InvalidHeaderError as e:
02435                 if self.ignore_zeros:
02436                     self._dbg(2, "0x%X: %s" % (self.offset, e))
02437                     self.offset += BLOCKSIZE
02438                     continue
02439                 elif self.offset == 0:
02440                     raise ReadError(str(e))
02441             except EmptyHeaderError:
02442                 if self.offset == 0:
02443                     raise ReadError("empty file")
02444             except TruncatedHeaderError as e:
02445                 if self.offset == 0:
02446                     raise ReadError(str(e))
02447             except SubsequentHeaderError as e:
02448                 raise ReadError(str(e))
02449             break
02450 
02451         if tarinfo is not None:
02452             self.members.append(tarinfo)
02453         else:
02454             self._loaded = True
02455 
02456         return tarinfo

Here is the call graph for this function:

Here is the caller graph for this function:

def tarfile.TarFile.open (   cls,
  name = None,
  mode = "r",
  fileobj = None,
  bufsize = RECORDSIZE,
  kwargs 
)
Open a tar archive for reading, writing or appending. Return
   an appropriate TarFile class.

   mode:
   'r' or 'r:*' open for reading with transparent compression
   'r:'         open for reading exclusively uncompressed
   'r:gz'       open for reading with gzip compression
   'r:bz2'      open for reading with bzip2 compression
   'a' or 'a:'  open for appending, creating the file if necessary
   'w' or 'w:'  open for writing without compression
   'w:gz'       open for writing with gzip compression
   'w:bz2'      open for writing with bzip2 compression

   'r|*'        open a stream of tar blocks with transparent compression
   'r|'         open an uncompressed stream of tar blocks for reading
   'r|gz'       open a gzip compressed stream of tar blocks
   'r|bz2'      open a bzip2 compressed stream of tar blocks
   'w|'         open an uncompressed stream for writing
   'w|gz'       open a gzip compressed stream for writing
   'w|bz2'      open a bzip2 compressed stream for writing

Definition at line 1705 of file tarfile.py.

01705 
01706     def open(cls, name=None, mode="r", fileobj=None, bufsize=RECORDSIZE, **kwargs):
01707         """Open a tar archive for reading, writing or appending. Return
01708            an appropriate TarFile class.
01709 
01710            mode:
01711            'r' or 'r:*' open for reading with transparent compression
01712            'r:'         open for reading exclusively uncompressed
01713            'r:gz'       open for reading with gzip compression
01714            'r:bz2'      open for reading with bzip2 compression
01715            'a' or 'a:'  open for appending, creating the file if necessary
01716            'w' or 'w:'  open for writing without compression
01717            'w:gz'       open for writing with gzip compression
01718            'w:bz2'      open for writing with bzip2 compression
01719 
01720            'r|*'        open a stream of tar blocks with transparent compression
01721            'r|'         open an uncompressed stream of tar blocks for reading
01722            'r|gz'       open a gzip compressed stream of tar blocks
01723            'r|bz2'      open a bzip2 compressed stream of tar blocks
01724            'w|'         open an uncompressed stream for writing
01725            'w|gz'       open a gzip compressed stream for writing
01726            'w|bz2'      open a bzip2 compressed stream for writing
01727         """
01728 
01729         if not name and not fileobj:
01730             raise ValueError("nothing to open")
01731 
01732         if mode in ("r", "r:*"):
01733             # Find out which *open() is appropriate for opening the file.
01734             for comptype in cls.OPEN_METH:
01735                 func = getattr(cls, cls.OPEN_METH[comptype])
01736                 if fileobj is not None:
01737                     saved_pos = fileobj.tell()
01738                 try:
01739                     return func(name, "r", fileobj, **kwargs)
01740                 except (ReadError, CompressionError) as e:
01741                     if fileobj is not None:
01742                         fileobj.seek(saved_pos)
01743                     continue
01744             raise ReadError("file could not be opened successfully")
01745 
01746         elif ":" in mode:
01747             filemode, comptype = mode.split(":", 1)
01748             filemode = filemode or "r"
01749             comptype = comptype or "tar"
01750 
01751             # Select the *open() function according to
01752             # given compression.
01753             if comptype in cls.OPEN_METH:
01754                 func = getattr(cls, cls.OPEN_METH[comptype])
01755             else:
01756                 raise CompressionError("unknown compression type %r" % comptype)
01757             return func(name, filemode, fileobj, **kwargs)
01758 
01759         elif "|" in mode:
01760             filemode, comptype = mode.split("|", 1)
01761             filemode = filemode or "r"
01762             comptype = comptype or "tar"
01763 
01764             if filemode not in "rw":
01765                 raise ValueError("mode must be 'r' or 'w'")
01766 
01767             stream = _Stream(name, filemode, comptype, fileobj, bufsize)
01768             try:
01769                 t = cls(name, filemode, stream, **kwargs)
01770             except:
01771                 stream.close()
01772                 raise
01773             t._extfileobj = False
01774             return t
01775 
01776         elif mode in "aw":
01777             return cls.taropen(name, mode, fileobj, **kwargs)
01778 
01779         raise ValueError("undiscernible mode")

Here is the call graph for this function:

def tarfile.TarFile.taropen (   cls,
  name,
  mode = "r",
  fileobj = None,
  kwargs 
)
Open uncompressed tar archive name for reading or writing.

Definition at line 1781 of file tarfile.py.

01781 
01782     def taropen(cls, name, mode="r", fileobj=None, **kwargs):
01783         """Open uncompressed tar archive name for reading or writing.
01784         """
01785         if len(mode) > 1 or mode not in "raw":
01786             raise ValueError("mode must be 'r', 'a' or 'w'")
01787         return cls(name, mode, fileobj, **kwargs)

def tarfile.TarFile.utime (   self,
  tarinfo,
  targetpath 
)
Set modification time of targetpath according to tarinfo.

Definition at line 2400 of file tarfile.py.

02400 
02401     def utime(self, tarinfo, targetpath):
02402         """Set modification time of targetpath according to tarinfo.
02403         """
02404         if not hasattr(os, 'utime'):
02405             return
02406         try:
02407             os.utime(targetpath, (tarinfo.mtime, tarinfo.mtime))
02408         except EnvironmentError as e:
02409             raise ExtractError("could not change modification time")

Here is the caller graph for this function:


Member Data Documentation

Definition at line 1619 of file tarfile.py.

Definition at line 1655 of file tarfile.py.

Definition at line 1611 of file tarfile.py.

Definition at line 1653 of file tarfile.py.

int tarfile.TarFile.debug = 0 [static]

Definition at line 1575 of file tarfile.py.

Definition at line 1648 of file tarfile.py.

tarfile.TarFile.dereference = False [static]

Definition at line 1577 of file tarfile.py.

Definition at line 1589 of file tarfile.py.

Definition at line 1583 of file tarfile.py.

Definition at line 1650 of file tarfile.py.

tarfile.TarFile.errors = None [static]

Definition at line 1591 of file tarfile.py.

Definition at line 1627 of file tarfile.py.

Definition at line 1595 of file tarfile.py.

Definition at line 1663 of file tarfile.py.

Definition at line 1587 of file tarfile.py.

tarfile.TarFile.ignore_zeros = False [static]

Definition at line 1580 of file tarfile.py.

Definition at line 1658 of file tarfile.py.

Definition at line 1654 of file tarfile.py.

Definition at line 1610 of file tarfile.py.

Definition at line 1626 of file tarfile.py.

Definition at line 107 of file object.h.

struct _typeobject* _object::ob_type [inherited]

Definition at line 108 of file object.h.

Definition at line 1656 of file tarfile.py.

Initial value:
{
        "tar": "taropen",   # uncompressed tar
        "gz":  "gzopen",    # gzip compressed tar
        "bz2": "bz2open"    # bzip2 compressed tar
    }

Definition at line 1846 of file tarfile.py.

Definition at line 1643 of file tarfile.py.

Definition at line 1593 of file tarfile.py.


The documentation for this class was generated from the following file: