cpython: 9d5217aaea13 (original) (raw)

Mercurial > cpython

changeset 100273:9d5217aaea13 2.7

Issues #22468, #21996, #22208: Clarify gettarinfo() and TarInfo usage * Make it more obvious gettarinfo() is based on stat(), and that non-ordinary files may need special care * Filename taken from fileobj.name; suggest dummy arcname as a workaround * Indicate TarInfo may be used directly, not just via gettarinfo() [#22468]

Martin Panter vadmium+py@gmail.com
date	Fri, 19 Feb 2016 23:34:56 +0000
parents	2d8e8d0e7162
children	ada8023878d0
files	Doc/library/tarfile.rst Lib/tarfile.py
diffstat	2 files changed, 23 insertions(+), 13 deletions(-)[+] [-] Doc/library/tarfile.rst 21 Lib/tarfile.py 15

line wrap: on

line diff

--- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -438,20 +438,29 @@ be finalized; only the internally used f 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.

create :class:TarInfo objects directly, or by 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.

Create a :class:TarInfo object from the result of :func:os.stat or
equivalent on an existing file. The file is either named by name, or
specified as a file object fileobj with a file descriptor. If
given, arcname specifies an alternative name for the file in the
archive, otherwise, the name is taken from fileobj’s
:attr:~file.name attribute, or the name argument. +
You can modify some
of the :class:TarInfo’s attributes before you add it using :meth:addfile.
If the file object is not an ordinary file object positioned at the
beginning of the file, attributes such as :attr:~TarInfo.size may need
modifying. This is the case for objects such as :class:~gzip.GzipFile.
The :attr:~TarInfo.name may also be modified, in which case arcname
could be a dummy string.

.. method:: TarFile.close()

--- a/Lib/tarfile.py +++ b/Lib/tarfile.py @@ -1844,11 +1844,12 @@ class TarFile(object): return [tarinfo.name for tarinfo in self.getmembers()] def gettarinfo(self, name=None, arcname=None, fileobj=None):

   """Create a TarInfo object for either the file `name' or the file[](#l2.7)

      object `fileobj' (using os.fstat on its file descriptor). You can[](#l2.8)

      modify some of the TarInfo's attributes before you add it using[](#l2.9)

      addfile(). If given, `arcname' specifies an alternative name for the[](#l2.10)

```
      file in the archive.[](#l2.11)
```

   """Create a TarInfo object from the result of os.stat or equivalent[](#l2.12)

      on an existing file. The file is either named by `name', or[](#l2.13)

      specified as a file object `fileobj' with a file descriptor. If[](#l2.14)

      given, `arcname' specifies an alternative name for the file in the[](#l2.15)

      archive, otherwise, the name is taken from the 'name' attribute of[](#l2.16)

      'fileobj', or the 'name' argument.[](#l2.17)
   """[](#l2.18)
   self._check("aw")[](#l2.19)

@@ -1869,7 +1870,7 @@ class TarFile(object): # Now, fill the TarInfo object with # information specific for the file. tarinfo = self.tarinfo()

```
   tarinfo.tarfile = self[](#l2.25)
```

   tarinfo.tarfile = self  # Not needed[](#l2.26)

# Use os.stat or os.lstat, depending on platform # and if symlinks shall be resolved. @@ -2034,7 +2035,7 @@ class TarFile(object): def 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().[](#l2.34)

      You can create TarInfo objects directly, or by using gettarinfo().[](#l2.35)
      On Windows platforms, `fileobj' should always be opened with mode[](#l2.36)
      'rb' to avoid irritation about the file size.[](#l2.37)
   """[](#l2.38)