merge from the debian-unstable tree

15 files changed, 204 insertions, 67 deletions

diff --git a/doc/examples/acquire.py b/doc/examples/acquire.py
index a23c41c6..41a38588 100644
--- a/doc/examples/acquire.py
+++ b/doc/examples/acquire.py
@@ -2,8 +2,6 @@
 import apt
 import apt_pkg
 import os
-import sys
-import tempfile
 
 
 def get_file(fetcher, uri, destFile):
diff --git a/doc/examples/action.py b/doc/examples/action.py
index 9b9d7dd3..8ee86eb7 100644
--- a/doc/examples/action.py
+++ b/doc/examples/action.py
@@ -3,7 +3,6 @@
 
 import apt_pkg
 import sys
-import copy
 from apt.progress import OpTextProgress
 from progress import TextFetchProgress
 
diff --git a/doc/examples/build-deps.py b/doc/examples/build-deps.py
index aeb5667c..b5ac88a2 100755
--- a/doc/examples/build-deps.py
+++ b/doc/examples/build-deps.py
@@ -32,7 +32,7 @@ if len(sys.argv) < 2:
     print "need a package name as argument"
     sys.exit(1)
 try:
-    base = cache[sys.argv[1]]
+    pkg = base = cache[sys.argv[1]]
 except KeyError:
     print "No package %s found" % sys.argv[1]
     sys.exit(1)
diff --git a/doc/examples/cdrom.py b/doc/examples/cdrom.py
index 743220a6..408bd720 100644
--- a/doc/examples/cdrom.py
+++ b/doc/examples/cdrom.py
@@ -3,10 +3,8 @@
 
 import apt_pkg
 import sys
-import os
-import copy
 
-from progress import CdromProgress
+from progress import TextCdromProgress
 
 
 # init
@@ -15,7 +13,7 @@ apt_pkg.init()
 cdrom = apt_pkg.GetCdrom()
 print cdrom
 
-progress = CdromProgress()
+progress = TextCdromProgress()
 
 (res, ident) = cdrom.Ident(progress)
 print "ident result is: %s (%s) " % (res, ident)
diff --git a/doc/examples/configisc.py b/doc/examples/configisc.py
index de8ec6be..8da1ad0a 100755
--- a/doc/examples/configisc.py
+++ b/doc/examples/configisc.py
@@ -10,7 +10,6 @@
 
 import apt_pkg
 import sys
-import posixpath
 
 ConfigFile = apt_pkg.ParseCommandLine(apt_pkg.Config, [], sys.argv)
 
diff --git a/doc/examples/depcache.py b/doc/examples/depcache.py
index 790cc9d6..de038fe8 100644
--- a/doc/examples/depcache.py
+++ b/doc/examples/depcache.py
@@ -1,10 +1,7 @@
 #!/usr/bin/python
 # example how to deal with the depcache
 
-import apt
 import apt_pkg
-import sys
-import copy
 from progress import TextProgress
 
 
diff --git a/doc/examples/gui-inst.py b/doc/examples/gui-inst.py
index 8138d922..68f06fc0 100755
--- a/doc/examples/gui-inst.py
+++ b/doc/examples/gui-inst.py
@@ -5,13 +5,13 @@ import pygtk
 pygtk.require('2.0')
 import gtk
 
-import apt.gtk.widgets
+import apt.progress.gtk2
 
 
 if __name__ == "__main__":
 
     win = gtk.Window()
-    progress = apt.gtk.widgets.GtkAptProgress()
+    progress = apt.progress.gtk2.GtkAptProgress()
     win.set_title("GtkAptProgress Demo")
     win.add(progress)
     progress.show()
diff --git a/doc/examples/inst.py b/doc/examples/inst.py
index a3a50356..5a7fc993 100644
--- a/doc/examples/inst.py
+++ b/doc/examples/inst.py
@@ -3,9 +3,6 @@
 
 import apt
 import sys
-import os
-import copy
-import time
 
 from apt.progress import InstallProgress
 
