Adding upstream version 2.7.6.upstream/2.7.6

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 323 insertions, 0 deletions

diff --git a/doc/source/library/apt_inst.rst b/doc/source/library/apt_inst.rst
new file mode 100644
index 0000000..6ba330a
--- /dev/null
+++ b/doc/source/library/apt_inst.rst
@@ -0,0 +1,323 @@
+:mod:`apt_inst` - Working with local Debian packages
+====================================================
+.. module:: apt_inst
+
+This module provides useful classes and functions to work with archives,
+modelled after the :class:`tarfile.TarFile` class. For working with Debian
+packages, the :class:`DebFile` class should be used as it provides easy access
+to the control.tar.* and data.tar.* members.
+
+The classes are mostly modeled after the :class:`tarfile.TarFile` class and
+enhanced with APT-specific methods. Because APT only provides a stream based
+view on a tar archive, this module's :class:`TarFile` class only provides a
+very small subset of those functions.
+
+Exceptions
+----------
+
+.. class:: Error
+
+    This is the same class as :class:`apt_pkg.Error`, provided here for
+    convenience.
+
+AR Archives
+-----------
+.. class:: ArArchive(file)
+
+    An ArArchive object represents an archive in the 4.4 BSD AR format,
+    which is used for e.g. deb packages.
+
+    The parameter *file* may be a string specifying the path of a file, or
+    a :class:`file`-like object providing the :meth:`fileno` method. It may
+    also be an int specifying a file descriptor (returned by e.g.
+    :func:`os.open`). The recommended way is to pass in the path to the file.
+
+    ArArchive (and its subclasses) support the iterator protocol, meaning that
+    an :class:`ArArchive` object can be iterated over yielding the members in
+    the archive (same as :meth:`getmembers`).
+
+    .. describe:: archive[key]
+
+        Return a ArMember object for the member given by *key*. Raise
+        LookupError if there is no ArMember with the given name.
+
+    .. describe:: key in archive
+
+        Return True if a member with the name *key* is found in the archive, it
+        is the same function as :meth:`getmember`.
+
+    .. method:: extract(name[, target: str]) -> bool
+
+        Extract the member given by *name* into the directory given by
+        *target*. If the extraction failed, an error is raised. Otherwise,
+        the method returns True if the owner could be set or False if the
+        owner could not be changed. It may also raise LookupError if there
+        is no member with the given name.
+
+        The parameter *target* is completely optional. If it is not given, the
+        function extracts into the current directory.
+
+    .. method:: extractall([target: str]) -> bool
+
+         Extract all into the directory given by target or the current
+         directory if target is not given. If the extraction failed, an error
+         is raised. Otherwise, the method returns True if the owner could be
+         set or False if the owner could not be changed.
+
+    .. method:: extractdata(name: str) -> bytes
+
+        Return the contents of the member given by *name*, as a bytes object.
+        Raise LookupError if there is no ArMember with the given name.
+
+    .. method:: getmember(name: str) -> ArMember
+
+        Return a ArMember object for the member given by *name*. Raise
+        LookupError if there is no ArMember with the given name.
+
+    .. method:: getmembers() -> list
+
+        Return a list of all members in the AR archive.
+
+    .. method:: getnames() -> list
+
+        Return a list of the names of all members in the AR archive.
+
+    .. method:: gettar(name: str, comp: str) -> TarFile
+
+        Return a TarFile object for the member given by *name* which will be
+        decompressed using the compression algorithm given by *comp*.
+        This is almost equal to::
+
+           member = arfile.getmember(name)
+           tarfile = TarFile(file, member.start, member.size, 'gzip')'
+
+        It just opens a new TarFile on the given position in the stream.
+
+.. class:: ArMember
+
+    An ArMember object represents a single file within an AR archive. For
+    Debian packages this can be e.g. control.tar.gz. This class provides
+    information about this file, such as the mode and size. It has no
+    constructor.
+
+    .. attribute:: gid
+
+        The group id of the owner.
+
+    .. attribute:: mode
+
+        The mode of the file.
+
+    .. attribute:: mtime
+
+        Last time of modification.
+
+    .. attribute:: name
+
+        The name of the file.
+
+    .. attribute:: size
+
+        The size of the files.
+
+    .. attribute:: start
+
+        The offset in the archive where the file starts.
+
+    .. attribute:: uid
+
+        The user id of the owner.
+
+Debian Packages
+---------------
+.. class:: DebFile(file)
+
+    A DebFile object represents a file in the .deb package format. It inherits
+    :class:`ArArchive`. In addition to the attributes and methods from
+    :class:`ArArchive`, DebFile provides the following methods:
+
+    .. attribute:: control
+
+        The :class:`TarFile` object associated with the control.tar.gz member.
+
+    .. attribute:: data
+
+        The :class:`TarFile` object associated with the
+        data.tar.{gz,bz2,lzma,xz} member.
+
+    .. attribute:: debian_binary
+
+        The package version, as contained in debian-binary.
+
+Tar Archives
+-------------
+.. class:: TarFile(file[, min: int, max: int, comp: str])
+
+    A TarFile object represents a single .tar file stream.
+
+    The parameter *file* may be a string specifying the path of a file, or
+    a :class:`file`-like object providing the :meth:`fileno` method. It may
+    also be an int specifying a file descriptor (returned by e.g.
+    :func:`os.open`).
+
+    The parameter *min* describes the offset in the file where the archive
+    begins and the parameter *max* is the size of the archive.
+
+    The compression of the archive is set by the parameter *comp*. It can
+    be set to any program supporting the -d switch, the default being gzip.
+
+    .. method:: extractall([rootdir: str]) -> True
+
+        Extract the archive in the current directory. The argument *rootdir*
+        can be used to change the target directory.
+
+    .. method:: extractdata(member: str) -> bytes
+
+        Return the contents of the member, as a bytes object. Raise
+        LookupError if there is no member with the given name.
+
+    .. method:: go(callback: callable[, member: str]) -> True
+
+        Go through the archive and call the callable *callback* for each
+        member with 2 arguments. The first argument is the :class:`TarMember`
+        and the second one is the data, as bytes.
+
+        The optional parameter *member* can be used to specify the member for
+        which call the callback. If not specified, it will be called for all
+        members. If specified and not found, LookupError will be raised.
+
+.. class:: TarMember
+
+    Represent a single member of a 'tar' archive.
+
+    This class which has been modelled after :class:`tarfile.TarInfo`
+    represents information about a given member in an archive.
+
+    .. method:: isblk()
+
+        Determine whether the member is a block device.
+
+    .. method:: ischr()
+
+        Determine whether the member is a character device.
+
+    .. method:: isdev()
+
+        Determine whether the member is a device (block,character or FIFO).
+
+    .. method:: isdir()
+
+        Determine whether the member is a directory.
+
+    .. method:: isfifo()
+
+        Determine whether the member is a FIFO.
+
+    .. method:: isfile()
+
+        Determine whether the member is a regular file.
+        
+    .. method:: islnk()
+
+        Determine whether the member is a hardlink.
+
+    .. method:: isreg()
+
+        Determine whether the member is a regular file, same as isfile().
+
+    .. method:: issym()
+
+        Determine whether the member is a symbolic link.
+        
+    .. attribute:: gid
+
+        The owner's group id
+
+    .. attribute:: linkname
+
+        The target of the link.
+
+    .. attribute:: major
+
+        The major ID of the device.
+
+    .. attribute:: minor
+
+        The minor ID of the device.
+
+    .. attribute:: mode
+
+        The mode (permissions).
+
+    .. attribute:: mtime
+
+        Last time of modification.
+
+    .. attribute:: name
+
+        The name of the file.
+
+    .. attribute:: size
+
+        The size of the file.
+
+    .. attribute:: uid
+
+        The owner's user id.
+
+
+
+Removed functions
+---------------------
+The following functions have been removed in python-apt 0.8.
+They are listed here to help developers port their applications to the new
+API which is completely different. For this purpose each function documentation
+includes an example showing how the function can be replaced.
+
+.. function:: arCheckMember(file, membername)
+
+    This function has been replaced by using the :keyword:`in` check on an
+    :class:`ArArchive` object::
+
+        member in ArArchive(file)
+
+.. function:: debExtract(file, func, chunk)
+
+    This function has been replaced by the :meth:`TarFile.go`
+    method. The following example shows the old code and the new code::
+
+        debExtract(open("package.deb"), my_callback, "data.tar.gz") #old
+
+        DebFile("package.deb").data.go(my_callback)
+
+    Please note that the signature of the callback is different in
+    :meth:`TarFile.go`.
+
+.. function:: tarExtract(file,func,comp)
+
+    This function has been replaced by the :meth:`TarFile.go`
+    method. The following example shows the old code and the new code::
+
+        tarExtract(open("archive.tar.gz"), my_callback, "gzip") #old
+        TarFile("archive.tar.gz", 0, 0, "gzip").go(my_callback)
+
+    Please note that the signature of the callback is different in
+    :meth:`TarFile.go`, it now expects a :class:`TarMember` and a bytestring
+    of the data.
+
+.. function:: debExtractArchive(file, rootdir)
+
+    This function has been replaced by :meth:`TarFile.extractall` and
+    :attr:`DebFile.data`::
+
+        debExtractArchive(open("package.deb"), rootdir) # old
+        DebFile("package.deb").data.extractall(rootdir) # new
+
+.. function:: debExtractControl(file[, member='control'])
+
+    This function has been replaced by :attr:`DebFile.control` and
+    :meth:`TarFile.extractdata`. In the following example, both commands
+    return the contents of the control file::
+
+        debExtractControl(open("package.deb"))
+        DebFile("package.deb").control.extractdata("control")