diff options
| -rw-r--r-- | Doc/library/tarfile.rst | 27 | ||||
| -rwxr-xr-x | Lib/tarfile.py | 21 |
2 files changed, 28 insertions, 20 deletions
diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index e418d5b..7a233c1 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -456,21 +456,28 @@ be finalized; only the internally used file object will be closed. See the .. method:: TarFile.addfile(tarinfo, fileobj=None) Add the :class:`TarInfo` object *tarinfo* to the archive. If *fileobj* is given, + it should be a :term:`binary file`, and ``tarinfo.size`` bytes are read from it and added to the archive. You can - create :class:`TarInfo` objects using :meth:`gettarinfo`. - - .. note:: - - On Windows platforms, *fileobj* should always be opened with mode ``'rb'`` to - avoid irritation about the file size. + create :class:`TarInfo` objects directly, or by using :meth:`gettarinfo`. .. method:: TarFile.gettarinfo(name=None, arcname=None, fileobj=None) - Create a :class:`TarInfo` object for either the file *name* or the :term:`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 :term:`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:`~io.FileIO.name` attribute, or the *name* argument. The name + should be a text string. + + 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() diff --git a/Lib/tarfile.py b/Lib/tarfile.py index 7d43b1e..1ac7007 100755 --- a/Lib/tarfile.py +++ b/Lib/tarfile.py @@ -1757,11 +1757,13 @@ 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 - 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. + """Create a TarInfo object from the result of 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 the 'name' attribute of + 'fileobj', or the 'name' argument. The name should be a text + string. """ self._check("awx") @@ -1782,7 +1784,7 @@ class TarFile(object): # Now, fill the TarInfo object with # information specific for the file. tarinfo = self.tarinfo() - tarinfo.tarfile = self + tarinfo.tarfile = self # Not needed # Use os.stat or os.lstat, depending on platform # and if symlinks shall be resolved. @@ -1949,10 +1951,9 @@ 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(). - On Windows platforms, `fileobj' should always be opened with mode - 'rb' to avoid irritation about the file size. + given, it should be a binary file, and tarinfo.size bytes are read + from it and added to the archive. You can create TarInfo objects + directly, or by using gettarinfo(). """ self._check("awx") |