diff --git a/doc/examples/progress.py b/doc/examples/progress.py
index 304bd117..2231001f 100644
--- a/doc/examples/progress.py
+++ b/doc/examples/progress.py
@@ -40,7 +40,7 @@ class TextFetchProgress(apt.FetchProgress):
 
     def pulse(self):
         print "Pulse: CPS: %s/s; Bytes: %s/%s; Item: %s/%s" % (
-            apt.SizeToStr(self.currentCPS), SizeToStr(self.currentBytes),
+            apt.SizeToStr(self.currentCPS), apt.SizeToStr(self.currentBytes),
             apt.SizeToStr(self.totalBytes), self.currentItems, self.totalItems)
         return True
 
@@ -81,12 +81,12 @@ class TextCdromProgress(apt.CdromProgress):
     def update(self, text, step):
         # check if we actually have some text to display
         if text != "":
-            print "Update: %s %s" % (string.strip(text), step)
+            print "Update: %s %s" % (text.strip(), step)
 
     def askCdromName(self):
         print "Please enter cd-name: ",
         cd_name = sys.stdin.readline()
-        return (True, string.strip(cd_name))
+        return (True, cd_name.strip())
 
     def changeCdrom(self):
         print "Please insert cdrom and press <ENTER>"
diff --git a/doc/examples/records.py b/doc/examples/records.py
index a0fc8dc4..681eac0c 100755
--- a/doc/examples/records.py
+++ b/doc/examples/records.py
@@ -5,9 +5,9 @@ import apt
 cache = apt.Cache()
 
 for pkg in cache:
-    if not pkg.candidateRecord:
+    if not pkg.candidate.record:
         continue
-    if "Task" in pkg.candidateRecord:
+    if "Task" in pkg.candidate.record:
         print "Pkg %s is part of '%s'" % (
-            pkg.name, pkg.candidateRecord["Task"].split())
+            pkg.name, pkg.candidate.record["Task"].split())
         #print pkg.candidateRecord
diff --git a/doc/source/apt/package.rst b/doc/source/apt/package.rst
index 1bd032ab..bb74915e 100644
--- a/doc/source/apt/package.rst
+++ b/doc/source/apt/package.rst
@@ -10,6 +10,16 @@ The Package class
 .. autoclass:: Package
     :members:
 
+    .. note::
+
+        Several methods have been deprecated in version 0.7.9 of python-apt,
+        please see the :class:`Version` class for the new alternatives.
+
+The Version class
+-----------------
+.. autoclass:: Version
+    :members:
+
 
 Dependency Information
 ----------------------
@@ -88,14 +98,14 @@ Examples
 
     cache = apt.Cache()
     pkg = cache['python-apt'] # Access the Package object for python-apt
-    print 'python-apt is trusted:', pkg.candidateOrigin.trusted
+    print 'python-apt is trusted:', pkg.candidate.origins[0].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
+    print 'python-apt is (summary):', pkg.candidate.summary
 
     # Now, really install it
     cache.commit()
diff --git a/doc/source/apt/gtk.widgets.rst b/doc/source/apt/progress.gtk2.rst
index 9fa84ead..a83ab111 100644
--- a/doc/source/apt/gtk.widgets.rst
+++ b/doc/source/apt/progress.gtk2.rst
@@ -1,6 +1,6 @@
-:mod:`apt.gtk.widgets` --- GTK widgets
-======================================
-.. automodule:: apt.gtk.widgets
+:mod:`apt.progress.gtk2` --- GTK widgets
+========================================
+.. automodule:: apt.progress.gtk2
 
 
 GObject progress classes
diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst
index 1c5866a9..6e7b772e 100644
--- a/doc/source/apt_pkg/index.rst
+++ b/doc/source/apt_pkg/index.rst
@@ -34,7 +34,7 @@ Object initialization
 ----------------------
 .. function:: GetCache([progress])
 
-    Return a :class:`pkgCache` object. The optional parameter ``progress``
+    Return a :class:`pkgCache` object. The optional parameter *progress*
     specifies an instance of :class:`apt.progress.OpProgress()` which will
     display the open progress.
 
@@ -44,25 +44,54 @@ Object initialization
 
     .. method:: Cdrom.Ident(progress)
 
-        Identify the cdrom. The parameter ``progress`` refers to an
+        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``
+        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
+    Return a :class:`pkgDepCache` object. The parameter *cache* specifies an
     instance of :class:`pkgCache` (see :func:`GetCache()`).
 
 
 .. function:: GetPkgSourceList()
 
