* 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, 15 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)