merge from the debian experimental branch

24 files changed, 2614 insertions, 0 deletions

diff --git a/doc/source/apt/cache.rst b/doc/source/apt/cache.rst
new file mode 100644
index 00000000..d96cba97
--- /dev/null
+++ b/doc/source/apt/cache.rst
@@ -0,0 +1,78 @@
+:mod:`apt.cache` --- The Cache class
+=====================================
+.. automodule:: apt.cache
+
+The Cache class
+---------------
+
+.. autoclass:: Cache
+    :members:
+    :undoc-members:
+
+    .. describe:: cache[pkgname]
+
+        Return a :class:`Package()` for the package with the name *pkgname*.
+
+Example
+^^^^^^^
+
+The following example shows how to load the cache, update it, and upgrade
+all the packages on the system::
+
+    import apt
+    import apt.progress
+
+    # First of all, open the cache
+    cache = apt.Cache()
+    # Now, lets update the package list
+    cache.update()
+    # We need to re-open the cache because it needs to read the package list
+    cache.open(None)
+    # Now we can do the same as 'apt-get upgrade' does
+    cache.upgrade()
+    # or we can play 'apt-get dist-upgrade'
+    cache.upgrade(True)
+    # Q: Why does nothing happen?
+    # A: You forgot to call commit()!
+    cache.commit(apt.progress.TextFetchProgress(),
+                 apt.progress.InstallProgress())
+
+
+
+Working with Filters
+--------------------
+.. autoclass:: Filter
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+.. autoclass:: MarkedChangesFilter
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+.. autoclass:: FilteredCache
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+
+Example
+^^^^^^^
+
+This is an example for a filtered cache, which only allows access to the
+packages whose state has been changed, eg. packages marked for installation::
+
+    >>> from apt.cache import FilteredCache, Cache, MarkedChangesFilter
+    >>> cache = apt.Cache()
+    >>> changed = apt.FilteredCache(cache)
+    >>> changed.setFilter(MarkedChangesFilter())
+    >>> print len(changed) == len(cache.GetChanges()) # Both need to have same length
+    True
+
+
+Exceptions
+----------
+.. autoexception:: FetchCancelledException
+.. autoexception:: FetchFailedException
+.. autoexception:: LockFailedException
diff --git a/doc/source/apt/cdrom.rst b/doc/source/apt/cdrom.rst
new file mode 100644
index 00000000..56381f14
--- /dev/null
+++ b/doc/source/apt/cdrom.rst
@@ -0,0 +1,7 @@
+:mod:`apt.cdrom` - Functionality like in apt-cdrom
+====================================================
+.. automodule:: apt.cdrom
+    :members:
+
+
+
diff --git a/doc/source/apt/debfile.rst b/doc/source/apt/debfile.rst
new file mode 100644
index 00000000..7133b5a8
--- /dev/null
+++ b/doc/source/apt/debfile.rst
@@ -0,0 +1,39 @@
+:mod:`apt.debfile` --- Classes related to debian package files
+==============================================================
+The :mod:`apt.debfile` provides classes to work with locally available
+debian packages, or source packages.
+
+.. module:: apt.debfile
+
+Binary packages
+----------------
+.. autoclass:: DebPackage
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+    The :class:`DebPackage` class is a class for working with '.deb' files,
+    also known as Debian packages.
+
+    It provides methods and attributes to get a list of the files in the
+    package, to install the package and much more.
+
+    If you specify *cache* it has to point to an :class:`apt.cache.Cache()`
+    object.
+
+    .. versionchanged:: 0.7.9
+        Introduce all new methods (everything except for :meth:`open()` and
+        :attr:`filelist`)
+
+
+Source packages
+----------------
+.. autoclass:: DscSrcPackage
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+    Provide functionality to work with locally available source packages,
+    especially with their '.dsc' file.
+
+    .. versionadded:: 0.7.9
diff --git a/doc/source/apt/gtk.widgets.rst b/doc/source/apt/gtk.widgets.rst
new file mode 100644
index 00000000..9fa84ead
--- /dev/null
+++ b/doc/source/apt/gtk.widgets.rst
@@ -0,0 +1,29 @@
+:mod:`apt.gtk.widgets` --- GTK widgets
+======================================
+.. automodule:: apt.gtk.widgets
+
+
+GObject progress classes
+-------------------------
+
+.. autoclass:: GDpkgInstallProgress
+    :members:
+
+.. autoclass:: GFetchProgress
+    :members:
+
+.. autoclass:: GInstallProgress
+    :members:
+
+.. autoclass:: GOpProgress
+    :members:
+
+GTK+ Class
+----------
+.. autoclass:: GtkAptProgress
+    :members:
+
+
+Example
+-------
+.. literalinclude:: ../examples/apt-gtk.py
diff --git a/doc/source/apt/index.rst b/doc/source/apt/index.rst
new file mode 100644
index 00000000..5047a0fd
--- /dev/null
+++ b/doc/source/apt/index.rst
@@ -0,0 +1,58 @@
+:mod:`apt` --- Highlevel apt package
+=====================================
+The highlevel apt package provides a lot of functionality, all
+with an easy-to-use interface.
+
+.. warning::
+    The API of this package is not considered stable. Evenmore, it is considered
+    to change the naming conventions in future to lowercase_with_underscores.
+
+    In case this happens, the API will still be kept compatible, with the old
+    functions provided as deprecated ones.
+
+.. automodule:: apt
+    :members:
+
+
+
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *
+
+
+Classes exported in apt
+------------------------
+These classes are defined in the submodules, but are also exported directly
+in the package.
+
+.. class:: Cache
+
+    Please see :class:`apt.cache.Cache` for documentation.
+
+.. class:: Cdrom
+
+    Please see :class:`apt.cdrom.Cdrom` for documentation.
+
+.. class:: CdromProgress
+
+    Please see :class:`apt.progress.CdromProgress` for documentation.
+
+.. class:: FetchProgress
+
+    Please see :class:`apt.progress.FetchProgress` for documentation.
+
+.. class:: InstallProgress
+
+    Please see :class:`apt.progress.InstallProgress` for documentation.
+
+.. class:: OpProgress
+
+    Please see :class:`apt.progress.OpProgress` for documentation.
+
+.. class:: Package
+
+    Please see :class:`apt.package.Package` for documentation.
+
diff --git a/doc/source/apt/package.rst b/doc/source/apt/package.rst
new file mode 100644
index 00000000..1bd032ab
--- /dev/null
+++ b/doc/source/apt/package.rst
@@ -0,0 +1,101 @@
+:mod:`apt.package` --- Classes for package handling
+====================================================
+
+
+.. automodule:: apt.package
+
+
+The Package class
+-----------------
+.. autoclass:: Package
+    :members:
+
+
+Dependency Information
+----------------------
+.. class:: BaseDependency
+
+    The :class:`BaseDependency` class defines various attributes for accessing
+    the parts of a dependency. The attributes are as follows:
+
+    .. attribute:: name
+
+        The name of the dependency
+
+    .. attribute:: relation
+
+        The relation (>>,>=,==,<<,<=,)
+
+    .. attribute:: version
+
+        The version or None.
+
+    .. attribute:: preDepend
+
+        Boolean value whether this is a pre-dependency.
+
+.. class:: Dependency
+
+    The dependency class represents a Or-Group of dependencies. It provides
+    an attribute to access the :class:`BaseDependency` object for the available
+    choices.
+
+    .. attribute:: or_dependencies
+
+        A list of :class:`BaseDependency` objects which could satisfy the
+        requirement of the Or-Group.
+
+
+Origin Information
+-------------------
+.. class:: Origin
+
+    The :class:`Origin` class provides access to the origin of the package.
+    It allows you to check the component, archive, the hostname, and even if
+    this package can be trusted.
+
+    .. attribute:: archive
+
+        The archive (eg. unstable)
+
+    .. attribute:: component
+
+        The component (eg. main)
+
+    .. attribute:: label
+
+        The Label, as set in the Release file
+
+    .. attribute:: origin
+
+        The Origin, as set in the Release file
+
+    .. attribute:: site
+
+        The hostname of the site.
+
+    .. attribute:: trusted
+
+       Boolean value whether this is trustworthy. An origin can be trusted, if
+       it provides a GPG-signed Release file and the GPG-key used is in the
+       keyring used by apt (see apt-key).
+
+Examples
+---------
+.. code-block:: python
+
+    import apt
+
+    cache = apt.Cache()
+    pkg = cache['python-apt'] # Access the Package object for python-apt
+    print 'python-apt is trusted:', pkg.candidateOrigin.trusted
+
+    # Mark python-apt for install
+    pkg.markInstall()
+
+    print 'python-apt is marked for install:', pkg.markedInstall
+
+    print 'python-apt is', pkg.summary #Python interface to libapt-pkg
+
+    # Now, really install it
+    cache.commit()
diff --git a/doc/source/apt/progress.rst b/doc/source/apt/progress.rst
new file mode 100644
index 00000000..8989aa27
--- /dev/null
+++ b/doc/source/apt/progress.rst
@@ -0,0 +1,37 @@
+:mod:`apt.progress` --- Classes for progress reporting
+======================================================
+.. automodule:: apt.progress
+
+.. warning::
+
+    This class is currently under re-organisation. Therefore, the API may
+    change soon. The old names will still be kept until it is safe to remove
+    them.
+
+
+
+Classes without output
+----------------------
+.. autoclass:: FetchProgress
+    :members:
+.. autoclass:: OpProgress
+    :members:
+.. autoclass:: CdromProgress
+    :members:
+.. autoclass:: DumbInstallProgress
+    :members:
+
+Implementing classes for text output
+------------------------------------
+.. autoclass:: TextFetchProgress
+    :members:
+.. autoclass:: OpTextProgress
+    :members:
+.. autoclass:: InstallProgress
+    :members:
+.. autoclass:: DpkgInstallProgress
+    :members:
+
+
+
+
diff --git a/doc/source/apt_inst.rst b/doc/source/apt_inst.rst
new file mode 100644
index 00000000..97705f61
--- /dev/null
+++ b/doc/source/apt_inst.rst
@@ -0,0 +1,96 @@
+:mod:`apt_inst` - Working with local Debian packages
+====================================================
+.. module:: apt_inst
+
+The :mod:`apt_inst` extension provides access to functions for working with
+locally available Debian packages (.deb files) and tar files.
+
+
+Checking packages
+------------------
+.. function:: arCheckMember(file, membername)
+
+    Check if the member specified by the parameter *membername* exists in
+    the AR file referenced by the :class:`file` object *file*.
+
+
+Listing contents
+-----------------
+.. function:: debExtract(file, func, chunk)
+
+    Call the function referenced by *func* for each member of the tar file
+    *chunk* which is contained in the AR file referenced by the file object
+    *file*.
+
+    An example would be::
+
+        debExtract(open("package.deb"), my_callback, "data.tar.gz")
+
+    See :ref:`emulating-dpkg-contents` for a more detailed example.
+
+.. function:: tarExtract(file,func,comp)
+
+    Call the function *func* for each member of the tar file *file*.
+
+    *Comp* is a string determining the compressor used. Possible options are
+    "lzma", "bzip2" and "gzip".
+
+
+Callback
+^^^^^^^^^
+Both of these functions expect a callback with the signature
+``(what, name, link, mode, uid, gid, size, mtime, major, minor)``.
+
+The parameter *what* describes the type of the member. It can be 'FILE',
+'DIR', or 'HARDLINK'.
+
+The parameter *name* refers to the name of the member. In case of links,
+*link* refers to the target of the link.
+
+
+Extracting contents
+-------------------
+
+.. function:: debExtractArchive(file, rootdir)
+
+    Extract the archive referenced by the :class:`file` object *file*
+    into the directory specified by *rootdir*.
+
+    See :ref:`emulating-dpkg-extract` for an example.
+
+    .. warning::
+
+        If the directory given by *rootdir* does not exist, the package is
+        extracted into the current directory.
+
+.. function:: debExtractControl(file[, member='control'])
+
+    Return the indicated file from the control tar. The default is 'control'.
+
+    If you want to print the control file of a given package, you could do
+    something like::
+
+        print debExtractControl(open("package.deb"))
+
+    :return: The contents of the file, as :class:`str`.
+
+
+.. _emulating-dpkg-extract:
+
+Example: Emulating :program:`dpkg` :option:`--extract`
+-------------------------------------------------------
+Here is a code snippet which emulates dpkg -x. It can be run as
+:program:`tool` :option:`pkg.deb` :option:`outdir`.
+
+.. literalinclude:: examples/dpkg-extract.py
+
+
+.. _emulating-dpkg-contents:
+
+Example: Emulating :program:`dpkg` :option:`--contents`
+-------------------------------------------------------
+.. literalinclude:: examples/dpkg-contents.py
+
+Example: Emulating :program:`dpkg` :option:`--info`
+----------------------------------------------------
+.. literalinclude:: examples/dpkg-info.py
diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst
new file mode 100644
index 00000000..af67d82f
--- /dev/null
+++ b/doc/source/apt_pkg/cache.rst
@@ -0,0 +1,1227 @@
+Classes in apt_pkg
+==================
+
+.. todo::
+
+    This should be split and cleaned up a bit.
+
+:class:`Acquire`
+----------------
+.. class:: Acquire
+
+    .. method:: Run()
+
+        Fetch all the items which have been added by
+        :func:`apt_pkg.GetPkgAcqFile`.
+
+    .. method:: Shutdown
+
+        Shut the fetcher down.
+
+:class:`PkgAcqFile`
+-------------------
+.. class:: PkgAcqFile
+
+    This class provides no methods or attributes
+
+:class:`AcquireItem`
+---------------------
+
+.. class:: AcquireItem
+
+    .. attribute:: ID
+
+        The ID of the item.
+
+    .. attribute:: Complete
+
+        Is the item completely acquired?
+
+    .. attribute:: Local
+
+        Is the item a local file?
+
+    .. attribute:: IsTrusted
+
+        Can the file be trusted?
+
+    .. attribute:: FileSize
+
+        The size of the file, in bytes.
+
+    .. attribute:: ErrorText
+
+        The error message. For example, when a file does not exist on a http
+        server, this will contain a 404 error message.
+
+    .. attribute:: DestFile
+
+        The location the file is saved as.
+
+    .. attribute:: DescURI
+
+        The source location.
+
+    **Status**:
+
+    .. attribute:: Status
+
+        Integer, representing the status of the item.
+
+    .. attribute:: StatIdle
+
+        Constant for comparing :attr:`AcquireItem.Status`.
+
+    .. attribute:: StatFetching
+
+        Constant for comparing :attr:`AcquireItem.Status`
+
+    .. attribute:: StatDone
+
+        Constant for comparing :attr:`AcquireItem.Status`
+
+    .. attribute:: StatError
+
+        Constant for comparing :attr:`AcquireItem.Status`
+
+    .. attribute:: StatAuthError
+
+        Constant for comparing :attr:`AcquireItem.Status`
+
+:class:`ActionGroup`
+--------------------
+
+.. class:: ActionGroup
+
+    Normally, apt checkes the package cache after every modification for
+    packages which are automatically installed but on which no package depends
+    anymore (it collects the package garbage).
+
+    Using ActionGroups you can turn this off and therefore make your code
+    much faster.
+
+    Initialize it using :func:`apt_pkg.GetPkgActionGroup`, eg::
+
+        apt_pkg.GetPkgActionGroup(depcache)
+
+    .. method:: release
+
+        Release the ActionGroup. This will reactive the collection of package
+        garbage.
+
+
+:class:`Configuration`
+----------------------
+
+.. class:: Configuration
+
+    The Configuration objects store the configuration of apt.
+
+    .. describe:: conf[key]
+
+        Return the value of the option given key *key*. If it does not
+        exist, raise :exc:`KeyError`.
+
+    .. describe:: conf[key] = value
+
+        Set the option at *key* to *value*.
+
+    .. method:: Find(key[, default=''])
+
+        Return the value for the given key *key*. This is the same as
+        :meth:`Configuration.get`.
+
+        If *key* does not exist, return *default*.
+
+    .. method:: FindFile(key[, default=''])
+
+        Return the filename hold by the configuration at *key*. This formats the
+        filename correctly and supports the Dir:: stuff in the configuration.
+
+        If *key* does not exist, return *default*.
+
+    .. method:: FindDir(key[, default='/'])
+
+        Return the absolute path to the directory specified in *key*. A
+        trailing slash is appended.
+
+        If *key* does not exist, return *default*.
+
+    .. method:: FindI(key[, default=0])
+
+        Return the integer value stored at *key*.
+
+        If *key* does not exist, return *default*.
+
+    .. method:: FindB(key[, default=0])
+
+        Return the boolean value stored at *key*. This returns an integer, but
+        it should be treated like True/False.
+
+        If *key* does not exist, return *default*.
+
+    .. method:: Set(key, value)
+
+        Set the value of *key* to *value*.
+
+    .. method:: Exists(key)
+
+        Check whether the key *key* exists in the configuration.
+
+    .. method:: SubTree(key)
+
+        Return a sub tree starting at *key*. The resulting object can be used
+        like this one.
+
+    .. method:: List([key])
+
+        List all items at *key*. Normally, return the keys at the top level,
+        eg. APT, Dir, etc.
+
+        Use *key* to specify a key of which the childs will be returned.
+
+    .. method:: ValueList([key])
+
+        Same as :meth:`Configuration.List`, but this time for the values.
+
+    .. method:: MyTag()
+
+        Return the tag name of the current tree. Normally this is an empty
+        string, but for subtrees it is the key of the subtree.
+
+    .. method:: Clear(key)
+
+        Clear the configuration. Remove all values and keys at *key*.
+
+    .. method:: keys([key])
+
+        Return all the keys, recursive. If *key* is specified, ... (FIXME)
+
+    .. method:: has_key(key)
+
+        Return whether the configuration contains the key *key*.
+
+    .. method:: get(key[, default=''])
+
+        This behaves just like :meth:`dict.get` and :meth:`Configuration.Find`,
+        it returns the value of key or if it does not exist, *default*.
+
+
+:class:`pkgCache`
+-----------------
+.. class:: pkgCache
+
+    The :class:`pkgCache` class prov
+
+    .. describe:: cache[pkgname]
+
+        Return the :class:`Package()` object for the package name given by
+        *pkgname*.
+
+    .. method:: Close()
+
+        Close the package cache.
+
+    .. method:: Open([progress])
+
+        Open the package cache again. The parameter *progress* may be set to
+        an :class:`apt.progress.OpProgress()` object or `None`.
+
+    .. method:: Update(progress, list)
+
+        Update the package cache.
+
+        The parameter *progress* points to an :class:`apt.progress.FetchProgress()`
+        object.
+
+        The parameter *list* refers to an object as returned by
+        :func:`apt_pkg.GetPkgSourceList`.
+
+    .. attribute:: DependsCount
+
+        The total number of dependencies.
+
+    .. attribute:: PackageCount
+
+        The total number of packages available in the cache.
+
+    .. attribute:: ProvidesCount
+
+        The number of provided packages.
+
+    .. attribute:: VerFileCount
+
+        .. todo:: Seems to be some mixture of versions and pkgFile.
+
+    .. attribute:: VersionCount
+
+        The total number of package versions available in the cache.
+
+    .. attribute:: PackageFileCount
+
+        The total number of Packages files available (the Packages files
+        listing the packages). This is the same as the length of the list in
+        the attribute :attr:`FileList`.
+
+    .. attribute:: FileList
+
+        A list of :class:`PackageFile` objects.
+
+
+:class:`PackageFile`
+--------------------
+.. class:: PackageFile
+
+    A :class:`PackageFile` represents a Packages file, eg.
+    /var/lib/dpkg/status.
+
+    .. attribute:: Architecture
+
+        The architecture of the package file.
+
+    .. attribute:: Archive
+
+        The archive (eg. unstable)
+
+    .. attribute:: Component
+
+        The component (eg. main)
+
+    .. attribute:: FileName
+
+        The name of the file.
+
+    .. attribute:: ID
+
+        The ID of the package. This is an integer which can be used to store
+        further information about the file [eg. as dictionary key].
+
+    .. attribute:: IndexType
+
+        The sort of the index file. In normal cases, this is
+        'Debian Package Index'.
+
+    .. attribute:: Label
+
+        The Label, as set in the Release file
+
+    .. attribute:: NotAutomatic
+
+        Whether packages from this list will be updated automatically. The
+        default for eg. example is 0 (aka false).
+
+    .. attribute:: NotSource
+
+        Whether the file has no source from which it can be updated. In such a
+        case, the value is 1; else 0. /var/lib/dpkg/status is 0 for example.
+
+        Example::
+
+            for pkgfile in cache.FileList:
+                if pkgfile.NotSource:
+                    print 'The file %s has no source.' % pkgfile.FileName
+
+    .. attribute:: Origin
+
+        The Origin, as set in the Release file
+
+    .. attribute:: Site
+
+        The hostname of the site.
+
+    .. attribute:: Size
+
+        The size of the file.
+
+    .. attribute:: Version
+
+        The version, as set in the release file (eg. "4.0" for "Etch")
+
+
+Example
+^^^^^^^
+.. literalinclude:: ../examples/cache-pkgfile.py
+
+
+:class:`Package`
+----------------
+
+.. class:: Package
+
+    The pkgCache::Package objects are an interface to package specific
+    features.
+
+
+    Attributes:
+
+    .. attribute:: CurrentVer
+
+        The version currently installed, or None. This returns a
+        :class:`Version` object.
+
+    .. attribute:: ID
+
+        The ID of the package. This can be used to store information about
+        the package. The ID is an int value.
+
+    .. attribute:: Name
+
+        This is the name of the package.
+
+    .. attribute:: ProvidesList
+
+        A list of packages providing this package. More detailed, this is a
+        list of tuples (str:pkgname, ????, :class:`Version`).
+
+        If you want to check for check for virtual packages, the expression
+        ``pkg.ProvidesList and not pkg.VersionList`` helps you. It detects if
+        the package is provided by something else and is not available as a
+        real package.
+
+    .. attribute:: RevDependsList
+
+        An iterator of :class:`Dependency` objects for dependencies on this
+        package.
+
+    .. attribute:: Section
+
+        The section of the package, as specified in the record. The list of
+        possible sections is defined in the Policy.
+
+    .. attribute:: VersionList
+
+        A list of :class:`Version` objects for all versions available in the
+        cache.
+
+    **States**:
+
+    .. attribute:: SelectedState
+
+        The state we want it to be, ie. if you mark a package for installation,
+        this is :attr:`apt_pkg.SelStateInstall`.
+
+        See :ref:`SelStates` for a list of available states.
+
+    .. attribute:: InstState
+
+        The state the currently installed version is in. This is normally
+        :attr:`apt_pkg.InstStateOK`, unless the installation failed.
+
+        See :ref:`InstStates` for a list of available states.
+
+    .. attribute:: CurState
+
+        The current state of the package (not installed, unpacked, installed,
+        etc). See :ref:`CurStates` for a list of available states.
+
+    **Flags**:
+
+    .. attribute:: Auto
+
+        Whether the package was installed automatically as a dependency of
+        another package. (or marked otherwise as automatically installed)
+
+    .. attribute:: Essential
+
+        Whether the package is essential.
+
+    .. attribute:: Important
+
+        Whether the package is important.
+
+Example:
+^^^^^^^^^
+.. literalinclude:: ../examples/cache-packages.py
+
+
+
+:class:`Version`
+----------------
+.. class:: Version
+
+    The version object contains all information related to a specific package
+    version.
+
+    .. attribute:: VerStr
+
+        The version, as a string.
+
+    .. attribute:: Section
+
+        The usual sections (eg. admin, net, etc.). Prefixed with the component
+        name for packages not in main (eg. non-free/admin).
+
+    .. attribute:: Arch
+
+        The architecture of the package, eg. amd64 or all.
+
+    .. attribute:: FileList
+
+        A list of (:class:`PackageFile`, int: index) tuples for all Package
+        files containing this version of the package.
+
+    .. attribute:: DependsListStr
+
+        A dictionary of dependencies. The key specifies the type of the
+        dependency ('Depends', 'Recommends', etc.).
+
+
+        The value is a list, containing items which refer to the or-groups of
+        dependencies. Each of these or-groups is itself a list, containing
+        tuples like ('pkgname', 'version', 'relation') for each or-choice.
+
+        An example return value for a package with a 'Depends: python (>= 2.4)'
+        would be::
+
+            {'Depends': [
+                            [
+                             ('python', '2.4', '>=')
+                            ]
+                        ]
+            }
+
+        The same for a dependency on A (>= 1) | B (>= 2)::
+
+            {'Depends': [
+                            [
+                                ('A', '1', '>='),
+                                ('B', '2', '>='),
+                            ]
+                        ]
+            }
+
+    .. attribute:: DependsList
+
+        This is basically the same as :attr:`Version.DependsListStr`,
+        but instead of the ('pkgname', 'version', 'relation') tuples,
+        it returns :class:`Dependency` objects, which can assist you with
+        useful functions.
+
+    .. attribute:: ParentPkg
+
+        The :class:`Package` object this version belongs to.
+
+    .. attribute:: ProvidesList
+
+        This returns a list of all packages provided by this version. Like
+        :attr:`Package.ProvidesList`, it returns a list of tuples
+        of the form ('virtualpkgname', ???, :class:`Version`), where as the
+        last item is the same as the object itself.
+
+    .. attribute:: Size
+
+        The size of the .deb file, in bytes.
+
+    .. attribute:: InstalledSize
+
+        The size of the package (in kilobytes), when unpacked on the disk.
+
+    .. attribute:: Hash
+
+        An integer hash value.
+
+    .. attribute:: ID
+
+        An integer id.
+
+    .. attribute:: Priority
+
+        The integer representation of the priority. This can be used to speed
+        up comparisons a lot, compared to :attr:`Version.PriorityStr`.
+
+        The values are defined in the :mod:`apt_pkg` extension, see
+        :ref:`Priorities` for more information.
+
+    .. attribute:: PriorityStr
+
+        Return the priority of the package version, as a string, eg.
+        "optional".
+
+    .. attribute:: Downloadable
+
+        Whether this package can be downloaded from a remote site.
+
+    .. attribute:: TranslatedDescription
+
+        Return a :class:`Description` object.
+
+
+:class:`Dependency`
+-------------------
+.. class:: Dependency
+
+    Represent a dependency from one package to another one.
+
+    .. method:: AllTargets
+
+        A list of :class:`Version` objects which satisfy the dependency,
+        and do not conflict with already installed ones.
+
+        From my experience, if you use this method to select the target
+        version, it is the best to select the last item unless any of the
+        other candidates is already installed. This leads to results being
+        very close to the normal package installation.
+
+    .. method:: SmartTargetPkg
+
+        Return a :class:`Version` object of a package which satisfies the
+        dependency and does not conflict with installed packages
+        (the 'natural target').
+
+    .. attribute:: TargetVer
+
+        The target version of the dependency, as string. Empty string if the
+        dependency is not versioned.
+
+    .. attribute:: TargetPkg
+
+        The :class:`Package` object of the target package.
+
+    .. attribute:: ParentVer
+
+        The :class:`Version` object of the parent version, ie. the package
+        which declares the dependency.
+
+    .. attribute:: ParentPkg
+
+        The :class:`Package` object of the package which declares the
+        dependency. This is the same as using ParentVer.ParentPkg.
+
+    .. attribute:: CompType
+
+        The type of comparison (>=, ==, >>, <=), as string.
+
+    .. attribute:: DepType
+
+        The type of the dependency, as string, eg. "Depends".
+
+    .. attribute:: ID
+
+        The ID of the package, as integer.
+
+Example: Find all missing dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+With the help of Dependency.AllTargets(), you can easily find all packages with
+broken dependencies:
+
+.. literalinclude:: ../examples/missing-deps.py
+
+
+:class:`Description`
+--------------------
+.. class:: Description
+
+    Represent the description of the package.
+
+    .. attribute:: LanguageCode
+
+        The language code of the description
+
+    .. attribute:: md5
+
+        The md5 hashsum of the description
+
+    .. attribute:: FileList
+
+        A list of tuples (:class:`PackageFile`, int: index).
+
+
+
+:class:`pkgDepCache`
+--------------------
+.. class:: pkgDepCache
+
+    The pkgDepCache object contains various methods to manipulate the cache,
+    to install packages, to remove them, and much more.
+
+    .. method:: Commit(fprogress, iprogress)
+
+        Apply all the changes made.
+
+        The parameter *fprogress* has to be set to an instance of
+        apt.progress.FetchProgress or one of its subclasses.
+
+        The parameter *iprogress* has to be set to an instance of
+        apt.progress.InstallProgress or one of its subclasses.
+
+    .. method:: FixBroken()
+
+        Try to fix all broken packages in the cache.
+
+    .. method:: GetCandidateVer(pkg)
+
+        Return the candidate version of the package, ie. the version that
+        would be installed normally.
+
+        The parameter *pkg* refers to an :class:`Package` object,
+        available using the :class:`pkgCache`.
+
+        This method returns a :class:`Version` object.
+
+    .. method:: SetCandidateVer(pkg, version)
+
+        The opposite of :meth:`pkgDepCache.GetCandidateVer`. Set the candidate
+        version of the :class:`Package` *pkg* to the :class:`Version`
+        *version*.
+
+
+    .. method:: Upgrade([distUpgrade=False])
+
+        Perform an upgrade. More detailed, this marks all the upgradable
+        packages for upgrade. You still need to call
+        :meth:`pkgDepCache.Commit` for the changes to apply.
+
+        To perform a dist-upgrade, the optional parameter *distUpgrade* has
+        to be set to True.
+
+    .. method:: FixBroken()
+
+        Fix broken packages.
+
+    .. method:: ReadPinFile()
+
+        Read the policy, eg. /etc/apt/preferences.
+
+    .. method:: MinimizeUpgrade()
+
+        Go over the entire set of packages and try to keep each package marked
+        for upgrade. If a conflict is generated then the package is restored.
+
+        .. todo::
+            Explain better..
+
+    .. method:: MarkKeep(pkg)
+
+        Mark the :class:`Package` *pkg* for keep.
+
+    .. method:: MarkDelete(pkg[, purge])
+
+        Mark the :class:`Package` *pkg* for delete. If *purge* is True,
+        the configuration files will be removed as well.
+
+    .. method:: MarkInstall(pkg[, autoInst=True[, fromUser=True]])
+
+        Mark the :class:`Package` *pkg* for install.
+
+        If *autoInst* is ``True``, the dependencies of the package will be
+        installed as well. This is the default.
+
+        If *fromUser* is ``True``, the package will be marked as manually
+        installed. This is the default.
+
+    .. method:: SetReinstall(pkg)
+
+        Set if the :class:`Package` *pkg* should be reinstalled.
+
+    .. method:: IsUpgradable(pkg)
+
+        Return ``1`` if the package is upgradable.
+
+        The package can be upgraded by calling :meth:`pkgDepCache.MarkInstall`.
+
+    .. method:: IsNowBroken(pkg)
+
+        Return `1` if the package is broken now (including changes made, but
+        not committed).
+
+    .. method:: IsInstBroken(pkg)
+
+        Return ``1`` if the package is broken on the current install. This
+        takes changes which have not been committed not into effect.
+
+    .. method:: IsGarbage(pkg)
+
+        Return ``1`` if the package is garbage, ie. if it is automatically
+        installed and no longer referenced by other packages.
+
+    .. method:: IsAutoInstalled(pkg)
+
+        Return ``1``  if the package is automatically installed (eg. as the
+        dependency of another package).
+
+    .. method:: MarkedInstall(pkg)
+
+        Return ``1`` if the package is marked for install.
+
+    .. method:: MarkedUpgrade(pkg)
+
+        Return ``1`` if the package is marked for upgrade.
+
+    .. method:: MarkedDelete(pkg)
+
+        Return ``1`` if the package is marked for delete.
+
+    .. method:: MarkedKeep(pkg)
+
+        Return ``1`` if the package is marked for keep.
+
+    .. method:: MarkedReinstall(pkg)
+
+        Return ``1`` if the package should be installed.
+
+    .. method:: MarkedDowngrade(pkg)
+
+        Return ``1`` if the package should be downgraded.
+
+    .. attribute:: KeepCount
+
+        Integer, number of packages marked as keep
+
+    .. attribute:: InstCount
+
+        Integer, number of packages marked for installation.
+
+    .. attribute:: DelCount
+
+        Number of packages which should be removed.
+
+    .. attribute:: BrokenCount
+
+        Number of packages which are broken.
+
+    .. attribute:: UsrSize
+
+        The size required for the changes on the filesystem. If you install
+        packages, this is positive, if you remove them its negative.
+
+    .. attribute:: DebSize
+
+        The size of the packages which are needed for the changes to be
+        applied.
+
+
+:class:`MetaIndex`
+------------------
+
+.. todo::
+
+    Complete them
+
+.. class:: MetaIndex
+
+    .. attribute:: URI
+    .. attribute:: Dist
+    .. attribute:: IsTrusted
+    .. attribute:: IndexFiles
+
+
+:class:`PackageIndexFile`
+-------------------------
+
+.. class:: PackageIndexFile
+
+    .. method:: ArchiveURI(path)
+
+        Return the full url to path in the archive.
+
+    .. attribute:: Label
+
+        Return the Label.
+
+    .. attribute:: Exists
+
+        Return whether the file exists.
+
+    .. attribute:: HasPackages
+
+        Return whether the file has packages.
+
+    .. attribute:: Size
+
+        Size of the file
+
+    .. attribute:: IsTrusted
+
+        Whether we can trust the file.
+
+
+:class:`PkgManager`
+-------------------
+
+.. class:: PkgManager
+
+    Class, as returned by :func:`apt_pkg.GetPackageManager`.
+
+    .. method:: GetArchives(fetcher, list, records)
+
+        Add all the selected packages to the :class:`Acquire()` object
+        *fetcher*.
+
+        The parameter *list* refers to a :class:`PkgSourceList()` object, as
+        returned by :func:`apt_pkg.GetPkgSourceList`.
+
+        The parameter *records* refers to a :class:`pkgRecords()` object, as
+        returned by :func:`apt_pkg.GetPkgRecords`.
+
+    .. method:: DoInstall()
+
+        Install the packages.
+
+    .. method:: FixMissing
+
+        Fix the installation if a package could not be downloaded.
+
+    .. attribute:: ResultCompleted
+
+        A constant for checking whether the the result is 'completed'.
+
+        Compare it against the return value of :meth:`PkgManager.GetArchives`
+        or :meth:`PkgManager.DoInstall`.
+
+    .. attribute:: ResultFailed
+
+        A constant for checking whether the the result is 'failed'.
+
+        Compare it against the return value of :meth:`PkgManager.GetArchives`
+        or :meth:`PkgManager.DoInstall`.
+
+    .. attribute:: ResultIncomplete
+
+        A constant for checking whether the the result is 'incomplete'.
+
+        Compare it against the return value of :meth:`PkgManager.GetArchives`
+        or :meth:`PkgManager.DoInstall`.
+
+:class:`pkgRecords`
+--------------------
+
+.. class:: PkgRecords
+
+    Provide access to the packages records. This provides very useful
+    attributes for fast (convient) access to some fields of the record.
+
+    See :func:`apt_pkg.GetPkgRecords` for initialization.
+
+
+    .. method:: Lookup(verfile_iter)
+
+        Change the actual package to the package given by the verfile_iter.
+
+        The parameter *verfile_iter* refers to a tuple consisting
+        of (:class:`PackageFile()`, int: index), as returned by various
+        attributes, including :attr:`Version.FileList`.
+
+        Example (shortened)::
+
+            cand = depcache.GetCandidateVer(cache['python-apt'])
+            records.Lookup(cand.FileList[0])
+            # Now you can access the record
+            print records.SourcePkg # == python-apt
+
+    .. attribute:: FileName
+
+        Return the field 'Filename' of the record. This is the path to the
+        package, relative to the base path of the archive.
+
+    .. attribute:: MD5Hash
+
+        Return the MD5 hashsum of the package This refers to the field
+        'MD5Sum' in the raw record.
+
+    .. attribute:: SHA1Hash
+
+        Return the SHA1 hashsum of the package. This refers to the field 'SHA1'
+        in the raw record.
+
+    .. attribute:: SHA256Hash
+
+        Return the SHA256 hashsum of the package. This refers to the field
+        'SHA256' in the raw record.
+
+        .. versionadded:: 0.7.9
+
+    .. attribute:: SourcePkg
+
+        Return the source package.
+
+    .. attribute:: SourceVer
+
+        Return the source version.
+
+    .. attribute:: Maintainer
+
+        Return the maintainer of the package.
+
+    .. attribute:: ShortDesc
+
+        Return the short description. This is the summary on the first line of
+        the 'Description' field.
+
+    .. attribute:: LongDesc
+
+        Return the long description. These are lines 2-END from the
+        'Description' field.
+
+    .. attribute:: Name
+
+        Return the name of the package. This is the 'Package' field.
+
+    .. attribute:: Homepage
+
+        Return the Homepage. This is the 'Homepage' field.
+
+    .. attribute:: Record
+
+        Return the whole record as a string. If you want to access fields of
+        the record not available as an attribute, you can use
+        :func:`apt_pkg.ParseSection` to parse the record and access the field
+        name.
+
+        Example::
+
+            section = apt_pkg.ParseSection(records.Record)
+            print section['SHA256']
+
+:class:`PkgSrcRecords`
+----------------------
+
+.. class:: PkgSrcRecords
+
+    This represents the entries in the Sources files, ie. the dsc files of
+    the source packages.
+
+    .. note::
+
+        If the Lookup failed, because no package could be found, no error is
+        raised. Instead, the attributes listed below are simply not existing
+        anymore (same applies when no Lookup has been made, or when it has
+        been restarted).
+
+    .. method:: Lookup(pkgname)
+
+        Lookup the record for the package named *pkgname*. To access all
+        available records, you need to call it multiple times.
+
+        Imagine a package P with two versions X, Y. The first ``Lookup(P)``
+        would set the record to version X and the second ``Lookup(P)`` to
+        version Y.
+
+    .. method:: Restart()
+
+        Restart the lookup.
+
+        Imagine a package P with two versions X, Y. The first ``Lookup(P)``
+        would set the record to version X and the second ``Lookup(P)`` to
+        version Y.
+
+        If you now call ``Restart()``, the internal position will be cleared.
+        Now you can call ``Lookup(P)`` again to move to X.
+
+    .. attribute:: Package
+
+        The name of the source package.
+
+    .. attribute:: Version
+
+        A string describing the version of the source package.
+
+    .. attribute:: Maintainer
+
+        A string describing the name of the maintainer.
+
+    .. attribute:: Section
+
+        A string describing the section.
+
+    .. attribute:: Record
+
+        The whole record, as a string. You can use :func:`apt_pkg.ParseSection`
+        if you need to parse it.
+
+        You need to parse the record if you want to access fields not available
+        via the attributes, eg. 'Standards-Version'
+
+    .. attribute:: Binaries
+
+        Return a list of strings describing the package names of the binaries
+        created by the source package. This matches the 'Binary' field in the
+        raw record.
+
+    .. attribute:: Index
+
+        The index in the Sources files.
+
+    .. attribute:: Files
+
+        The list of files. This returns a list of tuples with the contents
+        ``(str: md5, int: size, str: path, str:type)``.
+
+    .. attribute:: BuildDepends
+
+        Return the list of Build dependencies, as
+        ``(str: package, str: version, int: op, int: type)``.
+
+        .. table:: Values of *op*
+
+            ===== =============================================
+            Value      Meaning
+            ===== =============================================
+            0x0   No Operation (no versioned build dependency)
+            0x10  | (or) - this will be added to the other values
+            0x1   <= (less than or equal)
+            0x2   >= (greater than or equal)
+            0x3   << (less than)
+            0x4   >> (greater than)
+            0x5   == (equal)
+            0x6   != (not equal)
+            ===== =============================================
+
+        .. table:: Values of *type*
+
+            ===== ===================
+            Value Meaning
+            ===== ===================
+            0     Build-Depends
+            1     Build-Depends-Indep
+            2     Build-Conflicts
+            3     Build-Conflicts-Indep
+            ===== ===================
+
+        **Example**: In the following content, we will imagine a
+        build-dependency::
+
+            Build-Depends: A (>= 1) | B (>= 1), C
+
+        This results in::
+
+            [('A', '1', 18, 0), # 18 = 16 + 2 = 0x10 + 0x2
+             ('B', '1', 2, 0),
+             ('C', '', 0, 0)]
+
+        This is **not** the same as returned by
+        :func:`apt_pkg.ParseSrcDepends`.
+
+
+:class:`PkgSourceList`
+-----------------------
+
+.. class:: PkgSourceList
+
+    This is for :file:`/etc/apt/sources.list`.
+
+    .. method:: FindIndex(pkgfile)
+
+        Return a :class:`PackageIndexFile` object for the :class:`PackageFile`
+        *pkgfile*.
+
+    .. method:: ReadMainList
+
+        Read the main list.
+
+    .. method:: GetIndexes(acq[, all])
+
+        Add the index files to the :class:`Acquire()` object *acq*. If *all* is
+        given and ``True``, all files are fetched.
+
+
+:class:`ProblemResolver`
+------------------------
+.. class:: ProblemResolver
+
+    The problem resolver helps when there are problems in the package
+    selection. An example is a package which conflicts with another, already
+    installed package.
+
+    .. method:: Protect(pkg)
+
+        Protect the :class:`Package()` object given by the parameter *pkg*.
+
+        .. todo::
+
+            Really document it.
+
+    .. method:: InstallProtect()
+
+        Protect all installed packages from being removed.
+
+    .. method:: Remove(pkg)
+
+        Remove the :class:`Package()` object given by the parameter *pkg*.
+
+        .. todo::
+
+            Really document it.
+
+    .. method:: Clear(pkg)
+
+        Reset the :class:`Package()` *pkg* to the default state.
+
+        .. todo::
+
+            Really document it.
+
+    .. method:: Resolve()
+
+        Try to resolve problems by installing and removing packages.
+
+    .. method:: ResolveByKeep()
+
+        Try to resolve problems only by using keep.
+
+
+:class:`TagFile`
+----------------
+
+.. class:: TagFile
+
+    An object which represents a typical debian control file. Can be used for
+    Packages, Sources, control, Release, etc.
+
+    Use :func:`apt_pkg.ParseTagFile` to parse a file.
+
+    .. method:: Step
+
+        Step forward to the next section. This simply returns ``1`` if OK, and
+        ``0`` if there is no section
+
+    .. method:: Offset
+
+        Return the current offset (in bytes) from the beginning of the file.
+
+    .. method:: Jump(offset)
+
+        Jump back/forward to *offset*. Use ``Jump(0)`` to jump to the
+        beginning of the file again.
+
+    .. attribute:: Section
+
+        This is the current :class:`TagSection()` instance.
+
+:class:`TagSection`
+-------------------
+
+.. class:: TagSection
+
+    Represent a single section of a debian control file.
+
+    .. describe:: section[key]
+
+        Return the value of the field at *key*. If *key* is not available,
+        raise :exc:`KeyError`.
+
+    .. method:: Bytes
+
+        The number of bytes in the section.
+
+    .. method:: Find(key, default='')
+
+        Return the value of the field at the key *key* if available,
+        else return *default*.
+
+    .. method:: FindFlag(key)
+
+        Find a yes/no value for the key *key*. An example for such a
+        field is 'Essential'.
+
+    .. method:: get(key, default='')
+
+        Return the value of the field at the key *key* if available, else
+        return *default*.
+
+    .. method:: has_key(key)
+
+        Check whether the field with named by *key* exists.
+
+    .. method:: keys()
+
+        Return a list of keys in the section.
diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst
new file mode 100644
index 00000000..1c5866a9
--- /dev/null
+++ b/doc/source/apt_pkg/index.rst
@@ -0,0 +1,261 @@
+:mod:`apt_pkg` --- The low-level bindings for apt-pkg
+=====================================================
+.. module:: apt_pkg
+
+The apt_pkg extensions provides a more low-level way to work with apt. It can
+do everything apt can, and is written in C++. It has been in python-apt since
+the beginning.
+
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    *
+
+
+Module Initialization
+---------------------
+
+
+.. function:: initConfig
+
+    Initialize the configuration of apt. This is needed for most operations.
+
+.. function:: initSystem
+
+    Initialize the system.
+
+.. function:: init
+
+    Deprecated function. Use initConfig() and initSystem() instead.
+
+Object initialization
+----------------------
+.. function:: GetCache([progress])
+
+    Return a :class:`pkgCache` object. The optional parameter ``progress``
+    specifies an instance of :class:`apt.progress.OpProgress()` which will
+    display the open progress.
+
+.. function:: GetCdrom()
+
+    Return a Cdrom object with the following methods:
+
+    .. method:: Cdrom.Ident(progress)
+
+        Identify the cdrom. The parameter ``progress`` refers to an
+        :class:`apt.progress.CdromProgress()` object.
+
+    .. method:: Cdrom.Add(progress)
+
+        Add the cdrom to the sources.list file. The parameter ``progress``
+        refers to an :class:`apt.progress.CdromProgress()` object.
+
+
+
+.. function:: GetDepCache(cache)
+
+    Return a :class:`pkgDepCache` object. The parameter ``cache`` specifies an
+    instance of :class:`pkgCache` (see :func:`GetCache()`).
+
+
+.. function:: GetPkgSourceList()
+
+    Return a :class:`pkgSourceList` object.
+
+
+The Acquire interface
+----------------------
+.. function:: GetAcquire([progress])
+
+    Return an :class:`Acquire` object. This is a class which allows you
+    to fetch files, or archive contents. The parameter ``progress`` refers to
+    an :class:`apt.progress.FetchProgress()` object.
+
+    Acquire items have multiple methods:
+
+    .. method:: Acquire.Run()
+
+        Fetch all the items which have been added by :func:`GetPkgAcqFile`.
+
+    .. method:: Acquire.Shutdown()
+
+        Shut the fetcher down.
+
+    .. attribute:: Acquire.TotalNeeded
+
+        The total amount of bytes needed (including those of files which are
+        already present)
+
+    .. attribute:: Acquire.FetchNeeded
+
+        The total amount of bytes which need to be fetched.
+
+    .. attribute:: Acquire.PartialPresent
+
+        Whether some files have been acquired already. (???)
+
+
+.. function:: GetPkgAcqFile(aquire, uri[, md5, size, descr, shortDescr, destDir, destFile])
+
+    The parameter ``acquire`` refers to an :class:`Acquire()` object as returned
+    by :func:`GetAcquire`. The file will be added to the Acquire queue
+    automatically.
+
+    The parameter ``uri`` refers to the location of the file, any protocol
+    of apt is supported.
+
+    The parameter ``md5`` refers to the md5sum of the file. This can be used
+    for checking the file.
+
+    The parameter ``size`` can be used to specify the size of the package,
+    which can then be used to calculate the progress and validate the download.
+
+    The parameter ``descr`` is a descripition of the download. It may be
+    used to describe the item in the progress class. ``shortDescr`` is the
+    short form of it.
+
+    You can use ``destDir`` to manipulate the directory where the file will
+    be saved in. Together with ``destFile`` you can specify the complete target
+    path.
+
+
+
+Hash functions
+--------------
+The apt_pkg module also provides several hash functions. If you develop
+applications with python-apt it is often easier to use these functions instead
+of the ones provides in Python's :mod:`hashlib` module.
+
+.. function:: md5sum(object)
+
+    Return the md5sum of the object. ``object`` may either be a string, in
+    which case the md5sum of the string is returned, or a :class:`file()`
+    object, in which case the md5sum of its contents is returned.
+
+.. function:: sha1sum(object)
+
+    Return the sha1sum of the object. ``object`` may either be a string, in
+    which case the sha1sum of the string is returned, or a :class:`file()`
+    object, in which case the sha1sum of its contents is returned.
+
+.. function:: sha256sum(object)
+
+    Return the sha256sum of the object. ``object`` may either be a string, in
+    which case the sha256sum of the string is returned, or a :class:`file()`
+    object, in which case the sha256sum of its contents is returned.
+
+Other functions
+----------------
+
+.. note::
+
+    This documentation is created automatically and should be rewritten.
+
+.. autofunction:: Base64Encode
+.. autofunction:: CheckDep
+.. autofunction:: CheckDomainList
+.. autofunction:: DeQuoteString
+.. autofunction:: GetLock
+.. autofunction:: GetPackageManager
+.. autofunction:: GetPkgActionGroup
+.. autofunction:: GetPkgProblemResolver
+.. autofunction:: GetPkgRecords
+.. autofunction:: GetPkgSrcRecords
+.. autofunction:: newConfiguration
+.. autofunction:: ParseCommandLine
+.. autofunction:: ParseDepends
+.. autofunction:: ParseSection
+.. autofunction:: ParseSrcDepends
+.. autofunction:: ParseTagFile
+.. autofunction:: PkgSystemLock
+.. autofunction:: PkgSystemUnLock
+.. autofunction:: QuoteString
+.. autofunction:: ReadConfigFile
+.. autofunction:: ReadConfigFileISC
+.. autofunction:: RewriteSection
+.. autofunction:: SizeToStr
+.. autofunction:: StringToBool
+.. autofunction:: StrToTime
+.. autofunction:: TimeRFC1123
+.. autofunction:: TimeToStr
+.. autofunction:: UpstreamVersion
+.. autofunction:: URItoFileName
+.. autofunction:: VersionCompare
+
+
+Data
+-----
+
+.. data:: Config
+
+    An :class:`Configuration()` object with the default configuration. Actually,
+    this is a bit different object, but it is compatible.
+
+.. data:: RewritePackageOrder
+
+.. data:: RewriteSourceOrder
+
+
+.. _CurStates:
+
+Package States
+^^^^^^^^^^^^^^^
+.. data:: CurStateConfigFiles
+.. data:: CurStateHalfConfigured
+.. data:: CurStateHalfInstalled
+.. data:: CurStateInstalled
+.. data:: CurStateNotInstalled
+.. data:: CurStateUnPacked
+
+
+
+
+Dependency types
+^^^^^^^^^^^^^^^^
+.. data:: DepConflicts
+.. data:: DepDepends
+.. data:: DepObsoletes
+.. data:: DepPreDepends
+.. data:: DepRecommends
+.. data:: DepReplaces
+.. data:: DepSuggests
+
+.. _InstStates:
+
+Installed states
+^^^^^^^^^^^^^^^^^
+.. data:: InstStateHold
+.. data:: InstStateHoldReInstReq
+.. data:: InstStateOk
+.. data:: InstStateReInstReq
+
+.. _Priorities:
+
+Priorities
+^^^^^^^^^^
+.. data:: PriExtra
+.. data:: PriImportant
+.. data:: PriOptional
+.. data:: PriRequired
+.. data:: PriStandard
+
+
+.. _SelStates:
+
+Select states
+^^^^^^^^^^^^^^
+.. data:: SelStateDeInstall
+.. data:: SelStateHold
+.. data:: SelStateInstall
+.. data:: SelStatePurge
+.. data:: SelStateUnknown
+
+
+Build information
+^^^^^^^^^^^^^^^^^
+.. data:: Date
+.. data:: LibVersion
+.. data:: Time
+.. data:: Version
diff --git a/doc/source/aptsources/distinfo.rst b/doc/source/aptsources/distinfo.rst
new file mode 100644
index 00000000..96f9445d
--- /dev/null
+++ b/doc/source/aptsources/distinfo.rst
@@ -0,0 +1,10 @@
+:mod:`aptsources.distinfo` --- provide meta information for distro repositories
+===============================================================================
+
+.. automodule:: aptsources.distinfo
+    :members:
+    :undoc-members:
+
+    .. note::
+
+        This part of the documentation is created automatically.
diff --git a/doc/source/aptsources/distro.rst b/doc/source/aptsources/distro.rst
new file mode 100644
index 00000000..06ca0fda
--- /dev/null
+++ b/doc/source/aptsources/distro.rst
@@ -0,0 +1,10 @@
+:mod:`aptsources.distro` --- Distribution abstraction of the sources.list
+===============================================================================
+
+.. automodule:: aptsources.distro
+    :members:
+    :undoc-members:
+
+    .. note::
+
+        This part of the documentation is created automatically.
diff --git a/doc/source/aptsources/index.rst b/doc/source/aptsources/index.rst
new file mode 100644
index 00000000..898fbf74
--- /dev/null
+++ b/doc/source/aptsources/index.rst
@@ -0,0 +1,10 @@
+:mod:`aptsources` --- Working with sources.list
+=====================================================
+.. automodule:: aptsources
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    *
+
diff --git a/doc/source/aptsources/sourceslist.rst b/doc/source/aptsources/sourceslist.rst
new file mode 100644
index 00000000..509db3ce
--- /dev/null
+++ b/doc/source/aptsources/sourceslist.rst
@@ -0,0 +1,10 @@
+:mod:`aptsources.sourceslist` --- Provide an abstraction of the sources.list
+============================================================================
+
+.. automodule:: aptsources.sourceslist
+    :members:
+    :undoc-members:
+
+    .. note::
+
+        This part of the documentation is created automatically.
diff --git a/doc/source/coding.rst b/doc/source/coding.rst
new file mode 100644
index 00000000..1357ce14
--- /dev/null
+++ b/doc/source/coding.rst
@@ -0,0 +1,168 @@
+Coding for python-apt
+======================
+Let's say you need a new feature, you can develop it, and you want to get it
+included in python-apt. Then be sure to follow the following guidelines.
+
+Available branches
+-------------------
+First of all, let's talk a bit about the bzr branches of python-apt. In the
+following parts, we will assume that you use bzr to create your changes and
+submit them.
+
+**mvo:** http://people.ubuntu.com/~mvo/bzr/python-apt/mvo
+    This is Michael Vogt's branch. Most of the development of apt happens here,
+    as he is the lead maintainer of python-apt.
+
+    This branch is also available from Launchpads super mirror, via
+    ``lp:python-apt``. Checkouts from Launchpad are generally faster and can
+    use the bzr protocoll.
+
+    VCS-Browser: https://code.launchpad.net/~mvo/python-apt/python-apt--mvo
+
+**debian-sid:** http://bzr.debian.org/apt/python-apt/debian-sid
+    This is the official Debian branch of python-apt. All code which will be
+    uploaded to Debian is here. It is not as up-to-date as the mvo branch,
+    because this branch often gets updated just right before the release
+    happens.
+
+    VCS-Browser: http://bzr.debian.org/loggerhead/apt/python-apt/debian-sid/changes
+
+**jak:** http://bzr.debian.org/users/jak/python-apt/jak
+    This is Julian Andres Klode's (the documentation author's) branch. This
+    is the place where cleanup and documentation updates happen. It is based
+    off debian-sid or mvo.
+
+    VCS-Browser: http://bzr.debian.org/loggerhead/users/jak/python-apt/jak/changes
+
+**ubuntu:** ``lp:~ubuntu-core-dev/python-apt/ubuntu``
+    This is the official Ubuntu development branch. The same notes apply as
+    for the debian-sid branch above.
+
+    VCS-Browser: https://code.launchpad.net/~ubuntu-core-dev/python-apt/ubuntu
+
+
+C++ Coding style
+----------------
+When you work on the C++ code in the python/ directory, you should follow some
+basic rules.
+
+The indentation of the code is a bit non-standard. We currently use 3 spaces
+indentation for the C++ code.
+
+When you create new functions, you should follow some naming conventions. All
+C++ functions are named according to the ``CamelCase`` convention.
+
+The resulting Python functions should be ``CamelCase`` as well in apt_pkg, or
+``mixedCase`` in apt_inst. The same applies for variables, parameters,
+attributes, etc.
+
+.. note::
+
+    This coding style guidelines are incomplete. If you have any questions
+    send an email to deity@lists.debian.org.
+
+.. note::
+
+    The coding style may be changed completely during the port to Python 3.0.
+    But this will not happen very soon.
+
+
+Python Coding Style
+-------------------
+The coding style for all code written in python is :PEP:`8`. For modules added
+from version 0.7.9 on, there are no exceptions.
+
+Modules introduced prior to 0.7.9 use mixedCase names for methods, functions
+and variables. These names will be replaced by names conforming to :PEP:`8`
+in a future release of python-apt.
+
+Therefore, try to reduce the introduction of the mixedName code to the absolute
+minimum (sometimes you can also use shorter names).
+
+To prepare the port to Python 3.0, code should not use any functionality which
+is deprecated as of Python 2.6.
+
+The has_key() functionality may be used only on TagSection objects; as they
+provide no other way to do this. If someone is willing to adapt TagSection to
+support ``key in mapping`` and ``iter(mapping)``, this would be great.
+
+.. note::
+
+    You can use the tool pep8.py from http://svn.browsershots.org/trunk/devtools/pep8/
+    to validate your code. Please also run pylint, pychecker, and pyflakes and
+    fix all new **errors** they report (undefined names, etc.).
+
+Submitting your patch
+---------------------
+First of all, the patch you create should be based against the debian-sid
+branch of python-apt.
+
+Once you have made your change, check that it:
+
+    * conforms to :PEP:`8` (checked with pep8.py). It should, at least not
+      introduce new errors. (and never have whitespace at end of line)
+    * produces no new errors in pychecker, pyflakes and pylint (unless you
+      can't fix them, but please tell so when requesting the merge, so it can
+      be fixed before hitting one of the main branches).
+    * does not change the behaviour of existing code in a non-compatible way.
+
+If your change follows all points of the checklist, you can commit it to your
+repository. (You could commit it first, and check later, and then commit the
+fixes, but commits should be logical and it makes no sense to have to commits
+for one logical unit).
+
+Once you have made all your changes,  you can run ``bzr send -o patch-name``
+to create a so called *merge-directive*, which contains your changes and
+allows us to preserve the history of your changes. (But please replace patch-name
+with something useful).
+
+Now report a bug against the python-apt package, attach the merge directive
+you created in the previous step, and tag it with 'patch'. It might also be
+a good idea to prefix the bug report with '[PATCH]'.
+
+If your patch introduces new functions, parameters, etc. , but does not update
+the content of this documentation, please CC. jak@debian.org, and add a short
+notice to the bug report. Also see `Documentation updates`
+
+Once your patch got merged, you can *pull* the branch into which it has been
+merged into your local one. If you have made changes since you submitted your
+patch, you may need to *merge* the branch instead.
+
+.. note::
+
+    If you plan to work on python-apt for a longer time, it may be a good
+    idea to publish your branch somewhere. Alioth (http://alioth.debian.org)
+    and Launchpad (https://launchpad.net) provide bzr hosting. You can also
+    use any webspace with ftp or sftp connection (for the upload). Then you do
+    not need to send *merge directives*, but you can point to your branch
+    instead.
+
+
+Documentation updates
+---------------------
+If you want to update the documentation, please follow the procedure as written
+above. But please CC: jak@debian.org in the bug report.
+
+You can send your content in plain text, but reStructuredText is the preferred
+format. I (Julian Andres Klode) will review your patch and will forward them to
+Michael Vogt, for inclusion in his branch. On release, this will be merged into
+the debian-sid branch.
+
+
+Example patch session
+----------------------
+In the following example, we edit a file, create a merge directive (an enhanced
+patch), and report a wishlist bug with this patch against the python-apt
+package::
+
+    user@pc:~$ bzr clone http://bzr.debian.org/apt/python-apt/debian-sid/
+    user@pc:~$ cd debian-sid
+    user@pc:~/debian-sid$ editor FILES
+    user@pc:~/debian-sid$ pep8.py FILES # PEP 8 check, see above.
+    user@pc:~/debian-sid$ pylint -e FILES # Check with pylint
+    user@pc:~/debian-sid$ pyflakes FILES  # Check with pyflakes
+    user@pc:~/debian-sid$ pychecker FILES # Check with pychecker
+    user@pc:~/debian-sid$ bzr commit
+    user@pc:~/debian-sid$ bzr send -o my-patch
+    user@pc:~/debian-sid$ reportbug --severity=wishlist --tag=patch --attach=my-patch python-apt
+    user@pc:~/debian-sid$ # Add --list-cc=jak@debian.org if you change docs.
diff --git a/doc/source/conf.py b/doc/source/conf.py
new file mode 100644
index 00000000..8f71e3e3
--- /dev/null
+++ b/doc/source/conf.py
@@ -0,0 +1,200 @@
+# -*- coding: utf-8 -*-
+#
+# python-apt documentation build configuration file, created by
+# sphinx-quickstart on Wed Jan  7 17:04:36 2009.
+#
+# This file is execfile()d with the current directory set to its containing
+# dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed
+# automatically).
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+import os
+import sys
+
+# If your extensions are in another directory, add it here. If the directory
+# is relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('../..'))
+if os.path.exists("../../build"):
+    for dirname in os.listdir('../../build'):
+        sys.path.insert(0, os.path.abspath('../../build/' + dirname))
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
+              'sphinx.ext.intersphinx', 'sphinx.ext.todo']
+intersphinx_mapping = {'http://docs.python.org/': None}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'python-apt'
+copyright = u'2009, Julian Andres Klode <jak@debian.org>'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.7'
+# The full version, including alpha/beta/rc tags.
+release = '0.7.9~exp2'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = []
+
+# The reST default role (used for this markup: `text`) for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['.static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'python-aptdoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source index, target name, title, author, document class [howto/manual]).
+latex_documents = [
+  ('index', 'python-apt.tex', ur'python-apt Documentation',
+   ur'Julian Andres Klode <jak@debian.org>', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
+
+todo_include_todos = True
diff --git a/doc/source/examples/apt-gtk.py b/doc/source/examples/apt-gtk.py
new file mode 100644
index 00000000..c3bb09d5
--- /dev/null
+++ b/doc/source/examples/apt-gtk.py
@@ -0,0 +1,29 @@
+#!/usr/bin/python
+"""Example for gtk widgets"""
+import pygtk
+pygtk.require("2.0")
+import gtk
+
+import apt.gtk.widgets
+
+
+def main():
+    """Main function."""
+    win = gtk.Window()
+    win.connect("destroy", gtk.main_quit)
+    progress = apt.gtk.widgets.GtkAptProgress()
+    win.set_title("GtkAptProgress Demo")
+    win.add(progress)
+    progress.show()
+    win.show()
+    cache = apt.cache.Cache(progress.open)
+    if cache["xterm"].isInstalled:
+        cache["xterm"].markDelete()
+    else:
+        cache["xterm"].markInstall()
+    progress.show_terminal(expanded=True)
+    cache.commit(progress.fetch, progress.install)
+    gtk.main()
+
+if __name__ == "__main__":
+    main()
diff --git a/doc/source/examples/cache-packages.py b/doc/source/examples/cache-packages.py
new file mode 100644
index 00000000..1abe7cf2
--- /dev/null
+++ b/doc/source/examples/cache-packages.py
@@ -0,0 +1,22 @@
+#!/usr/bin/python
+"""Example for packages. Print all essential and important packages"""
+
+import apt_pkg
+
+
+def main():
+    """Main."""
+    apt_pkg.InitConfig()
+    apt_pkg.InitSystem()
+    cache = apt_pkg.GetCache()
+    print "Essential packages:"
+    for pkg in cache.Packages:
+        if pkg.Essential:
+            print " ", pkg.Name
+    print "Important packages:"
+    for pkg in cache.Packages:
+        if pkg.Important:
+            print " ", pkg.Name
+
+if __name__ == "__main__":
+    main()
diff --git a/doc/source/examples/cache-pkgfile.py b/doc/source/examples/cache-pkgfile.py
new file mode 100644
index 00000000..f25975d3
--- /dev/null
+++ b/doc/source/examples/cache-pkgfile.py
@@ -0,0 +1,29 @@
+#!/usr/bin/python
+import apt_pkg
+
+
+def main():
+    """Example for PackageFile()"""
+    apt_pkg.init()
+    cache = apt_pkg.GetCache()
+    for pkgfile in cache.FileList:
+        print 'Package-File:', pkgfile.FileName
+        print 'Index-Type:', pkgfile.IndexType # 'Debian Package Index'
+        if pkgfile.NotSource:
+            print 'Source: None'
+        else:
+            if pkgfile.Site:
+                # There is a source, and a site, print the site
+                print 'Source:', pkgfile.Site
+            else:
+                # It seems to be a local repository
+                print 'Source: Local package file'
+        if pkgfile.NotAutomatic:
+            # The system won't be updated automatically (eg. experimental)
+            print 'Automatic: No'
+        else:
+            print 'Automatic: Yes'
+        print
+
+if __name__ == '__main__':
+    main()
diff --git a/doc/source/examples/dpkg-contents.py b/doc/source/examples/dpkg-contents.py
new file mode 100644
index 00000000..99d1596f
--- /dev/null
+++ b/doc/source/examples/dpkg-contents.py
@@ -0,0 +1,55 @@
+#!/usr/bin/python
+"""Emulate dpkg --contents"""
+
+import grp
+import pwd
+import stat
+import sys
+import time
+
+import apt_inst
+
+
+def format_mode(what, mode):
+    """Return the symbolic mode"""
+    s_mode = dict(DIR="d", HARDLINK="h", FILE="-").get(what)
+    s_mode += ((mode & stat.S_IRUSR) and "r" or "-")
+    s_mode += ((mode & stat.S_IWUSR) and "w" or "-")
+    s_mode += ((mode & stat.S_IXUSR) and (mode & stat.S_ISUID and "s" or "x")
+                                      or (mode & stat.S_ISUID and "S" or "-"))
+    s_mode += ((mode & stat.S_IRGRP) and "r" or "-")
+    s_mode += ((mode & stat.S_IWGRP) and "w" or "-")
+    s_mode += ((mode & stat.S_IXGRP) and (mode & stat.S_ISGID and "s" or "x")
+                                      or (mode & stat.S_ISGID and "S" or "-"))
+    s_mode += ((mode & stat.S_IROTH) and "r" or "-")
+    s_mode += ((mode & stat.S_IWOTH) and "w" or "-")
+    s_mode += ((mode & stat.S_IXOTH) and "x" or "-")
+    return s_mode
+
+
+def callback(what, name, link, mode, uid, gid, size, mtime, major, minor):
+    """callback for debExtract"""
+    s_mode = format_mode(what, mode)
+    s_owner = "%s/%s" % (pwd.getpwuid(uid)[0], grp.getgrgid(gid)[0])
+    s_size = "%9d" % size
+    s_time = time.strftime("%Y-%m-%d %H:%M", time.localtime(mtime))
+    s_name = name.startswith(".") and name or ("./" + name)
+    if link:
+        s_name += " link to %s" % link
+    print s_mode, s_owner, s_size, s_time, s_name
+
+
+def main():
+    """Main function"""
+    if len(sys.argv) < 2:
+        print >> sys.stderr, "need filename argumnet"
+        sys.exit(1)
+
+    fobj = open(sys.argv[1])
+    try:
+        apt_inst.debExtract(fobj, callback, "data.tar.gz")
+    finally:
+        fobj.close()
+
+if __name__ == "__main__":
+    main()
diff --git a/doc/source/examples/dpkg-extract.py b/doc/source/examples/dpkg-extract.py
new file mode 100644
index 00000000..ced8652f
--- /dev/null
+++ b/doc/source/examples/dpkg-extract.py
@@ -0,0 +1,25 @@
+#!/usr/bin/python
+"""Emulate dpkg --extract package.deb outdir"""
+import os
+import sys
+
+import apt_inst
+
+
+def main():
+    """Main function."""
+    if len(sys.argv) < 3:
+        print >> sys.stderr, "Usage:", __file__, "package.deb outdir"
+        sys.exit(1)
+    if not os.path.exists(sys.argv[2]):
+        print >> sys.stderr, "The directory %s does not exist" % sys.argv[2]
+        sys.exit(1)
+
+    fobj = open(sys.argv[1])
+    try:
+        apt_inst.debExtractArchive(fobj, sys.argv[2])
+    finally:
+        fobj.close()
+
+if __name__ == "__main__":
+    main()
diff --git a/doc/source/examples/dpkg-info.py b/doc/source/examples/dpkg-info.py
new file mode 100644
index 00000000..ff98d8b1
--- /dev/null
+++ b/doc/source/examples/dpkg-info.py
@@ -0,0 +1,20 @@
+#!/usr/bin/python
+"""Emulate dpkg --info package.deb control-file"""
+import sys
+
+from apt_inst import debExtractControl
+
+
+def main():
+    """Main function."""
+    if len(sys.argv) < 3:
+        print >> sys.stderr, 'Usage: tool file.deb control-file'
+        sys.exit(0)
+    fobj = open(sys.argv[1])
+    try:
+        print debExtractControl(fobj, sys.argv[2])
+    finally:
+        fobj.close()
+
+if __name__ == '__main__':
+    main()
diff --git a/doc/source/examples/missing-deps.py b/doc/source/examples/missing-deps.py
new file mode 100644
index 00000000..3ca16e45
--- /dev/null
+++ b/doc/source/examples/missing-deps.py
@@ -0,0 +1,52 @@
+#!/usr/bin/python
+"""Check the archive for missing dependencies"""
+import apt_pkg
+
+
+def fmt_dep(dep):
+    """Format a Dependency object [of apt_pkg] as a string."""
+    ret = dep.TargetPkg.Name
+    if dep.TargetVer:
+        ret += " (%s %s)" % (dep.CompType, dep.TargetVer)
+    return ret
+
+
+def check_version(pkgver):
+    """Check the version of the package"""
+    missing = []
+
+    for or_group in pkgver.DependsList.get("Pre-Depends", []) + \
+                    pkgver.DependsList.get("Depends", []):
+        if not any(dep.AllTargets() for dep in or_group):
+            # If none of the or-choices can be satisfied, add it to missing
+            missing.append(or_group)
+
+    if missing:
+        print "Package:", pkgver.ParentPkg.Name
+        print "Version:", pkgver.VerStr
+        print "Missing:",
+        print ", ".join(" | ".join(fmt_dep(dep) for dep in or_group)
+                        for or_group in missing)
+        print
+
+
+def main():
+    """The main function."""
+    apt_pkg.InitConfig()
+    apt_pkg.InitSystem()
+
+    cache = apt_pkg.GetCache()
+
+    for pkg in sorted(cache.Packages, key=lambda pkg: pkg.Name):
+        # pkg is from a list of packages, sorted by name.
+        for version in pkg.VersionList:
+            # Check every version
+            for pfile, _ in version.FileList:
+                if (pfile.Origin == "Debian" and pfile.Component == "main" and
+                    pfile.Archive == "unstable"):
+                    # We only want packages from Debian unstable main.
+                    check_version(version)
+                    break
+
+if __name__ == "__main__":
+    main()
diff --git a/doc/source/index.rst b/doc/source/index.rst
new file mode 100644
index 00000000..23ea4cca
--- /dev/null
+++ b/doc/source/index.rst
@@ -0,0 +1,41 @@
+Welcome to python-apt's documentation!
+======================================
+
+.. note::
+
+    This documentation can not be considered complete at the moment. But it
+    provides better documentation than the documentation available through
+    pydoc.
+
+.. note::
+
+
+    This documentation has been created by Sphinx, using reStructuredText files
+    written by Julian Andres Klode <jak@debian.org>, and in case of the apt
+    package, from the documentation shipped in the modules.
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   apt/index
+   apt_pkg/index
+   apt_inst
+   aptsources/index
+   coding
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
+TODO
+======
+.. todolist::