python: Document every class, function, property.

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

1 files changed, 208 insertions, 72 deletions

diff --git a/python/cache.cc b/python/cache.cc
index 99d06184..ac9832e2 100644
--- a/python/cache.cc
+++ b/python/cache.cc
@@ -152,9 +152,21 @@ static PyObject *PkgCacheOpen(PyObject *Self,PyObject *Args)
 
 static PyMethodDef PkgCacheMethods[] =
 {
-   {"update",PkgCacheUpdate,METH_VARARGS,"Update the cache"},
+   {"update",PkgCacheUpdate,METH_VARARGS,
+    "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' takes an apt.progress.base.AcquireProgress\n"
+    "object as its argument which will display the progress of fetching\n"
+    "the index files. The parameter 'sources' takes an apt_pkg.SourceList\n"
+    "object which lists the sources. The parameter 'progress' takes an\n"
+    "integer describing the interval (in microseconds) in which the\n"
+    "pulse() method of the 'progress' object will be called."
+    },
 #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
    {}
@@ -208,14 +220,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,
+    "The number of provided packages."},
+   {"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."},
    {}
 };
 
@@ -440,6 +460,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)
@@ -463,7 +489,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
 };
@@ -520,19 +546,43 @@ 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"
+     "whereas 'version' is an apt_pkg.Version object."},
+    {"selected_state",PackageGetSelectedState,0,
+     "The state of the selection; 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, can 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, 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). Not used anymore."},
+    {"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."},
     {}
 };
 
@@ -546,6 +596,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)
@@ -569,7 +625,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
@@ -613,9 +669,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."},
     {}
 };
 
@@ -627,6 +687,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)
@@ -650,7 +714,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
@@ -841,22 +905,48 @@ static PyObject *VersionRepr(PyObject *Self)
 #undef NOTNULL
 
 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); whereas operator\n"
+    "is one of '<', '<=', '=', '>=', '>'."},
+   {"downloadable",VersionGetDownloadable,0,
+    "Whether the version can be downloaded."},
+   {"file_list",VersionGetFileList,0,
+    "A list of tuples (pf: 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, can be compared against\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 provides 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."},
    {}
 };
 
@@ -993,22 +1083,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 there is no source this file comes from; i.e. whether packages\n"
+   "listed in this file can not 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 is\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
@@ -1030,7 +1141,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
@@ -1094,8 +1205,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."},
    {}
 };
 
@@ -1165,18 +1281,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 =
 {
@@ -1201,7 +1333,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
@@ -1263,6 +1395,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)
@@ -1286,7 +1422,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
 };