* doc/: Heavily improve documentation

Complete the documentation of pkgCache, pkgDepCache, pkgCache::Package.

Introduce new documentation for pkgCache::Version, pkgCache::Dependency,
pkgCache::PackageFile, pkgcache::Description.

There is also an example now which checks for missing dependencies.

7 files changed, 655 insertions, 14 deletions

diff --git a/doc/source/apt/debfile.rst b/doc/source/apt/debfile.rst
index 70c39087..c0146df9 100644
--- a/doc/source/apt/debfile.rst
+++ b/doc/source/apt/debfile.rst
@@ -21,8 +21,10 @@ Binary packages
     If you specify ``cache`` it has to point to an :class:`apt.cache.Cache()`
     object.
 
-    All methods except for :meth:`open()` and the attribute :attr:`filelist` have been
-    introduced in version 0.7.9.
+    .. versionchanged:: 0.7.9
+        Introduce all new methods (everything except for :meth:`open()` and
+        :attr:`filelist`)
+
 
 Source packages
 ----------------
diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst
index abb0fab2..81ee2a8e 100644
--- a/doc/source/apt_pkg/cache.rst
+++ b/doc/source/apt_pkg/cache.rst
@@ -1,5 +1,10 @@
-Low-Level Cache Handling
-===========================
+Classes in apt_pkg
+==================
+
+.. todo::
+
+    This should be split and cleaned up a bit.
+
 
 .. class:: Acquire
 
@@ -12,6 +17,9 @@ Low-Level Cache Handling
 
         Shut the fetcher down.
 
+
+The cache
+---------
 .. class:: pkgCache
 
     The :class:`pkgCache` class prov
@@ -37,10 +45,121 @@ Low-Level Cache Handling
 
     .. method:: __getitem__(item)
 
-        Return an :class:`pkgCachePackage` object for the package with the given
+        Return an :class:`Package` object for the package with the given
         name.
 
-.. class:: pkgCachePackage
+    .. 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.
+
+
+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:
+
+        .. code-block:: python
+
+            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
+
+
+A Package
+---------
+
+.. class:: Package
 
     The pkgCache::Package objects are an interface to package specific
     features.
@@ -48,23 +167,285 @@ Low-Level Cache Handling
 
     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
+
+
+
+Version, as returned by eg. :meth:`pkgDepCache.GetCandidateVer`
+---------------------------------------------------------------
+.. 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:
+
+        .. code-block:: python
+
+            {'Depends': [
+                            [
+                             ('python', '2.4', '>=')
+                            ]
+                        ]
+            }
+
+        The same for a dependency on A (>= 1) | B (>= 2):
+
+        .. code-block:: python
+
+            {'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
 
-        The ID of the package. This can be used to store information about
-        the package. The ID is an int value.
+        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.
+
+
+The Dependency class
+--------------------
+.. 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
 
-Working with dependencies
--------------------------
+        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
+
+
+The Description class
+---------------------
+.. 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).
+
+
+
+The pkgDepCache wrapper
+-----------------------
 .. class:: pkgDepCache
 
     The pkgDepCache object contains various methods to manipulate the cache,
@@ -89,7 +470,138 @@ Working with dependencies
         Return the candidate version of the package, ie. the version that
         would be installed normally.
 
-        The parameter ``pkg`` refers to an :class:`pkgCachePackage` object,
+        The parameter ``pkg`` refers to an :class:`Package` object,
         available using the :class:`pkgCache`.
 
-        This method returns a :class:`pkgCacheVersion` object.
+        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.
diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst
index 5f23df31..1c5866a9 100644
--- a/doc/source/apt_pkg/index.rst
+++ b/doc/source/apt_pkg/index.rst
@@ -83,6 +83,20 @@ The Acquire interface
 
         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
@@ -184,6 +198,8 @@ Data
 .. data:: RewriteSourceOrder
 
 
+.. _CurStates:
+
 Package States
 ^^^^^^^^^^^^^^^
 .. data:: CurStateConfigFiles
@@ -206,6 +222,8 @@ Dependency types
 .. data:: DepReplaces
 .. data:: DepSuggests
 
+.. _InstStates:
+
 Installed states
 ^^^^^^^^^^^^^^^^^
 .. data:: InstStateHold
@@ -213,6 +231,7 @@ Installed states
 .. data:: InstStateOk
 .. data:: InstStateReInstReq
 
+.. _Priorities:
 
 Priorities
 ^^^^^^^^^^
@@ -222,7 +241,10 @@ Priorities
 .. data:: PriRequired
 .. data:: PriStandard
 
-Dselect states
+
+.. _SelStates:
+
+Select states
 ^^^^^^^^^^^^^^
 .. data:: SelStateDeInstall
 .. data:: SelStateHold
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 907e2275..bb8056ad 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -30,7 +30,8 @@ if os.path.exists("../../build"):
 
 # 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']
+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.
@@ -193,3 +194,5 @@ latex_documents = [
 
 # If false, no module index is generated.
 #latex_use_modindex = True
+
+todo_include_todos = True
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/missing-deps.py b/doc/source/examples/missing-deps.py
new file mode 100644
index 00000000..0870eb98
--- /dev/null
+++ b/doc/source/examples/missing-deps.py
@@ -0,0 +1,51 @@
+#!/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()