[Python-checkins] cpython (2.7): Issues #22468, #21996, #22208: Clarify gettarinfo() and TarInfo usage
martin.panter
python-checkins at python.org
Fri Feb 19 19:18:59 EST 2016
https://hg.python.org/cpython/rev/9d5217aaea13
changeset: 100273:9d5217aaea13
branch: 2.7
parent: 100268:2d8e8d0e7162
user: Martin Panter <vadmium+py at gmail.com>
date: Fri Feb 19 23:34:56 2016 +0000
summary:
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()
files:
Doc/library/tarfile.rst | 21 +++++++++++++++------
Lib/tarfile.py | 15 ++++++++-------
2 files changed, 23 insertions(+), 13 deletions(-)
diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst
--- a/Doc/library/tarfile.rst
+++ b/Doc/library/tarfile.rst
@@ -438,20 +438,29 @@
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()
diff --git a/Lib/tarfile.py b/Lib/tarfile.py
--- a/Lib/tarfile.py
+++ b/Lib/tarfile.py
@@ -1844,11 +1844,12 @@
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.
"""
self._check("aw")
@@ -1869,7 +1870,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.
@@ -2034,7 +2035,7 @@
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().
+ You can create TarInfo objects directly, or by using gettarinfo().
On Windows platforms, `fileobj' should always be opened with mode
'rb' to avoid irritation about the file size.
"""
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list