* 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, 106 insertions, 26 deletions

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