bpo-28230: Document the pathlib support in tarfile and add tests. (#512)
diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst
index 2167f32..2450716 100644
--- a/Doc/library/tarfile.rst
+++ b/Doc/library/tarfile.rst
@@ -146,6 +146,10 @@
.. versionchanged:: 3.5
The ``'x'`` (exclusive creation) mode was added.
+ .. versionchanged:: 3.6
+ The *name* parameter accepts a :term:`path-like object`.
+
+
.. class:: TarFile
Class for reading and writing tar archives. Do not use this class directly:
@@ -266,7 +270,8 @@
All following arguments are optional and can be accessed as instance attributes
as well.
- *name* is the pathname of the archive. It can be omitted if *fileobj* is given.
+ *name* is the pathname of the archive. *name* may be a :term:`path-like object`.
+ It can be omitted if *fileobj* is given.
In this case, the file object's :attr:`name` attribute is used if it exists.
*mode* is either ``'r'`` to read from an existing archive, ``'a'`` to append
@@ -319,6 +324,10 @@
.. versionchanged:: 3.5
The ``'x'`` (exclusive creation) mode was added.
+ .. versionchanged:: 3.6
+ The *name* parameter accepts a :term:`path-like object`.
+
+
.. classmethod:: TarFile.open(...)
Alternative constructor. The :func:`tarfile.open` function is actually a
@@ -390,14 +399,17 @@
.. versionchanged:: 3.5
Added the *numeric_owner* parameter.
+ .. versionchanged:: 3.6
+ The *path* parameter accepts a :term:`path-like object`.
+
.. method:: TarFile.extract(member, path="", set_attrs=True, *, numeric_owner=False)
Extract a member from the archive to the current working directory, using its
full name. Its file information is extracted as accurately as possible. *member*
may be a filename or a :class:`TarInfo` object. You can specify a different
- directory using *path*. File attributes (owner, mtime, mode) are set unless
- *set_attrs* is false.
+ directory using *path*. *path* may be a :term:`path-like object`.
+ File attributes (owner, mtime, mode) are set unless *set_attrs* is false.
If *numeric_owner* is :const:`True`, the uid and gid numbers from the tarfile
are used to set the owner/group for the extracted files. Otherwise, the named
@@ -418,6 +430,10 @@
.. versionchanged:: 3.5
Added the *numeric_owner* parameter.
+ .. versionchanged:: 3.6
+ The *path* parameter accepts a :term:`path-like object`.
+
+
.. method:: TarFile.extractfile(member)
Extract a member from the archive as a file object. *member* may be a filename
@@ -457,7 +473,8 @@
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
+ specified as a :term:`file object` *fileobj* with a file descriptor.
+ *name* may be a :term:`path-like object`. 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
@@ -471,6 +488,9 @@
The :attr:`~TarInfo.name` may also be modified, in which case *arcname*
could be a dummy string.
+ .. versionchanged:: 3.6
+ The *name* parameter accepts a :term:`path-like object`.
+
.. method:: TarFile.close()