25 files changed, 1143 insertions, 0 deletions
diff --git a/doc/examples/acquire.py b/doc/examples/acquire.py
new file mode 100644
index 0000000..3d1e31b
--- /dev/null
+++ b/doc/examples/acquire.py
@@ -0,0 +1,80 @@
+#!/usr/bin/python3
+import os
+
+import apt_pkg
+
+import apt
+import apt.progress.text
+
+
+def get_file(fetcher, uri, destfile):
+    # get the file
+    af = apt_pkg.AcquireFile(fetcher, uri=uri, descr="sample descr", destfile=destfile)
+    print(f"desc_uri: {af.desc_uri} -> {af.destfile}")
+    res = fetcher.run()
+    if res != fetcher.RESULT_CONTINUE:
+        return False
+    return True
+
+
+apt_pkg.init()
+
+# apt_pkg.config.set("Debug::pkgDPkgPM","1");
+# apt_pkg.config.set("Debug::pkgPackageManager","1");
+# apt_pkg.config.set("Debug::pkgDPkgProgressReporting","1");
+
+cache = apt_pkg.Cache()
+depcache = apt_pkg.DepCache(cache)
+
+recs = apt_pkg.PackageRecords(cache)
+list = apt_pkg.SourceList()
+list.read_main_list()
+
+# show the amount fetch needed for a dist-upgrade
+depcache.upgrade(True)
+progress = apt.progress.text.AcquireProgress()
+fetcher = apt_pkg.Acquire(progress)
+pm = apt_pkg.PackageManager(depcache)
+pm.get_archives(fetcher, list, recs)
+print(f"{apt_pkg.size_to_str(fetcher.fetch_needed)} ({fetcher.fetch_needed})")
+actiongroup = apt_pkg.ActionGroup(depcache)
+for pkg in cache.packages:
+    depcache.mark_keep(pkg)
+
+try:
+    os.mkdir("/tmp/pyapt-test")
+    os.mkdir("/tmp/pyapt-test/partial")
+except OSError:
+    pass
+apt_pkg.config.set("Dir::Cache::archives", "/tmp/pyapt-test")
+
+pkg = cache["2vcard"]
+depcache.mark_install(pkg)
+
+progress = apt.progress.text.AcquireProgress()
+fetcher = apt_pkg.Acquire(progress)
+# fetcher = apt_pkg.Acquire()
+pm = apt_pkg.PackageManager(depcache)
+
+print(pm)
+print(fetcher)
+
+get_file(fetcher, "ftp://ftp.debian.org/debian/dists/README", "/tmp/lala")
+
+pm.get_archives(fetcher, list, recs)
+
+for item in fetcher.items:
+    print(item)
+    if item.status == item.STAT_ERROR:
+        print("Some error ocured: '%s'" % item.error_text)
+    if not item.complete:
+        print("No error, still nothing downloaded (%s)" % item.error_text)
+    print()
+
+
+res = fetcher.run()
+print("fetcher.Run() returned: %s" % res)
+
+print("now runing pm.DoInstall()")
+res = pm.do_install(1)
+print("pm.DoInstall() returned: %s" % res)
diff --git a/doc/examples/action.py b/doc/examples/action.py
new file mode 100644
index 0000000..59e050b
--- /dev/null
+++ b/doc/examples/action.py
@@ -0,0 +1,116 @@
+#!/usr/bin/python3
+#
+# LOW LEVEL example how to deal with the depcache
+#
+# you probably do not want to use this low level code and use
+# the high level "apt" interface instead that can do all this
+# but with a nicer API
+
+import apt_pkg
+from progress import TextFetchProgress
+
+from apt.progress.text import OpProgress
+
+# init
+apt_pkg.init()
+
+progress = OpProgress()
+cache = apt_pkg.Cache(progress)
+print("Available packages: %s " % cache.package_count)
+
+print("Fetching")
+progress = TextFetchProgress()
+source = apt_pkg.SourceList()
+cache.update(progress, source)
+
+iter = cache["base-config"]
+print("example package iter: %s" % iter)
+
+# get depcache
+print("\n\n depcache")
+depcache = apt_pkg.DepCache(cache)
+depcache.read_pinfile()
+print("got a depcache: %s " % depcache)
+print("Marked for install: %s " % depcache.inst_count)
+
+print("\n\n Reinit")
+depcache.init(progress)
+
+# sys.exit()
+
+# get a canidate version
+ver = depcache.get_candidate_ver(iter)
+print("Candidate version: %s " % ver)
+
+print("\n\nQuerry interface")
+print(f"{iter.name}.is_upgradable(): {depcache.is_upgradable(iter)}")
+
+print("\nMarking interface")
+print("Marking '%s' for install" % iter.name)
+depcache.mark_install(iter)
+print("Install count: %s " % depcache.inst_count)
+print(f"{iter.name}.marked_install(): {depcache.marked_install(iter)}")
+print(f"{iter.name}.marked_upgrade(): {depcache.marked_upgrade(iter)}")
+print(f"{iter.name}.marked_delete(): {depcache.marked_delete(iter)}")
+
+print("Marking %s for delete" % iter.name)
+depcache.mark_delete(iter)
+print("del_count: %s " % depcache.del_count)
+print(f"{iter.name}.marked_delete(): {depcache.marked_delete(iter)}")
+
+iter = cache["apt"]
+print("\nMarking '%s' for install" % iter.name)
+depcache.mark_install(iter)
+print("Install count: %s " % depcache.inst_count)
+print(f"{iter.name}.marked_install(): {depcache.marked_install(iter)}")
+print(f"{iter.name}.marked_upgrade(): {depcache.marked_upgrade(iter)}")
+print(f"{iter.name}.marked_delete(): {depcache.marked_delete(iter)}")
+
+print("Marking %s for keep" % iter.name)
+depcache.mark_keep(iter)
+print("Install: %s " % depcache.inst_count)
+
+iter = cache["python-apt"]
+print("\nMarking '%s' for install" % iter.name)
+depcache.mark_install(iter)
+print("Install: %s " % depcache.inst_count)
+print("Broken count: %s" % depcache.broken_count)
+print("fix_broken() ")
+depcache.fix_broken()
+print("Broken count: %s" % depcache.broken_count)
+
+print("\nPerforming upgrade")
+depcache.upgrade()
+print("Keep: %s " % depcache.keep_count)
+print("Install: %s " % depcache.inst_count)
+print("Delete: %s " % depcache.del_count)
+print("usr_size: %s " % apt_pkg.size_to_str(depcache.usr_size))
+print("deb_size: %s " % apt_pkg.size_to_str(depcache.deb_size))
+
+for pkg in cache.packages:
+    if (
+        pkg.current_ver is not None
+        and not depcache.marked_install(pkg)
+        and depcache.is_upgradable(pkg)
+    ):
+        print("upgrade didn't upgrade (kept): %s" % pkg.name)
+
+print("\nPerforming Distupgrade")
+depcache.upgrade(True)
+print("Keep: %s " % depcache.keep_count)
+print("Install: %s " % depcache.inst_count)
+print("Delete: %s " % depcache.del_count)
+print("usr_size: %s " % apt_pkg.size_to_str(depcache.usr_size))
+print("deb_size: %s " % apt_pkg.size_to_str(depcache.deb_size))
+
+# overview about what would happen
+for pkg in cache.packages:
+    if depcache.marked_install(pkg):
+        if pkg.current_ver is not None:
+            print("Marked upgrade: %s " % pkg.name)
+        else:
+            print("Marked install: %s" % pkg.name)
+    elif depcache.marked_delete(pkg):
+        print("Marked delete: %s" % pkg.name)
+    elif depcache.marked_keep(pkg):
+        print("Marked keep: %s" % pkg.name)
diff --git a/doc/examples/all_deps.py b/doc/examples/all_deps.py
new file mode 100644
index 0000000..df8610a
--- /dev/null
+++ b/doc/examples/all_deps.py
@@ -0,0 +1,37 @@
+#!/usr/bin/python3
+import sys
+
+import apt
+
+
+def dependencies(cache, pkg, deps, key="Depends"):
+    # print "pkg: %s (%s)" % (pkg.name, deps)
+    candver = cache._depcache.get_candidate_ver(pkg._pkg)
+    if candver is None:
+        return deps
+    dependslist = candver.depends_list
+    if key in dependslist:
+        for depVerList in dependslist[key]:
+            for dep in depVerList:
+                if dep.target_pkg.name in cache:
+                    if (
+                        pkg.name != dep.target_pkg.name
+                        and dep.target_pkg.name not in deps
+                    ):
+                        deps.add(dep.target_pkg.name)
+                        dependencies(cache, cache[dep.target_pkg.name], deps, key)
+    return deps
+
+
+pkgname = sys.argv[1]
+c = apt.Cache()
+pkg = c[pkgname]
+
+deps = set()
+
+deps = dependencies(c, pkg, deps, "Depends")
+print(" ".join(deps))
+
+preDeps = set()
+preDeps = dependencies(c, pkg, preDeps, "PreDepends")
+print(" ".join(preDeps))
diff --git a/doc/examples/architecture.py b/doc/examples/architecture.py
new file mode 100644
index 0000000..3972234
--- /dev/null
+++ b/doc/examples/architecture.py
@@ -0,0 +1,12 @@
+import apt_pkg
+
+
+def main():
+    apt_pkg.init_config()
+
+    print("Native architecture:", apt_pkg.config["APT::Architecture"])
+    print("All architectures:", apt_pkg.config.value_list("APT::Architectures"))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/doc/examples/build-deps-old.py b/doc/examples/build-deps-old.py
new file mode 100755
index 0000000..71a081e
--- /dev/null
+++ b/doc/examples/build-deps-old.py
@@ -0,0 +1,74 @@
+#!/usr/bin/python3
+# this is a example how to access the build dependencies of a package
+
+import sys
+
+import apt_pkg
+
+
+def get_source_pkg(pkg, records, depcache):
+    """get the source package name of a given package"""
+    version = depcache.get_candidate_ver(pkg)
+    if not version:
+        return None
+    file, index = version.file_list.pop(0)
+    records.lookup((file, index))
+    if records.source_pkg != "":
+        srcpkg = records.source_pkg
+    else:
+        srcpkg = pkg.name
+    return srcpkg
+
+
+# main
+apt_pkg.init()
+cache = apt_pkg.Cache()
+depcache = apt_pkg.DepCache(cache)
+depcache.init()
+records = apt_pkg.PackageRecords(cache)
+srcrecords = apt_pkg.SourceRecords()
+
+# base package that we use for build-depends calculation
+if len(sys.argv) < 2:
+    print("need a package name as argument")
+    sys.exit(1)
+try:
+    pkg = base = cache[sys.argv[1]]
+except KeyError:
+    print("No package %s found" % sys.argv[1])
+    sys.exit(1)
+all_build_depends = set()
+
+# get the build depdends for the package itself
+srcpkg_name = get_source_pkg(base, records, depcache)
+print("srcpkg_name: %s " % srcpkg_name)
+if not srcpkg_name:
+    print("Can't find source package for '%s'" % pkg.mame)
+srcrec = srcrecords.lookup(srcpkg_name)
+if srcrec:
+    print("Files:")
+    print(srcrecords.files)
+    bd = srcrecords.build_depends
+    print("build-depends of the package: %s " % bd)
+    for b in bd:
+        all_build_depends.add(b[0])
+
+# calculate the build depends for all dependencies
+depends = depcache.get_candidate_ver(base).depends_list
+for dep in depends["Depends"]:  # FIXME: do we need to consider PreDepends?
+    pkg = dep[0].target_pkg
+    srcpkg_name = get_source_pkg(pkg, records, depcache)
+    if not srcpkg_name:
+        print("Can't find source package for '%s'" % pkg.name)
+        continue
+    srcrec = srcrecords.lookup(srcpkg_name)
+    if srcrec:
+        # print srcrecords.package
+        # print srcrecords.binaries
+        bd = srcrecords.build_depends
+        # print "%s: %s " % (srcpkg_name, bd)
+        for b in bd:
+            all_build_depends.add(b[0])
+
+
+print("\n".join(all_build_depends))
diff --git a/doc/examples/build-deps.py b/doc/examples/build-deps.py
new file mode 100755
index 0000000..714d1c4
--- /dev/null
+++ b/doc/examples/build-deps.py
@@ -0,0 +1,58 @@
+#!/usr/bin/python3
+# this is a example how to access the build dependencies of a package
+
+import sys
+
+import apt_pkg
+
+import apt
+
+# main
+cache = apt.Cache()
+srcrecords = apt_pkg.SourceRecords()
+
+# base package that we use for build-depends calculation
+if len(sys.argv) < 2:
+    print("need a package name as argument")
+    sys.exit(1)
+try:
+    pkg = base = cache[sys.argv[1]]
+except KeyError:
+    print("No package %s found" % sys.argv[1])
+    sys.exit(1)
+all_build_depends = set()
+
+# get the build depdends for the package itself
+srcpkg_name = base.candidate.source_name
+print("srcpkg_name: %s " % srcpkg_name)
+if not srcpkg_name:
+    print("Can't find source package for '%s'" % pkg.name)
+srcrec = srcrecords.lookup(srcpkg_name)
+if srcrec:
+    print("Files:")
+    print(srcrecords.files)
+    bd = srcrecords.build_depends
+    print("build-depends of the package: %s " % bd)
+    for b in bd:
+        all_build_depends.add(b[0])
+
+# calculate the build depends for all dependencies
+depends = base.candidate.dependencies
+for or_dep in depends:
+    for dep in or_dep.or_dependencies:
+        pkg = cache[dep.name]
+        srcpkg_name = pkg.candidate.source_name
+        if not srcpkg_name:
+            print("Can't find source package for '%s'" % pkg.name)
+            continue
+        srcrec = srcrecords.lookup(srcpkg_name)
+        if srcrec:
+            # print srcrecords.package
+            # print srcrecords.binaries
+            bd = srcrecords.build_depends
+            # print "%s: %s " % (srcpkg_name, bd)
+            for b in bd:
+                all_build_depends.add(b[0])
+
+
+print("\n".join(all_build_depends))
diff --git a/doc/examples/cdrom.py b/doc/examples/cdrom.py
new file mode 100644
index 0000000..ad4d2ba
--- /dev/null
+++ b/doc/examples/cdrom.py
@@ -0,0 +1,24 @@
+#!/usr/bin/python3
+# example how to deal with the depcache
+
+import sys
+
+import apt_pkg
+from progress import TextCdromProgress
+
+# init
+apt_pkg.init()
+
+cdrom = apt_pkg.Cdrom()
+print(cdrom)
+
+progress = TextCdromProgress()
+
+(res, ident) = cdrom.ident(progress)
+print(f"ident result is: {res} ({ident}) ")
+
+apt_pkg.config["APT::CDROM::Rename"] = "True"
+cdrom.add(progress)
+
+print("Exiting")
+sys.exit(0)
diff --git a/doc/examples/checkstate.py b/doc/examples/checkstate.py
new file mode 100755
index 0000000..d4276e8
--- /dev/null
+++ b/doc/examples/checkstate.py
@@ -0,0 +1,37 @@
+#!/usr/bin/python3
+#
+#
+# this example is not usefull to find out about updated, upgradable packages
+# use the depcache.py example for it (because a pkgPolicy is not used here)
+#
+
+import apt_pkg
+
+apt_pkg.init()
+
+cache = apt_pkg.Cache()
+packages = cache.packages
+
+uninstalled, updated, upgradable = {}, {}, {}
+
+for package in packages:
+    versions = package.version_list
+    if not versions:
+        continue
+    version = versions[0]
+    for other_version in versions:
+        if apt_pkg.version_compare(version.ver_str, other_version.ver_str) < 0:
+            version = other_version
+    if package.current_ver:
+        current = package.current_ver
+        if apt_pkg.version_compare(current.ver_str, version.ver_str) < 0:
+            upgradable[package.name] = version
+            break
+        else:
+            updated[package.name] = current
+    else:
+        uninstalled[package.name] = version
+
+
+for line in (uninstalled, updated, upgradable):
+    print(list(line.items())[0])
diff --git a/doc/examples/config.py b/doc/examples/config.py
new file mode 100755
index 0000000..fb687e3
--- /dev/null
+++ b/doc/examples/config.py
@@ -0,0 +1,60 @@
+#!/usr/bin/python3
+# Example demonstrating how to use the configuration/commandline system
+# for configuration.
+# Some valid command lines..
+#   config.py -h --help            ; Turn on help
+#   config.py -no-h --no-help --help=no  ; Turn off help
+#   config.py -qqq -q=3            ; verbosity to 3
+#   config.py -c /etc/apt/apt.conf ; include that config file]
+#   config.py -o help=true         ; Turn on help by giving a
+#                                  ; config file string
+#   config.py -no-h -- -help       ; Turn off help, specify the file '-help'
+# -c and -o are standard APT-program options.
+
+import posixpath
+import sys
+
+# This shows how to use the system for configuration and option control.
+# The other varient is for ISC object config files. See configisc.py.
+import apt_pkg
+
+# Create a new empty Configuration object - there is also the system global
+# configuration object apt_pkg.config which is used interally by apt-pkg
+# routines to control unusual situations. I recommend using the sytem global
+# whenever possible..
+Cnf = apt_pkg.Configuration()
+
+print("Command line is", sys.argv)
+
+# Load the default configuration file, init_config() does this better..
+Cnf.set("config-file", "/etc/apt/apt.conf")  # or Cnf["config-file"] = ".."
+if posixpath.exists(Cnf.find_file("config-file")):
+    apt_pkg.read_config_file(Cnf, "/etc/apt/apt.conf")
+
+# Merge the command line arguments into the configuration space
+Arguments = [
+    ("h", "help", "help"),
+    ("v", "version", "version"),
+    ("q", "quiet", "quiet", "IntLevel"),
+    ("c", "config-file", "", "ConfigFile"),
+    ("o", "option", "", "ArbItem"),
+]
+print("FileNames", apt_pkg.parse_commandline(Cnf, Arguments, sys.argv))
+
+print("Quiet level selected is", Cnf.find_i("quiet", 0))
+
+# Do some stuff with it
+if Cnf.find_b("version", 0) == 1:
+    print("Version selected - 1.1")
+
+if Cnf.find_b("help", 0) == 1:
+    print("python-apt", apt_pkg.VERSION, "compiled on", apt_pkg.DATE, apt_pkg.TIME)
+    print("Hi, I am the help text for this program")
+    sys.exit(0)
+
+print("No help for you, try -h")
+
+# Print the configuration space
+print("The Configuration space looks like:")
+for item in list(Cnf.keys()):
+    print(f'{item} "{Cnf[item]}";')
diff --git a/doc/examples/configisc.py b/doc/examples/configisc.py
new file mode 100755
index 0000000..10700dc
--- /dev/null
+++ b/doc/examples/configisc.py
@@ -0,0 +1,49 @@
+#!/usr/bin/python3
+# Example demonstrating how to use the configuration/commandline system
+# for object setup.
+
+# This parses the given config file in 'ISC' style where the sections
+# represent object instances and shows how to iterate over the sections.
+# Pass it the sample apt-ftparchive configuration,
+# doc/examples/ftp-archive.conf
+# or a bind8 config file..
+
+import sys
+
+import apt_pkg
+
+ConfigFile = apt_pkg.parse_commandline(apt_pkg.config, [], sys.argv)
+
+if len(ConfigFile) != 1:
+    print("Must have exactly 1 file name")
+    sys.exit(0)
+
+Cnf = apt_pkg.Configuration()
+apt_pkg.read_config_file_isc(Cnf, ConfigFile[0])
+
+# Print the configuration space
+# print "The Configuration space looks like:"
+# for item in Cnf.keys():
+#   print "%s \"%s\";" % (item, Cnf[item])
+
+# bind8 config file..
+if "Zone" in Cnf:
+    print("Zones: ", Cnf.sub_tree("zone").list())
+    for item in Cnf.list("zone"):
+        SubCnf = Cnf.sub_tree(item)
+        if SubCnf.find("type") == "slave":
+            print(
+                "Masters for {}: {}".format(
+                    SubCnf.my_tag(), SubCnf.value_list("masters")
+                )
+            )
+else:
+    print("Tree definitions:")
+    for item in Cnf.list("tree"):
+        SubCnf = Cnf.sub_tree(item)
+        # This could use Find which would eliminate the possibility of
+        # exceptions.
+        print(
+            "Subtree %s with sections '%s' and architectures '%s'"
+            % (SubCnf.my_tag(), SubCnf["Sections"], SubCnf["Architectures"])
+        )
diff --git a/doc/examples/deb_inspect.py b/doc/examples/deb_inspect.py
new file mode 100755
index 0000000..72050e3
--- /dev/null
+++ b/doc/examples/deb_inspect.py
@@ -0,0 +1,61 @@
+#!/usr/bin/python3
+# some example for apt_inst
+
+import os.path
+import sys
+
+import apt_inst
+import apt_pkg
+
+
+def Callback(member, data):
+    """callback for debExtract"""
+    print(
+        "'%s','%s',%u,%u,%u,%u,%u,%u,%u"
+        % (
+            member.name,
+            member.linkname,
+            member.mode,
+            member.uid,
+            member.gid,
+            member.size,
+            member.mtime,
+            member.major,
+            member.minor,
+        )
+    )
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("need filename argumnet")
+        sys.exit(1)
+    file = sys.argv[1]
+
+    print("Working on: %s" % file)
+    print("Displaying data.tar.gz:")
+    apt_inst.DebFile(open(file)).data.go(Callback)
+
+    print("Now extracting the control file:")
+    control = apt_inst.DebFile(open(file)).control.extractdata("control")
+    sections = apt_pkg.TagSection(control)
+
+    print("Maintainer is: ")
+    print(sections["Maintainer"])
+
+    print()
+    print("DependsOn: ")
+    depends = sections["Depends"]
+    print(apt_pkg.parse_depends(depends))
+
+    print("extracting archive")
+    dir = "/tmp/deb"
+    os.mkdir(dir)
+    apt_inst.DebFile(open(file)).data.extractall(dir)
+
+    def visit(arg, dirname, names):
+        print("%s/" % dirname)
+        for file in names:
+            print("\t%s" % file)
+
+    os.path.walk(dir, visit, None)
diff --git a/doc/examples/depcache.py b/doc/examples/depcache.py
new file mode 100644
index 0000000..f6dff52
--- /dev/null
+++ b/doc/examples/depcache.py
@@ -0,0 +1,109 @@
+#!/usr/bin/python3
+# example how to deal with the depcache
+
+import apt_pkg
+from progress import TextProgress
+
+# init
+apt_pkg.init()
+
+progress = TextProgress()
+cache = apt_pkg.Cache(progress)
+print("Available packages: %s " % cache.package_count)
+
+iter = cache["base-config"]
+print("example package iter: %s" % iter)
+
+# get depcache
+print("\n\n depcache")
+depcache = apt_pkg.DepCache(cache)
+depcache.read_pinfile()
+# init is needed after the creation/pin file reading
+depcache.init(progress)
+print("got a depcache: %s " % depcache)
+print("Marked for install: %s " % depcache.inst_count)
+
+print("\n\n Reinit")
+depcache.init(progress)
+
+# sys.exit()
+
+
+# get a canidate version
+ver = depcache.get_candidate_ver(iter)
+print("Candidate version: %s " % ver)
+
+print("\n\nQuerry interface")
+print(f"{iter.name}.is_upgradable(): {depcache.is_upgradable(iter)}")
+
+print("\nMarking interface")
+print("Marking '%s' for install" % iter.name)
+depcache.mark_install(iter)
+print("Install count: %s " % depcache.inst_count)
+print(f"{iter.name}.marked_install(): {depcache.marked_install(iter)}")
+print(f"{iter.name}.marked_upgrade(): {depcache.marked_upgrade(iter)}")
+print(f"{iter.name}.marked_delete(): {depcache.marked_delete(iter)}")
+
+print("Marking %s for delete" % iter.name)
+depcache.mark_delete(iter)
+print("del_count: %s " % depcache.del_count)
+print(f"{iter.name}.marked_delete(): {depcache.marked_delete(iter)}")
+
+
+iter = cache["3dchess"]
+print("\nMarking '%s' for install" % iter.name)
+depcache.mark_install(iter)
+print("Install count: %s " % depcache.inst_count)
+print(f"{iter.name}.marked_install(): {depcache.marked_install(iter)}")
+print(f"{iter.name}.marked_upgrade(): {depcache.marked_upgrade(iter)}")
+print(f"{iter.name}.marked_delete(): {depcache.marked_delete(iter)}")
+
+print("Marking %s for keep" % iter.name)
+depcache.mark_keep(iter)
+print("Install: %s " % depcache.inst_count)
+
+iter = cache["synaptic"]
+print("\nMarking '%s' for install" % iter.name)
+depcache.mark_install(iter)
+print("Install: %s " % depcache.inst_count)
+print("Broken count: %s" % depcache.broken_count)
+print("fix_broken() ")
+depcache.fix_broken()
+print("Broken count: %s" % depcache.broken_count)
+
+print("\nPerforming upgrade")
+depcache.upgrade()
+print("Keep: %s " % depcache.keep_count)
+print("Install: %s " % depcache.inst_count)
+print("Delete: %s " % depcache.del_count)
+print("usr_size: %s " % apt_pkg.size_to_str(depcache.usr_size))
+print("deb_size: %s " % apt_pkg.size_to_str(depcache.deb_size))
+
+for pkg in cache.packages:
+    if (
+        pkg.current_ver is not None
+        and not depcache.marked_install(pkg)
+        and depcache.is_upgradable(pkg)
+    ):
+        print("upgrade didn't upgrade (kept): %s" % pkg.name)
+
+
+print("\nPerforming DistUpgrade")
+depcache.upgrade(True)
+print("Keep: %s " % depcache.keep_count)
+print("Install: %s " % depcache.inst_count)
+print("Delete: %s " % depcache.del_count)
+print("usr_size: %s " % apt_pkg.size_to_str(depcache.usr_size))
+print("deb_size: %s " % apt_pkg.size_to_str(depcache.deb_size))
+
+# overview about what would happen
+for pkg in cache.packages:
+    if depcache.marked_install(pkg):
+        if pkg.current_ver is not None:
+            print("Marked upgrade: %s " % pkg.name)
+        else:
+            print("Marked install: %s" % pkg.name)
+    elif depcache.marked_delete(pkg):
+        print("Marked delete: %s" % pkg.name)
+    elif depcache.marked_keep(pkg):
+        print("Marked keep: %s" % pkg.name)
diff --git a/doc/examples/dependant-pkgs.py b/doc/examples/dependant-pkgs.py
new file mode 100755
index 0000000..e5985b8
--- /dev/null
+++ b/doc/examples/dependant-pkgs.py
@@ -0,0 +1,38 @@
+#!/usr/bin/python3
+
+import sys
+
+import apt
+
+pkgs = set()
+cache = apt.Cache()
+for pkg in cache:
+    candver = cache._depcache.get_candidate_ver(pkg._pkg)
+    if candver is None:
+        continue
+    dependslist = candver.depends_list
+    for dep in list(dependslist.keys()):
+        # get the list of each dependency object
+        for depVerList in dependslist[dep]:
+            for z in depVerList:
+                # get all TargetVersions of
+                # the dependency object
+                for tpkg in z.all_targets():
+                    if sys.argv[1] == tpkg.parent_pkg.name:
+                        pkgs.add(pkg.name)
+
+main = set()
+universe = set()
+for pkg in pkgs:
+    cand = cache[pkg].candidate
+    if "universe" in cand.section:
+        universe.add(cand.source_name)
+    else:
+        main.add(cand.source_name)
+
+print("main:")
+print("\n".join(sorted(main)))
+print()
+
+print("universe:")
+print("\n".join(sorted(universe)))
diff --git a/doc/examples/desc.py b/doc/examples/desc.py
new file mode 100644
index 0000000..7e8e3e8
--- /dev/null
+++ b/doc/examples/desc.py
@@ -0,0 +1,25 @@
+#!/usr/bin/python3
+
+import apt_pkg
+
+apt_pkg.init()
+
+apt_pkg.config.set("APT::Acquire::Translation", "de")
+
+cache = apt_pkg.Cache()
+depcache = apt_pkg.DepCache(cache)
+
+pkg = cache["gcc"]
+cand = depcache.get_candidate_ver(pkg)
+print(cand)
+
+desc = cand.TranslatedDescription
+print(desc)
+print(desc.file_list)
+(f, index) = desc.file_list.pop(0)
+
+records = apt_pkg.PackageRecords(cache)
+records.lookup((f, index))
+desc = records.long_desc
+print(len(desc))
+print(desc)
diff --git a/doc/examples/indexfile.py b/doc/examples/indexfile.py
new file mode 100644
index 0000000..34ea94e
--- /dev/null
+++ b/doc/examples/indexfile.py
@@ -0,0 +1,22 @@
+#!/usr/bin/python3
+
+import apt_pkg
+
+apt_pkg.init()
+
+sources = apt_pkg.SourceList()
+sources.read_main_list()
+
+cache = apt_pkg.Cache()
+depcache = apt_pkg.DepCache(cache)
+pkg = cache["libimlib2"]
+cand = depcache.get_candidate_ver(pkg)
+for f, i in cand.file_list:
+    index = sources.find_index(f)
+    print(index)
+    if index:
+        print(index.size)
+        print(index.is_trusted)
+        print(index.exists)
+        print(index.has_packages)
+        print(index.archive_uri("some/path"))
diff --git a/doc/examples/inst.py b/doc/examples/inst.py
new file mode 100644
index 0000000..892b43b
--- /dev/null
+++ b/doc/examples/inst.py
@@ -0,0 +1,47 @@
+#!/usr/bin/python3
+# example how to deal with the depcache
+
+import sys
+
+import apt
+from apt.progress import InstallProgress
+
+
+class TextInstallProgress(InstallProgress):
+    def __init__(self):
+        apt.progress.InstallProgress.__init__(self)
+        self.last = 0.0
+
+    def updateInterface(self):
+        InstallProgress.updateInterface(self)
+        if self.last >= self.percent:
+            return
+        sys.stdout.write(f"\r[{self.percent}] {self.status}\n")
+        sys.stdout.flush()
+        self.last = self.percent
+
+    def conffile(self, current, new):
+        print(f"conffile prompt: {current} {new}")
+
+    def error(self, errorstr):
+        print("got dpkg error: '%s'" % errorstr)
+
+
+cache = apt.Cache(apt.progress.OpTextProgress())
+
+fprogress = apt.progress.TextFetchProgress()
+iprogress = TextInstallProgress()
+
+pkg = cache["3dchess"]
+
+# install or remove, the importend thing is to keep us busy :)
+if pkg.is_installed:
+    print("Going to delete %s" % pkg.name)
+    pkg.mark_delete()
+else:
+    print("Going to install %s" % pkg.name)
+    pkg.mark_install()
+res = cache.commit(fprogress, iprogress)
+print(res)
+
+sys.exit(0)
diff --git a/doc/examples/metaindex.py b/doc/examples/metaindex.py
new file mode 100644
index 0000000..2497e65
--- /dev/null
+++ b/doc/examples/metaindex.py
@@ -0,0 +1,16 @@
+#!/usr/bin/python3
+
+import apt_pkg
+
+apt_pkg.init()
+
+sources = apt_pkg.SourceList()
+sources.read_main_list()
+
+
+for metaindex in sources.list:
+    print(metaindex)
+    print("uri: ", metaindex.uri)
+    print("dist: ", metaindex.dist)
+    print("index_files: ", "\n".join([str(i) for i in metaindex.index_files]))
+    print()
diff --git a/doc/examples/print_uris.py b/doc/examples/print_uris.py
new file mode 100755
index 0000000..1b59e00
--- /dev/null
+++ b/doc/examples/print_uris.py
@@ -0,0 +1,10 @@
+#!/usr/bin/python3
+#
+# a example that prints the URIs of all upgradable packages
+#
+
+import apt
+
+for pkg in apt.Cache():
+    if pkg.is_upgradable:
+        print(pkg.candidate.uri)
diff --git a/doc/examples/progress.py b/doc/examples/progress.py
new file mode 100644
index 0000000..680a64d
--- /dev/null
+++ b/doc/examples/progress.py
@@ -0,0 +1,118 @@
+#!/usr/bin/python3
+
+import sys
+import time
+
+import apt_pkg
+
+import apt
+import apt.progress.base
+
+
+class TextProgress(apt.progress.base.OpProgress):
+    def __init__(self):
+        self.last = 0.0
+
+    def update(self, percent):
+        if (self.last + 1.0) <= percent:
+            sys.stdout.write("\rProgress: %i.2          " % (percent))
+            self.last = percent
+        if percent >= 100:
+            self.last = 0.0
+
+    def done(self):
+        self.last = 0.0
+        print("\rDone                      ")
+
+
+class TextFetchProgress(apt.progress.base.AcquireProgress):
+    def __init__(self):
+        pass
+
+    def start(self):
+        pass
+
+    def stop(self):
+        pass
+
+    def fail(self, item):
+        print("fail", item)
+
+    def fetch(self, item):
+        print("fetch", item)
+
+    def ims_hit(self, item):
+        print("ims_hit", item)
+
+    def pulse(self, owner):
+        print(
+            "pulse: CPS: %s/s; Bytes: %s/%s; Item: %s/%s"
+            % (
+                apt_pkg.size_to_str(self.current_cps),
+                apt_pkg.size_to_str(self.current_bytes),
+                apt_pkg.size_to_str(self.total_bytes),
+                self.current_items,
+                self.total_items,
+            )
+        )
+        return True
+
+    def media_change(self, medium, drive):
+        print(f"Please insert medium {medium} in drive {drive}")
+        sys.stdin.readline()
+        # return False
+
+
+class TextInstallProgress(apt.progress.base.InstallProgress):
+    def __init__(self):
+        apt.progress.base.InstallProgress.__init__(self)
+
+    def start_update(self):
+        print("start_update")
+
+    def finish_update(self):
+        print("finish_update")
+
+    def status_change(self, pkg, percent, status):
+        print(f"[{percent}] {pkg}: {status}")
+
+    def update_interface(self):
+        apt.progress.base.InstallProgress.update_interface(self)
+        # usefull to e.g. redraw a GUI
+        time.sleep(0.1)
+
+
+class TextCdromProgress(apt.progress.base.CdromProgress):
+    def __init__(self):
+        pass
+
+    # update is called regularly so that the gui can be redrawn
+
+    def update(self, text, step):
+        # check if we actually have some text to display
+        if text != "":
+            print(f"Update: {text.strip()} {step}")
+
+    def ask_cdrom_name(self):
+        sys.stdout.write("Please enter cd-name: ")
+        cd_name = sys.stdin.readline()
+        return (True, cd_name.strip())
+
+    def change_cdrom(self):
+        print("Please insert cdrom and press <ENTER>")
+        answer = sys.stdin.readline()
+        print(answer)
+        return True
+
+
+if __name__ == "__main__":
+    c = apt.Cache()
+    pkg = c["3dchess"]
+    if pkg.is_installed:
+        pkg.mark_delete()
+    else:
+        pkg.mark_install()
+
+    res = c.commit(TextFetchProgress(), TextInstallProgress())
+
+    print(res)
diff --git a/doc/examples/recommends.py b/doc/examples/recommends.py
new file mode 100755
index 0000000..8539cd5
--- /dev/null
+++ b/doc/examples/recommends.py
@@ -0,0 +1,37 @@
+#!/usr/bin/python3
+
+import apt_pkg
+
+apt_pkg.init()
+
+cache = apt_pkg.Cache()
+
+
+class Wanted:
+    def __init__(self, name):
+        self.name = name
+        self.recommended = []
+        self.suggested = []
+
+
+wanted = {}
+
+for package in cache.packages:
+    current = package.current_ver
+    if not current:
+        continue
+    depends = current.depends_list
+    for key, attr in (("Suggests", "suggested"), ("Recommends", "recommended")):
+        list = depends.get(key, [])
+        for dependency in list:
+            name = dependency[0].target_pkg.name
+            dep = cache[name]
+            if dep.current_ver:
+                continue
+            getattr(wanted.setdefault(name, Wanted(name)), attr).append(package.name)
+
+ks = list(wanted.keys())
+ks.sort()
+
+for want in ks:
+    print(want, wanted[want].recommended, wanted[want].suggested)
diff --git a/doc/examples/records.py b/doc/examples/records.py
new file mode 100755
index 0000000..b88ed75
--- /dev/null
+++ b/doc/examples/records.py
@@ -0,0 +1,16 @@
+#!/usr/bin/python3
+
+import apt
+
+cache = apt.Cache()
+
+for pkg in cache:
+    if not pkg.candidate.record:
+        continue
+    if "Task" in pkg.candidate.record:
+        print(
+            "Pkg {} is part of '{}'".format(
+                pkg.name, pkg.candidate.record["Task"].split()
+            )
+        )
+        # print pkg.candidateRecord
diff --git a/doc/examples/sources.py b/doc/examples/sources.py
new file mode 100644
index 0000000..b467b7d
--- /dev/null
+++ b/doc/examples/sources.py
@@ -0,0 +1,21 @@
+#!/usr/bin/python3
+
+import apt_pkg
+
+apt_pkg.init()
+
+# cache = apt_pkg.Cache()
+# sources = apt_pkg.SourceRecords(cache)
+
+sources = apt_pkg.SourceRecords()
+sources.restart()
+while sources.lookup("hello"):
+    print(
+        sources.package,
+        sources.version,
+        sources.maintainer,
+        sources.section,
+        repr(sources.binaries),
+    )
+    print(sources.files)
+    print(sources.index.archive_uri(sources.files[0][2]))
diff --git a/doc/examples/tagfile.py b/doc/examples/tagfile.py
new file mode 100755
index 0000000..beb749b
--- /dev/null
+++ b/doc/examples/tagfile.py
@@ -0,0 +1,8 @@
+#!/usr/bin/python3
+import apt_pkg
+
+Parse = apt_pkg.TagFile(open("/var/lib/dpkg/status"))
+
+while Parse.step() == 1:
+    print(Parse.section.get("Package"))
+    print(apt_pkg.parse_depends(Parse.section.get("Depends", "")))
diff --git a/doc/examples/update.py b/doc/examples/update.py
new file mode 100755
index 0000000..a8d46b6
--- /dev/null
+++ b/doc/examples/update.py
@@ -0,0 +1,14 @@
+#!/usr/bin/python3
+import os.path
+
+import apt_pkg
+
+import apt
+
+if __name__ == "__main__":
+    apt_pkg.config.set("APT::Update::Pre-Invoke::", "touch /tmp/update-about-to-run")
+    apt_pkg.config.set("APT::Update::Post-Invoke::", "touch /tmp/update-was-run")
+    c = apt.Cache()
+    res = c.update(apt.progress.TextFetchProgress())
+    print("res: ", res)
+    assert os.path.exists("/tmp/update-about-to-run")
diff --git a/doc/examples/versiontest.py b/doc/examples/versiontest.py
new file mode 100755
index 0000000..fcc4c25
--- /dev/null
+++ b/doc/examples/versiontest.py
@@ -0,0 +1,54 @@
+#!/usr/bin/python3
+
+# This is a simple clone of tests/versiontest.cc
+import re
+import sys
+
+import apt_pkg
+
+apt_pkg.init_config()
+apt_pkg.init_system()
+
+TestFile = apt_pkg.parse_commandline(apt_pkg.config, [], sys.argv)
+if len(TestFile) != 1:
+    print("Must have exactly 1 file name")
+    sys.exit(0)
+
+# Go over the file..
+list = open(TestFile[0])
+CurLine = 0
+while True:
+    Line = list.readline()
+    CurLine = CurLine + 1
+    if Line == "":
+        break
+    Line = Line.strip()
+    if len(Line) == 0 or Line[0] == "#":
+        continue
+
+    Split = re.split("[ \n]", Line)
+
+    # Check forward
+    if apt_pkg.version_compare(Split[0], Split[1]) != int(Split[2]):
+        print(
+            "Comparision failed on line %u. '%s' ? '%s' %i != %i"
+            % (
+                CurLine,
+                Split[0],
+                Split[1],
+                apt_pkg.version_compare(Split[0], Split[1]),
+                int(Split[2]),
+            )
+        )
+    # Check reverse
+    if apt_pkg.version_compare(Split[1], Split[0]) != -1 * int(Split[2]):
+        print(
+            "Comparision failed on line %u. '%s' ? '%s' %i != %i"
+            % (
+                CurLine,
+                Split[1],
+                Split[0],
+                apt_pkg.version_compare(Split[1], Split[0]),
+                -1 * int(Split[2]),
+            )
+        )