-    Return a :class:`pkgSourceList` object.
+    Return a :class:`PkgSourceList` object.
+
+.. function:: GetPackageManager(depcache)
+
+    Return a new :class:`PkgManager` object. The parameter *depcache* specifies
+    a :class:`pkgDepCache` object as returned by :func:`GetDepCache`.
+
+.. function:: GetPkgActionGroup(depcache)
+
+    Return a new :class:`ActionGroup` object. The parameter *depcache*
+    specifies a :class:`pkgDepCache` object as returned by :func:`GetDepCache`.
+
+.. function:: GetPkgProblemResolver(depcache)
+
+    Return a new :class:`ProblemResolver` object. The parameter *depcache*
+    specifies a :class:`pkgDepCache` object as returned by :func:`GetDepCache`.
+
+.. function:: GetPkgRecords(cache)
+
+    Return a new :class:`PkgRecords` object.
+
+    The parameter *cache* refers to an :class:`pkgCache` object, as returned
+    by :func:`GetCache`.
+
+.. function:: GetPkgSrcRecords()
+
+    Return a new :class:`PkgSrcRecords` object.
+
+.. function:: newConfiguration()
+
+    Return a new :class:`Configuration` object.
 
 
 The Acquire interface
@@ -70,7 +99,7 @@ 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
+    to fetch files, or archive contents. The parameter *progress* refers to
     an :class:`apt.progress.FetchProgress()` object.
 
     Acquire items have multiple methods:
@@ -99,26 +128,29 @@ The Acquire interface
 
 .. function:: GetPkgAcqFile(aquire, uri[, md5, size, descr, shortDescr, destDir, destFile])
 
-    The parameter ``acquire`` refers to an :class:`Acquire()` object as returned
+    Create a new :class:`PkgAcqFile()` object and register it with *acquire*,
+    so it will be fetched.
+
+    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
+    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
+    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,
+    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
+    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.
+    You can use *destDir* to manipulate the directory where the file will
+    be saved in. Instead of *destDir*, you can also specify the full path to
+    the file using the parameter *destFile*. You can not combine both.
 
 
 
@@ -130,19 +162,19 @@ 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
+    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
+    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
+    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.
 
@@ -151,19 +183,15 @@ Other functions
 
 .. note::
 
-    This documentation is created automatically and should be rewritten.
+    This documentation is (in parts) created automatically, and still needs to
+    be improved.
 
 .. 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
@@ -173,16 +201,108 @@ Other functions
 .. autofunction:: PkgSystemUnLock
 .. autofunction:: QuoteString
 .. autofunction:: ReadConfigFile
+.. autofunction:: ReadConfigDir()
 .. autofunction:: ReadConfigFileISC
 .. autofunction:: RewriteSection
