Issues #22468, #21996, #22208: Clarify gettarinfo() and TarInfo usage
* The Windows-specific binary notice was probably a Python 2 thing
* Make it more obvious gettarinfo() is based on stat(), and that non-ordinary
files may need special care
* The file name must be text; suggest dummy arcname as a workaround
* Indicate TarInfo may be used directly, not just via gettarinfo()
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 @@
.. 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()