python: Document every class, function, property.

Finally, a complete reference to apt_pkg available
via pydoc and __doc__ attributes.

1 files changed, 123 insertions, 43 deletions

diff --git a/python/apt_pkgmodule.cc b/python/apt_pkgmodule.cc
index e2be4f1d..e7023e4a 100644
--- a/python/apt_pkgmodule.cc
+++ b/python/apt_pkgmodule.cc
@@ -63,7 +63,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;
@@ -145,7 +148,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;
@@ -154,14 +159,27 @@ 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 the form\n"
+"of tuples ``(pkg, ver, comptype)``. In this tuple, the element 'pkg' is the\n"
+"name of the package, the element 'ver' the version [or '' if no version was\n"
+"requested. The element 'ver' is a comparison operator such as <,<=,=,>=,>.";
+
+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 the form\n"
+"of tuples ``(pkg, ver, comptype)``. In this tuple, the element 'pkg' is the\n"
+"name of the package, the element 'ver' the version [or '' if no version was\n"
+"requested. The element 'ver' is a comparison operator such as <,<=,=,>=,>."
+"\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)
@@ -237,7 +255,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;
@@ -277,7 +300,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;
@@ -317,7 +345,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;
@@ -358,8 +391,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"
+"Short hand 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)
@@ -373,8 +408,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)
@@ -387,8 +422,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 underlying system.";
 static PyObject *InitSystem(PyObject *Self,PyObject *Args)
 {
    if (PyArg_ParseTuple(Args,"") == 0)
@@ -404,11 +439,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;
@@ -418,12 +455,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)
@@ -436,8 +475,8 @@ static PyObject *PkgSystemLock(PyObject *Self,PyObject *Args)
 }
 
 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)
@@ -488,7 +527,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},
@@ -496,16 +535,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"
+    "Quote the string 'string' by encoding a standard set of characters\n"
+    "plus the characters given 'repl' using their HTTP value, e.g.\n"
+    "'%20' for ' '."},
+   {"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 (e.g. ' ')."},
+   {"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 using the Base64. The input may not\n"
+    "contain '\0' (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 an Unix timestamp."},
 
    // DEPRECATED
    #ifdef COMPAT_0_7
@@ -533,7 +606,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"},
@@ -663,12 +737,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. It allows parsing of\n"
+    "index files, configuration files, installation/removal of packages and\n"
+    "much more";
+
 #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,
@@ -692,7 +772,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