diff options
| -rw-r--r-- | Doc/library/tarfile.rst | 102 |
1 files changed, 51 insertions, 51 deletions
diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index ff25fe914f..b62148aead 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -34,10 +34,8 @@ Some facts and figures: character devices and block devices and is able to acquire and restore file information like timestamp, access permissions and owner. -* can handle tape devices. - -.. function:: open(name[, mode[, fileobj[, bufsize]]], **kwargs) +.. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, \*\*kwargs) Return a :class:`TarFile` object for the pathname *name*. For detailed information on :class:`TarFile` objects and the keyword arguments that are @@ -78,7 +76,7 @@ Some facts and figures: for *name*. It is supposed to be at position 0. For special purposes, there is a second format for *mode*: - ``'filemode|[compression]'``. :func:`open` will return a :class:`TarFile` + ``'filemode|[compression]'``. :func:`tarfile.open` will return a :class:`TarFile` object that processes its data as a stream of blocks. No random seeking will be done on the file. If given, *fileobj* may be any object that has a :meth:`read` or :meth:`write` method (depending on the *mode*). *bufsize* @@ -116,7 +114,7 @@ Some facts and figures: .. class:: TarFile Class for reading and writing tar archives. Do not use this class directly, - better use :func:`open` instead. See :ref:`tarfile-objects`. + better use :func:`tarfile.open` instead. See :ref:`tarfile-objects`. .. function:: is_tarfile(name) @@ -125,7 +123,7 @@ Some facts and figures: module can read. -.. class:: TarFileCompat(filename[, mode[, compression]]) +.. class:: TarFileCompat(filename, mode='r', compression=TAR_PLAIN) Class for limited access to tar archives with a :mod:`zipfile`\ -like interface. Please consult the documentation of the :mod:`zipfile` module for more details. @@ -167,16 +165,17 @@ Some facts and figures: .. exception:: ExtractError - Is raised for *non-fatal* errors when using :meth:`extract`, but only if + Is raised for *non-fatal* errors when using :meth:`TarFile.extract`, but only if :attr:`TarFile.errorlevel`\ ``== 2``. .. exception:: HeaderError - Is raised by :meth:`frombuf` if the buffer it gets is invalid. + Is raised by :meth:`TarInfo.frombuf` if the buffer it gets is invalid. .. versionadded:: 2.6 + Each of the following constants defines a tar archive format that the :mod:`tarfile` module is able to create. See section :ref:`tar-formats` for details. @@ -202,12 +201,21 @@ details. The default format for creating archives. This is currently :const:`GNU_FORMAT`. +The following variables are available on module level: + + +.. data:: ENCODING + + The default character encoding i.e. the value from either + :func:`sys.getfilesystemencoding` or :func:`sys.getdefaultencoding`. + + .. seealso:: Module :mod:`zipfile` Documentation of the :mod:`zipfile` standard module. - `GNU tar manual, Basic Tar Format <http://www.gnu.org/software/tar/manual/html_node/tar_134.html#SEC134>`_ + `GNU tar manual, Basic Tar Format <http://www.gnu.org/software/tar/manual/html_node/Standard.html>`_ Documentation for tar archive files, including GNU tar extensions. @@ -223,7 +231,7 @@ archive several times. Each archive member is represented by a :class:`TarInfo` object, see :ref:`tarinfo-objects` for details. -.. class:: TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=None, errors=None, pax_headers=None, debug=0, errorlevel=0) +.. class:: TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors=None, pax_headers=None, debug=0, errorlevel=0) All following arguments are optional and can be accessed as instance attributes as well. @@ -254,18 +262,18 @@ object, see :ref:`tarinfo-objects` for details. .. versionadded:: 2.6 - If *dereference* is ``False``, add symbolic and hard links to the archive. If it - is ``True``, add the content of the target files to the archive. This has no + If *dereference* is :const:`False`, add symbolic and hard links to the archive. If it + is :const:`True`, add the content of the target files to the archive. This has no effect on systems that do not support symbolic links. - If *ignore_zeros* is ``False``, treat an empty block as the end of the archive. - If it is *True*, skip empty (and invalid) blocks and try to get as many members + If *ignore_zeros* is :const:`False`, treat an empty block as the end of the archive. + If it is :const:`True`, skip empty (and invalid) blocks and try to get as many members as possible. This is only useful for reading concatenated or damaged archives. *debug* can be set from ``0`` (no debug messages) up to ``3`` (all debug messages). The messages are written to ``sys.stderr``. - If *errorlevel* is ``0``, all errors are ignored when using :meth:`extract`. + If *errorlevel* is ``0``, all errors are ignored when using :meth:`TarFile.extract`. Nevertheless, they appear as error messages in the debug output, when debugging is enabled. If ``1``, all *fatal* errors are raised as :exc:`OSError` or :exc:`IOError` exceptions. If ``2``, all *non-fatal* errors are raised as @@ -285,8 +293,8 @@ object, see :ref:`tarinfo-objects` for details. .. method:: TarFile.open(...) - Alternative constructor. The :func:`open` function on module level is actually a - shortcut to this classmethod. See section :ref:`tarfile-mod` for details. + Alternative constructor. The :func:`tarfile.open` function is actually a + shortcut to this classmethod. .. method:: TarFile.getmember(name) @@ -322,11 +330,11 @@ object, see :ref:`tarinfo-objects` for details. .. method:: TarFile.next() Return the next member of the archive as a :class:`TarInfo` object, when - :class:`TarFile` is opened for reading. Return ``None`` if there is no more + :class:`TarFile` is opened for reading. Return :const:`None` if there is no more available. -.. method:: TarFile.extractall([path[, members]]) +.. method:: TarFile.extractall(path=".", members=None) Extract all members from the archive to the current working directory or directory *path*. If optional *members* is given, it must be a subset of the @@ -346,7 +354,7 @@ object, see :ref:`tarinfo-objects` for details. .. versionadded:: 2.5 -.. method:: TarFile.extract(member[, path]) +.. method:: TarFile.extract(member, path="") 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* @@ -355,9 +363,8 @@ object, see :ref:`tarinfo-objects` for details. .. note:: - Because the :meth:`extract` method allows random access to a tar archive there - are some issues you must take care of yourself. See the description for - :meth:`extractall` above. + The :meth:`extract` method does not take care of several extraction issues. + In most cases you should consider using the :meth:`extractall` method. .. warning:: @@ -369,7 +376,7 @@ object, see :ref:`tarinfo-objects` for details. Extract a member from the archive as a file object. *member* may be a filename or a :class:`TarInfo` object. If *member* is a regular file, a file-like object is returned. If *member* is a link, a file-like object is constructed from the - link's target. If *member* is none of the above, ``None`` is returned. + link's target. If *member* is none of the above, :const:`None` is returned. .. note:: @@ -377,7 +384,7 @@ object, see :ref:`tarinfo-objects` for details. :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`seek`, :meth:`tell`. -.. method:: TarFile.add(name[, arcname[, recursive[, exclude]]]) +.. method:: TarFile.add(name, arcname=None, recursive=True, exclude=None) Add the file *name* to the archive. *name* may be any type of file (directory, fifo, symbolic link, etc.). If given, *arcname* specifies an alternative name @@ -391,7 +398,7 @@ object, see :ref:`tarinfo-objects` for details. Added the *exclude* parameter. -.. method:: TarFile.addfile(tarinfo[, fileobj]) +.. method:: TarFile.addfile(tarinfo, fileobj=None) 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 @@ -403,7 +410,7 @@ object, see :ref:`tarinfo-objects` for details. avoid irritation about the file size. -.. method:: TarFile.gettarinfo([name[, arcname[, fileobj]]]) +.. 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 @@ -451,7 +458,7 @@ It does *not* contain the file's data itself. :meth:`getmember`, :meth:`getmembers` and :meth:`gettarinfo`. -.. class:: TarInfo([name]) +.. class:: TarInfo(name="") Create a :class:`TarInfo` object. @@ -472,7 +479,7 @@ It does *not* contain the file's data itself. .. versionadded:: 2.6 -.. method:: TarInfo.tobuf([format[, encoding [, errors]]]) +.. method:: TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='strict') Create a string buffer from a :class:`TarInfo` object. For information on the arguments see the constructor of the :class:`TarFile` class. @@ -604,6 +611,21 @@ How to extract an entire tar archive to the current working directory:: tar.extractall() tar.close() +How to extract a subset of a tar archive with :meth:`TarFile.extractall` using +a generator function instead of a list:: + + import os + import tarfile + + def py_files(members): + for tarinfo in members: + if os.path.splitext(tarinfo.name)[1] == ".py": + yield tarinfo + + tar = tarfile.open("sample.tar.gz") + tar.extractall(members=py_files(tar)) + tar.close() + How to create an uncompressed tar archive from a list of filenames:: import tarfile @@ -626,28 +648,6 @@ How to read a gzip compressed tar archive and display some member information:: print "something else." tar.close() -How to create a tar archive with faked information:: - - import tarfile - tar = tarfile.open("sample.tar.gz", "w:gz") - for name in namelist: - tarinfo = tar.gettarinfo(name, "fakeproj-1.0/" + name) - tarinfo.uid = 123 - tarinfo.gid = 456 - tarinfo.uname = "johndoe" - tarinfo.gname = "fake" - tar.addfile(tarinfo, file(name)) - tar.close() - -The *only* way to extract an uncompressed tar stream from ``sys.stdin``:: - - import sys - import tarfile - tar = tarfile.open(mode="r|", fileobj=sys.stdin) - for tarinfo in tar: - tar.extract(tarinfo) - tar.close() - .. _tar-formats: |