* merged from debian, remaining changes:

  - updated mirrors
  - build python2.4
  - use DH_PYCENTRAL=include-links
  - use --install-layout=deb
  - pre-build.sh: update ubuntu mirrors on bzr-buildpackage

* apt/package.py: Handle cases where no candidate is available, by returning
  None in the candidate property. (Closes: #523801)
* apt/package.py: Handle cases where no candidate is available and
  one of the deprecated properties (e.g. candidateVersion) is
  requested. (Closes: #523801)
* setup.py, debian/rules: Support version in setup.py again by getting
  the value from the variable DEBVER (defined in debian/rules), falling
  back to None.
* Build-Depend on python-debian, use it to get version number from changelog
* Depend on libjs-jquery, and remove internal copy (Closes: #521532)
* apt/package.py:
  - Introduce Version.{uri,uris,fetch_binary()}
* debian/control:
  - Remove mdz from Uploaders (Closes: #521477), add myself.
  - Update Standards-Version to 3.8.1
  - Use ${binary:Version} instead of ${Source-Version}
  - Fix spelling error: python -> Python
* debian/copyright: Switch to machine-interpretable copyright
* Fix documentation building
  - doc/source/conf.py: Only include directories for current python version.
  - debian/control: Build-Depend on python-gtk2, python-vte.
  - setup.py: If pygtk can not be imported, do not build the documentation.
* Breaks: debdelta (<< 0.28~) to avoid more problems due to the internal
  API changes from 0.7.9.
* apt/gtk/widgets.py:
  - Handle older versions of python-gobject which do not ship glib
* apt/package.py: Introduce the Version class
  - Deprecate Package.candidate*() and Package.installed*(), except for
    installedFiles.
  - Provide Version.get_source() (LP: #118788)
  - Provide Package.versions (Closes: #513236)
* apt/progress/: New package, replaces apt.progress and apt.gtk
  - apt/progress/gtk2.py: Moved here from apt/gtk/widgets.py
  - apt/progress/__init__.py: Move here from apt/progress.py
* doc/source/*: Improve the documentation
  - Document more attributes and functions of apt_pkg (they are all listed)
* aptsources/distro.py:
  - use iso_3166.xml instead of iso_3166.tab
  - fix incorrect indent
* debian/control:
  - add Recommends to iso-codes (for iso_3166.xml)
* apt/package.py:
  - make sure to set the defaulttimeout back to the
    original value (in getChangelog(), LP: #314212)
    Closes: #513315
* apt/cache.py:
  - when setting a alternative rootdir, read the
    config from it as well
* python/configuration.cc, python/apt_pkgmodule.cc:
  - add apt_pkg.ReadConfigDir()
* python/cache.cc, tests/getcache_mem_corruption.py:
  - test if progress objects have the right methods
    and raise error if not (thanks to Emanuele Rocca)
    closes: #497049
* apt/package.py:
  - avoid uneeded interal references in the Package objects
* aptsources/sourceslist.py:
  - fix bug in invalid lines detection (LP: #324614)

5 files changed, 193 insertions, 44 deletions

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