-.. autofunction:: SizeToStr
-.. autofunction:: StringToBool
-.. autofunction:: StrToTime
-.. autofunction:: TimeRFC1123
-.. autofunction:: TimeToStr
-.. autofunction:: UpstreamVersion
-.. autofunction:: URItoFileName
-.. autofunction:: VersionCompare
+
+.. function:: SizeToStr(size)
+
+    Return a string presenting the human-readable version of the integer
+    *size*. When calculating the units (k,M,G,etc.) the size is divided by the
+    factor 1000.
+
+    Example::
+
+        >>> apt_pkg.SizeToStr(10000)
+        '10.0k'
+
+.. function:: StringToBool(input)
+
+    Parse the string *input* and return one of **-1**, **0**, **1**.
+
+    .. table:: Return values
+
+        ===== =============================================
+        Value      Meaning
+        ===== =============================================
+         -1   The string *input* is not recognized.
+          0   The string *input* evaluates to **False**.
+         +1   The string *input* evaluates to **True**.
+        ===== =============================================
+
+    Example::
+
+        >>> apt_pkg.StringToBool("yes")
+        1
+        >>> apt_pkg.StringToBool("no")
+        0
+        >>> apt_pkg.StringToBool("not-recognized")
+        -1
+
+.. function:: StrToTime(rfc_time)
+
+    Convert the :rfc:`1123` conforming string *rfc_time* to the unix time, and
+    return the integer. This is the opposite of :func:`TimeRFC1123`.
+
+    Example::
+
+        >> apt_pkg.StrToTime('Thu, 01 Jan 1970 00:00:00 GMT')
+        0
+
+.. function:: TimeRFC1123(seconds)
+
+    Format the unix time specified by the integer *seconds*, according to the
+    requirements of :rfc:`1123`.
+
+    Example::
+
+        >>> apt_pkg.TimeRFC1123(0)
+        'Thu, 01 Jan 1970 00:00:00 GMT'
+
+
+.. function:: TimeToStr(seconds)
+
+    Format a given duration in a human-readable manner. The parameter *seconds*
+    refers to a number of seconds, given as an integer. The return value is a
+    string with a unit like 's' for seconds.
+
+    Example::
+
+        >>> apt_pkg.TimeToStr(3601)
+        '1h0min1s'
+
+
+
+.. function:: UpstreamVersion(version)
+
+    Return the string *version*, eliminating everything following the last
+    '-'. Thus, this should be equivalent to ``version.rsplit('-', 1)[0]``.
+
+.. function:: URItoFileName(uri)
+
+    Take a string *uri* as parameter and return a filename which can be used to
+    store the file, based on the URI.
+
+    Example::
+
+        >>> apt_pkg.URItoFileName('http://debian.org/index.html')
+        'debian.org_index.html'
+
+
+.. function:: VersionCompare(a, b)
+
+    Compare two versions, *a* and *b*, and return an integer value which has
+    the same characteristic as the built-in :func:`cmp` function.
+
+    .. table:: Return values
+
+        ===== =============================================
+        Value      Meaning
+        ===== =============================================
+        > 0   The version *a* is greater than version *b*.
+        = 0   Both versions are equal.
+        < 0   The version *a* is less than version *b*.
+        ===== =============================================
 
 
 Data
@@ -256,6 +376,18 @@ Select states
 Build information
 ^^^^^^^^^^^^^^^^^
 .. data:: Date
+
+    The date on which this extension has been compiled.
+
 .. data:: LibVersion
+
+    The version of the apt_pkg library. This is **not** the version of apt,
+    nor the version of python-apt.
+
 .. data:: Time
+
+    The time this extension has been built.
+
 .. data:: Version
+
+    The version of apt (not of python-apt).
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 8f71e3e3..40154a6f 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -23,9 +23,13 @@ import sys
 # absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
 sys.path.insert(0, os.path.abspath('../..'))
+
+# Find the path to the built apt_pkg and apt_inst extensions
 if os.path.exists("../../build"):
+    version = '.'.join(str(x) for x in sys.version_info[:2])
     for dirname in os.listdir('../../build'):
-        sys.path.insert(0, os.path.abspath('../../build/' + dirname))
+        if version in dirname:
+            sys.path.insert(0, os.path.abspath('../../build/' + dirname))
 
 # General configuration
 # ---------------------
@@ -56,10 +60,13 @@ copyright = u'2009, Julian Andres Klode <jak@debian.org>'
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
+from debian_bundle.changelog import Changelog
+
+changes = Changelog(open('../../debian/changelog'))
 # The short X.Y version.
-version = '0.7'
+version = '.'.join(changes.full_version.split('.')[:2])
 # The full version, including alpha/beta/rc tags.
-release = '0.7.9~exp2'
+release = changes.full_version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/source/examples/apt-gtk.py b/doc/source/examples/apt-gtk.py
index c3bb09d5..835ea4ee 100644
--- a/doc/source/examples/apt-gtk.py
+++ b/doc/source/examples/apt-gtk.py
@@ -4,14 +4,14 @@ import pygtk
 pygtk.require("2.0")
 import gtk
 
-import apt.gtk.widgets
+import apt.progress.gtk2
 
 
 def main():
     """Main function."""
     win = gtk.Window()
     win.connect("destroy", gtk.main_quit)
-    progress = apt.gtk.widgets.GtkAptProgress()
+    progress = apt.progress.gtk2.GtkAptProgress()
     win.set_title("GtkAptProgress Demo")
     win.add(progress)
     progress.show()