* 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.

3 files changed, 102 insertions, 0 deletions

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()