(original) (raw)

changeset: 100272:e66c476b25ec parent: 100270:f9391e2b74a5 parent: 100271:94a94deaf06a user: Martin Panter vadmium+py@gmail.com date: Fri Feb 19 23:46:59 2016 +0000 files: Lib/tarfile.py description: Issue #22468: Merge gettarinfo() doc from 3.5 diff -r f9391e2b74a5 -r e66c476b25ec Doc/library/tarfile.rst --- a/Doc/library/tarfile.rst Fri Feb 19 08:57:50 2016 +0100 +++ b/Doc/library/tarfile.rst Fri Feb 19 23:46:59 2016 +0000 @@ -456,21 +456,28 @@ .. 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 -r f9391e2b74a5 -r e66c476b25ec Lib/tarfile.py --- a/Lib/tarfile.py Fri Feb 19 08:57:50 2016 +0100 +++ b/Lib/tarfile.py Fri Feb 19 23:46:59 2016 +0000 @@ -1757,11 +1757,13 @@ 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 @@ # 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 @@ 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") /vadmium+py@gmail.com