* merge from debian bzr, remaining changes:

  - different mirror list
* data/templates/gNewSense.info.in,
  data/templates/gNewSense.mirrors:
  - add gNewSense template and mirrors, thanks to Karl Goetz
* apt/cache.py:
  - Make Cache.get_changes() much (~35x) faster (Closes: #578074).
  - Make Cache.req_reinstall_pkgs much faster as well.
  - Make Cache.get_providing_packages() about 1000 times faster.
  - Use has_versions and has_provides from apt_pkg.Package where possible.
* apt/package.py:
  - Decode using utf-8 in installed_files (LP: #407953).
  - Fix fetch_source() to work when source name = binary name (LP: #552400).
  - Merge a patch from Sebastian Heinlein to make get_changelog() only
    check sources where source version >= binary version (Closes: #581831).
  - Add Version.source_version and enhance Sebastian's patch to make use
    of it, in order to find the best changelog for the package.
* python:
  - Return bool instead of int to Python where possible, looks better.
  - Document every class, function, property.
* python/cache.cc:
  - Check that 2nd argument to Cache.update() really is a SourceList object.
  - Fix PackageFile.not_automatic to use NotAutomatic instead of NotSource.
  - Add Package.has_versions to see which packages have at least one version,
    and Package.has_provides for provides.
  - Add rich compare methods to the Version object.
* python/generic.cc:
  - Fix a memory leak when using old attribute names.
  - Map ArchiveURI property to archive_uri
* python/progress.cc:
  - Do not pass arguments to InstallProgress.wait_child().
* doc:
  - Update the long documentation.
* debian/control:
  - Change priority to standard, keep -doc and -dev on optional.
* utils/migrate-0.8.py:
  - Open files in universal newline support and pass filename to ast.parse.
  - Add has_key to the list of deprecated functions.
  - Don't abort if parsing failed.
  - do not require files to end in .py if they are passed on the command
    line or if they contain python somewhere in the shebang line.
* apt/cache.py:
  - make cache open silent by default (use apt.progress.base.OpProgress)
* tests/data/aptsources_ports/sources.list:
  - fix ports test-data
* tests/test_apt_cache.py:
  - add simple test for basic cache/dependency iteration

23 files changed, 1091 insertions, 442 deletions

diff --git a/python/acquire-item.cc b/python/acquire-item.cc
index cb41f489..e94ea352 100644
--- a/python/acquire-item.cc
+++ b/python/acquire-item.cc
@@ -124,17 +124,34 @@ static int acquireitem_set_id(PyObject *self, PyObject *value, void *closure)
 
 
 static PyGetSetDef acquireitem_getset[] = {
-    {"complete",acquireitem_get_complete},
-    {"desc_uri",acquireitem_get_desc_uri},
-    {"destfile",acquireitem_get_destfile},
-    {"error_text",acquireitem_get_error_text},
-    {"filesize",acquireitem_get_filesize},
-    {"id",acquireitem_get_id,acquireitem_set_id},
-    {"mode",acquireitem_get_mode},
-    {"is_trusted",acquireitem_get_is_trusted},
-    {"local",acquireitem_get_local},
-    {"partialsize",acquireitem_get_partialsize},
-    {"status",acquireitem_get_status},
+    {"complete",acquireitem_get_complete,0,
+     "A boolean value determining whether the item has been fetched\n"
+     "completely"},
+    {"desc_uri",acquireitem_get_desc_uri,NULL,
+     "A string describing the URI from which the item is acquired."},
+    {"destfile",acquireitem_get_destfile,NULL,
+     "The path to the file where the item will be stored."},
+    {"error_text",acquireitem_get_error_text,NULL,
+     "If an error occured, a string describing the error; empty string\n"
+     "otherwise."},
+    {"filesize",acquireitem_get_filesize,NULL,
+     "The size of the file (number of bytes). If unknown, it is set to 0."},
+    {"id",acquireitem_get_id,acquireitem_set_id,
+     "The ID of the item. An integer which can be set by progress classes."},
+    {"mode",acquireitem_get_mode,NULL,
+     "A localized string such as 'Fetching' which indicates the current\n"
+     "mode."},
+    {"is_trusted",acquireitem_get_is_trusted,NULL,
+     "Whether the item is trusted or not. Only True for packages\n"
+     "which come from a repository signed with one of the keys in\n"
+     "APT's keyring."},
+    {"local",acquireitem_get_local,NULL,
+     "Whether we are fetching a local item (copy:/) or not."},
+    {"partialsize",acquireitem_get_partialsize,NULL,
+     "The amount of data which has already been fetched (number of bytes)."},
+    {"status",acquireitem_get_status,NULL,
+     "An integer representing the item's status which can be compared\n"
+     "against one of the STAT_* constants defined in this class."},
     {}
 };
 
@@ -158,6 +175,12 @@ static void acquireitem_dealloc(PyObject *self)
     CppDeallocPtr<pkgAcquire::Item*>(self);
 }
 
+static const char *acquireitem_doc =
+    "Represent a single item to be fetched by an Acquire object.\n\n"
+    "It is not possible to construct instances of this class directly.\n"
+    "Prospective users should construct instances of a subclass such as\n"
+    "AcquireFile instead. It is not possible to create subclasses on the\n"
+    "Python level, only on the C++ level.";
 PyTypeObject PyAcquireItem_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
     "apt_pkg.AcquireItem",         // tp_name
@@ -181,7 +204,7 @@ PyTypeObject PyAcquireItem_Type = {
     0,                                   // tp_as_buffer
     Py_TPFLAGS_DEFAULT |
     Py_TPFLAGS_HAVE_GC,                  // tp_flags
-    "AcquireItem Object",                // tp_doc
+    acquireitem_doc,                // tp_doc
     CppTraverse<pkgAcquire::Item*>, // tp_traverse
     CppClear<pkgAcquire::Item*>,    // tp_clear
     0,                                   // tp_richcompare
@@ -226,9 +249,27 @@ static PyObject *acquirefile_new(PyTypeObject *type, PyObject *Args, PyObject *
 
 static char *acquirefile_doc =
     "AcquireFile(owner, uri[, md5, size, descr, short_descr, destdir,"
-    "destfile]) -> New AcquireFile() object\n\n"
-    "The parameter *owner* refers to an apt_pkg.Acquire() object. You can use\n"
-    "*destdir* OR *destfile* to specify the destination directory/file.";
+    "destfile])\n\n"
+    "Represent a file to be fetched. The parameter 'owner' points to\n"
+    "an apt_pkg.Acquire object and the parameter 'uri' to the source\n"
+    "location. Normally, the file will be stored in the current directory\n"
+    "using the file name given in the URI. This directory can be changed\n"
+    "by passing the name of a directory to the 'destdir' parameter. It is\n"
+    "also possible to set a path to a file using the 'destfile' parameter,\n"
+    "but both cannot be specified together.\n"
+    "\n"
+    "The parameters 'short_descr' and 'descr' can be used to specify\n"
+    "a short description and a longer description for the item. This\n"
+    "information is used by progress classes to refer to the item and\n"
+    "should be short, for example, package name as 'short_descr' and\n"
+    "and something like 'http://localhost sid/main python-apt 0.7.94.2'\n"
+    "as 'descr'."
+    "\n"
+    "The parameters 'md5' and 'size' are used to verify the resulting\n"
+    "file. The parameter 'size' is also to calculate the total amount\n"
+    "of data to be fetched and is useful for resuming a interrupted\n"
+    "download.\n\n"
+    "All parameters can be given by name (i.e. as keyword arguments).";
 
 PyTypeObject PyAcquireFile_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
diff --git a/python/acquire.cc b/python/acquire.cc
index 3f24a3e7..1d750f37 100644
--- a/python/acquire.cc
+++ b/python/acquire.cc
@@ -65,15 +65,25 @@ static PyObject *acquireworker_get_resumepoint(PyObject *self, void *closure)
 }
 
 static PyGetSetDef acquireworker_getset[] = {
-    {"current_item",acquireworker_get_current_item},
-    {"status",acquireworker_get_status},
-    {"current_size",acquireworker_get_current_size},
-    {"total_size",acquireworker_get_total_size},
-    {"resumepoint",acquireworker_get_resumepoint},
+    {"current_item",acquireworker_get_current_item,0,
+     "The item currently being fetched, as an apt_pkg.AcquireItemDesc object."},
+    {"status",acquireworker_get_status,0,
+     "The status of the worker, as a string."},
+    {"current_size",acquireworker_get_current_size,0,
+     "The amount of data fetched so far for the current item."},
+    {"total_size",acquireworker_get_total_size,0,
+     "The total size of the item."},
+    {"resumepoint",acquireworker_get_resumepoint,0,
+     "The amount of data which was already available when the download was\n"
+     "started."},
     {NULL}
 };
 
-
+static const char *acquireworker_doc =
+    "Represent a sub-process responsible for fetching files from\n"
+    "remote locations. This sub-process uses 'methods' located in\n"
+    "the directory specified by the configuration option\n"
+    "Dir::Bin::Methods.";
 PyTypeObject PyAcquireWorker_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
     "apt_pkg.AcquireWorker",                // tp_name
@@ -97,7 +107,7 @@ PyTypeObject PyAcquireWorker_Type = {
     0,                                   // tp_as_buffer
     Py_TPFLAGS_DEFAULT|                  // tp_flags
     Py_TPFLAGS_HAVE_GC,
-    0,                 // tp_doc
+    acquireworker_doc,                 // tp_doc
     CppTraverse<pkgAcquire::Worker*>, // tp_traverse
     CppClear<pkgAcquire::Worker*>,   // tp_clear
     0,                                    // tp_richcompare
@@ -147,16 +157,21 @@ static PyObject *acquireitemdesc_get_owner(CppPyObject<pkgAcquire::ItemDesc*> *s
 }
 
 static PyGetSetDef acquireitemdesc_getset[] = {
-    {"uri",acquireitemdesc_get_uri,0,"The URI from which to download this item."},
-    {"description",acquireitemdesc_get_description},
-    {"shortdesc",acquireitemdesc_get_shortdesc},
-    {"owner",(getter)acquireitemdesc_get_owner},
+    {"uri",acquireitemdesc_get_uri,0,
+     "The URI from which this item would be downloaded."},
+    {"description",acquireitemdesc_get_description,0,
+     "A string describing the item."},
+    {"shortdesc",acquireitemdesc_get_shortdesc,0,
+     "A short string describing the item (e.g. package name)."},
+    {"owner",(getter)acquireitemdesc_get_owner,0,
+     "The owner of the item, an apt_pkg.AcquireItem object."},
     {NULL}
 };
 
 static char *acquireitemdesc_doc =
-    "Represent an AcquireItemDesc";
-
+    "Provide the description of an item and the URI the item is\n"
+    "fetched from. Progress classes make use of such objects to\n"
+    "retrieve description and other information about an item.";
 PyTypeObject PyAcquireItemDesc_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
     "apt_pkg.AcquireItemDesc",                // tp_name
@@ -227,8 +242,17 @@ static PyObject *PkgAcquireShutdown(PyObject *Self,PyObject *Args)
 
 
 static PyMethodDef PkgAcquireMethods[] = {
-    {"run",PkgAcquireRun,METH_VARARGS,"Run the fetcher"},
-    {"shutdown",PkgAcquireShutdown, METH_VARARGS,"Shutdown the fetcher"},
+    {"run",PkgAcquireRun,METH_VARARGS,
+     "run() -> int\n\nRun the fetcher and return one of RESULT_CANCELLED,\n"
+     "RESULT_CONTINUE, RESULT_FAILED. RESULT_CONTINUE means that all items\n"
+     "which where queued prior to calling run() have been fetched\n"
+     "successfully. RESULT_CANCELLED means that the process was canceled\n"
+     "by the progress class. And RESULT_FAILED means a generic failure."},
+    {"shutdown",PkgAcquireShutdown, METH_VARARGS,
+     "shutdown()\n\n"
+     "Shut the fetcher down, removing all items from it. Future access to\n"
+     "queued AcquireItem objects will cause a segfault. The partial result\n"
+     "is kept on the disk and not removed and APT might reuse it."},
     {}
 };
 
@@ -275,11 +299,18 @@ static PyObject *PkgAcquireGetItems(PyObject *Self,void*)
 }
 
 static PyGetSetDef PkgAcquireGetSet[] = {
-    {"fetch_needed",PkgAcquireGetFetchNeeded},
-    {"items",PkgAcquireGetItems},
-    {"workers",PkgAcquireGetWorkers},
-    {"partial_present",PkgAcquireGetPartialPresent},
-    {"total_needed",PkgAcquireGetTotalNeeded},
+    {"fetch_needed",PkgAcquireGetFetchNeeded,0,
+     "The total amount of data to be fetched (number of bytes)."},
+    {"items",PkgAcquireGetItems,0,
+     "A list of all items as apt_pkg.AcquireItem objects, including already\n"
+     "fetched ones and to be fetched ones."},
+    {"workers",PkgAcquireGetWorkers,0,
+     "A list of all active workers as apt_pkg.AcquireWorker objects."},
+    {"partial_present",PkgAcquireGetPartialPresent,0,
+     "The amount of data which is already available (number of bytes)."},
+    {"total_needed",PkgAcquireGetTotalNeeded,0,
+     "The amount of data that needs to fetched plus the amount of data\n"
+     "which has already been fetched (number of bytes)."},
     {}
 };
 
@@ -321,10 +352,11 @@ PyObject *PyAcquire_FromCpp(pkgAcquire *fetcher, bool Delete, PyObject *owner) {
 }
 
 static char *doc_PkgAcquire =
-    "Acquire(progress: apt_pkg.AcquireProgress) -> Acquire() object.\n\n"
-    "Create a new acquire object. The parameter *progress* can be used to\n"
-    "specify an apt_pkg.AcquireProgress() object, which will display the\n"
-    "progress of the fetching.";
+    "Acquire([progress: apt.progress.base.AcquireProgress])\n\n"
+    "Coordinate the retrieval of files via network or local file system\n"
+    "(using 'copy:/path/to/file' style URIs). The optional argument\n"
+    "'progress' takes an apt.progress.base.AcquireProgress object\n"
+    "which may report progress information.";
 
 PyTypeObject PyAcquire_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
diff --git a/python/apt_instmodule.cc b/python/apt_instmodule.cc
index 2721509e..732f1bd0 100644
--- a/python/apt_instmodule.cc
+++ b/python/apt_instmodule.cc
@@ -102,7 +102,7 @@ static PyObject *debExtractArchive(PyObject *Self,PyObject *Args)
       if (_error->PendingError() == true) {
 	 if (Rootdir != NULL)
 	    chdir (cwd);
-	 return HandleErrors(Py_BuildValue("b",false));
+	 return HandleErrors();
       }
 
       // extracts relative to the current dir
@@ -112,9 +112,9 @@ static PyObject *debExtractArchive(PyObject *Self,PyObject *Args)
       if (Rootdir != NULL)
 	 chdir (cwd);
       if (res == false)
-	 return HandleErrors(Py_BuildValue("b",res));
+	 return HandleErrors(PyBool_FromLong(res));
    }
-   return HandleErrors(Py_BuildValue("b",res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 									/*}}}*/
 // arFindMember - Find member in AR archive              		/*{{{*/
@@ -136,12 +136,12 @@ static PyObject *arCheckMember(PyObject *Self,PyObject *Args)
    FileFd Fd(fileno,false);
    ARArchive AR(Fd);
    if (_error->PendingError() == true)
-      return HandleErrors(Py_BuildValue("b",res));
+      return HandleErrors();
 
    if(AR.FindMember(Member) != 0)
       res = true;
 
-   return HandleErrors(Py_BuildValue("b",res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 									/*}}}*/
 
@@ -168,7 +168,7 @@ static PyMethodDef *methods = 0;
 
 
 static const char *apt_inst_doc =
-    "Functions for working with AR,tar archives and .deb packages.\n\n"
+    "Functions for working with ar/tar archives and .deb packages.\n\n"
     "This module provides useful classes and functions to work with\n"
     "archives, modelled after the 'TarFile' class in the 'tarfile' module.";
 #define ADDTYPE(mod,name,type) { \
diff --git a/python/apt_pkgmodule.cc b/python/apt_pkgmodule.cc
index 2a181619..c6353fcc 100644
--- a/python/apt_pkgmodule.cc
+++ b/python/apt_pkgmodule.cc
@@ -64,7 +64,10 @@ static PyObject *newConfiguration(PyObject *self,PyObject *args)
 
 // Version Wrappers							/*{{{*/
 // These are kind of legacy..
-static char *doc_VersionCompare = "VersionCompare(a,b) -> int";
+static char *doc_VersionCompare =
+    "version_compare(a: str, b: str) -> int\n\n"
+    "Compare the given versions; return -1 if 'a' is smaller than 'b',\n"
+    "0 if they are equal, and 2 if 'a' is larger than 'b'.";
 static PyObject *VersionCompare(PyObject *Self,PyObject *Args)
 {
    char *A;
@@ -89,8 +92,8 @@ static char *doc_CheckDep =
     "Check that the given requirement is fulfilled; i.e. that the version\n"
     "string given by 'pkg_ver' matches the version string 'dep_ver' under\n"
     "the condition specified by the operator 'dep_op' (<,<=,=,>=,>).\n\n"
-    "This functions returns True if 'pkg_ver' matches 'dep_ver' under the\n"
-    "condition 'dep_op'; e.g. this returns True:\n\n"
+    "Return True if 'pkg_ver' matches 'dep_ver' under the\n"
+    "condition 'dep_op'; for example, this returns True:\n\n"
     "    apt_pkg.check_dep('1', '<=', '2')";
 static PyObject *CheckDep(PyObject *Self,PyObject *Args)
 {
@@ -146,7 +149,9 @@ static PyObject *CheckDepOld(PyObject *Self,PyObject *Args)
 }
 #endif
 
-static char *doc_UpstreamVersion = "UpstreamVersion(a) -> string";
+static char *doc_UpstreamVersion =
+    "upstream_version(ver: str) -> str\n\n"
+    "Return the upstream version for the package version given by 'ver'.";
 static PyObject *UpstreamVersion(PyObject *Self,PyObject *Args)
 {
    char *Ver;
@@ -155,14 +160,29 @@ static PyObject *UpstreamVersion(PyObject *Self,PyObject *Args)
    return CppPyString(_system->VS->UpstreamVersion(Ver));
 }
 
-static char *doc_ParseDepends =
-"ParseDepends(s) -> list of tuples\n"
+static const char *doc_ParseDepends =
+"parse_depends(s: str) -> list\n"
 "\n"
-"The resulting tuples are (Pkg,Ver,Operation). Each anded dependency is a\n"
-"list of or'd dependencies\n"
-"Source depends are evaluated against the curernt arch and only those that\n"
-"Match are returned.\n\n"
-"apt_pkg.Parse{,Src}Depends() are old forms which return >>,<< instead of >,<";
+"Parse the dependencies given by 's' and return a list of lists. Each of\n"
+"these lists represents one or more options for an 'or' dependency in\n"
+"the form of '(pkg, ver, comptype)' tuples. The tuple element 'pkg'\n"
+"is the name of the package; the element 'ver' is the version, or ''\n"
+"if no version was requested. The element 'ver' is a comparison\n"
+"operator ('<', '<=', '=', '>=', or '>').";
+
+static const char *parse_src_depends_doc =
+"parse_src_depends(s: str) -> list\n"
+"\n"
+"Parse the dependencies given by 's' and return a list of lists. Each of\n"
+"these lists represents one or more options for an 'or' dependency in\n"
+"the form of '(pkg, ver, comptype)' tuples. The tuple element 'pkg'\n"
+"is the name of the package; the element 'ver' is the version, or ''\n"
+"if no version was requested. The element 'ver' is a comparison\n"
+"operator ('<', '<=', '=', '>=', or '>')."
+"\n\n"
+"Dependencies may be restricted to certain architectures and the result\n"
+"only contains those dependencies for the architecture set in the\n"
+"configuration variable APT::Architecture";
 static PyObject *RealParseDepends(PyObject *Self,PyObject *Args,
                                   bool ParseArchFlags, string name,
                                   bool debStyle=false)
@@ -238,7 +258,12 @@ static PyObject *ParseSrcDepends_old(PyObject *Self,PyObject *Args)
 									/*}}}*/
 // md5sum - Compute the md5sum of a file or string			/*{{{*/
 // ---------------------------------------------------------------------
-static char *doc_md5sum = "md5sum(String) -> String or md5sum(File) -> String";
+static const char *doc_md5sum =
+    "md5sum(object) -> str\n\n"
+    "Return the md5sum of the object. 'object' may either be a string, in\n"
+    "which case the md5sum of the string is returned, or a file() object\n"
+    "(or file descriptor), in which case the md5sum of its contents is\n"
+    "returned.";
 static PyObject *md5sum(PyObject *Self,PyObject *Args)
 {
    PyObject *Obj;
@@ -278,7 +303,12 @@ static PyObject *md5sum(PyObject *Self,PyObject *Args)
 									/*}}}*/
 // sha1sum - Compute the sha1sum of a file or string			/*{{{*/
 // ---------------------------------------------------------------------
-static char *doc_sha1sum = "sha1sum(String) -> String or sha1sum(File) -> String";
+static const char *doc_sha1sum =
+    "sha1sum(object) -> str\n\n"
+    "Return the sha1sum of the object. 'object' may either be a string, in\n"
+    "which case the sha1sum of the string is returned, or a file() object\n"
+    "(or file descriptor), in which case the sha1sum of its contents is\n"
+    "returned.";
 static PyObject *sha1sum(PyObject *Self,PyObject *Args)
 {
    PyObject *Obj;
@@ -318,7 +348,12 @@ static PyObject *sha1sum(PyObject *Self,PyObject *Args)
 									/*}}}*/
 // sha256sum - Compute the sha1sum of a file or string			/*{{{*/
 // ---------------------------------------------------------------------
-static char *doc_sha256sum = "sha256sum(String) -> String or sha256sum(File) -> String";
+static const char *doc_sha256sum =
+    "sha256sum(object) -> str\n\n"
+    "Return the sha256sum of the object. 'object' may either be a string, in\n"
+    "which case the sha256sum of the string is returned, or a file() object\n"
+    "(or file descriptor), in which case the sha256sum of its contents is\n"
+    "returned.";;
 static PyObject *sha256sum(PyObject *Self,PyObject *Args)
 {
    PyObject *Obj;
@@ -359,8 +394,10 @@ static PyObject *sha256sum(PyObject *Self,PyObject *Args)
 // init - 3 init functions						/*{{{*/
 // ---------------------------------------------------------------------
 static char *doc_Init =
-"init() -> None\n"
-"Legacy. Do InitConfig then parse the command line then do InitSystem\n";
+"init()\n\n"
+"Shorthand for doing init_config() and init_system(). When working\n"
+"with command line arguments, first call init_config() then parse\n"
+"the command line and finally call init_system().";
 static PyObject *Init(PyObject *Self,PyObject *Args)
 {
    if (PyArg_ParseTuple(Args,"") == 0)
@@ -374,8 +411,8 @@ static PyObject *Init(PyObject *Self,PyObject *Args)
 }
 
 static char *doc_InitConfig =
-"initconfig() -> None\n"
-"Load the default configuration and the config file\n";
+"init_config()\n\n"
+"Load the default configuration and the config file.";
 static PyObject *InitConfig(PyObject *Self,PyObject *Args)
 {
    if (PyArg_ParseTuple(Args,"") == 0)
@@ -388,8 +425,8 @@ static PyObject *InitConfig(PyObject *Self,PyObject *Args)
 }
 
 static char *doc_InitSystem =
-"initsystem() -> None\n"
-"Construct the underlying system\n";
+"init_system()\n\n"
+"Construct the apt_pkg system.";
 static PyObject *InitSystem(PyObject *Self,PyObject *Args)
 {
    if (PyArg_ParseTuple(Args,"") == 0)
@@ -405,11 +442,13 @@ static PyObject *InitSystem(PyObject *Self,PyObject *Args)
 // fileutils.cc: GetLock						/*{{{*/
 // ---------------------------------------------------------------------
 static char *doc_GetLock =
-"GetLock(string) -> int\n"
-"This will create an empty file of the given name and lock it. Once this"
-" is done all other calls to GetLock in any other process will fail with"
-" -1. The return result is the fd of the file, the call should call"
-" close at some time\n";
+"get_lock(file: str, errors: bool) -> int\n\n"
+"Create an empty file of the given name and lock it. If the locking\n"
+"succeeds, return the file descriptor of the lock file. Afterwards,\n"
+"locking the file from another process will fail and thus cause\n"
+"get_lock() to return -1 or raise an Error (if 'errors' is True).\n\n"
+"From Python 2.6 on, it is recommended to use the context manager\n"
+"provided by apt_pkg.FileLock instead using the with-statement.";
 static PyObject *GetLock(PyObject *Self,PyObject *Args)
 {
    const char *file;
@@ -419,12 +458,14 @@ static PyObject *GetLock(PyObject *Self,PyObject *Args)
 
    int fd = GetLock(file, errors);
 
-   return  HandleErrors(Py_BuildValue("i", fd));
+   return HandleErrors(Py_BuildValue("i", fd));
 }
 
 static char *doc_PkgSystemLock =
-"PkgSystemLock() -> boolean\n"
-"Get the global pkgsystem lock\n";
+"pkgsystem_lock() -> bool\n\n"
+"Acquire the global lock for the package system by using /var/lib/dpkg/lock\n"
+"to do the locking. From Python 2.6 on, the apt_pkg.SystemLock context\n"
+"manager is available and should be used instead.";
 static PyObject *PkgSystemLock(PyObject *Self,PyObject *Args)
 {
    if (PyArg_ParseTuple(Args,"") == 0)
@@ -433,12 +474,12 @@ static PyObject *PkgSystemLock(PyObject *Self,PyObject *Args)
    bool res = _system->Lock();
 
    Py_INCREF(Py_None);
-   return HandleErrors(Py_BuildValue("b", res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
 static char *doc_PkgSystemUnLock =
-"PkgSystemUnLock() -> boolean\n"
-"Unset the global pkgsystem lock\n";
+"pkgsystem_unlock() -> bool\n\n"
+"Release the global lock for the package system.";
 static PyObject *PkgSystemUnLock(PyObject *Self,PyObject *Args)
 {
    if (PyArg_ParseTuple(Args,"") == 0)
@@ -447,7 +488,7 @@ static PyObject *PkgSystemUnLock(PyObject *Self,PyObject *Args)
    bool res = _system->UnLock();
 
    Py_INCREF(Py_None);
-   return HandleErrors(Py_BuildValue("b", res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
 									/*}}}*/
@@ -465,8 +506,8 @@ static PyMethodDef methods[] =
    // Internationalization.
    {"gettext",py_gettext,METH_VARARGS,
     "gettext(msg: str[, domain: str = 'python-apt']) -> str\n\n"
-    "Translate the given string. Much Faster than Python's version and only\n"
-    "does translations after setlocale() has been called."},
+    "Translate the given string. This is much faster than Python's version\n"
+    "and only does translations after setlocale() has been called."},
 
    // Tag File
    {"rewrite_section",RewriteSection,METH_VARARGS,doc_RewriteSection},
@@ -489,7 +530,7 @@ static PyMethodDef methods[] =
 
    // Depends
    {"parse_depends",ParseDepends,METH_VARARGS,doc_ParseDepends},
-   {"parse_src_depends",ParseSrcDepends,METH_VARARGS,doc_ParseDepends},
+   {"parse_src_depends",ParseSrcDepends,METH_VARARGS,parse_src_depends_doc},
 
    // Stuff
    {"md5sum",md5sum,METH_VARARGS,doc_md5sum},
@@ -497,16 +538,50 @@ static PyMethodDef methods[] =
    {"sha256sum",sha256sum,METH_VARARGS,doc_sha256sum},
 
    // Strings
-   {"check_domain_list",StrCheckDomainList,METH_VARARGS,"CheckDomainList(String,String) -> Bool"},
-   {"quote_string",StrQuoteString,METH_VARARGS,"QuoteString(String,String) -> String"},
-   {"dequote_string",StrDeQuote,METH_VARARGS,"DeQuoteString(String) -> String"},
-   {"size_to_str",StrSizeToStr,METH_VARARGS,"SizeToStr(int) -> String"},
-   {"time_to_str",StrTimeToStr,METH_VARARGS,"TimeToStr(int) -> String"},
-   {"uri_to_filename",StrURItoFileName,METH_VARARGS,"URItoFileName(String) -> String"},
-   {"base64_encode",StrBase64Encode,METH_VARARGS,"Base64Encode(String) -> String"},
-   {"string_to_bool",StrStringToBool,METH_VARARGS,"StringToBool(String) -> int"},
-   {"time_rfc1123",StrTimeRFC1123,METH_VARARGS,"TimeRFC1123(int) -> String"},
-   {"str_to_time",StrStrToTime,METH_VARARGS,"StrToTime(String) -> Int"},
+   {"check_domain_list",StrCheckDomainList,METH_VARARGS,
+    "check_domain_list(host: str, domains: str) -> bool\n\n"
+    "Check if the host given by 'host' belongs to one of the domains\n"
+    "specified in the comma separated string 'domains'. An example\n"
+    "would be:\n\n"
+    "    check_domain_list('alioth.debian.org','debian.net,debian.org')\n\n"
+    "which would return True because alioth belongs to debian.org."},
+   {"quote_string",StrQuoteString,METH_VARARGS,
+    "quote_string(string: str, repl: str) -> str\n\n"
+    "Escape the string 'string', replacing any character not allowed in a URL"
+    "or specified by 'repl' with its ASCII value preceded by a percent sign"
+    "(so for example ' ' becomes '%20')."},
+   {"dequote_string",StrDeQuote,METH_VARARGS,
+    "dequote_string(string: str) -> str\n\n"
+    "Dequote the given string by replacing all HTTP encoded values such\n"
+    "as '%20' with their decoded value (in this case, ' ')."},
+   {"size_to_str",StrSizeToStr,METH_VARARGS,
+    "size_to_str(bytes: int) -> str\n\n"
+    "Return a string describing the size in a human-readable manner using\n"
+    "SI prefix and base-10 units, e.g. '1k' for 1000, '1M' for 1000000, etc."},
+   {"time_to_str",StrTimeToStr,METH_VARARGS,
+    "time_to_str(seconds: int) -> str\n\n"
+    "Return a string describing the number of seconds in a human\n"
+    "readable manner using days, hours, minutes and seconds."},
+   {"uri_to_filename",StrURItoFileName,METH_VARARGS,
+    "uri_to_filename(uri: str) -> str\n\n"
+    "Return a filename based on the given URI after replacing some\n"
+    "parts not suited for filenames (e.g. '/')."},
+   {"base64_encode",StrBase64Encode,METH_VARARGS,
+    "base64_encode(value: bytes) -> str\n\n"
+    "Encode the given bytestring into Base64. The input may not\n"
+    "contain a null byte character (use the base64 module for this)."},
+   {"string_to_bool",StrStringToBool,METH_VARARGS,
+    "string_to_bool(string: str) -> int\n\n"
+    "Return 1 if the string is a value such as 'yes', 'true', '1';\n"
+    "0 if the string is a value such as 'no', 'false', '0'; -1 if\n"
+    "the string is not recognized."},
+   {"time_rfc1123",StrTimeRFC1123,METH_VARARGS,
+    "time_rfc1123(unixtime: int) -> str\n\n"
+    "Format the given Unix time according to the requirements of\n"
+    "RFC 1123."},
+   {"str_to_time",StrStrToTime,METH_VARARGS,
+    "str_to_time(rfc_time: str) -> int\n\n"
+    "Convert the given RFC 1123 formatted string to a Unix timestamp."},
 
    // DEPRECATED
    #ifdef COMPAT_0_7
@@ -534,7 +609,8 @@ static PyMethodDef methods[] =
    {"ParseDepends",ParseDepends_old,METH_VARARGS,doc_ParseDepends},
    {"ParseSrcDepends",ParseSrcDepends_old,METH_VARARGS,doc_ParseDepends},
 
-   {"CheckDomainList",StrCheckDomainList,METH_VARARGS,"CheckDomainList(String,String) -> Bool"},
+   {"CheckDomainList",StrCheckDomainList,METH_VARARGS,
+    "CheckDomainList(String,String) -> Bool"},
    {"QuoteString",StrQuoteString,METH_VARARGS,"QuoteString(String,String) -> String"},
    {"DeQuoteString",StrDeQuote,METH_VARARGS,"DeQuoteString(String) -> String"},
    {"SizeToStr",StrSizeToStr,METH_VARARGS,"SizeToStr(int) -> String"},
@@ -664,12 +740,18 @@ static struct _PyAptPkgAPIStruct API = {
     PyModule_AddObject(mod,name,(PyObject *)type); }
 
 
+static const char *apt_pkg_doc =
+    "Classes and functions wrapping the apt-pkg library.\n\n"
+    "The apt_pkg module provides several classes and functions for accessing\n"
+    "the functionality provided by the apt-pkg library. Typical uses might\n"
+    "include reading APT index files and configuration files and installing\n"
+    "or removing packages.";
+
 #if PY_MAJOR_VERSION >= 3
 static struct PyModuleDef moduledef = {
         PyModuleDef_HEAD_INIT,
         "apt_pkg",
-        "Classes and functions wrapping the apt-pkg library.\n\n"
-        "The apt_pkg module provides...",
+        apt_pkg_doc,
         -1,
         methods,
         0,
@@ -693,7 +775,7 @@ extern "C" void initapt_pkg()
    #if PY_MAJOR_VERSION >= 3
    PyObject *Module = PyModule_Create(&moduledef);
    #else
-   PyObject *Module = Py_InitModule("apt_pkg",methods);
+   PyObject *Module = Py_InitModule3("apt_pkg",methods, apt_pkg_doc);
    #endif
 
    // Global variable linked to the global configuration class
diff --git a/python/arfile.cc b/python/arfile.cc
index 4f3b4ad7..a279807d 100644
--- a/python/arfile.cc
+++ b/python/arfile.cc
@@ -82,12 +82,12 @@ static PyGetSetDef armember_getset[] = {
     {"size",armember_get_size,0,"The size of the files."},
     {"start",armember_get_start,0,
      "The offset in the archive where the file starts."},
-    {"uid",armember_get_uid,0,"The user id of the owner."},
+    {"uid",armember_get_uid,0,"The user ID of the owner."},
     {NULL}
 };
 
 static const char *armember_doc =
-    "An ArMember object represents a single file within an AR archive. For\n"
+    "Represent a single file within an AR archive. For\n"
     "Debian packages this can be e.g. control.tar.gz. This class provides\n"
     "information about this file, such as the mode and size.";
 PyTypeObject PyArMember_Type = {
@@ -141,7 +141,7 @@ struct PyArArchiveObject : public CppPyObject<PyARArchiveHack*> {
 
 static const char *ararchive_getmember_doc =
     "getmember(name: str) -> ArMember\n\n"
-    "Return a ArMember object for the member given by name. Raise\n"
+    "Return an ArMember object for the member given by 'name'. Raise\n"
     "LookupError if there is no ArMember with the given name.";
 static PyObject *ararchive_getmember(PyArArchiveObject *self, PyObject *arg)
 {
@@ -238,11 +238,11 @@ static PyObject *_extract(FileFd &Fd, const ARArchive::Member *member,
 
 static const char *ararchive_extract_doc =
     "extract(name: str[, target: str]) -> bool\n\n"
-    "Extract the member given by name into the directory given by target.\n"
-    "If the extraction failed, an error is raised. Otherwise, the method\n"
-    "returns True if the owner could be set or False if the owner could not\n"
-    "be changed. It may also raise LookupError if there is member with\n"
-    "the given name.";
+    "Extract the member given by 'name' into the directory given\n"
+    "by 'target'. If the extraction fails, raise OSError. In case\n"
+    "of success, return True if the file owner could be set or\n"
+    "False if this was not possible. If the requested member\n"
+    "does not exist, raise LookupError.";
 static PyObject *ararchive_extract(PyArArchiveObject *self, PyObject *args)
 {
     char *name = 0;
@@ -260,11 +260,10 @@ static PyObject *ararchive_extract(PyArArchiveObject *self, PyObject *args)
 }
 
 static const char *ararchive_extractall_doc =
-    "extract([target: str]) -> bool\n\n"
-    "Extract all into the directory given by target.\n"
-    "If the extraction failed, an error is raised. Otherwise, the method\n"
-    "returns True if the owner could be set or False if the owner could not\n"
-    "be changed.";
+    "extractall([target: str]) -> bool\n\n"
+    "Extract all archive contents into the directory given by 'target'. If\n"
+    "the extraction fails, raise an error. Otherwise, return True if the\n"
+    "owner could be set or False if the owner could not be changed.";
 
 static PyObject *ararchive_extractall(PyArArchiveObject *self, PyObject *args)
 {
@@ -311,7 +310,7 @@ static PyObject *ararchive_gettar(PyArArchiveObject *self, PyObject *args)
 
 static const char *ararchive_getmembers_doc =
     "getmembers() -> list\n\n"
-    "Return a list of all members in the AR archive.";
+    "Return a list of all members in the archive.";
 static PyObject *ararchive_getmembers(PyArArchiveObject *self)
 {
     PyObject *list = PyList_New(0);
@@ -329,7 +328,7 @@ static PyObject *ararchive_getmembers(PyArArchiveObject *self)
 
 static const char *ararchive_getnames_doc =
     "getnames() -> list\n\n"
-    "Return a list of the names of all members in the AR archive.";
+    "Return a list of the names of all members in the archive.";
 static PyObject *ararchive_getnames(PyArArchiveObject *self)
 {
     PyObject *list = PyList_New(0);
@@ -424,12 +423,12 @@ static PyMappingMethods ararchive_as_mapping = {
 
 static const char *ararchive_doc =
     "ArArchive(file: str/int/file)\n\n"
-    "An ArArchive object represents an archive in the 4.4 BSD AR format, \n"
+    "Represent an archive in the 4.4 BSD ar format,\n"
     "which is used for e.g. deb packages.\n\n"
     "The parameter 'file' may be a string specifying the path of a file, or\n"
     "a file-like object providing the fileno() method. It may also be an int\n"
     "specifying a file descriptor (returned by e.g. os.open()).\n"
-    "The recommended way is to pass in the path to the file.";
+    "The recommended way of using it is to pass in the path to the file.";
 
 PyTypeObject PyArArchive_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -599,10 +598,10 @@ static const char *debfile_doc =
     "The parameter 'file' may be a string specifying the path of a file, or\n"
     "a file-like object providing the fileno() method. It may also be an int\n"
     "specifying a file descriptor (returned by e.g. os.open()).\n"
-    "The recommended way is to pass in the path to the file.\n\n"
+    "The recommended way of using it is to pass in the path to the file.\n\n"
     "It differs from ArArchive by providing the members 'control', 'data'\n"
-    "and 'version' for accessing the control.tar.gz,data.tar.{gz,bz2,lzma}\n"
-    ",debian-binary members in the archive.";
+    "and 'version' for accessing the control.tar.gz, data.tar.{gz,bz2,lzma},\n"
+    "and debian-binary members in the archive.";
 
 PyTypeObject PyDebFile_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
diff --git a/python/cache.cc b/python/cache.cc
index 515f0193..b0cfb469 100644
--- a/python/cache.cc
+++ b/python/cache.cc
@@ -85,6 +85,20 @@ static PyObject *CreateProvides(PyObject *Owner,pkgCache::PrvIterator I)
 
 // Cache Class								/*{{{*/
 // ---------------------------------------------------------------------
+
+static const char *cache_update_doc =
+    "update(progress, sources: SourceList, pulse_interval: int) -> bool\n\n"
+    "Update the index files used by the cache. A call to this method\n"
+    "does not affect the current Cache object; instead, a new one\n"
+    "should be created in order to use the changed index files.\n\n"
+    "The parameter 'progress' can be used to specify an\n"
+    "apt.progress.base.AcquireProgress() object , which will report\n"
+    "progress information while the index files are being fetched.\n"
+    "The parameter 'sources', if provided, is an apt_pkg.SourcesList\n"
+    "object listing the remote repositories to be used.\n"
+    "The 'pulse_interval' parameter indicates how long (in microseconds)\n"
+    "to wait between calls to the pulse() method of the 'progress' object.\n"
+    "The default is 500000 microseconds.";
 static PyObject *PkgCacheUpdate(PyObject *Self,PyObject *Args)
 {
    PyObject *pyFetchProgressInst = 0;
@@ -99,7 +113,7 @@ static PyObject *PkgCacheUpdate(PyObject *Self,PyObject *Args)
    pkgSourceList *source = GetCpp<pkgSourceList*>(pySourcesList);
    bool res = ListUpdate(progress, *source, pulseInterval);
 
-   PyObject *PyRes = Py_BuildValue("b", res);
+   PyObject *PyRes = PyBool_FromLong(res);
    return HandleErrors(PyRes);
 }
 
@@ -154,9 +168,10 @@ static PyObject *PkgCacheOpen(PyObject *Self,PyObject *Args)
 
 static PyMethodDef PkgCacheMethods[] =
 {
-   {"update",PkgCacheUpdate,METH_VARARGS,"Update the cache"},
+   {"update",PkgCacheUpdate,METH_VARARGS,cache_update_doc},
 #ifdef COMPAT_0_7
-   {"Open", PkgCacheOpen, METH_VARARGS,"Open the cache"},
+   {"Open", PkgCacheOpen, METH_VARARGS,
+    "Open the cache; deprecated and unsafe"},
    {"Close", PkgCacheClose, METH_VARARGS,"Close the cache"},
 #endif
    {}
@@ -210,14 +225,22 @@ static PyObject *PkgCacheGetFileList(PyObject *Self, void*) {
 }
 
 static PyGetSetDef PkgCacheGetSet[] = {
-   {"depends_count",PkgCacheGetDependsCount},
-   {"file_list",PkgCacheGetFileList},
-   {"package_count",PkgCacheGetPackageCount},
-   {"package_file_count",PkgCacheGetPackageFileCount},
-   {"packages",PkgCacheGetPackages},
-   {"provides_count",PkgCacheGetProvidesCount},
-   {"ver_file_count",PkgCacheGetVerFileCount},
-   {"version_count",PkgCacheGetVersionCount},
+   {"depends_count",PkgCacheGetDependsCount,0,
+    "The number of apt_pkg.Dependency objects stored in the cache."},
+   {"file_list",PkgCacheGetFileList,0,
+    "A list of apt_pkg.PackageFile objects stored in the cache."},
+   {"package_count",PkgCacheGetPackageCount,0,
+    "The number of apt_pkg.Package objects stored in the cache."},
+   {"package_file_count",PkgCacheGetPackageFileCount,0,
+    "The number of apt_pkg.PackageFile objects stored in the cache."},
+   {"packages",PkgCacheGetPackages,0,
+    "A list of apt_pkg.Package objects stored in the cache."},
+   {"provides_count",PkgCacheGetProvidesCount,0,
+    "Number of Provides relations described in the cache."},
+   {"ver_file_count",PkgCacheGetVerFileCount,0,
+    "The number of (Version, PackageFile) relations."},
+   {"version_count",PkgCacheGetVersionCount,0,
+    "The number of apt_pkg.Version objects stored in the cache."},
    {}
 };
 
@@ -313,13 +336,17 @@ static Py_ssize_t CacheMapLen(PyObject *Self)
 }
 
 static char *doc_PkgCache = "Cache([progress]) -> Cache() object.\n\n"
-    "The cache provides access to the packages and other stuff.\n\n"
+    "The APT cache file contains a hash table mapping names of binary\n"
+    "packages to their metadata. A Cache object is the in-core\n"
+    "representation of the same. It provides access to APT’s idea of the\n"
+    "list of available packages.\n"
     "The optional parameter *progress* can be used to specify an \n"
-    "apt.progress.OpProgress() object (or similar) which displays\n"
-    "the opening progress. If not specified, the progress is\n"
-    "displayed in simple text form.\n\n"
-    "The cache can be used like a mapping of package names to Package\n"
-    "objects.";
+    "apt.progress.base.OpProgress() object (or similar) which reports\n"
+    "progress information while the cache is being opened.  If this\n"
+    "parameter is not supplied, the progress will be reported in simple,\n"
+    "human-readable text to standard output.\n\n"
+    "The cache can be used like a mapping from package names to Package\n"
+    "objects (although only getting items is supported).";
 static PySequenceMethods CacheSeq = {0,0,0,0,0,0,0,CacheContains,0,0};
 static PyMappingMethods CacheMap = {CacheMapLen,CacheMapOp,0};
 PyTypeObject PyCache_Type =
@@ -442,6 +469,12 @@ static PySequenceMethods PkgListSeq =
    0                 // assign slice
 };
 
+static const char *packagelist_doc =
+    "A PackageList is an internally used structure to represent\n"
+    "the 'packages' attribute of apt_pkg.Cache objects in a more\n"
+    "efficient manner by creating Package objects only when they\n"
+    "are accessed.";
+
 PyTypeObject PyPackageList_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -465,7 +498,7 @@ PyTypeObject PyPackageList_Type =
    0,                                   // tp_setattro
    0,                                   // tp_as_buffer
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, // tp_flags
-   0,                                   // tp_doc
+   packagelist_doc,                     // tp_doc
    CppTraverse<PkgListStruct>,     // tp_traverse
    CppClear<PkgListStruct>,        // tp_clear
 };
@@ -487,9 +520,9 @@ MkGet(PackageGetInstState,Py_BuildValue("i",Pkg->InstState))
 MkGet(PackageGetCurrentState,Py_BuildValue("i",Pkg->CurrentState))
 MkGet(PackageGetID,Py_BuildValue("i",Pkg->ID))
 #
-MkGet(PackageGetAuto,Py_BuildValue("i",(Pkg->Flags & pkgCache::Flag::Auto) != 0))
-MkGet(PackageGetEssential,Py_BuildValue("i",(Pkg->Flags & pkgCache::Flag::Essential) != 0))
-MkGet(PackageGetImportant,Py_BuildValue("i",(Pkg->Flags & pkgCache::Flag::Important) != 0))
+MkGet(PackageGetAuto,PyBool_FromLong((Pkg->Flags & pkgCache::Flag::Auto) != 0))
+MkGet(PackageGetEssential,PyBool_FromLong((Pkg->Flags & pkgCache::Flag::Essential) != 0))
+MkGet(PackageGetImportant,PyBool_FromLong((Pkg->Flags & pkgCache::Flag::Important) != 0))
 #undef MkGet
 #undef Owner
 
@@ -508,6 +541,19 @@ static PyObject *PackageGetVersionList(PyObject *Self,void*)
    }
    return List;
 }
+
+static PyObject *PackageGetHasVersions(PyObject *Self,void*)
+{
+   pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(Self);
+   return PyBool_FromLong(Pkg.VersionList().end() == false);
+}
+
+static PyObject *PackageGetHasProvides(PyObject *Self,void*)
+{
+   pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(Self);
+   return PyBool_FromLong(Pkg.ProvidesList().end() == false);
+}
+
 static PyObject *PackageGetCurrentVer(PyObject *Self,void*)
 {
    pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(Self);
@@ -522,19 +568,47 @@ static PyObject *PackageGetCurrentVer(PyObject *Self,void*)
 }
 
 static PyGetSetDef PackageGetSet[] = {
-    {"name",PackageGetName},
-    {"section",PackageGetSection},
-    {"rev_depends_list",PackageGetRevDependsList},
-    {"provides_list",PackageGetProvidesList},
-    {"selected_state",PackageGetSelectedState},
-    {"inst_state",PackageGetInstState},
-    {"current_state",PackageGetCurrentState},
-    {"id",PackageGetID},
-    {"auto",PackageGetAuto},
-    {"essential",PackageGetEssential},
-    {"important",PackageGetImportant},
-    {"version_list",PackageGetVersionList},
-    {"current_ver",PackageGetCurrentVer},
+    {"name",PackageGetName,0,
+     "The name of the package."},
+    {"section",PackageGetSection,0,
+     "The section of the package."},
+    {"rev_depends_list",PackageGetRevDependsList,0,
+     "An apt_pkg.DependencyList object of all reverse dependencies."},
+    {"provides_list",PackageGetProvidesList,0,
+     "A list of all packages providing this package. The list contains\n"
+     "tuples in the format (providesname, providesver, version)\n"
+     "where 'version' is an apt_pkg.Version object."},
+    {"selected_state",PackageGetSelectedState,0,
+     "The state of the selection, which can be compared against the constants\n"
+     "SELSTATE_DEINSTALL, SELSTATE_HOLD, SELSTATE_INSTALL, SELSTATE_PURGE,\n"
+     "SELSTATE_UNKNOWN of the apt_pkg module."},
+    {"inst_state",PackageGetInstState,0,
+     "The state of the install, which be compared against the constants\n"
+     "INSTSTATE_HOLD, INSTSTATE_HOLD_REINSTREQ, INSTSTATE_OK,\n"
+     "INSTSTATE_REINSTREQ of the apt_pkg module."},
+    {"current_state",PackageGetCurrentState,0,
+     "The current state, which can be compared against the constants\n"
+     "CURSTATE_CONFIG_FILES, CURSTATE_HALF_CONFIGURED,\n"
+     "CURSTATE_HALF_INSTALLED, CURSTATE_INSTALLED, CURSTATE_NOT_INSTALLED,\n"
+     "CURSTATE_UNPACKED of the apt_pkg module."},
+    {"id",PackageGetID,0,
+     "The numeric ID of the package"},
+    {"auto",PackageGetAuto,0,
+     "Ignore it, it does nothing. You want to use\n"
+     "DepCache.is_auto_installed instead."},
+    {"essential",PackageGetEssential,0,
+     "Boolean value determining whether the package is essential."},
+    {"important",PackageGetImportant,0,
+     "Boolean value determining whether the package has the 'important'\n"
+     "flag set ('Important: yes' in the Packages file). No longer used."},
+    {"version_list",PackageGetVersionList,0,
+     "A list of all apt_pkg.Version objects for this package."},
+    {"current_ver",PackageGetCurrentVer,0,
+     "The version of the package currently installed or None."},
+    {"has_versions",PackageGetHasVersions,0,
+     "Whether the package has at least one version in the cache."},
+    {"has_provides",PackageGetHasProvides,0,
+     "Whether the package is provided by at least one other package."},
     {}
 };
 
@@ -548,6 +622,12 @@ static PyObject *PackageRepr(PyObject *Self)
                               Pkg->ID);
 }
 
+static const char *package_doc =
+    "Represent a package. A package is uniquely identified by its name\n"
+    "and each package can have zero or more versions which can be\n"
+    "accessed via the version_list property. Packages can be installed\n"
+    "and removed by apt_pkg.DepCache.";
+
 PyTypeObject PyPackage_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -571,7 +651,7 @@ PyTypeObject PyPackage_Type =
    0,                                   // tp_setattro
    0,                                   // tp_as_buffer
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, // tp_flags
-   "Package Object",                    // tp_doc
+   package_doc,                         // tp_doc
    CppTraverse<pkgCache::PkgIterator>, // tp_traverse
    CppClear<pkgCache::PkgIterator>,// tp_clear
    0,                                   // tp_richcompare
@@ -615,9 +695,13 @@ static PyObject *DescriptionGetFileList(PyObject *Self,void*)
 }
 
 static PyGetSetDef DescriptionGetSet[] = {
-    {"language_code",DescriptionGetLanguageCode},
-    {"md5",DescriptionGetMd5},
-    {"file_list",DescriptionGetFileList},
+    {"language_code",DescriptionGetLanguageCode,0,
+     "The language code of the description. Empty string for untranslated\n"
+     "descriptions."},
+    {"md5",DescriptionGetMd5,0,
+     "The MD5 hash of the description."},
+    {"file_list",DescriptionGetFileList,0,
+     "A list of all apt_pkg.PackageFile objects related to this description."},
     {}
 };
 
@@ -629,6 +713,10 @@ static PyObject *DescriptionRepr(PyObject *Self)
                               Desc.md5());
 }
 
+static const char *description_doc =
+    "Represent a package description and some attributes. Needed for\n"
+    "things like translated descriptions.";
+
 PyTypeObject PyDescription_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -652,7 +740,7 @@ PyTypeObject PyDescription_Type =
    0,                                   // tp_setattro
    0,                                   // tp_as_buffer
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, // tp_flags
-   "apt_pkg.Description Object",        // tp_doc
+   description_doc,                     // tp_doc
    CppTraverse<pkgCache::DescIterator>, // tp_traverse
    CppClear<pkgCache::DescIterator>,// tp_clear
    0,                                   // tp_richcompare
@@ -799,7 +887,7 @@ static PyObject *VersionGetPriorityStr(PyObject *Self, void*) {
    return Safe_FromString(Version_GetVer(Self).PriorityType());
 }
 static PyObject *VersionGetDownloadable(PyObject *Self, void*) {
-   return Py_BuildValue("b",Version_GetVer(Self).Downloadable());
+   return PyBool_FromLong(Version_GetVer(Self).Downloadable());
 }
 static PyObject *VersionGetTranslatedDescription(PyObject *Self, void*) {
    pkgCache::VerIterator &Ver = GetCpp<pkgCache::VerIterator>(Self);
@@ -819,9 +907,9 @@ static PyObject *VersionGetIsTrusted(PyObject *Self, void*) {
       {
 	 pkgIndexFile *index;
 	 if(Sources.FindIndex(i.File(), index) && !index->IsTrusted())
-	    return Py_BuildValue("b", false);
+	    Py_RETURN_FALSE;
       }
-      return Py_BuildValue("b", true);
+      Py_RETURN_TRUE;
    }
 }
 #endif
@@ -842,23 +930,68 @@ static PyObject *VersionRepr(PyObject *Self)
 }
 #undef NOTNULL
 
+static PyObject *version_richcompare(PyObject *obj1, PyObject *obj2, int op)
+{
+    if (!PyVersion_Check(obj2))
+        return Py_INCREF(Py_NotImplemented), Py_NotImplemented;
+
+    const pkgCache::VerIterator &a = GetCpp<pkgCache::VerIterator>(obj1);
+    const pkgCache::VerIterator &b = GetCpp<pkgCache::VerIterator>(obj2);
+    const int comparison = _system->VS->CmpVersion(a.VerStr(), b.VerStr());
+    switch (op) {
+        case Py_LT: return PyBool_FromLong(comparison < 0);
+        case Py_LE: return PyBool_FromLong(comparison <= 0);
+        case Py_EQ: return PyBool_FromLong(comparison == 0);
+        case Py_NE: return PyBool_FromLong(comparison != 0);
+        case Py_GE: return PyBool_FromLong(comparison >= 0);
+        case Py_GT: return PyBool_FromLong(comparison > 0);
+        default: return NULL; // should not happen.
+    }
+}
+
 static PyGetSetDef VersionGetSet[] = {
-   {"arch",VersionGetArch},
-   {"depends_list",VersionGetDependsList},
-   {"depends_list_str",VersionGetDependsListStr},
-   {"downloadable",VersionGetDownloadable},
-   {"file_list",VersionGetFileList},
-   {"hash",VersionGetHash},
-   {"id",VersionGetID},
-   {"installed_size",VersionGetInstalledSize},
-   {"parent_pkg",VersionGetParentPkg},
-   {"priority",VersionGetPriority},
-   {"priority_str",VersionGetPriorityStr},
-   {"provides_list",VersionGetProvidesList},
-   {"section",VersionGetSection},
-   {"size",VersionGetSize},
-   {"translated_description",VersionGetTranslatedDescription},
-   {"ver_str",VersionGetVerStr},
+   {"arch",VersionGetArch,0,
+    "The architecture of this specific version of the package."},
+   {"depends_list",VersionGetDependsList,0,
+    "A dictionary mapping dependency types to lists (A) of lists (B) of\n"
+    "apt_pkg.Dependency objects. The lists (B) represent or dependencies\n"
+    "like 'a || b'."},
+   {"depends_list_str",VersionGetDependsListStr,0,
+    "Same as depends_list, except that the apt_pkg.Dependency objects\n"
+    "are 3-tuples of the form (name, version, operator); where operator\n"
+    "is one of '<', '<=', '=', '>=', '>'."},
+   {"downloadable",VersionGetDownloadable,0,
+    "Whether the version can be downloaded."},
+   {"file_list",VersionGetFileList,0,
+    "A list of tuples (packagefile: apt_pkg.PackageFile, index: int) for the\n"
+    "PackageFile objects related to this package. The index can be used\n"
+    "to retrieve the record of this package version."},
+   {"hash",VersionGetHash,0,
+    "The numeric hash of the version used in the internal storage."},
+   {"id",VersionGetID,0,
+    "The numeric ID of the package."},
+   {"installed_size",VersionGetInstalledSize,0,
+    "The installed size of this package version."},
+   {"parent_pkg",VersionGetParentPkg,0,
+    "The parent package of this version."},
+   {"priority",VersionGetPriority,0,
+    "The priority of the package as an integer, which can be compared to\n"
+    "the constants PRI_EXTRA, PRI_IMPORTANT, PRI_OPTIONAL, PRI_REQUIRED,\n"
+    "PRI_STANDARD of the apt_pkg module."},
+   {"priority_str",VersionGetPriorityStr,0,
+    "The priority of the package, as a string."},
+   {"provides_list",VersionGetProvidesList,0,
+    "A list of all packages provided by this version. See\n"
+    "Package.provides_list for a description of the format."},
+   {"section",VersionGetSection,0,
+    "The section of this package version."},
+   {"size",VersionGetSize,0,
+    "The size of the package file."},
+   {"translated_description",VersionGetTranslatedDescription,0,
+    "An apt_pkg.Description object for the translated description if\n"
+    "available or the untranslated fallback."},
+   {"ver_str",VersionGetVerStr,0,
+    "The version string."},
    {}
 };
 
@@ -888,7 +1021,7 @@ PyTypeObject PyVersion_Type =
    "Version Object",                    // tp_doc
    CppTraverse<pkgCache::VerIterator>, // tp_traverse
    CppClear<pkgCache::VerIterator>,// tp_clear
-   0,                                   // tp_richcompare
+   version_richcompare,                 // tp_richcompare
    0,                                   // tp_weaklistoffset
    0,                                   // tp_iter
    0,                                   // tp_iternext
@@ -963,7 +1096,7 @@ static PyObject *PackageFile_GetSize(PyObject *Self,void*)
 static PyObject *PackageFile_GetNotSource(PyObject *Self,void*)
 {
     pkgCache::PkgFileIterator &File = GetCpp<pkgCache::PkgFileIterator>(Self);
-    return Py_BuildValue("i",(File->Flags & pkgCache::Flag::NotSource) != 0);
+    return PyBool_FromLong((File->Flags & pkgCache::Flag::NotSource) != 0);
 }
 static PyObject *PackageFile_GetNotAutomatic(PyObject *Self,void*)
 {
@@ -995,22 +1128,43 @@ static PyObject *PackageFileRepr(PyObject *Self)
 #undef S
 
 static PyGetSetDef PackageFileGetSet[] = {
-  {(char*)"architecture",PackageFile_GetArchitecture},
-  {(char*)"archive",PackageFile_GetArchive},
-  {(char*)"component",PackageFile_GetComponent},
-  {(char*)"filename",PackageFile_GetFileName},
-  {(char*)"id",PackageFile_GetID},
-  {(char*)"index_type",PackageFile_GetIndexType},
-  {(char*)"label",PackageFile_GetLabel},
-  {(char*)"not_automatic",PackageFile_GetNotAutomatic},
-  {(char*)"not_source",PackageFile_GetNotSource},
-  {(char*)"origin",PackageFile_GetOrigin},
-  {(char*)"site",PackageFile_GetSite},
-  {(char*)"size",PackageFile_GetSize},
-  {(char*)"version",PackageFile_GetVersion},
+  {"architecture",PackageFile_GetArchitecture,0,
+   "The architecture of the package file. Unused, empty string nowadays."},
+  {"archive",PackageFile_GetArchive,0,
+   "The archive of the package file (i.e. 'Suite' in the Release file)."},
+  {"component",PackageFile_GetComponent,0,
+   "The component of this package file (e.g. 'main')."},
+  {"filename",PackageFile_GetFileName,0,
+   "The path to the file."},
+  {"id",PackageFile_GetID,0,
+   "The numeric ID of this PackageFile object."},
+  {"index_type",PackageFile_GetIndexType,0,
+   "A string describing the type of index. Known values are\n"
+   "'Debian Package Index', 'Debian Translation Index', and\n"
+   "'Debian dpkg status file'."},
+  {"label",PackageFile_GetLabel,0,
+   "The label set in the release file (e.g. 'Debian')."},
+  {"not_automatic",PackageFile_GetNotAutomatic,0,
+   "Whether the NotAutomatic flag is set in the Release file."},
+  {"not_source",PackageFile_GetNotSource,0,
+   "Whether this package file lacks an active (sources.list) source;"
+   "packages listed in such a file cannot be downloaded."},
+  {"origin",PackageFile_GetOrigin,0,
+   "The origin set in the release file."},
+  {"site",PackageFile_GetSite,0,
+   "The hostname of the location this file comes from."},
+  {"size",PackageFile_GetSize,0,
+   "The size of the file."},
+  {"version",PackageFile_GetVersion,0,
+   "The version set in the release file (e.g. '5.0.X' for lenny, where X\n"
+   "is a point release)."},
   {}
 };
 
+static const char *packagefile_doc =
+    "A package file is an index file stored in the cache with some\n"
+    "additional pieces of information.";
+
 PyTypeObject PyPackageFile_Type = {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
    "apt_pkg.PackageFile",                                // tp_name
@@ -1032,7 +1186,7 @@ PyTypeObject PyPackageFile_Type = {
    0,                                                    // tp_setattro
    0,                                                    // tp_as_buffer
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC,              // tp_flags
-   "apt_pkg.PackageFile Object",                         // tp_doc
+   packagefile_doc,                                      // tp_doc
    CppTraverse<pkgCache::PkgFileIterator>,          // tp_traverse
    CppClear<pkgCache::PkgFileIterator>,             // tp_clear
    0,                                                    // tp_richcompare
@@ -1096,8 +1250,13 @@ static PyObject *DepAllTargets(PyObject *Self,PyObject *Args)
 
 static PyMethodDef DependencyMethods[] =
 {
-   {"smart_target_pkg",DepSmartTargetPkg,METH_VARARGS,"Returns the natural Target or None"},
-   {"all_targets",DepAllTargets,METH_VARARGS,"Returns all possible Versions that match this dependency"},
+   {"smart_target_pkg",DepSmartTargetPkg,METH_VARARGS,
+    "smart_target_pkg() -> apt_pkg.Package\n\n"
+    "Return the first package which provides a package with the name\n"
+    "of the target package."},
+   {"all_targets",DepAllTargets,METH_VARARGS,
+    "all_targets() -> list\n\n"
+    "A list of all apt_pkg.Version objects satisfying the dependency."},
    {}
 };
 
@@ -1167,18 +1326,34 @@ static PyObject *DependencyGetID(PyObject *Self,void*)
 }
 
 static PyGetSetDef DependencyGetSet[] = {
-   {"comp_type",DependencyGetCompType},
-   {"dep_type",DependencyGetDepType},
-   {"dep_type_untranslated",DependencyGetDepTypeUntranslated},
-   {"dep_type_enum",DependencyGetDepTypeEnum},
-   {"id",DependencyGetID},
-   {"parent_pkg",DependencyGetParentPkg},
-   {"parent_ver",DependencyGetParentVer},
-   {"target_pkg",DependencyGetTargetPkg},
-   {"target_ver",DependencyGetTargetVer},
+   {"comp_type",DependencyGetCompType,0,
+    "The type of comparison, as a string (one of '<', '<=', '=', '>=', '>')."},
+   {"dep_type",DependencyGetDepType,0,
+    "The type of the dependency; may be translated"},
+   {"dep_type_untranslated",DependencyGetDepTypeUntranslated,0,
+    "Same as dep_type, but guaranteed to be untranslated."},
+   {"dep_type_enum",DependencyGetDepTypeEnum,0,
+    "Same as dep_type, but with a numeric value instead of a string. Can\n"
+    "be compared against the TYPE_ constants defined in this class."},
+   {"id",DependencyGetID,0,
+    "The numeric ID of this dependency object."},
+   {"parent_pkg",DependencyGetParentPkg,0,
+    "The apt_pkg.Package object of the package which depends."},
+   {"parent_ver",DependencyGetParentVer,0,
+    "The apt_pkg.Version object of the package which depends."},
+   {"target_pkg",DependencyGetTargetPkg,0,
+    "The apt_pkg.Package object of the package depended upon"},
+   {"target_ver",DependencyGetTargetVer,0,
+    "The version of the package depended upon as a string"},
    {}
 };
 
+static const char *dependency_doc =
+    "Represent a dependency from one package version to a package,\n"
+    "and (optionally) a version relation (e.g. >= 1). Dependency\n"
+    "objects also provide useful functions like all_targets() or\n"
+    "smart_target_pkg() for selecting packages to satisfy the\n"
+    "dependency.";
 
 PyTypeObject PyDependency_Type =
 {
@@ -1203,7 +1378,7 @@ PyTypeObject PyDependency_Type =
    0,                                   // tp_setattro
    0,                                   // tp_as_buffer
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, // tp_flags
-   "Dependency Object",                 // tp_doc
+   dependency_doc,                      // tp_doc
    CppTraverse<pkgCache::DepIterator>, // tp_traverse
    CppClear<pkgCache::DepIterator>, // tp_clear
    0,                                   // tp_richcompare
@@ -1265,6 +1440,10 @@ static PySequenceMethods RDepListSeq =
    0                 // assign slice
 };
 
+static const char *dependencylist_doc =
+    "A simple list-like type for representing multiple dependency\n"
+    "objects in an efficient manner; without having to generate\n"
+    "all Dependency objects in advance.";
 PyTypeObject PyDependencyList_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -1288,7 +1467,7 @@ PyTypeObject PyDependencyList_Type =
    0,                                   // tp_setattro
    0,                                   // tp_as_buffer
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, // tp_flags
-   "DependencyList Object",             // tp_doc
+   dependencylist_doc,             // tp_doc
    CppTraverse<RDepListStruct>,    // tp_traverse
    CppClear<RDepListStruct>,       // tp_clear
 };
diff --git a/python/cdrom.cc b/python/cdrom.cc
index d732a810..e6cc8e29 100644
--- a/python/cdrom.cc
+++ b/python/cdrom.cc
@@ -30,7 +30,7 @@
 
 static char *cdrom_add_doc =
     "add(progress: apt_pkg.CdromProgress) -> bool\n\n"
-    "Add the given CD-ROM to the sources.list. Returns True on success, may\n"
+    "Add the given CD-ROM to the sources.list. Return True on success;\n"
     "raise an error on failure or return False.";
 static PyObject *cdrom_add(PyObject *Self,PyObject *Args)
 {
@@ -51,8 +51,11 @@ static PyObject *cdrom_add(PyObject *Self,PyObject *Args)
 
 static char *cdrom_ident_doc =
     "ident(progress: apt_pkg.CdromProgress) -> str\n\n"
-    "Try to identify the CD-ROM and if successful return the identity as a\n"
-    "string. Otherwise, return None or raise an error.";
+    "Try to identify the CD-ROM and if successful return the hexadecimal\n"
+    "CDROM-ID (and a integer version suffix seperated by -) as a\n"
+    "string. Otherwise, return None or raise an error.\n\n"
+    "The ID is created by hashing all file and directory names on the\n"
+    "CD-ROM and appending the version.";
 static PyObject *cdrom_ident(PyObject *Self,PyObject *Args)
 {
     pkgCdrom &Cdrom = GetCpp<pkgCdrom>(Self);
@@ -95,7 +98,8 @@ static PyObject *cdrom_ident_old(PyObject *Self,PyObject *Args)
     string ident;
     bool res = Cdrom.Ident(ident, &progress);
 
-    PyObject *result = Py_BuildValue("(bs)", res, ident.c_str());
+    PyObject *boolres = PyBool_FromLong(res);
+    PyObject *result = Py_BuildValue("(Os)", boolres, ident.c_str());
 
     return HandleErrors(result);
 }
diff --git a/python/configuration.cc b/python/configuration.cc
index 299e06ec..7c9ed7bc 100644
--- a/python/configuration.cc
+++ b/python/configuration.cc
@@ -33,7 +33,10 @@ static inline Configuration &GetSelf(PyObject *Obj)
 									/*}}}*/
 
 // Method Wrappers							/*{{{*/
-static char *doc_Find = "Find(Name[,default]) -> String/None";
+static const char *doc_Find =
+    "find(key: str[, default: str = '']) -> str\n\n"
+    "Find the value for the given key and return it. If the\n"
+    "given key does not exist, return default instead.";
 static PyObject *CnfFind(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -43,7 +46,21 @@ static PyObject *CnfFind(PyObject *Self,PyObject *Args)
    return CppPyString(GetSelf(Self).Find(Name,Default));
 }
 
-static char *doc_FindFile = "FindFile(Name[,default]) -> String/None";
+static const char *doc_FindFile =
+    "find_file(key: str[, default: str = '']) -> str\n\n"
+    "Same as find(), but for filenames. In the APT configuration, there\n"
+    "is a special section Dir:: for storing filenames. find_file() locates\n"
+    "the given key and then goes up and prepends the directory names to the\n"
+    "return value. For example, for:\n"
+    "\n"
+    "    apt_pkg.config['Dir'] = 'a'\n"
+    "    apt_pkg.config['Dir::D'] = 'b'\n"
+    "    apt_pkg.config['Dir::D::F'] = 'c'\n"
+    "\n"
+    "find_file('Dir::D::F') returns 'a/b/c'. There is also a special\n"
+    "configuration setting RootDir which will always be prepended to the\n"
+    "result (the default being ''). Thus, if RootDir is 'x', the example\n"
+    "would return 'x/a/b/c'.";
 static PyObject *CnfFindFile(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -53,7 +70,10 @@ static PyObject *CnfFindFile(PyObject *Self,PyObject *Args)
    return CppPyString(GetSelf(Self).FindFile(Name,Default));
 }
 
-static char *doc_FindDir = "FindDir(Name[,default]) -> String/None";
+static const char *doc_FindDir =
+    "find_dir(key: str[, default: str = '']) -> str\n\n"
+    "Same as find_file(), but for directories. The difference is\n"
+    "that this function adds a trailing slash to the result.";
 static PyObject *CnfFindDir(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -63,7 +83,9 @@ static PyObject *CnfFindDir(PyObject *Self,PyObject *Args)
    return CppPyString(GetSelf(Self).FindDir(Name,Default));
 }
 
-static char *doc_FindI = "FindI(Name[,default]) -> Integer";
+static const char *doc_FindI =
+    "find_i(key: str[, default: int = 0]) -> int\n\n"
+    "Same as find, but for integer values.";
 static PyObject *CnfFindI(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -73,17 +95,23 @@ static PyObject *CnfFindI(PyObject *Self,PyObject *Args)
    return Py_BuildValue("i",GetSelf(Self).FindI(Name,Default));
 }
 
-static char *doc_FindB = "FindB(Name[,default]) -> Integer";
+static const char *doc_FindB =
+    "find_i(key: str[, default: bool = False]) -> bool\n\n"
+    "Same as find, but for boolean values; returns False on unknown values.";
 static PyObject *CnfFindB(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
    int Default = 0;
    if (PyArg_ParseTuple(Args,"s|i",&Name,&Default) == 0)
       return 0;
-   return Py_BuildValue("i",(int)GetSelf(Self).FindB(Name,(Default == 0?false:true)));
+   return PyBool_FromLong(GetSelf(Self).FindB(Name,(Default == 0?false:true)));
 }
 
-static char *doc_Set = "Set(Name,Value) -> None";
+static const char *doc_Set =
+    "set(key: str, value: str)\n\n"
+    "Set the given key to the given value. To set int or bool values,\n"
+    "encode them using str(value) and then use find_i()/find_b()\n"
+    "to retrieve their value again.";
 static PyObject *CnfSet(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -96,13 +124,15 @@ static PyObject *CnfSet(PyObject *Self,PyObject *Args)
    return Py_None;
 }
 
-static char *doc_Exists = "Exists(Name) -> Integer";
+static const char *doc_Exists =
+    "exists(key: str) -> bool\n\n"
+    "Check whether the given key exists.";
 static PyObject *CnfExists(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
    if (PyArg_ParseTuple(Args,"s",&Name) == 0)
       return 0;
-   return Py_BuildValue("i",(int)GetSelf(Self).Exists(Name));
+   return PyBool_FromLong((int)GetSelf(Self).Exists(Name));
 }
 
 static int CnfContains(PyObject *Self,PyObject *Arg)
@@ -110,7 +140,9 @@ static int CnfContains(PyObject *Self,PyObject *Arg)
    return (int)GetSelf(Self).Exists(PyString_AsString(Arg));
 }
 
-static char *doc_Clear = "Clear(Name) -> None";
+static const char *doc_Clear = 
+    "clear(key: str)\n\n"
+    "Remove the specified option and all sub-options.";
 static PyObject *CnfClear(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -124,7 +156,13 @@ static PyObject *CnfClear(PyObject *Self,PyObject *Args)
 }
 
 // The amazing narrowing search ability!
-static char *doc_SubTree = "SubTree(Name) -> Configuration";
+static const char *doc_SubTree =
+    "sub_tree(key: str) -> apt_pkg.Configuration\n\n"
+    
+    "Return a new apt_pkg.Configuration object with the given option\n"
+    "as its root. Example:\n\n"
+    "    apttree = config.subtree('APT')\n"
+    "    apttree['Install-Suggests'] = config['APT::Install-Suggests']";
 static PyObject *CnfSubTree(PyObject *Self,PyObject *Args)
 {
    char *Name;
@@ -142,7 +180,14 @@ static PyObject *CnfSubTree(PyObject *Self,PyObject *Args)
 }
 
 // Return a list of items at a specific level
-static char *doc_List = "List([root]) -> List";
+static char *doc_List =
+    "list([root: str]) -> list\n\n"
+    "Return a list of all items at the given root, using their full\n"
+    "name. For example, in a configuration object where the options A,\n"
+    "B, and B::C are set, the following expressions evaluate to True:\n\n"
+    "   conf.list() == ['A', 'B']\n"
+    "   conf.list('A') == ['']\n"
+    "   conf.list('B') == ['B::C']\n";
 static PyObject *CnfList(PyObject *Self,PyObject *Args)
 {
    char *RootName = 0;
@@ -169,7 +214,9 @@ static PyObject *CnfList(PyObject *Self,PyObject *Args)
 
 /* Return a list of values of items at a specific level.. This is used to
    get out value lists */
-static char *doc_ValueList = "ValueList([root]) -> List";
+static char *doc_ValueList =
+    "value_list([root: str]) -> list\n\n"
+    "Same as list(), but instead of returning the keys, return the values.";
 static PyObject *CnfValueList(PyObject *Self,PyObject *Args)
 {
    char *RootName = 0;
@@ -191,7 +238,11 @@ static PyObject *CnfValueList(PyObject *Self,PyObject *Args)
    return List;
 }
 
-static char *doc_MyTag = "MyTag() -> String";
+static char *doc_MyTag =
+    "my_tag() -> str\n\n"
+    "Return the tag of the root of this Configuration object. For the\n"
+    "default object, this is an empty string. For a subtree('APT') of\n"
+    "such an object, it would be 'APT' (given as an example).";
 static PyObject *CnfMyTag(PyObject *Self,PyObject *Args)
 {
    if (PyArg_ParseTuple(Args,"") == 0)
@@ -204,7 +255,10 @@ static PyObject *CnfMyTag(PyObject *Self,PyObject *Args)
 }
 
 // Look like a mapping
-static char *doc_Keys = "keys([root]) -> List";
+static char *doc_Keys =
+    "keys([root: str]) -> list\n\n"
+    "Return a list of all keys in the configuration object. If 'root'\n"
+    "is given, limit the list to those below the root.";
 static PyObject *CnfKeys(PyObject *Self,PyObject *Args)
 {
    char *RootName = 0;
@@ -274,7 +328,10 @@ static int CnfMapSet(PyObject *Self,PyObject *Arg,PyObject *Val)
 }
 									/*}}}*/
 // Config file loaders							/*{{{*/
-char *doc_LoadConfig = "LoadConfig(Configuration,FileName) -> None";
+char *doc_LoadConfig =
+    "read_config_file(configuration: apt_pkg.Configuration, filename: str)\n\n"
+    "Read the configuration file 'filename' and set the appropriate\n"
+    "options in the configuration object.";
 PyObject *LoadConfig(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -292,7 +349,11 @@ PyObject *LoadConfig(PyObject *Self,PyObject *Args)
    Py_INCREF(Py_None);
    return HandleErrors(Py_None);
 }
-char *doc_LoadConfigISC = "LoadConfigISC(Configuration,FileName) -> None";
+char *doc_LoadConfigISC =
+    "read_config_file_isc(configuration: apt_pkg.Configuration, filename: str)\n\n"
+    "Like read_config_file(), but for configuration files like bind's\n"
+    "named.conf. They have a slightly different format than APT\n"
+    "configuration files.";
 PyObject *LoadConfigISC(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -310,7 +371,10 @@ PyObject *LoadConfigISC(PyObject *Self,PyObject *Args)
    Py_INCREF(Py_None);
    return HandleErrors(Py_None);
 }
-char *doc_LoadConfigDir = "LoadConfigDir(Configuration,DirName) -> None";
+char *doc_LoadConfigDir =
+    "read_config_dir(configuration: apt_pkg.Configuration, dirname: str)\n\n"
+    "Read all configuration files in the dir given by 'dirname' in the\n"
+    "correct order.";
 PyObject *LoadConfigDir(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -333,14 +397,20 @@ PyObject *LoadConfigDir(PyObject *Self,PyObject *Args)
 // ParseCommandLine - Wrapper for the command line interface		/*{{{*/
 // ---------------------------------------------------------------------
 char *doc_ParseCommandLine =
-"ParseCommandLine(Configuration,ListOfOptions,List-argv) -> List\n"
+"parse_commandLine(config: Configuration, options: list, argv: list) -> list\n"
 "\n"
-"This function is like getopt except it manipulates a configuration space.\n"
-"output is a list of non-option arguments (filenames, etc).\n"
-"ListOfOptions is a list of tuples of the form:\n"
-"  ('c',\"long-opt or None\",\"Configuration::Variable\",\"optional type\")\n"
-"Where type may be one of HasArg, IntLevel, Boolean, InvBoolean,\n"
-"ConfigFile, or ArbItem. The default is Boolean.";
+"Parse the command line in 'argv' into the configuration space. The\n"
+"list 'options' contains a list of 3-tuples or 4-tuples in the form:\n"
+"\n"
+"   (short_option: str, long_option: str, variable: str[, type: str])\n"
+"\n"
+"The element 'short_option' is one character, the 'long_option' element\n"
+"is the name of the long option, the element 'variable' the name of the\n"
+"configuration option the result will be stored in and type is one of\n"
+"'HasArg', 'IntLevel', 'Boolean', 'InvBoolean', 'ConfigFile',\n"
+"'ArbItem'. The default type is 'Boolean'. Read the online documentation\n"
+"in python-apt-doc and its tutorial on writing an apt-cdrom clone for more\n"
+"details.";
 PyObject *ParseCommandLine(PyObject *Self,PyObject *Args)
 {
    PyObject *POList;
@@ -465,6 +535,16 @@ static PyObject *CnfNew(PyTypeObject *type, PyObject *args, PyObject *kwds) {
 // Type for a Normal Configuration object
 static PySequenceMethods ConfigurationSeq = {0,0,0,0,0,0,0,CnfContains,0,0};
 static PyMappingMethods ConfigurationMap = {0,CnfMap,CnfMapSet};
+
+static const char *configuration_doc =
+    "Configuration()\n\n"
+    "Represent the configuration of APT by mapping option keys to\n"
+    "values and storing configuration parsed from files like\n"
+    "/etc/apt/apt.conf. The most important Configuration object\n"
+    "is apt_pkg.config which points to the global configuration\n"
+    "object. Other top-level Configuration objects can be created\n"
+    "by calling the constructor, but there is usually no reason to.";
+
 PyTypeObject PyConfiguration_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -489,7 +569,7 @@ PyTypeObject PyConfiguration_Type =
    0,                                   // tp_as_buffer
    (Py_TPFLAGS_DEFAULT |                // tp_flags
     Py_TPFLAGS_BASETYPE),
-   "Configuration Object",              // tp_doc
+   configuration_doc,                   // tp_doc
    0,                                   // tp_traverse
    0,                                   // tp_clear
    0,                                   // tp_richcompare
diff --git a/python/depcache.cc b/python/depcache.cc
index 0d5d7882..e7d7d946 100644
--- a/python/depcache.cc
+++ b/python/depcache.cc
@@ -157,18 +157,18 @@ static PyObject *PkgDepCacheCommit(PyObject *Self,PyObject *Args)
       // fail if something else went wrong
       //FIXME: make this more flexible, e.g. with a failedDl handler
       if(Failed)
-	 return Py_BuildValue("b", false);
+	 Py_RETURN_FALSE;
       _system->UnLock(true);
 
       pkgPackageManager::OrderResult Res = iprogress.Run(PM);
       //std::cout << "iprogress.Run() returned: " << (int)Res << std::endl;
 
       if (Res == pkgPackageManager::Failed || _error->PendingError() == true) {
-	 return HandleErrors(Py_BuildValue("b", false));
+	 return HandleErrors(PyBool_FromLong(false));
       }
       if (Res == pkgPackageManager::Completed) {
 	 //std::cout << "iprogress.Run() returned Completed " << std::endl;
-	 return Py_BuildValue("b", true);
+     Py_RETURN_TRUE;
       }
 
       //std::cout << "looping again, install unfinished" << std::endl;
@@ -176,7 +176,7 @@ static PyObject *PkgDepCacheCommit(PyObject *Self,PyObject *Args)
       // Reload the fetcher object and loop again for media swapping
       Fetcher.Shutdown();
       if (PM->GetArchives(&Fetcher,&List,&Recs) == false) {
-	 return Py_BuildValue("b", false);
+	 Py_RETURN_FALSE;
       }
       _system->Lock();
    }
@@ -196,11 +196,11 @@ static PyObject *PkgDepCacheSetCandidateVer(PyObject *Self,PyObject *Args)
 
    pkgCache::VerIterator &I = GetCpp<pkgCache::VerIterator>(VersionObj);
    if(I.end()) {
-      return HandleErrors(Py_BuildValue("b",false));
+      return HandleErrors(PyBool_FromLong(false));
    }
    depcache->SetCandidateVersion(I);
 
-   return HandleErrors(Py_BuildValue("b",true));
+   return HandleErrors(PyBool_FromLong(true));
 }
 
 static PyObject *PkgDepCacheGetCandidateVer(PyObject *Self,PyObject *Args)
@@ -241,7 +241,7 @@ static PyObject *PkgDepCacheUpgrade(PyObject *Self,PyObject *Args)
    Py_END_ALLOW_THREADS
 
    Py_INCREF(Py_None);
-   return HandleErrors(Py_BuildValue("b",res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
 static PyObject *PkgDepCacheMinimizeUpgrade(PyObject *Self,PyObject *Args)
@@ -257,7 +257,7 @@ static PyObject *PkgDepCacheMinimizeUpgrade(PyObject *Self,PyObject *Args)
    Py_END_ALLOW_THREADS
 
    Py_INCREF(Py_None);
-   return HandleErrors(Py_BuildValue("b",res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
 
@@ -291,7 +291,7 @@ static PyObject *PkgDepCacheFixBroken(PyObject *Self,PyObject *Args)
    res &=pkgFixBroken(*depcache);
    res &=pkgMinimizeUpgrade(*depcache);
 
-   return HandleErrors(Py_BuildValue("b",res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
 
@@ -380,7 +380,6 @@ static PyObject *PkgDepCacheMarkAuto(PyObject *Self,PyObject *Args)
    return HandleErrors(Py_None);
 }
 
-
 static PyObject *PkgDepCacheIsUpgradable(PyObject *Self,PyObject *Args)
 {
    pkgDepCache *depcache = GetCpp<pkgDepCache *>(Self);
@@ -392,7 +391,7 @@ static PyObject *PkgDepCacheIsUpgradable(PyObject *Self,PyObject *Args)
    pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(PackageObj);
    pkgDepCache::StateCache &state = (*depcache)[Pkg];
 
-   return HandleErrors(Py_BuildValue("b",state.Upgradable()));
+   return HandleErrors(PyBool_FromLong(state.Upgradable()));
 }
 
 static PyObject *PkgDepCacheIsGarbage(PyObject *Self,PyObject *Args)
@@ -406,7 +405,7 @@ static PyObject *PkgDepCacheIsGarbage(PyObject *Self,PyObject *Args)
    pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(PackageObj);
    pkgDepCache::StateCache &state = (*depcache)[Pkg];
 
-   return HandleErrors(Py_BuildValue("b",state.Garbage));
+   return HandleErrors(PyBool_FromLong(state.Garbage));
 }
 
 static PyObject *PkgDepCacheIsAutoInstalled(PyObject *Self,PyObject *Args)
@@ -420,7 +419,7 @@ static PyObject *PkgDepCacheIsAutoInstalled(PyObject *Self,PyObject *Args)
    pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(PackageObj);
    pkgDepCache::StateCache &state = (*depcache)[Pkg];
 
-   return HandleErrors(Py_BuildValue("b",state.Flags & pkgCache::Flag::Auto));
+   return HandleErrors(PyBool_FromLong(state.Flags & pkgCache::Flag::Auto));
 }
 
 static PyObject *PkgDepCacheIsNowBroken(PyObject *Self,PyObject *Args)
@@ -434,7 +433,7 @@ static PyObject *PkgDepCacheIsNowBroken(PyObject *Self,PyObject *Args)
    pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(PackageObj);
    pkgDepCache::StateCache &state = (*depcache)[Pkg];
 
-   return HandleErrors(Py_BuildValue("b",state.NowBroken()));
+   return HandleErrors(PyBool_FromLong(state.NowBroken()));
 }
 
 static PyObject *PkgDepCacheIsInstBroken(PyObject *Self,PyObject *Args)
@@ -448,7 +447,7 @@ static PyObject *PkgDepCacheIsInstBroken(PyObject *Self,PyObject *Args)
    pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(PackageObj);
    pkgDepCache::StateCache &state = (*depcache)[Pkg];
 
-   return HandleErrors(Py_BuildValue("b",state.InstBroken()));
+   return HandleErrors(PyBool_FromLong(state.InstBroken()));
 }
 
 
@@ -463,7 +462,7 @@ static PyObject *PkgDepCacheMarkedInstall(PyObject *Self,PyObject *Args)
    pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(PackageObj);
    pkgDepCache::StateCache &state = (*depcache)[Pkg];
 
-   return HandleErrors(Py_BuildValue("b",state.NewInstall()));
+   return HandleErrors(PyBool_FromLong(state.NewInstall()));
 }
 
 
@@ -478,7 +477,7 @@ static PyObject *PkgDepCacheMarkedUpgrade(PyObject *Self,PyObject *Args)
    pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(PackageObj);
    pkgDepCache::StateCache &state = (*depcache)[Pkg];
 
-   return HandleErrors(Py_BuildValue("b",state.Upgrade()));
+   return HandleErrors(PyBool_FromLong(state.Upgrade()));
 }
 
 static PyObject *PkgDepCacheMarkedDelete(PyObject *Self,PyObject *Args)
@@ -492,7 +491,7 @@ static PyObject *PkgDepCacheMarkedDelete(PyObject *Self,PyObject *Args)
    pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(PackageObj);
    pkgDepCache::StateCache &state = (*depcache)[Pkg];
 
-   return HandleErrors(Py_BuildValue("b",state.Delete()));
+   return HandleErrors(PyBool_FromLong(state.Delete()));
 }
 
 static PyObject *PkgDepCacheMarkedKeep(PyObject *Self,PyObject *Args)
@@ -506,7 +505,7 @@ static PyObject *PkgDepCacheMarkedKeep(PyObject *Self,PyObject *Args)
    pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(PackageObj);
    pkgDepCache::StateCache &state = (*depcache)[Pkg];
 
-   return HandleErrors(Py_BuildValue("b",state.Keep()));
+   return HandleErrors(PyBool_FromLong(state.Keep()));
 }
 
 static PyObject *PkgDepCacheMarkedDowngrade(PyObject *Self,PyObject *Args)
@@ -520,7 +519,7 @@ static PyObject *PkgDepCacheMarkedDowngrade(PyObject *Self,PyObject *Args)
    pkgCache::PkgIterator &Pkg = GetCpp<pkgCache::PkgIterator>(PackageObj);
    pkgDepCache::StateCache &state = (*depcache)[Pkg];
 
-   return HandleErrors(Py_BuildValue("b",state.Downgrade()));
+   return HandleErrors(PyBool_FromLong(state.Downgrade()));
 }
 
 static PyObject *PkgDepCacheMarkedReinstall(PyObject *Self,PyObject *Args)
@@ -536,41 +535,104 @@ static PyObject *PkgDepCacheMarkedReinstall(PyObject *Self,PyObject *Args)
 
    bool res = state.Install() && (state.iFlags & pkgDepCache::ReInstall);
 
-   return HandleErrors(Py_BuildValue("b",res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
 
 static PyMethodDef PkgDepCacheMethods[] =
 {
-   {"init",PkgDepCacheInit,METH_VARARGS,"Init the depcache (done on construct automatically)"},
-   {"get_candidate_ver",PkgDepCacheGetCandidateVer,METH_VARARGS,"Get candidate version"},
-   {"set_candidate_ver",PkgDepCacheSetCandidateVer,METH_VARARGS,"Set candidate version"},
+   {"init",PkgDepCacheInit,METH_VARARGS,
+    "init(progress: apt.progress.base.OpProgress)\n\n"
+    "Initialize the depcache (done automatically when constructing\n"
+    "the object)."},
+   {"get_candidate_ver",PkgDepCacheGetCandidateVer,METH_VARARGS,
+    "get_candidate_ver(pkg: apt_pkg.Package) -> apt_pkg.Version\n\n"
+    "Return the candidate version for the package, normally the version\n"
+    "with the highest pin (changeable using set_candidate_ver)."},
+   {"set_candidate_ver",PkgDepCacheSetCandidateVer,METH_VARARGS,
+    "set_candidate_ver(pkg: apt_pkg.Package, ver: apt_pkg.Version) -> bool\n\n"
+    "Set the candidate version of 'pkg' to 'ver'."},
 
    // global cache operations
-   {"upgrade",PkgDepCacheUpgrade,METH_VARARGS,"Perform Upgrade (optional boolean argument if dist-upgrade should be performed)"},
-   {"fix_broken",PkgDepCacheFixBroken,METH_VARARGS,"Fix broken packages"},
-   {"read_pinfile",PkgDepCacheReadPinFile,METH_VARARGS,"Read the pin policy"},
-   {"minimize_upgrade",PkgDepCacheMinimizeUpgrade, METH_VARARGS,"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."},
+   {"upgrade",PkgDepCacheUpgrade,METH_VARARGS,
+    "upgrade([dist_upgrade: bool = True]) -> bool\n\n"
+    "Mark the packages for upgrade under the same conditions apt-get\n"
+    "upgrade does. If 'dist_upgrade' is True, also allow packages to\n"
+    "be upgraded if they require installation/removal of other packages;\n"
+    "just like apt-get dist-upgrade."},
+   {"fix_broken",PkgDepCacheFixBroken,METH_VARARGS,
+    "fix_broken() -> bool\n\n"
+    "Fix broken packages."},
+   {"read_pinfile",PkgDepCacheReadPinFile,METH_VARARGS,
+    "read_pinfile([file: str])\n\n"
+    "Read the pin policy"},
+   {"minimize_upgrade",PkgDepCacheMinimizeUpgrade, METH_VARARGS,
+    "minimize_upgrade() -> bool\n\n"
+    "Go over the entire set of packages and try to keep each package\n"
+    "marked for upgrade. If a conflict is generated then the package\n"
+    "is restored."},
    // Manipulators
-   {"mark_keep",PkgDepCacheMarkKeep,METH_VARARGS,"Mark package for keep"},
-   {"mark_delete",PkgDepCacheMarkDelete,METH_VARARGS,"Mark package for delete (optional boolean argument if it should be purged)"},
-   {"mark_install",PkgDepCacheMarkInstall,METH_VARARGS,"Mark package for Install"},
-   {"mark_auto",PkgDepCacheMarkAuto,METH_VARARGS,"mark_auto(pkg: apt_pkg.Package, auto: bool)\n\nMark package as automatically installed."},
-   {"set_reinstall",PkgDepCacheSetReInstall,METH_VARARGS,"Set if the package should be reinstalled"},
+   {"mark_keep",PkgDepCacheMarkKeep,METH_VARARGS,
+    "mark_keep(pkg: apt_pkg.Package)\n\n"
+    "Mark package to be kept."},
+   {"mark_delete",PkgDepCacheMarkDelete,METH_VARARGS,
+    "mark_delete(pkg: apt_pkg.Package[, purge: bool = False])\n\n"
+    "Mark package for deletion, and if 'purge' is True also for purging."},
+   {"mark_install",PkgDepCacheMarkInstall,METH_VARARGS,
+    "mark_install(pkg: apt_pkg.Package[, auto_inst=True, from_user=True])\n\n"
+    "Mark the package for installation. The parameter 'auto_inst' controls\n"
+    "whether the dependencies of the package are marked for installation\n"
+    "as well. The parameter 'from_user' controls whether the package is\n"
+    "registered as NOT automatically installed."},
+   {"mark_auto",PkgDepCacheMarkAuto,METH_VARARGS,
+    "mark_auto(pkg: apt_pkg.Package, auto: bool)\n\n"
+    "Mark package as automatically installed (if auto=True),\n"
+    "or as not automatically installed (if auto=False)."},
+   {"set_reinstall",PkgDepCacheSetReInstall,METH_VARARGS,
+    "set_reinstall(pkg: apt_pkg.Package, reinstall: bool)\n\n"
+    "Set whether the package should be reinstalled (reinstall = True or False)."},
    // state information
-   {"is_upgradable",PkgDepCacheIsUpgradable,METH_VARARGS,"Is pkg upgradable"},
-   {"is_now_broken",PkgDepCacheIsNowBroken,METH_VARARGS,"Is pkg is now broken"},
-   {"is_inst_broken",PkgDepCacheIsInstBroken,METH_VARARGS,"Is pkg broken on the current install"},
-   {"is_garbage",PkgDepCacheIsGarbage,METH_VARARGS,"Is pkg garbage (mark-n-sweep)"},
-   {"is_auto_installed",PkgDepCacheIsAutoInstalled,METH_VARARGS,"Is pkg marked as auto installed"},
-   {"marked_install",PkgDepCacheMarkedInstall,METH_VARARGS,"Is pkg marked for install"},
-   {"marked_upgrade",PkgDepCacheMarkedUpgrade,METH_VARARGS,"Is pkg marked for upgrade"},
-   {"marked_delete",PkgDepCacheMarkedDelete,METH_VARARGS,"Is pkg marked for delete"},
-   {"marked_keep",PkgDepCacheMarkedKeep,METH_VARARGS,"Is pkg marked for keep"},
-   {"marked_reinstall",PkgDepCacheMarkedReinstall,METH_VARARGS,"Is pkg marked for reinstall"},
-   {"marked_downgrade",PkgDepCacheMarkedDowngrade,METH_VARARGS,"Is pkg marked for downgrade"},
+   {"is_upgradable",PkgDepCacheIsUpgradable,METH_VARARGS,
+    "is_upgradable(pkg: apt_pkg.Package) -> bool\n\n"
+    "Check whether the package is upgradable."},
+   {"is_now_broken",PkgDepCacheIsNowBroken,METH_VARARGS,
+    "is_now_broken(pkg: apt_pkg.Package) -> bool\n\n"
+    "Check whether the package is broken, taking marked changes into account."},
+   {"is_inst_broken",PkgDepCacheIsInstBroken,METH_VARARGS,
+    "is_inst_broken(pkg: apt_pkg.Package) -> bool\n\n"
+    "Check whether the package is broken, ignoring marked changes."},
+   {"is_garbage",PkgDepCacheIsGarbage,METH_VARARGS,
+    "is_garbage(pkg: apt_pkg.Package) -> bool\n\n"
+    "Check whether the package is garbage, i.e. whether it is automatically\n"
+    "installed and the reverse dependencies are not installed anymore."},
+   {"is_auto_installed",PkgDepCacheIsAutoInstalled,METH_VARARGS,
+    "is_auto_installed(pkg: apt_pkg.Package) -> bool\n\n"
+    "Check whether the package is marked as automatically installed."},
+   {"marked_install",PkgDepCacheMarkedInstall,METH_VARARGS,
+    "marked_install(pkg: apt_pkg.Package) -> bool\n\n"
+    "Check whether the package is marked for installation."},
+   {"marked_upgrade",PkgDepCacheMarkedUpgrade,METH_VARARGS,
+    "marked_upgrade(pkg: apt_pkg.Package) -> bool\n\n"
+    "Check whether the package is marked for upgrade."},
+   {"marked_delete",PkgDepCacheMarkedDelete,METH_VARARGS,
+    "marked_delete(pkg: apt_pkg.Package) -> bool\n\n"
+    "Check whether the package is marked for removal."},
+   {"marked_keep",PkgDepCacheMarkedKeep,METH_VARARGS,
+    "marked_keep(pkg: apt_pkg.Package) -> bool\n\n"
+    "Check whether the package should be kept."},
+   {"marked_reinstall",PkgDepCacheMarkedReinstall,METH_VARARGS,
+    "marked_reinstall(pkg: apt_pkg.Package) -> bool\n\n"
+    "Check whether the package is marked for re-installation."},
+   {"marked_downgrade",PkgDepCacheMarkedDowngrade,METH_VARARGS,
+    "marked_downgrade(pkg: apt_pkg.Package) -> bool\n\n"
+    "Check whether the package is marked for downgrade."},
    // Action
-   {"commit", PkgDepCacheCommit, METH_VARARGS, "Commit pending changes"},
+   {"commit", PkgDepCacheCommit, METH_VARARGS,
+    "commit(acquire_progress, install_progress)\n\n"
+    "Commit all the marked changes. This method takes two arguments,\n"
+    "'acquire_progress' takes an apt.progress.base.AcquireProgress\n"
+    "object and 'install_progress' an apt.progress.base.InstallProgress\n"
+    "object."},
    {}
 };
 
@@ -608,13 +670,23 @@ static PyObject *PkgDepCacheGetPolicy(PyObject *Self,void*) {
 
 
 static PyGetSetDef PkgDepCacheGetSet[] = {
-    {"broken_count",PkgDepCacheGetBrokenCount},
-    {"deb_size",PkgDepCacheGetDebSize},
-    {"del_count",PkgDepCacheGetDelCount},
-    {"inst_count",PkgDepCacheGetInstCount},
-    {"keep_count",PkgDepCacheGetKeepCount},
-    {"usr_size",PkgDepCacheGetUsrSize},
-    {"policy",PkgDepCacheGetPolicy},
+    {"broken_count",PkgDepCacheGetBrokenCount,0,
+     "The number of packages with broken dependencies in the cache."},
+    {"deb_size",PkgDepCacheGetDebSize,0,
+     "The size of the packages which are needed for the changes to be\n"
+     "applied."},
+    {"del_count",PkgDepCacheGetDelCount,0,
+     "The number of packages marked for removal."},
+    {"inst_count",PkgDepCacheGetInstCount,0,
+     "The number of packages marked for installation."},
+    {"keep_count",PkgDepCacheGetKeepCount,0,
+     "The number of packages marked for keep."},
+    {"usr_size",PkgDepCacheGetUsrSize,0,
+     "The amount of space required for installing/removing the packages,\n"
+     "i.e. the Installed-Size of all packages marked for installation\n"
+     "minus the Installed-Size of all packages for removal."},
+    {"policy",PkgDepCacheGetPolicy,0,
+     "The apt_pkg.Policy object used by this cache."},
     {}
 };
 
@@ -643,9 +715,9 @@ static PyObject *PkgDepCacheNew(PyTypeObject *type,PyObject *Args,PyObject *kwds
    return HandleErrors(DepCachePyObj);
 }
 
-static char *doc_PkgDepCache = "DepCache(cache) -> DepCache() object\n\n"
+static char *doc_PkgDepCache = "DepCache(cache: apt_pkg.Cache)\n\n"
     "A DepCache() holds extra information on the state of the packages.\n\n"
-    "The parameter *cache* refers to an apt_pkg.Cache() object.";
+    "The parameter 'cache' refers to an apt_pkg.Cache() object.";
 PyTypeObject PyDepCache_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -750,7 +822,7 @@ static PyObject *PkgProblemResolverResolve(PyObject *Self,PyObject *Args)
    res = fixer->Resolve(brokenFix);
    Py_END_ALLOW_THREADS
 
-   return HandleErrors(Py_BuildValue("b", res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
 static PyObject *PkgProblemResolverResolveByKeep(PyObject *Self,PyObject *Args)
@@ -764,7 +836,7 @@ static PyObject *PkgProblemResolverResolveByKeep(PyObject *Self,PyObject *Args)
    res = fixer->ResolveByKeep();
    Py_END_ALLOW_THREADS
 
-   return HandleErrors(Py_BuildValue("b", res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
 static PyObject *PkgProblemResolverProtect(PyObject *Self,PyObject *Args)
@@ -816,17 +888,37 @@ static PyObject *PkgProblemResolverInstallProtect(PyObject *Self,PyObject *Args)
 static PyMethodDef PkgProblemResolverMethods[] =
 {
    // config
-   {"protect", PkgProblemResolverProtect, METH_VARARGS, "protect(PkgIterator)"},
-   {"remove", PkgProblemResolverRemove, METH_VARARGS, "remove(PkgIterator)"},
-   {"clear", PkgProblemResolverClear, METH_VARARGS, "clear(PkgIterator)"},
-   {"install_protect", PkgProblemResolverInstallProtect, METH_VARARGS, "install_protect()"},
+   {"protect", PkgProblemResolverProtect, METH_VARARGS,
+    "protect(pkg: apt_pkg.Package)\n\n"
+    "Mark the package as protected in the resolver, meaning that its\n"
+    "state will not be changed."},
+   {"remove", PkgProblemResolverRemove, METH_VARARGS,
+    "remove(pkg: apt_pkg.Package)\n\n"
+    "Mark the package for removal in the resolver."},
+   {"clear", PkgProblemResolverClear, METH_VARARGS,
+    "clear(pkg: apt_pkg.Package)\n\n"
+    "Revert the actions done by protect()/remove() on the package."},
+   {"install_protect", PkgProblemResolverInstallProtect, METH_VARARGS,
+    "install_protect()\n\n"
+    "Install all protected packages."},
 
    // Actions
-   {"resolve", PkgProblemResolverResolve, METH_VARARGS, "Try to intelligently resolve problems by installing and removing packages"},
-   {"resolve_by_keep", PkgProblemResolverResolveByKeep, METH_VARARGS, "Try to resolv problems only by using keep"},
+   {"resolve", PkgProblemResolverResolve, METH_VARARGS,
+    "resolve([fix_broken: bool = True]) -> bool\n\n"
+    "Try to intelligently resolve problems by installing and removing\n"
+    "packages. If 'fix_broken' is True, apt will try to repair broken\n"
+    "dependencies of installed packages."},
+   {"resolve_by_keep", PkgProblemResolverResolveByKeep, METH_VARARGS,
+    "resolve_by_keep() -> bool\n\n"
+    "Try to resolve problems only by using keep."},
    {}
 };
 
+static const char *problemresolver_doc =
+    "ProblemResolver(depcache: apt_pkg.DepCache)\n\n"
+    "ProblemResolver objects take care of resolving problems\n"
+    "with dependencies. They mark packages for installation/\n"
+    "removal and try to satisfy all dependencies.";
 PyTypeObject PyProblemResolver_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -852,7 +944,7 @@ PyTypeObject PyProblemResolver_Type =
    (Py_TPFLAGS_DEFAULT |                // tp_flags
     Py_TPFLAGS_BASETYPE |
     Py_TPFLAGS_HAVE_GC),
-   "ProblemResolver Object",            // tp_doc
+   problemresolver_doc,                 // tp_doc
    CppTraverse<pkgProblemResolver *>, // tp_traverse
    CppClear<pkgProblemResolver *>, // tp_clear
    0,                                   // tp_richcompare
@@ -877,7 +969,11 @@ PyTypeObject PyProblemResolver_Type =
 // pkgActionGroup Class						        /*{{{*/
 // ---------------------------------------------------------------------
 
-
+static const char *actiongroup_release_doc =
+    "release()\n\n"
+    "End the scope of this action group.  If this is the only action\n"
+    "group bound to the cache, this will cause any deferred cleanup\n"
+    "actions to be performed.";
 static PyObject *PkgActionGroupRelease(PyObject *Self,PyObject *Args)
 {
    pkgDepCache::ActionGroup *ag = GetCpp<pkgDepCache::ActionGroup*>(Self);
@@ -888,11 +984,19 @@ static PyObject *PkgActionGroupRelease(PyObject *Self,PyObject *Args)
    return HandleErrors(Py_None);
 }
 
+static const char *actiongroup__enter__doc =
+    "__enter__() -> ActionGroup\n\n"
+    "A dummy action which just returns the object itself, so it can\n"
+    "be used as a context manager.";
 static PyObject *PkgActionGroupEnter(PyObject *Self,PyObject *Args) {
    if (PyArg_ParseTuple(Args,"") == 0)
       return 0;
     return Self;
 }
+
+static const char *actiongroup__exit__doc =
+    "__exit__(*excinfo) -> bool\n\n"
+    "Same as release(), but for use as a context manager.";
 static PyObject *PkgActionGroupExit(PyObject *Self,PyObject *Args) {
    pkgDepCache::ActionGroup *ag = GetCpp<pkgDepCache::ActionGroup*>(Self);
    ag->release();
@@ -901,11 +1005,9 @@ static PyObject *PkgActionGroupExit(PyObject *Self,PyObject *Args) {
 
 static PyMethodDef PkgActionGroupMethods[] =
 {
-   {"release", PkgActionGroupRelease, METH_VARARGS, "release()"},
-   {"__exit__", PkgActionGroupExit, METH_VARARGS, "__exit__(...) -> "
-               "Release the action group, for 'with' statement."},
-   {"__enter__", PkgActionGroupEnter, METH_VARARGS, "__enter__() -> "
-               "Enter, for the 'with' statement. Does nothing."},
+   {"release", PkgActionGroupRelease, METH_VARARGS, actiongroup_release_doc},
+   {"__enter__", PkgActionGroupEnter, METH_VARARGS, actiongroup__enter__doc},
+   {"__exit__", PkgActionGroupExit, METH_VARARGS, actiongroup__exit__doc},
    {}
 };
 
diff --git a/python/hashes.cc b/python/hashes.cc
index d0b0fb0c..8cc86f4e 100644
--- a/python/hashes.cc
+++ b/python/hashes.cc
@@ -88,9 +88,8 @@ static char *hashes_doc =
     "Hashes([object: (bytes, file)])\n\n"
     "Calculate hashes for the given object. It can be used to create all\n"
     "supported hashes for a file.\n\n"
-    "The parameter *object* can be a bytes (3.X) / str (2.X) object, or an\n"
-    "object providing the fileno() method or an integer describing a file\n"
-    "descriptor.";
+    "The parameter 'object' can be a bytestring, an object providing the\n"
+    "fileno() method, or an integer describing a file descriptor.";
 
 PyTypeObject PyHashes_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
diff --git a/python/indexfile.cc b/python/indexfile.cc
index c6d0b1cc..037be210 100644
--- a/python/indexfile.cc
+++ b/python/indexfile.cc
@@ -27,7 +27,9 @@ static PyObject *IndexFileArchiveURI(PyObject *Self,PyObject *Args)
 
 static PyMethodDef IndexFileMethods[] =
 {
-   {"archive_uri",IndexFileArchiveURI,METH_VARARGS,"Returns the ArchiveURI"},
+   {"archive_uri",IndexFileArchiveURI,METH_VARARGS,
+    "archive_uri(path: str) -> str\n\n"
+    "Return the URI to the given path in the archive."},
    {}
 };
 
@@ -39,16 +41,16 @@ static PyObject *IndexFileGetDescribe(PyObject *Self,void*) {
    return Safe_FromString(File->Describe().c_str());
 }
 static PyObject *IndexFileGetExists(PyObject *Self,void*) {
-   return Py_BuildValue("i",(File->Exists()));
+   return PyBool_FromLong((File->Exists()));
 }
 static PyObject *IndexFileGetHasPackages(PyObject *Self,void*) {
-   return Py_BuildValue("i",(File->HasPackages()));
+   return PyBool_FromLong((File->HasPackages()));
 }
 static PyObject *IndexFileGetSize(PyObject *Self,void*) {
    return Py_BuildValue("i",(File->Size()));
 }
 static PyObject *IndexFileGetIsTrusted(PyObject *Self,void*) {
-   return Py_BuildValue("i",(File->IsTrusted()));
+   return PyBool_FromLong((File->IsTrusted()));
 }
 #undef File
 
@@ -67,15 +69,26 @@ static PyObject *IndexFileRepr(PyObject *Self)
 #undef S
 
 static PyGetSetDef IndexFileGetSet[] = {
-    {"describe",IndexFileGetDescribe},
-    {"exists",IndexFileGetExists},
-    {"has_packages",IndexFileGetHasPackages},
-    {"is_trusted",IndexFileGetIsTrusted},
-    {"label",IndexFileGetLabel},
-    {"size",IndexFileGetSize},
+    {"describe",IndexFileGetDescribe,0,
+     "A string describing the index file."},
+    {"exists",IndexFileGetExists,0,
+     "A boolean value determining whether the index file exists."},
+    {"has_packages",IndexFileGetHasPackages,0,
+     "A boolean value determining whether the index file has packages."},
+    {"is_trusted",IndexFileGetIsTrusted,0,
+     "A boolean value determining whether the file can be trusted; e.g.\n"
+     "because it is from a source with a GPG signed Release file."},
+    {"label",IndexFileGetLabel,0,
+     "The label of the index file."},
+    {"size",IndexFileGetSize,0,
+     "The size of the files, measured in bytes."},
     {}
 };
 
+static const char *indexfile_doc =
+    "Represent an index file, i.e. package indexes, translation indexes,\n"
+    "and source indexes.";
+
 PyTypeObject PyIndexFile_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -100,7 +113,7 @@ PyTypeObject PyIndexFile_Type =
    0,                                   // tp_setattro
    0,                                   // tp_as_buffer
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, // tp_flags
-   "IndexFile Object",               // tp_doc
+   indexfile_doc,                       // tp_doc
    CppTraverse<pkgIndexFile*>,     // tp_traverse
    CppClear<pkgIndexFile*>,        // tp_clear
    0,                                   // tp_richcompare
diff --git a/python/indexrecords.cc b/python/indexrecords.cc
index 80960160..d6a3263c 100644
--- a/python/indexrecords.cc
+++ b/python/indexrecords.cc
@@ -41,12 +41,14 @@ static PyObject *indexrecords_load(PyObject *self,PyObject *args)
     if (PyArg_ParseTuple(args, "s", &filename) == 0)
         return 0;
     indexRecords *records = GetCpp<indexRecords*>(self);
-    return HandleErrors(Py_BuildValue("i", records->Load(filename)));
+    return HandleErrors(PyBool_FromLong(records->Load(filename)));
 }
 
-static char *indexrecords_lookup_doc = "lookup(metakey)\n\n"
-    "Lookup the filename given by metakey, return a tuple (hash, size).\n"
-    "The hash part is a HashString() object.";
+static char *indexrecords_lookup_doc =
+    "lookup(key: str) -> (HashString, int)\n\n"
+    "Look up the filename given by 'key' and return a tuple (hash, size),\n"
+    "where the first element 'hash' is an apt_pkg.HashString object\n"
+    "and the second element 'size' is an int object.";
 static PyObject *indexrecords_lookup(PyObject *self,PyObject *args)
 {
     const char *keyname;
@@ -74,15 +76,17 @@ static PyObject *indexrecords_get_dist(PyObject *self)
 
 static PyMethodDef indexrecords_methods[] = {
     {"load",indexrecords_load,METH_VARARGS,
-     "load(filename: str)\n\nLoad the file given by filename."},
+     "load(filename: str)\n\n"
+     "Load the file given by filename."},
     {"get_dist",(PyCFunction)indexrecords_get_dist,METH_NOARGS,
-     "get_dist() -> str\n\nReturn a distribution set in the release file."},
+     "get_dist() -> str\n\n"
+     "Return a distribution set in the release file."},
     {"lookup",indexrecords_lookup,METH_VARARGS,indexrecords_lookup_doc},
     {}
 };
 
 static char *indexrecords_doc = "IndexRecords()\n\n"
-    "Representation of a release file.";
+    "Representation of a Release file.";
 PyTypeObject PyIndexRecords_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
     "apt_pkg.IndexRecords",              // tp_name
diff --git a/python/lock.cc b/python/lock.cc
index fc78c0cb..2c957df1 100644
--- a/python/lock.cc
+++ b/python/lock.cc
@@ -78,11 +78,11 @@ static char *systemlock_doc = "SystemLock()\n\n"
     "Context manager for locking the package system. The lock is established\n"
     "as soon as the method __enter__() is called. It is released when\n"
     "__exit__() is called.\n\n"
-    "This should be used via the 'with' statement, e.g.::\n\n"
+    "This should be used via the 'with' statement, for example:\n\n"
     "   with apt_pkg.SystemLock():\n"
     "       ...\n\n"
     "Once the block is left, the lock is released automatically. The object\n"
-    "can be used multiple times::\n\n"
+    "can be used multiple times:\n\n"
     "   lock = apt_pkg.SystemLock()\n"
     "   with lock:\n"
     "       ...\n"
@@ -210,11 +210,11 @@ static char *filelock_doc = "SystemLock(filename: str)\n\n"
     "Context manager for locking using a file. The lock is established\n"
     "as soon as the method __enter__() is called. It is released when\n"
     "__exit__() is called.\n\n"
-    "This should be used via the 'with' statement, e.g.::\n\n"
+    "This should be used via the 'with' statement, for example:\n\n"
     "   with apt_pkg.FileLock(filename):\n"
     "       ...\n\n"
     "Once the block is left, the lock is released automatically. The object\n"
-    "can be used multiple times::\n\n"
+    "can be used multiple times:\n\n"
     "   lock = apt_pkg.FileLock(filename)\n"
     "   with lock:\n"
     "       ...\n"
diff --git a/python/metaindex.cc b/python/metaindex.cc
index 2dcade7d..a00cf04e 100644
--- a/python/metaindex.cc
+++ b/python/metaindex.cc
@@ -27,7 +27,7 @@ static PyObject *MetaIndexGetDist(PyObject *Self,void*) {
 
 static PyObject *MetaIndexGetIsTrusted(PyObject *Self,void*) {
     metaIndex *meta = GetCpp<metaIndex*>(Self);
-    return Py_BuildValue("i",(meta->IsTrusted()));
+    return PyBool_FromLong((meta->IsTrusted()));
 }
 
 static PyObject *MetaIndexGetIndexFiles(PyObject *Self,void*) {
@@ -48,10 +48,13 @@ static PyObject *MetaIndexGetIndexFiles(PyObject *Self,void*) {
 }
 
 static PyGetSetDef MetaIndexGetSet[] = {
-   {"dist",MetaIndexGetDist},
-   {"index_files",MetaIndexGetIndexFiles},
-   {"is_trusted",MetaIndexGetIsTrusted},
-   {"uri",MetaIndexGetURI},
+   {"dist",MetaIndexGetDist,0,"The distribution, as a string."},
+   {"index_files",MetaIndexGetIndexFiles,0,
+    "A list of all IndexFile objects associated with this meta index."},
+   {"is_trusted",MetaIndexGetIsTrusted,0,
+    "A boolean value determining whether the file can be trusted."},
+   {"uri",MetaIndexGetURI,0,
+    "The uri the meta index is located at."},
    {}
 };
 
@@ -66,6 +69,11 @@ static PyObject *MetaIndexRepr(PyObject *Self)
 }
 #undef S
 
+
+static const char *metaindex_doc =
+    "Provide information on meta-indexes (i.e. Release files), such as\n"
+    "whether they are trusted or their URI.";
+    
 PyTypeObject PyMetaIndex_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -89,7 +97,7 @@ PyTypeObject PyMetaIndex_Type =
    0,                                      // tp_setattro
    0,                                      // tp_as_buffer
    Py_TPFLAGS_DEFAULT,                     // tp_flags
-   "apt_pkg.MetaIndex Object",             // tp_doc
+   metaindex_doc,                          // tp_doc
    0,                                      // tp_traverse
    0,                                      // tp_clear
    0,                                      // tp_richcompare
diff --git a/python/pkgmanager.cc b/python/pkgmanager.cc
index e8346b3d..df66c8c7 100644
--- a/python/pkgmanager.cc
+++ b/python/pkgmanager.cc
@@ -66,7 +66,7 @@ static PyObject *PkgManagerGetArchives(PyObject *Self,PyObject *Args)
    bool res = pm->GetArchives(s_fetcher, s_list,
 			      &s_records.Records);
 
-   return HandleErrors(Py_BuildValue("b",res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
 static PyObject *PkgManagerDoInstall(PyObject *Self,PyObject *Args)
@@ -93,18 +93,35 @@ static PyObject *PkgManagerFixMissing(PyObject *Self,PyObject *Args)
 
    bool res = pm->FixMissing();
 
-   return HandleErrors(Py_BuildValue("b",res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
 static PyMethodDef PkgManagerMethods[] =
 {
-   {"get_archives",PkgManagerGetArchives,METH_VARARGS,"Load the selected archives into the fetcher"},
-   {"do_install",PkgManagerDoInstall,METH_VARARGS,"Do the actual install"},
-   {"fix_missing",PkgManagerFixMissing,METH_VARARGS,"Fix the install if a pkg couldn't be downloaded"},
+   {"get_archives",PkgManagerGetArchives,METH_VARARGS,
+    "get_archives(fetcher: Acquire, list: SourceList, recs: PackageRecords) -> bool\n\n"
+    "Download the packages marked for installation via the Acquire object\n"
+    "'fetcher', using the information found in 'list' and 'recs'."},
+   {"do_install",PkgManagerDoInstall,METH_VARARGS,
+    "do_install(status_fd: int) -> int\n\n"
+    "Install the packages and return one of the class constants\n"
+    "RESULT_COMPLETED, RESULT_FAILED, RESULT_INCOMPLETE. The argument\n"
+    "status_fd can be used to specify a file descriptor that APT will\n"
+    "write status information on (see README.progress-reporting in the\n"
+    "apt source code for information on what will be written there)."},
+   {"fix_missing",PkgManagerFixMissing,METH_VARARGS,
+    "fix_missing() -> bool\n\n"
+    "Fix the installation if a package could not be downloaded."},
    {}
 };
 
 
+static const char *packagemanager_doc =
+    "PackageManager(depcache: apt_pkg.DepCache)\n\n"
+    "PackageManager objects allow the fetching of packages marked for\n"
+    "installation and the installation of those packages. The parameter\n"
+    "'depcache' specifies an apt_pkg.DepCache object where information\n"
+    "about the package selections is retrieved from.";
 PyTypeObject PyPackageManager_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -129,7 +146,7 @@ PyTypeObject PyPackageManager_Type =
    0,                                   // tp_as_buffer
    (Py_TPFLAGS_DEFAULT |                // tp_flags
     Py_TPFLAGS_BASETYPE),
-   "PackageManager Object",             // tp_doc
+   packagemanager_doc,                  // tp_doc
    0,                                   // tp_traverse
    0,                                   // tp_clear
    0,                                   // tp_richcompare
diff --git a/python/pkgrecords.cc b/python/pkgrecords.cc
index 916a2e0f..efa99b62 100644
--- a/python/pkgrecords.cc
+++ b/python/pkgrecords.cc
@@ -44,12 +44,14 @@ static PyObject *PkgRecordsLookup(PyObject *Self,PyObject *Args)
    Struct.Last = &Struct.Records.Lookup(pkgCache::VerFileIterator(*Cache,Cache->VerFileP+Index));
 
    // always return true (to make it consistent with the pkgsrcrecords object
-   return Py_BuildValue("i", 1);
+   return PyBool_FromLong(1);
 }
 
 static PyMethodDef PkgRecordsMethods[] =
 {
-   {"lookup",PkgRecordsLookup,METH_VARARGS,"Changes to a new package"},
+   {"lookup",PkgRecordsLookup,METH_VARARGS,
+    "lookup((packagefile: apt_pkg.PackageFile, index: int)) -> bool\n\n"
+    "Changes to a new package"},
    {}
 };
 
@@ -117,18 +119,35 @@ static PyObject *PkgRecordsGetRecord(PyObject *Self,void*) {
    return PyString_FromStringAndSize(start,stop-start);
 }
 static PyGetSetDef PkgRecordsGetSet[] = {
-   {"filename",PkgRecordsGetFileName},
-   {"homepage",PkgRecordsGetHomepage},
-   {"long_desc",PkgRecordsGetLongDesc},
-   {"md5_hash",PkgRecordsGetMD5Hash},
-   {"maintainer",PkgRecordsGetMaintainer},
-   {"name",PkgRecordsGetName},
-   {"record",PkgRecordsGetRecord},
-   {"sha1_hash",PkgRecordsGetSHA1Hash},
-   {"sha256_hash",PkgRecordsGetSHA256Hash},
-   {"short_desc",PkgRecordsGetShortDesc},
-   {"source_pkg",PkgRecordsGetSourcePkg},
-   {"source_ver",PkgRecordsGetSourceVer},
+   {"filename",PkgRecordsGetFileName,0,
+    "The filename of the package, as stored in the 'Filename' field."},
+   {"homepage",PkgRecordsGetHomepage,0,
+    "The homepage of the package, as stored in the 'Homepage' field."},
+   {"long_desc",PkgRecordsGetLongDesc,0,
+    "The long description of the packages; i.e. all lines in the\n"
+    "'Description' field except for the first one."},
+   {"md5_hash",PkgRecordsGetMD5Hash,0,
+    "The MD5 hash value of the package, as stored in the 'MD5Sum' field."},
+   {"maintainer",PkgRecordsGetMaintainer,0,
+    "The maintainer of the package, as stored in the 'Maintainer' field."},
+   {"name",PkgRecordsGetName,0,
+    "The name of the package, as stored in the 'Package' field."},
+   {"record",PkgRecordsGetRecord,0,
+    "The raw record, suitable for parsing by apt_pkg.TagSection."},
+   {"sha1_hash",PkgRecordsGetSHA1Hash,0,
+    "The SHA1 hash value, as stored in the 'SHA1' field."},
+   {"sha256_hash",PkgRecordsGetSHA256Hash,0,
+    "The SHA256 hash value, as stored in the 'SHA256' field."},
+   {"short_desc",PkgRecordsGetShortDesc,0,
+    "The short description of the package, i.e. the first line of the\n"
+    "'Description' field."},
+   {"source_pkg",PkgRecordsGetSourcePkg,0,
+    "The name of the source package, if different from the name of the\n"
+    "binary package. This information is retrieved from the 'Source' field."},
+   {"source_ver",PkgRecordsGetSourceVer,0,
+    "The version of the source package, if it differs from the version\n"
+    "of the binary package. Just like 'source_pkg', this information\n"
+    "is retrieved from the 'Source' field."},
    {}
 };
 
@@ -144,6 +163,13 @@ static PyObject *PkgRecordsNew(PyTypeObject *type,PyObject *Args,PyObject *kwds)
 							      GetCpp<pkgCache *>(Owner)));
 }
 
+static const char *packagerecords_doc =
+    "PackageRecords(cache: apt_pkg.Cache)\n\n"
+    "Package Records contain information about packages. Those objects\n"
+    "can be used to retrieve information such as maintainer or filename\n"
+    "of a package. They can also be used to retrieve the raw records\n"
+    "of the packages (i.e. those stanzas stored in Packages files).";
+
 PyTypeObject PyPackageRecords_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -169,9 +195,9 @@ PyTypeObject PyPackageRecords_Type =
    (Py_TPFLAGS_DEFAULT |                // tp_flags
     Py_TPFLAGS_BASETYPE |
     Py_TPFLAGS_HAVE_GC),
-   "Records Object",                    // tp_doc
-   CppTraverse<PkgRecordsStruct>,  // tp_traverse
-   CppClear<PkgRecordsStruct>,     // tp_clear
+   packagerecords_doc,                  // tp_doc
+   CppTraverse<PkgRecordsStruct>,       // tp_traverse
+   CppClear<PkgRecordsStruct>,          // tp_clear
    0,                                   // tp_richcompare
    0,                                   // tp_weaklistoffset
    0,                                   // tp_iter
diff --git a/python/pkgsrcrecords.cc b/python/pkgsrcrecords.cc
index 729a74b5..da3d0e04 100644
--- a/python/pkgsrcrecords.cc
+++ b/python/pkgsrcrecords.cc
@@ -34,7 +34,12 @@ struct PkgSrcRecordsStruct
 // PkgSrcRecords Class							/*{{{*/
 // ---------------------------------------------------------------------
 
-static char *doc_PkgSrcRecordsLookup = "xxx";
+static char *doc_PkgSrcRecordsLookup =
+    "lookup(name: str) -> bool\n\n"
+    "Look up the source package with the given name. Each call moves\n"
+    "the position of the records parser forward. If there are no\n"
+    "more records, return None. If the lookup failed this way,\n"
+    "access to any of the attributes will result in an AttributeError.";
 static PyObject *PkgSrcRecordsLookup(PyObject *Self,PyObject *Args)
 {
    PkgSrcRecordsStruct &Struct = GetCpp<PkgSrcRecordsStruct>(Self);
@@ -50,10 +55,13 @@ static PyObject *PkgSrcRecordsLookup(PyObject *Self,PyObject *Args)
       return HandleErrors(Py_None);
    }
 
-   return Py_BuildValue("i", 1);
+   return PyBool_FromLong(1);
 }
 
-static char *doc_PkgSrcRecordsRestart = "Start Lookup from the beginning";
+static char *doc_PkgSrcRecordsRestart =
+    "restart()\n\n"
+    "Restart the lookup process. This moves the parser to the first\n"
+    "package and lookups can now be made just like on a new object.";
 static PyObject *PkgSrcRecordsRestart(PyObject *Self,PyObject *Args)
 {
    PkgSrcRecordsStruct &Struct = GetCpp<PkgSrcRecordsStruct>(Self);
@@ -220,15 +228,27 @@ static PyObject *PkgSrcRecordsGetBuildDepends_old(PyObject *Self,void*) {
 #endif
 
 static PyGetSetDef PkgSrcRecordsGetSet[] = {
-   {"binaries",PkgSrcRecordsGetBinaries},
-   {"build_depends",PkgSrcRecordsGetBuildDepends},
-   {"files",PkgSrcRecordsGetFiles},
-   {"index",PkgSrcRecordsGetIndex},
-   {"maintainer",PkgSrcRecordsGetMaintainer},
-   {"package",PkgSrcRecordsGetPackage},
-   {"record",PkgSrcRecordsGetRecord},
-   {"section",PkgSrcRecordsGetSection},
-   {"version",PkgSrcRecordsGetVersion},
+   {"binaries",PkgSrcRecordsGetBinaries,0,
+    "A list of the names of the binaries produced by this source package."},
+   {"build_depends",PkgSrcRecordsGetBuildDepends,0,
+    "A dictionary describing the build-time dependencies of the package;\n"
+    "the format is the same as used for apt_pkg.Version.depends_list_str."},
+   {"files",PkgSrcRecordsGetFiles,0,
+    "A list of tuples (md5: str, size: int, path: str, type: str), whereas\n"
+    "'type' can be 'diff' (includes .debian.tar.gz), 'dsc', 'tar'."},
+   {"index",PkgSrcRecordsGetIndex,0,
+    "The index file associated with this record as a list of\n"
+    "apt_pkg.IndexFile objects."},
+   {"maintainer",PkgSrcRecordsGetMaintainer,0,
+    "The maintainer of the package."},
+   {"package",PkgSrcRecordsGetPackage,0,
+    "The name of the source package."},
+   {"record",PkgSrcRecordsGetRecord,0,
+    "The raw record, suitable for parsing using apt_pkg.TagSection."},
+   {"section",PkgSrcRecordsGetSection,0,
+    "The section of the source package."},
+   {"version",PkgSrcRecordsGetVersion,0,
+    "The version of the source package."},
 #ifdef COMPAT_0_7
    {"BuildDepends",PkgSrcRecordsGetBuildDepends_old,0,"Deprecated function and deprecated output format."},
 #endif
@@ -243,6 +263,11 @@ static PyObject *PkgSrcRecordsNew(PyTypeObject *type,PyObject *args,PyObject *kw
    return HandleErrors(CppPyObject_NEW<PkgSrcRecordsStruct>(NULL, type));
 }
 
+static const char *sourcerecords_doc =
+    "SourceRecords()\n\n"
+    "Provide an easy way to look up the records of source packages and\n"
+    "provide easy attributes for some widely used fields of the record.";
+
 PyTypeObject PySourceRecords_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -267,7 +292,7 @@ PyTypeObject PySourceRecords_Type =
    0,                                   // tp_as_buffer
    (Py_TPFLAGS_DEFAULT |                // tp_flags
     Py_TPFLAGS_BASETYPE),
-   "SourceRecords Object",              // tp_doc
+   sourcerecords_doc,                   // tp_doc
    0,                                   // tp_traverse
    0,                                   // tp_clear
    0,                                   // tp_richcompare
diff --git a/python/policy.cc b/python/policy.cc
index 3e1ec589..7eccb30c 100644
--- a/python/policy.cc
+++ b/python/policy.cc
@@ -37,8 +37,8 @@ static PyObject *policy_new(PyTypeObject *type,PyObject *Args,
     return CppPyObject_NEW<pkgPolicy*>(cache,&PyPolicy_Type,policy);
 }
 
-static char *policy_get_priority_doc = "get_priority(package: apt_pkg.Package)"
-    " -> int\n\n"
+static char *policy_get_priority_doc =
+    "get_priority(package: apt_pkg.Package) -> int\n\n"
     "Return the priority of the package.";
 
 PyObject *policy_get_priority(PyObject *self, PyObject *arg) {
@@ -52,8 +52,8 @@ PyObject *policy_get_priority(PyObject *self, PyObject *arg) {
     }
 }
 
-static char *policy_get_candidate_ver_doc = "get_match(package: apt_pkg.Package)"
-    " -> apt_pkg.Version\n\n"
+static char *policy_get_candidate_ver_doc =
+    "get_match(package: apt_pkg.Package) -> apt_pkg.Version\n\n"
     "Get the best package for the job.";
 
 PyObject *policy_get_candidate_ver(PyObject *self, PyObject *arg) {
@@ -69,8 +69,8 @@ PyObject *policy_get_candidate_ver(PyObject *self, PyObject *arg) {
     }
 }
 
-static char *policy_get_match_doc = "get_match(package: apt_pkg.Package) -> "
-    "apt_pkg.Version\n\n"
+static char *policy_get_match_doc =
+    "get_match(package: apt_pkg.Package) -> apt_pkg.Version\n\n"
     "Return a matching version for the given package.";
 
 static PyObject *policy_get_match(PyObject *self, PyObject *arg) {
@@ -84,9 +84,10 @@ static PyObject *policy_get_match(PyObject *self, PyObject *arg) {
     return CppPyObject_NEW<pkgCache::VerIterator>(arg,&PyVersion_Type,ver);
 }
 
-static char *policy_read_pinfile_doc = "read_pinfile(filename: str) -> bool\n\n"
-    "Read the pin file given by filename (e.g. '/etc/apt/preferences') and\n"
-    "add it to the policy.";
+static char *policy_read_pinfile_doc =
+    "read_pinfile(filename: str) -> bool\n\n"
+    "Read the pin file given by filename (e.g. '/etc/apt/preferences')\n"
+    "and add it to the policy.";
 
 static PyObject *policy_read_pinfile(PyObject *self, PyObject *arg) {
     if (!PyString_Check(arg))
@@ -97,9 +98,10 @@ static PyObject *policy_read_pinfile(PyObject *self, PyObject *arg) {
 }
 
 #if (APT_PKG_MAJOR >= 4 && APT_PKG_MINOR >= 8)
-static char *policy_read_pindir_doc = "read_pindir(dirname: str) -> bool\n\n"
-    "Read the pin files in the given dir (e.g. '/etc/apt/preferences.d') and\n"
-    "add them to the policy.";
+static char *policy_read_pindir_doc =
+    "read_pindir(dirname: str) -> bool\n\n"
+    "Read the pin files in the given dir (e.g. '/etc/apt/preferences.d')\n"
+    "and add them to the policy.";
 
 static PyObject *policy_read_pindir(PyObject *self, PyObject *arg) {
     if (!PyString_Check(arg))
@@ -110,12 +112,12 @@ static PyObject *policy_read_pindir(PyObject *self, PyObject *arg) {
 }
 #endif
 
-static char *policy_create_pin_doc = "create_pin(type: str, pkg: str, "
-    "data: str, priority: int)\n\n"
+static char *policy_create_pin_doc =
+    "create_pin(type: str, pkg: str, data: str, priority: int)\n\n"
     "Create a pin for the policy. The parameter 'type' refers to one of the\n"
-    "following strings: 'Version', 'Release', 'Origin'. The argument 'pkg'\n"
-    "is the name of the package, the parameter 'data' refers to the value\n"
-    "e.g. unstable for type='Release' and the other possible options. \n"
+    "strings 'Version', 'Release', or 'Origin'. The argument 'pkg' is the\n"
+    "name of the package. The parameter 'data' refers to the value\n"
+    "(e.g. 'unstable' for type='Release') and the other possible options.\n"
     "The parameter 'priority' gives the priority of the pin.";
 
 static PyObject *policy_create_pin(PyObject *self, PyObject *args) {
@@ -154,7 +156,8 @@ static PyMethodDef policy_methods[] = {
     {}
 };
 
-static char *policy_doc = "Policy(cache)\n\n"
+static char *policy_doc =
+    "Policy(cache)\n\n"
     "Representation of the policy of the Cache object given by cache. This\n"
     "provides a superset of policy-related functionality compared to the\n"
     "DepCache class. The DepCache can be used for most purposes, but there\n"
diff --git a/python/progress.cc b/python/progress.cc
index 18081690..9002b3eb 100644
--- a/python/progress.cc
+++ b/python/progress.cc
@@ -501,9 +501,7 @@ pkgPackageManager::OrderResult PyInstallProgress::Run(pkgPackageManager *pm)
       else
           method = PyObject_GetAttrString(callbackInst, "wait_child");
       //std::cerr << "custom waitChild found" << std::endl;
-      PyObject *arglist = Py_BuildValue("(i)",child_id);
-      PyObject *result = PyObject_CallObject(method, arglist);
-      Py_DECREF(arglist);
+      PyObject *result = PyObject_CallObject(method, NULL);
       if (result == NULL) {
 	 std::cerr << "waitChild method invalid" << std::endl;
 	 PyErr_Print();
diff --git a/python/sourcelist.cc b/python/sourcelist.cc
index 5a950b2c..b04bf5cb 100644
--- a/python/sourcelist.cc
+++ b/python/sourcelist.cc
@@ -21,7 +21,10 @@
 // PkgsourceList Class							/*{{{*/
 // ---------------------------------------------------------------------
 
-static char *doc_PkgSourceListFindIndex = "xxx";
+static char *doc_PkgSourceListFindIndex =
+    "find_index(pkgfile: apt_pkg.PackageFile) -> apt_pkg.IndexFile\n\n"
+    "Return the index file for the given package file, or None if none\n"
+    "could be found.";
 static PyObject *PkgSourceListFindIndex(PyObject *Self,PyObject *Args)
 {
    pkgSourceList *list = GetCpp<pkgSourceList*>(Self);
@@ -47,16 +50,23 @@ static PyObject *PkgSourceListFindIndex(PyObject *Self,PyObject *Args)
    return Py_None;
 }
 
-static char *doc_PkgSourceListReadMainList = "xxx";
+static char *doc_PkgSourceListReadMainList =
+    "read_main_list() -> bool\n\n"
+    "Read /etc/apt/sources.list and similar files to populate the list\n"
+    "of indexes.";
 static PyObject *PkgSourceListReadMainList(PyObject *Self,PyObject *Args)
 {
    pkgSourceList *list = GetCpp<pkgSourceList*>(Self);
    bool res = list->ReadMainList();
 
-   return HandleErrors(Py_BuildValue("b",res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
-static char *doc_PkgSourceListGetIndexes = "Load the indexes into the fetcher";
+static char *doc_PkgSourceListGetIndexes =
+    "get_indexes(acquire: apt_pkg.Acquire[, all: bool=False]) -> bool\n\n"
+    "Add all indexes (i.e. stuff like Release files, Packages files)\n"
+    "to the Acquire object 'acquire'. If 'all' is True, all indexes\n"
+    "will be added, otherwise only changed indexes will be added.";
 static PyObject *PkgSourceListGetIndexes(PyObject *Self,PyObject *Args)
 {
    pkgSourceList *list = GetCpp<pkgSourceList*>(Self);
@@ -69,7 +79,7 @@ static PyObject *PkgSourceListGetIndexes(PyObject *Self,PyObject *Args)
    pkgAcquire *fetcher = GetCpp<pkgAcquire*>(pyFetcher);
    bool res = list->GetIndexes(fetcher, all);
 
-   return HandleErrors(Py_BuildValue("b",res));
+   return HandleErrors(PyBool_FromLong(res));
 }
 
 static PyMethodDef PkgSourceListMethods[] =
@@ -110,6 +120,10 @@ static PyObject *PkgSourceListNew(PyTypeObject *type,PyObject *args,PyObject *kw
    return CppPyObject_NEW<pkgSourceList*>(NULL, type,new pkgSourceList());
 }
 
+static const char *sourcelist_doc =
+    "SourceList()\n\n"
+    "Represent the list of sources stored in /etc/apt/sources.list and\n"
+    "similar files.";
 PyTypeObject PySourceList_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -134,7 +148,7 @@ PyTypeObject PySourceList_Type =
    0,                                   // tp_as_buffer
    (Py_TPFLAGS_DEFAULT |                // tp_flags
     Py_TPFLAGS_BASETYPE),
-   "pkgSourceList Object",              // tp_doc
+   sourcelist_doc,                      // tp_doc
    0,                                   // tp_traverse
    0,                                   // tp_clear
    0,                                   // tp_richcompare
diff --git a/python/string.cc b/python/string.cc
index b95ee3eb..6a1ce4e2 100644
--- a/python/string.cc
+++ b/python/string.cc
@@ -116,7 +116,7 @@ PyObject *StrCheckDomainList(PyObject *Self,PyObject *Args)
    char *List = 0;
    if (PyArg_ParseTuple(Args,"ss",&Host,&List) == 0)
       return 0;
-   return Py_BuildValue("i",CheckDomainList(Host,List));
+   return PyBool_FromLong(CheckDomainList(Host,List));
 }
 
 									/*}}}*/
diff --git a/python/tag.cc b/python/tag.cc
index bc470620..5db34c1d 100644
--- a/python/tag.cc
+++ b/python/tag.cc
@@ -89,7 +89,10 @@ void TagFileFree(PyObject *Obj)
 									/*}}}*/
 
 // Tag Section Wrappers							/*{{{*/
-static char *doc_Find = "Find(Name) -> String/None";
+static char *doc_Find =
+    "find(name: str[, default = None]) -> str\n\n"
+    "Find the key given by 'name' and return the value. If the key can\n"
+    "not be found, return 'default'.";
 static PyObject *TagSecFind(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -108,7 +111,10 @@ static PyObject *TagSecFind(PyObject *Self,PyObject *Args)
    return PyString_FromStringAndSize(Start,Stop-Start);
 }
 
-static char *doc_FindRaw = "FindRaw(Name) -> String/None";
+static char *doc_FindRaw =
+    "find_raw(name: str[, default = None] -> str\n\n"
+    "Same as find(), but returns the complete 'key: value' field; instead of\n"
+    "just the value.";
 static PyObject *TagSecFindRaw(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -131,7 +137,11 @@ static PyObject *TagSecFindRaw(PyObject *Self,PyObject *Args)
    return PyString_FromStringAndSize(Start,Stop-Start);
 }
 
-static char *doc_FindFlag = "FindFlag(Name) -> integer/none";
+static char *doc_FindFlag =
+    "find_flag(name: str) -> int\n\n"
+    "Return 1 if the key's value is 'yes' or a similar value describing\n"
+    "a boolean true. If the field does not exist, or does not have such a\n"
+    "value, return 0.";
 static PyObject *TagSecFindFlag(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -144,7 +154,7 @@ static PyObject *TagSecFindFlag(PyObject *Self,PyObject *Args)
       Py_INCREF(Py_None);
       return Py_None;
    }
-   return Py_BuildValue("i",Flag);
+   return PyBool_FromLong(Flag);
 }
 
 // Map access, operator []
@@ -175,7 +185,9 @@ static Py_ssize_t TagSecLength(PyObject *Self)
 }
 
 // Look like a mapping
-static char *doc_Keys = "keys() -> List";
+static char *doc_Keys =
+    "keys() -> list\n\n"
+    "Return a list of all keys.";
 static PyObject *TagSecKeys(PyObject *Self,PyObject *Args)
 {
    pkgTagSection &Tags = GetCpp<pkgTagSection>(Self);
@@ -200,7 +212,9 @@ static PyObject *TagSecKeys(PyObject *Self,PyObject *Args)
 }
 
 #if PY_MAJOR_VERSION < 3
-static char *doc_Exists = "Exists(Name) -> integer";
+static char *doc_Exists =
+    "has_key(name: str) -> bool\n\n"
+    "Return True if the key given by 'name' exists, False otherwise.";
 static PyObject *TagSecExists(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -209,9 +223,7 @@ static PyObject *TagSecExists(PyObject *Self,PyObject *Args)
 
    const char *Start;
    const char *Stop;
-   if (GetCpp<pkgTagSection>(Self).Find(Name,Start,Stop) == false)
-      return Py_BuildValue("i",0);
-   return Py_BuildValue("i",1);
+   return PyBool_FromLong(GetCpp<pkgTagSection>(Self).Find(Name,Start,Stop));
 }
 #endif
 
@@ -227,7 +239,9 @@ static int TagSecContains(PyObject *Self,PyObject *Arg)
    return 1;
 }
 
-static char *doc_Bytes = "Bytes() -> integer";
+static char *doc_Bytes =
+    "bytes() -> int\n\n"
+    "Return the number of bytes this section is large.";
 static PyObject *TagSecBytes(PyObject *Self,PyObject *Args)
 {
    if (PyArg_ParseTuple(Args,"") == 0)
@@ -245,7 +259,9 @@ static PyObject *TagSecStr(PyObject *Self)
 }
 									/*}}}*/
 // TagFile Wrappers							/*{{{*/
-static char *doc_Step = "Step() -> Integer\n0 means EOF.";
+static char *doc_Step =
+    "step() -> bool\n\n"
+    "Step forward in the file";
 static PyObject *TagFileStep(PyObject *Self,PyObject *Args)
 {
    if (PyArg_ParseTuple(Args,"") == 0)
@@ -253,9 +269,9 @@ static PyObject *TagFileStep(PyObject *Self,PyObject *Args)
 
    TagFileData &Obj = *(TagFileData *)Self;
    if (Obj.Object.Step(Obj.Section->Object) == false)
-      return HandleErrors(Py_BuildValue("i",0));
+      return HandleErrors(PyBool_FromLong(0));
 
-   return HandleErrors(Py_BuildValue("i",1));
+   return HandleErrors(PyBool_FromLong(1));
 }
 
 // TagFile Wrappers							/*{{{*/
@@ -296,7 +312,9 @@ static PyObject *TagFileIter(PyObject *Self) {
     return Self;
 }
 
-static char *doc_Offset = "Offset() -> Integer";
+static char *doc_Offset =
+    "offset() -> int\n\n"
+    "Return the current offset.";
 static PyObject *TagFileOffset(PyObject *Self,PyObject *Args)
 {
    if (PyArg_ParseTuple(Args,"") == 0)
@@ -304,7 +322,11 @@ static PyObject *TagFileOffset(PyObject *Self,PyObject *Args)
    return Py_BuildValue("i",((TagFileData *)Self)->Object.Offset());
 }
 
-static char *doc_Jump = "Jump(Offset) -> Integer";
+static char *doc_Jump =
+    "jump(offset: int) -> bool\n\n"
+    "Jump to the given offset; return True on success. Note that jumping to\n"
+    "an offset is not very reliable, and the 'section' attribute may point\n"
+    "to an unexpected section.";
 static PyObject *TagFileJump(PyObject *Self,PyObject *Args)
 {
    int Offset;
@@ -313,9 +335,9 @@ static PyObject *TagFileJump(PyObject *Self,PyObject *Args)
 
    TagFileData &Obj = *(TagFileData *)Self;
    if (Obj.Object.Jump(Obj.Section->Object,Offset) == false)
-      return HandleErrors(Py_BuildValue("i",0));
+      return HandleErrors(PyBool_FromLong(0));
 
-   return HandleErrors(Py_BuildValue("i",1));
+   return HandleErrors(PyBool_FromLong(1));
 }
 									/*}}}*/
 // ParseSection - Parse a single section from a tag file		/*{{{*/
@@ -346,7 +368,7 @@ static PyObject *TagSecNew(PyTypeObject *type,PyObject *Args,PyObject *kwds) {
 }
 
 #ifdef COMPAT_0_7
-char *doc_ParseSection ="ParseSection(Text) -> TagSection() object. Deprecated.";
+char *doc_ParseSection = "ParseSection(Text) -> TagSection()\n\nDeprecated.";
 PyObject *ParseSection(PyObject *self,PyObject *Args)
 {
    if (getenv("PYTHON_APT_DEPRECATION_WARNINGS") != NULL)
@@ -387,7 +409,7 @@ static PyObject *TagFileNew(PyTypeObject *type,PyObject *Args,PyObject *kwds)
    return HandleErrors(New);
 }
 #ifdef COMPAT_0_7
-char *doc_ParseTagFile = "ParseTagFile(File) -> TagFile() object. Deprecated.";
+char *doc_ParseTagFile = "ParseTagFile(file) -> TagFile()\n\nDeprecated.";
 PyObject *ParseTagFile(PyObject *self,PyObject *Args) {
    if (getenv("PYTHON_APT_DEPRECATION_WARNINGS") != NULL)
       PyErr_WarnEx(PyExc_DeprecationWarning, "apt_pkg.ParseTagFile() is "
@@ -402,20 +424,19 @@ PyObject *ParseTagFile(PyObject *self,PyObject *Args) {
 /* An interesting future extension would be to add a user settable
    order list */
 char *doc_RewriteSection =
-"RewriteSection(Section,Order,RewriteList) -> String\n"
+"rewrite_section(section: TagSection, order: list, rewrite_list: list) -> str\n"
 "\n"
-"The section rewriter allows a section to be taken in, have fields added,\n"
-"removed or changed and then put back out. During this process the fields\n"
-"within the section are sorted to corrispond to a proper order. Order is a\n"
-"list of field names with their proper capitialization.\n"
-"apt_pkg.RewritePackageOrder and apt_pkg.RewriteSourceOrder are two predefined\n"
-"orders.\n"
-"RewriteList is a list of tuples. Each tuple is of the form:\n"
-"  (Tag,NewValue[,RenamedTo])\n"
-"Tag specifies the tag in the source section. NewValue is the new value of\n"
-"that tag and the optional RenamedTo field can cause the tag to be changed.\n"
-"If NewValue is None then the tag is removed\n"
-"Ex. ('Source','apt','Package') is used for .dsc files.";
+"Rewrite the section given by 'section' using 'rewrite_list', and order the\n"
+"fields according to 'order'.\n\n"
+"The parameter 'order' is a list object containing the names of the fields\n"
+"in the order they should appear in the rewritten section.\n"
+"apt_pkg.REWRITE_PACKAGE_ORDER and apt_pkg.REWRITE_SOURCE_ORDER are two\n"
+"predefined lists for rewriting package and source sections, respectively\n\n"
+"The parameter 'rewrite_list' is a list of tuples of the form\n"
+"'(tag, newvalue[, renamed_to])', where 'tag' describes the field which\n"
+"should be changed, 'newvalue' the value which should be inserted or None\n"
+"to delete the field, and the optional renamed_to can be used to rename the\n"
+"field.";
 PyObject *RewriteSection(PyObject *self,PyObject *Args)
 {
    PyObject *Section;
@@ -491,11 +512,11 @@ PySequenceMethods TagSecSeqMeth = {0,0,0,0,0,0,0,TagSecContains,0,0};
 PyMappingMethods TagSecMapMeth = {TagSecLength,TagSecMap,0};
 
 
-static char *doc_TagSec = "TagSection(text) -> Create a new object.\n\n"
-   "TagSection() objects provide methods to access rfc822-style formatted\n"
-   "header sections, like those in debian/control or Packages files.\n\n"
+static char *doc_TagSec = "TagSection(text: str)\n\n"
+   "Provide methods to access RFC822-style header sections, like those\n"
+   "found in debian/control or Packages files.\n\n"
    "TagSection() behave like read-only dictionaries and also provide access\n"
-   "to the functions provided by the C++ class (e.g. Find)";
+   "to the functions provided by the C++ class (e.g. find)";
 PyTypeObject PyTagSection_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -560,22 +581,24 @@ static PyObject *TagFileGetSection(PyObject *Self,void*) {
 }
 
 static PyGetSetDef TagFileGetSet[] = {
-    {"section",TagFileGetSection,0,"Return a TagSection.",0},
+    {"section",TagFileGetSection,0,
+     "The current section, as a TagSection object.",0},
     {}
 };
 
 
-static char *doc_TagFile = "TagFile(file) -> TagFile() object. \n\n"
-   "TagFile() objects provide access to debian control files, which consists\n"
-   "of multiple RFC822-like formatted sections.\n\n"
+static char *doc_TagFile = "TagFile(file)\n\n"
+   "TagFile() objects provide access to debian control files, which consist\n"
+   "of multiple RFC822-style sections.\n\n"
    "To provide access to those sections, TagFile objects provide an iterator\n"
    "which yields TagSection objects for each section.\n\n"
    "TagFile objects also provide another API which uses a shared TagSection\n"
    "object in the 'section' member. The functions step() and jump() can be\n"
-   "used to navigate in the file; and offset() tells the current position.\n\n"
+   "used to navigate within the file; offset() returns the current\n"
+   "position.\n\n"
    "It is important to not mix the use of both APIs, because this can have\n"
    "unwanted effects.\n\n"
-   "The parameter *file* refers to an object providing a fileno() method or\n"
+   "The parameter 'file' refers to an object providing a fileno() method or\n"
    "a file descriptor (an integer)";
 
 // Type for a Tag File
diff --git a/python/tarfile.cc b/python/tarfile.cc
index 6363af0f..215d3a8c 100644
--- a/python/tarfile.cc
+++ b/python/tarfile.cc
@@ -235,7 +235,7 @@ static PyMethodDef tarmember_methods[] = {
     {"ischr",tarmember_ischr,METH_NOARGS,
      "Determine whether the member is a character device."},
     {"isdev",tarmember_isdev,METH_NOARGS,
-     "Determine whether the member is a device (block,character or FIFO)."},
+     "Determine whether the member is a device (block, character or FIFO)."},
     {"isdir",tarmember_isdir,METH_NOARGS,
      "Determine whether the member is a directory."},
     {"isfifo",tarmember_isfifo,METH_NOARGS,
@@ -252,7 +252,7 @@ static PyMethodDef tarmember_methods[] = {
 };
 
 static PyGetSetDef tarmember_getset[] = {
-    {"gid",tarmember_get_gid,0,"The owner's group id"},
+    {"gid",tarmember_get_gid,0,"The owner's group ID."},
     {"linkname",tarmember_get_linkname,0,"The target of the link."},
     {"major",tarmember_get_major,0,"The major ID of the device."},
     {"minor",tarmember_get_minor,0,"The minor ID of the device."},
@@ -260,7 +260,7 @@ static PyGetSetDef tarmember_getset[] = {
     {"mtime",tarmember_get_mtime,0,"Last time of modification."},
     {"name",tarmember_get_name,0,"The name of the file."},
     {"size",tarmember_get_size,0,"The size of the file."},
-    {"uid",tarmember_get_uid,0,"The owner's user id."},
+    {"uid",tarmember_get_uid,0,"The owner's user ID."},
     {NULL}
 };
 
@@ -375,11 +375,11 @@ static PyObject *tarfile_extractall(PyObject *self, PyObject *args)
 
 static const char *tarfile_go_doc =
     "go(callback: callable[, member: str]) -> True\n\n"
-    "Go through the archive and call the callable callback for each\n"
+    "Go through the archive and call the callable 'callback' for each\n"
     "member with 2 arguments. The first argument is the TarMember and\n"
     "the second one is the data, as bytes.\n\n"
     "The optional parameter 'member' can be used to specify the member for\n"
-    "which call the callback. If not specified, it will be called for all\n"
+    "which to call the callback. If not specified, it will be called for all\n"
     "members. If specified and not found, LookupError will be raised.";
 static PyObject *tarfile_go(PyObject *self, PyObject *args)
 {