* 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

1 files changed, 56 insertions, 24 deletions

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)