[Python-checkins] r63411 - python/trunk/Doc/library/tarfile.rst
lars.gustaebel
python-checkins at python.org
Sat May 17 18:50:22 CEST 2008
Author: lars.gustaebel
Date: Sat May 17 18:50:22 2008
New Revision: 63411
Log:
Replace signatures with optional arguments in square brackets with
keyword arguments and the actual default values.
Fix references that point nowhere or to the wrong place.
Add description of the ENCODING module-level variable.
Fix the URL pointing to the GNU tar manual.
Remove two obsolete examples.
Add an example on how to use a generator with TarFile.extractall().
Modified:
python/trunk/Doc/library/tarfile.rst
Modified: python/trunk/Doc/library/tarfile.rst
==============================================================================
--- python/trunk/Doc/library/tarfile.rst (original)
+++ python/trunk/Doc/library/tarfile.rst Sat May 17 18:50:22 2008
@@ -34,10 +34,8 @@
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 @@
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 @@
.. 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 @@
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 @@
.. 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 @@
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 @@
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 @@
.. 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 @@
.. 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 @@
.. 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 @@
.. 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 @@
.. 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 @@
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 @@
: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 @@
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 @@
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 @@
:meth:`getmember`, :meth:`getmembers` and :meth:`gettarinfo`.
-.. class:: TarInfo([name])
+.. class:: TarInfo(name="")
Create a :class:`TarInfo` object.
@@ -472,7 +479,7 @@
.. 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 @@
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 @@
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:
More information about the Python-checkins
mailing list