summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
authorSerhiy Storchaka <storchaka@gmail.com>2017-03-08 08:32:44 (GMT)
committerGitHub <noreply@github.com>2017-03-08 08:32:44 (GMT)
commitc45cd167d403d7d98078d5fc4a37b16195dc7a35 (patch)
tree542232a6009ca248d11342b88e9290978545641a /Doc/library
parent21a74312f2d1ddee71fade709af49d078085ec30 (diff)
downloadcpython-c45cd167d403d7d98078d5fc4a37b16195dc7a35.zip
cpython-c45cd167d403d7d98078d5fc4a37b16195dc7a35.tar.gz
cpython-c45cd167d403d7d98078d5fc4a37b16195dc7a35.tar.bz2
bpo-28230: Document the pathlib support in tarfile and add tests. (#512)
Diffstat (limited to 'Doc/library')
-rw-r--r--Doc/library/tarfile.rst28
1 files changed, 24 insertions, 4 deletions
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 @@ Some facts and figures:
.. 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 @@ be finalized; only the internally used file object will be closed. See the
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 @@ be finalized; only the internally used file object will be closed. See the
.. 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 @@ be finalized; only the internally used file object will be closed. See the
.. 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 @@ be finalized; only the internally used file object will be closed. See the
.. 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 @@ be finalized; only the internally used file object will be closed. See the
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 @@ be finalized; only the internally used file object will be closed. See the
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()