summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--debian/changelog1
-rw-r--r--python/acquire-item.cc60
-rw-r--r--python/acquire.cc68
-rw-r--r--python/apt_pkgmodule.cc166
-rw-r--r--python/arfile.cc19
-rw-r--r--python/cache.cc280
-rw-r--r--python/configuration.cc119
-rw-r--r--python/depcache.cc172
-rw-r--r--python/indexfile.cc29
-rw-r--r--python/indexrecords.cc16
-rw-r--r--python/metaindex.cc19
-rw-r--r--python/pkgmanager.cc25
-rw-r--r--python/pkgrecords.cc58
-rw-r--r--python/pkgsrcrecords.cc49
-rw-r--r--python/policy.cc33
-rw-r--r--python/sourcelist.cc22
-rw-r--r--python/tag.cc82
17 files changed, 893 insertions, 325 deletions
diff --git a/debian/changelog b/debian/changelog
index 29606cb5..377e7e05 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -6,6 +6,7 @@ python-apt (0.7.94.3) UNRELEASED; urgency=low
- Fix fetch_source() to work when source name = binary name (LP: #552400).
* 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.
diff --git a/python/acquire-item.cc b/python/acquire-item.cc
index cdb4a4bc..d8185ff1 100644
--- a/python/acquire-item.cc
+++ b/python/acquire-item.cc
@@ -124,17 +124,30 @@ 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. 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 string indicating the current mode e.g. 'Fetching'."},
+ {"is_trusted",acquireitem_get_is_trusted,NULL,
+ "Whether the item is trusted or not."},
+ {"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."},
+ {"status",acquireitem_get_status,NULL,
+ "The status of the item."},
{}
};
@@ -158,6 +171,10 @@ static void acquireitem_dealloc(PyObject *self)
CppDeallocPtr<pkgAcquire::Item*>(self);
}
+static const char *acquireitem_doc =
+ "Representation of an Acquire item. It is not possible to create\n"
+ "instances of this class, but it is possible to create instances\n"
+ "of the AcquireFile subclass.";
PyTypeObject PyAcquireItem_Type = {
PyVarObject_HEAD_INIT(&PyType_Type, 0)
"apt_pkg.AcquireItem", // tp_name
@@ -181,7 +198,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 +243,22 @@ 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. The destination can be specified by either 'destdir'\n"
+ "for specifying the destination directory or 'destfile' for\n"
+ "specifying the path to the destination file.\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.\n"
+ "\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)
diff --git a/python/acquire.cc b/python/acquire.cc
index cc9ee310..27e592bc 100644
--- a/python/acquire.cc
+++ b/python/acquire.cc
@@ -65,15 +65,24 @@ 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 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 for the 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 fetched prior to resuming the\n"
+ "download."},
{NULL}
};
-
+static const char *acquireworker_doc =
+ "Acquire workers represent exactly one subprocess used for fetching\n"
+ "files. This subprocess is created from the methods stored in\n"
+ "Dir::Bin::Methods.\n\n";
PyTypeObject PyAcquireWorker_Type = {
PyVarObject_HEAD_INIT(&PyType_Type, 0)
"apt_pkg.AcquireWorker", // tp_name
@@ -97,7 +106,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 +156,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 to download this item."},
+ {"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";
-
+ "Describe an AcquireItem. This class provides the description of the\n"
+ "item and the uri the item is fetched from. It is used in progress\n"
+ "classes to get the descriptions to display.";
PyTypeObject PyAcquireItemDesc_Type = {
PyVarObject_HEAD_INIT(&PyType_Type, 0)
"apt_pkg.AcquireItemDesc", // tp_name
@@ -227,8 +241,12 @@ 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."},
+ {"shutdown",PkgAcquireShutdown, METH_VARARGS,
+ "shutdown()\n\n"
+ "Shut the fetcher down, removing all items from it."},
{}
};
@@ -275,11 +293,17 @@ 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."},
+ {"items",PkgAcquireGetItems,0,
+ "A list of all items as apt_pkg.AcquireItem objects."},
+ {"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."},
+ {"total_needed",PkgAcquireGetTotalNeeded,0,
+ "The amount of data that needs to fetched plus the amount of data\n"
+ "which has already been fetched."},
{}
};
@@ -321,8 +345,8 @@ 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"
+ "Acquire(progress: apt_pkg.AcquireProgress) -> Acquire()\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.";
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
diff --git a/python/arfile.cc b/python/arfile.cc
index 4f3b4ad7..7ebf51f9 100644
--- a/python/arfile.cc
+++ b/python/arfile.cc
@@ -238,11 +238,11 @@ static PyObject *_extract(FileFd &Fd, const ARArchive::Member *member,
static const char *ararchive_extract_doc =
"extract(name: str[, target: str]) -> bool\n\n"
- "Extract the member given by name into the directory given by target.\n"
- "If the extraction failed, an error is raised. Otherwise, the method\n"
- "returns True if the owner could be set or False if the owner could not\n"
- "be changed. It may also raise LookupError if there is member with\n"
- "the given name.";
+ "Extract the member given by 'name' into the directory given\n"
+ "by 'target'. If the extraction failed, raise OSError. In case\n"
+ "of success, return True if the file owner could be set or\n"
+ "False if this was not possible. If the requested member\n"
+ "does not exist, raise LookupError.";
static PyObject *ararchive_extract(PyArArchiveObject *self, PyObject *args)
{
char *name = 0;
@@ -260,11 +260,10 @@ static PyObject *ararchive_extract(PyArArchiveObject *self, PyObject *args)
}
static const char *ararchive_extractall_doc =
- "extract([target: str]) -> bool\n\n"
- "Extract all into the directory given by target.\n"
- "If the extraction failed, an error is raised. Otherwise, the method\n"
- "returns True if the owner could be set or False if the owner could not\n"
- "be changed.";
+ "extractall([target: str]) -> bool\n\n"
+ "Extract all into the directory given by 'target'. If the extraction\n"
+ "failed, raise an error. Otherwise, return True if the owner could\n"
+ "be set or False if the owner could not be changed.";
static PyObject *ararchive_extractall(PyArArchiveObject *self, PyObject *args)
{
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
};
diff --git a/python/configuration.cc b/python/configuration.cc
index 1b5010ab..1aff56fb 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, e.g. 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 only for integer values.";
static PyObject *CnfFindI(PyObject *Self,PyObject *Args)
{
char *Name = 0;
@@ -73,7 +95,9 @@ 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 only for boolean values.";
static PyObject *CnfFindB(PyObject *Self,PyObject *Args)
{
char *Name = 0;
@@ -83,7 +107,11 @@ static PyObject *CnfFindB(PyObject *Self,PyObject *Args)
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). One can then use find_i()/find_b()\n"
+ "to retrieve their value again.";
static PyObject *CnfSet(PyObject *Self,PyObject *Args)
{
char *Name = 0;
@@ -96,7 +124,9 @@ 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;
@@ -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"
+ "Unset the option at the given key and all sub options.";
static PyObject *CnfClear(PyObject *Self,PyObject *Args)
{
char *Name = 0;
@@ -124,7 +156,12 @@ 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 objects which starts at the\n"
+ "given option. 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 +179,9 @@ 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.";
static PyObject *CnfList(PyObject *Self,PyObject *Args)
{
char *RootName = 0;
@@ -169,7 +208,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 +232,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 +249,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 +322,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 given by filename and set the options\n"
+ "defined therein in the configuration object.";
PyObject *LoadConfig(PyObject *Self,PyObject *Args)
{
char *Name = 0;
@@ -292,7 +343,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 +365,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 +391,19 @@ 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"
+"and the tutorial therin about writing an apt-cdrom clone for more details.";
PyObject *ParseCommandLine(PyObject *Self,PyObject *Args)
{
PyObject *POList;
@@ -465,6 +528,14 @@ 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"
+ "Configuration objects represent the configuration of apt. They map\n"
+ "keys to values and store configuration parsed from files like\n"
+ "/etc/apt/apt.conf. The most important object is apt_pkg.config\n"
+ "which points to the global configuration object. Additional objects\n"
+ "can be created, but this is normally not needed.";
PyTypeObject PyConfiguration_Type =
{
PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -489,7 +560,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
diff --git a/python/depcache.cc b/python/depcache.cc
index dc6a999b..a9627037 100644
--- a/python/depcache.cc
+++ b/python/depcache.cc
@@ -542,35 +542,97 @@ static PyObject *PkgDepCacheMarkedReinstall(PyObject *Self,PyObject *Args)
static PyMethodDef PkgDepCacheMethods[] =
{
- {"init",PkgDepCacheInit,METH_VARARGS,"Init the depcache (done on construct automatically)"},
- {"get_candidate_ver",PkgDepCacheGetCandidateVer,METH_VARARGS,"Get candidate version"},
- {"set_candidate_ver",PkgDepCacheSetCandidateVer,METH_VARARGS,"Set candidate version"},
+ {"init",PkgDepCacheInit,METH_VARARGS,
+ "init(progress: apt.progress.base.OpProgress)\n\n"
+ "Initialize the depcache (done on construct automatically)"},
+ {"get_candidate_ver",PkgDepCacheGetCandidateVer,METH_VARARGS,
+ "get_candidate_ver(pkg: apt_pkg.Package) -> apt_pkg.Version\n\n"
+ "Return the candidate version for the package, normally the version\n"
+ "with the highest pin (changeable using set_candidate_ver)."},
+ {"set_candidate_ver",PkgDepCacheSetCandidateVer,METH_VARARGS,
+ "set_candidate_ver(pkg: apt_pkg.Package, ver: apt_pkg.Version) -> bool\n\n"
+ "Set the candidate version of 'pkg' to 'ver'."},
// global cache operations
- {"upgrade",PkgDepCacheUpgrade,METH_VARARGS,"Perform Upgrade (optional boolean argument if dist-upgrade should be performed)"},
- {"fix_broken",PkgDepCacheFixBroken,METH_VARARGS,"Fix broken packages"},
- {"read_pinfile",PkgDepCacheReadPinFile,METH_VARARGS,"Read the pin policy"},
- {"minimize_upgrade",PkgDepCacheMinimizeUpgrade, METH_VARARGS,"Go over the entire set of packages and try to keep each package marked for upgrade. If a conflict is generated then the package is restored."},
+ {"upgrade",PkgDepCacheUpgrade,METH_VARARGS,
+ "upgrade([dist_upgrade: bool = True]) -> bool\n\n"
+ "Mark the packages for upgrade under the same conditions apt-get\n"
+ "upgrade does. If 'dist_upgrade' is True, also allow packages to\n"
+ "be upgraded if they require installation/removal of other packages;\n"
+ "just like apt-get dist-upgrade."},
+ {"fix_broken",PkgDepCacheFixBroken,METH_VARARGS,
+ "fix_broken() -> bool\n\n"
+ "Fix broken packages."},
+ {"read_pinfile",PkgDepCacheReadPinFile,METH_VARARGS,
+ "read_pinfile([file: str])\n\n"
+ "Read the pin policy"},
+ {"minimize_upgrade",PkgDepCacheMinimizeUpgrade, METH_VARARGS,
+ "minimize_upgrade() -> bool\n\n"
+ "Go over the entire set of packages and try to keep each package\n"
+ "marked for upgrade. If a conflict is generated then the package\n"
+ "is restored."},
// Manipulators
- {"mark_keep",PkgDepCacheMarkKeep,METH_VARARGS,"Mark package for keep"},
- {"mark_delete",PkgDepCacheMarkDelete,METH_VARARGS,"Mark package for delete (optional boolean argument if it should be purged)"},
- {"mark_install",PkgDepCacheMarkInstall,METH_VARARGS,"Mark package for Install"},
- {"mark_auto",PkgDepCacheMarkAuto,METH_VARARGS,"mark_auto(pkg: apt_pkg.Package, auto: bool)\n\nMark package as automatically installed."},
- {"set_reinstall",PkgDepCacheSetReInstall,METH_VARARGS,"Set if the package should be reinstalled"},
+ {"mark_keep",PkgDepCacheMarkKeep,METH_VARARGS,
+ "mark_keep(pkg: apt_pkg.Package)\n\n"
+ "Mark package for keep"},
+ {"mark_delete",PkgDepCacheMarkDelete,METH_VARARGS,
+ "mark_delete(pkg: apt_pkg.Package[, purge: bool = False])\n\n"
+ "Mark package for deletion, and if 'purge' is True also for purging."},
+ {"mark_install",PkgDepCacheMarkInstall,METH_VARARGS,
+ "mark_install(pkg: apt_pkg.Package[, auto_inst=True, from_user=True])\n\n"
+ "Mark the package for installation. The parameter 'auto_inst' controls\n"
+ "whether the dependencies of the package are marked for installation\n"
+ "as well. The parameter 'from_user' controls whether the package is\n"
+ "registered as NOT automatically installed."},
+ {"mark_auto",PkgDepCacheMarkAuto,METH_VARARGS,
+ "mark_auto(pkg: apt_pkg.Package, auto: bool)\n\n"
+ "Mark package as automatically installed (if auto=True),\n"
+ "or as not automatically installed (if auto=False)."},
+ {"set_reinstall",PkgDepCacheSetReInstall,METH_VARARGS,
+ "set_reinstall(pkg: apt_pkg.Package, reinstall: bool)\n\n"
+ "Set if the package should be reinstalled (reinstall = True or False)."},
// state information
- {"is_upgradable",PkgDepCacheIsUpgradable,METH_VARARGS,"Is pkg upgradable"},
- {"is_now_broken",PkgDepCacheIsNowBroken,METH_VARARGS,"Is pkg is now broken"},
- {"is_inst_broken",PkgDepCacheIsInstBroken,METH_VARARGS,"Is pkg broken on the current install"},
- {"is_garbage",PkgDepCacheIsGarbage,METH_VARARGS,"Is pkg garbage (mark-n-sweep)"},
- {"is_auto_installed",PkgDepCacheIsAutoInstalled,METH_VARARGS,"Is pkg marked as auto installed"},
- {"marked_install",PkgDepCacheMarkedInstall,METH_VARARGS,"Is pkg marked for install"},
- {"marked_upgrade",PkgDepCacheMarkedUpgrade,METH_VARARGS,"Is pkg marked for upgrade"},
- {"marked_delete",PkgDepCacheMarkedDelete,METH_VARARGS,"Is pkg marked for delete"},
- {"marked_keep",PkgDepCacheMarkedKeep,METH_VARARGS,"Is pkg marked for keep"},
- {"marked_reinstall",PkgDepCacheMarkedReinstall,METH_VARARGS,"Is pkg marked for reinstall"},
- {"marked_downgrade",PkgDepCacheMarkedDowngrade,METH_VARARGS,"Is pkg marked for downgrade"},
+ {"is_upgradable",PkgDepCacheIsUpgradable,METH_VARARGS,
+ "is_upgradable(pkg: apt_pkg.Package) -> bool\n\n"
+ "Check whether the package is upgradable."},
+ {"is_now_broken",PkgDepCacheIsNowBroken,METH_VARARGS,
+ "is_now_broken(pkg: apt_pkg.Package) -> bool\n\n"
+ "Check whether the package is broken, taking marked changes into account."},
+ {"is_inst_broken",PkgDepCacheIsInstBroken,METH_VARARGS,
+ "is_inst_broken(pkg: apt_pkg.Package) -> bool\n\n"
+ "Check whether the package is broken, ignoring marked changes."},
+ {"is_garbage",PkgDepCacheIsGarbage,METH_VARARGS,
+ "is_garbage(pkg: apt_pkg.Package) -> bool\n\n"
+ "Check whether the package is garbage, i.e. whether it is automatically\n"
+ "installed and the reverse dependencies are not installed anymore."},
+ {"is_auto_installed",PkgDepCacheIsAutoInstalled,METH_VARARGS,
+ "is_auto_installed(pkg: apt_pkg.Package) -> bool\n\n"
+ "Check whether the package is marked as automatically installed."},
+ {"marked_install",PkgDepCacheMarkedInstall,METH_VARARGS,
+ "marked_install(pkg: apt_pkg.Package) -> bool\n\n"
+ "Check whether the package is marked for installation."},
+ {"marked_upgrade",PkgDepCacheMarkedUpgrade,METH_VARARGS,
+ "marked_upgrade(pkg: apt_pkg.Package) -> bool\n\n"
+ "Check whether the package is marked for upgrade."},
+ {"marked_delete",PkgDepCacheMarkedDelete,METH_VARARGS,
+ "marked_delete(pkg: apt_pkg.Package) -> bool\n\n"
+ "Check whether the package is marked for removal."},
+ {"marked_keep",PkgDepCacheMarkedKeep,METH_VARARGS,
+ "marked_keep(pkg: apt_pkg.Package) -> bool\n\n"
+ "Check whether the package should be kept."},
+ {"marked_reinstall",PkgDepCacheMarkedReinstall,METH_VARARGS,
+ "marked_reinstall(pkg: apt_pkg.Package) -> bool\n\n"
+ "Check whether the package is marked for re-installation."},
+ {"marked_downgrade",PkgDepCacheMarkedDowngrade,METH_VARARGS,
+ "marked_downgrade(pkg: apt_pkg.Package) -> bool\n\n"
+ "Check whether the package is marked for downgrade."},
// Action
- {"commit", PkgDepCacheCommit, METH_VARARGS, "Commit pending changes"},
+ {"commit", PkgDepCacheCommit, METH_VARARGS,
+ "commit(acquire_progress, install_progress)\n\n"
+ "Commit all the marked changes. This method takes two arguments,\n"
+ "'acquire_progress' takes an apt.progress.base.AcquireProgress\n"
+ "object and 'install_progress' an apt.progress.base.InstallProgress\n"
+ "object."},
{}
};
@@ -608,13 +670,23 @@ static PyObject *PkgDepCacheGetPolicy(PyObject *Self,void*) {
static PyGetSetDef PkgDepCacheGetSet[] = {
- {"broken_count",PkgDepCacheGetBrokenCount},
- {"deb_size",PkgDepCacheGetDebSize},
- {"del_count",PkgDepCacheGetDelCount},
- {"inst_count",PkgDepCacheGetInstCount},
- {"keep_count",PkgDepCacheGetKeepCount},
- {"usr_size",PkgDepCacheGetUsrSize},
- {"policy",PkgDepCacheGetPolicy},
+ {"broken_count",PkgDepCacheGetBrokenCount,0,
+ "The number of packages with broken dependencies in the cache."},
+ {"deb_size",PkgDepCacheGetDebSize,0,
+ "The size of the packages which are needed for the changes to be\n"
+ "applied."},
+ {"del_count",PkgDepCacheGetDelCount,0,
+ "The number of packages marked for removal."},
+ {"inst_count",PkgDepCacheGetInstCount,0,
+ "The number of packages marked for installation."},
+ {"keep_count",PkgDepCacheGetKeepCount,0,
+ "The number of packages marked for keep."},
+ {"usr_size",PkgDepCacheGetUsrSize,0,
+ "The amount of space required for installing/removing the packages,\n"
+ "i.e. the Installed-Size of all packages marked for installation\n"
+ "minus the Installed-Size of all packages for for removal."},
+ {"policy",PkgDepCacheGetPolicy,0,
+ "The apt_pkg.Policy object used by this cache."},
{}
};
@@ -643,9 +715,9 @@ static PyObject *PkgDepCacheNew(PyTypeObject *type,PyObject *Args,PyObject *kwds
return HandleErrors(DepCachePyObj);
}
-static char *doc_PkgDepCache = "DepCache(cache) -> DepCache() object\n\n"
+static char *doc_PkgDepCache = "DepCache(cache: apt_pkg.Cache)\n\n"
"A DepCache() holds extra information on the state of the packages.\n\n"
- "The parameter *cache* refers to an apt_pkg.Cache() object.";
+ "The parameter 'cache' refers to an apt_pkg.Cache() object.";
PyTypeObject PyDepCache_Type =
{
PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -814,17 +886,37 @@ static PyObject *PkgProblemResolverInstallProtect(PyObject *Self,PyObject *Args)
static PyMethodDef PkgProblemResolverMethods[] =
{
// config
- {"protect", PkgProblemResolverProtect, METH_VARARGS, "protect(PkgIterator)"},
- {"remove", PkgProblemResolverRemove, METH_VARARGS, "remove(PkgIterator)"},
- {"clear", PkgProblemResolverClear, METH_VARARGS, "clear(PkgIterator)"},
- {"install_protect", PkgProblemResolverInstallProtect, METH_VARARGS, "install_protect()"},
+ {"protect", PkgProblemResolverProtect, METH_VARARGS,
+ "protect(pkg: apt_pkg.Package)\n\n"
+ "Mark the package as protected in the resolver, meaning that its\n"
+ "state will not be changed."},
+ {"remove", PkgProblemResolverRemove, METH_VARARGS,
+ "remove(pkg: apt_pkg.Package)\n\n"
+ "Mark the package for removal in the resolver."},
+ {"clear", PkgProblemResolverClear, METH_VARARGS,
+ "clear(pkg: apt_pkg.Package)\n\n"
+ "Revert the actions done by protect()/remove() on the package."},
+ {"install_protect", PkgProblemResolverInstallProtect, METH_VARARGS,
+ "install_protect()\n\n"
+ "Install all protected packages."},
// Actions
- {"resolve", PkgProblemResolverResolve, METH_VARARGS, "Try to intelligently resolve problems by installing and removing packages"},
- {"resolve_by_keep", PkgProblemResolverResolveByKeep, METH_VARARGS, "Try to resolv problems only by using keep"},
+ {"resolve", PkgProblemResolverResolve, METH_VARARGS,
+ "resolve([fix_broken: bool = True]) -> bool\n\n"
+ "Try to intelligently resolve problems by installing and removing\n"
+ "packages. If 'fix_broken' is True, apt will try to repair broken\n"
+ "dependencies of installed packages."},
+ {"resolve_by_keep", PkgProblemResolverResolveByKeep, METH_VARARGS,
+ "resolve_by_keep() -> bool\n\n"
+ "Try to resolve problems only by using keep."},
{}
};
+static const char *problemresolver_doc =
+ "ProblemResolver(depcache: apt_pkg.DepCache)\n\n"
+ "ProblemResolver objects take care of resolving problems\n"
+ "with dependencies. They mark packages for installation/\n"
+ "removal and try to satisfy all dependencies.";
PyTypeObject PyProblemResolver_Type =
{
PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -850,7 +942,7 @@ PyTypeObject PyProblemResolver_Type =
(Py_TPFLAGS_DEFAULT | // tp_flags
Py_TPFLAGS_BASETYPE |
Py_TPFLAGS_HAVE_GC),
- "ProblemResolver Object", // tp_doc
+ problemresolver_doc, // tp_doc
CppTraverse<pkgProblemResolver *>, // tp_traverse
CppClear<pkgProblemResolver *>, // tp_clear
0, // tp_richcompare
diff --git a/python/indexfile.cc b/python/indexfile.cc
index 524e59a4..037be210 100644
--- a/python/indexfile.cc
+++ b/python/indexfile.cc
@@ -27,7 +27,9 @@ static PyObject *IndexFileArchiveURI(PyObject *Self,PyObject *Args)
static PyMethodDef IndexFileMethods[] =
{
- {"archive_uri",IndexFileArchiveURI,METH_VARARGS,"Returns the ArchiveURI"},
+ {"archive_uri",IndexFileArchiveURI,METH_VARARGS,
+ "archive_uri(path: str) -> str\n\n"
+ "Return the URI to the given path in the archive."},
{}
};
@@ -67,15 +69,26 @@ static PyObject *IndexFileRepr(PyObject *Self)
#undef S
static PyGetSetDef IndexFileGetSet[] = {
- {"describe",IndexFileGetDescribe},
- {"exists",IndexFileGetExists},
- {"has_packages",IndexFileGetHasPackages},
- {"is_trusted",IndexFileGetIsTrusted},
- {"label",IndexFileGetLabel},
- {"size",IndexFileGetSize},
+ {"describe",IndexFileGetDescribe,0,
+ "A string describing the index file."},
+ {"exists",IndexFileGetExists,0,
+ "A boolean value determining whether the index file exists."},
+ {"has_packages",IndexFileGetHasPackages,0,
+ "A boolean value determining whether the index file has packages."},
+ {"is_trusted",IndexFileGetIsTrusted,0,
+ "A boolean value determining whether the file can be trusted; e.g.\n"
+ "because it is from a source with a GPG signed Release file."},
+ {"label",IndexFileGetLabel,0,
+ "The label of the index file."},
+ {"size",IndexFileGetSize,0,
+ "The size of the files, measured in bytes."},
{}
};
+static const char *indexfile_doc =
+ "Represent an index file, i.e. package indexes, translation indexes,\n"
+ "and source indexes.";
+
PyTypeObject PyIndexFile_Type =
{
PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -100,7 +113,7 @@ PyTypeObject PyIndexFile_Type =
0, // tp_setattro
0, // tp_as_buffer
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, // tp_flags
- "IndexFile Object", // tp_doc
+ indexfile_doc, // tp_doc
CppTraverse<pkgIndexFile*>, // tp_traverse
CppClear<pkgIndexFile*>, // tp_clear
0, // tp_richcompare
diff --git a/python/indexrecords.cc b/python/indexrecords.cc
index ac4a7c2e..c5ebcfbc 100644
--- a/python/indexrecords.cc
+++ b/python/indexrecords.cc
@@ -44,9 +44,11 @@ static PyObject *indexrecords_load(PyObject *self,PyObject *args)
return HandleErrors(PyBool_FromLong(records->Load(filename)));
}
-static char *indexrecords_lookup_doc = "lookup(metakey)\n\n"
- "Lookup the filename given by metakey, return a tuple (hash, size).\n"
- "The hash part is a HashString() object.";
+static char *indexrecords_lookup_doc =
+ "lookup(key: str) -> (HashString, int)\n\n"
+ "Lookup the filename given by 'key', return a tuple (hash, size),\n"
+ "whereas the first element 'hash' is an apt_pkg.HashString object\n"
+ "and the second element 'size' an int object.";
static PyObject *indexrecords_lookup(PyObject *self,PyObject *args)
{
const char *keyname;
@@ -74,15 +76,17 @@ static PyObject *indexrecords_get_dist(PyObject *self)
static PyMethodDef indexrecords_methods[] = {
{"load",indexrecords_load,METH_VARARGS,
- "load(filename: str)\n\nLoad the file given by filename."},
+ "load(filename: str)\n\n"
+ "Load the file given by filename."},
{"get_dist",(PyCFunction)indexrecords_get_dist,METH_NOARGS,
- "get_dist() -> str\n\nReturn a distribution set in the release file."},
+ "get_dist() -> str\n\n"
+ "Return a distribution set in the release file."},
{"lookup",indexrecords_lookup,METH_VARARGS,indexrecords_lookup_doc},
{}
};
static char *indexrecords_doc = "IndexRecords()\n\n"
- "Representation of a release file.";
+ "Representation of a Release file.";
PyTypeObject PyIndexRecords_Type = {
PyVarObject_HEAD_INIT(&PyType_Type, 0)
"apt_pkg.IndexRecords", // tp_name
diff --git a/python/metaindex.cc b/python/metaindex.cc
index cb066980..66aa76fb 100644
--- a/python/metaindex.cc
+++ b/python/metaindex.cc
@@ -48,10 +48,13 @@ static PyObject *MetaIndexGetIndexFiles(PyObject *Self,void*) {
}
static PyGetSetDef MetaIndexGetSet[] = {
- {"dist",MetaIndexGetDist},
- {"index_files",MetaIndexGetIndexFiles},
- {"is_trusted",MetaIndexGetIsTrusted},
- {"uri",MetaIndexGetURI},
+ {"dist",MetaIndexGetDist,0,"The distribution, as a string."},
+ {"index_files",MetaIndexGetIndexFiles,0,
+ "A list of all IndexFile objects associated with this meta index."},
+ {"is_trusted",MetaIndexGetIsTrusted,0,
+ "A boolean value determining whether the file can be trusted."},
+ {"uri",MetaIndexGetURI,0,
+ "The uri the meta index is located at."},
{}
};
@@ -66,6 +69,12 @@ static PyObject *MetaIndexRepr(PyObject *Self)
}
#undef S
+
+static const char *metaindex_doc =
+ "Represent a meta index, i.e. a Release file. This class provides\n"
+ "some information about those release files, e.g. whether they\n"
+ "are signed or not.";
+
PyTypeObject PyMetaIndex_Type =
{
PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -89,7 +98,7 @@ PyTypeObject PyMetaIndex_Type =
0, // tp_setattro
0, // tp_as_buffer
Py_TPFLAGS_DEFAULT, // tp_flags
- "apt_pkg.MetaIndex Object", // tp_doc
+ metaindex_doc, // tp_doc
0, // tp_traverse
0, // tp_clear
0, // tp_richcompare
diff --git a/python/pkgmanager.cc b/python/pkgmanager.cc
index 3a40655a..b501ee1a 100644
--- a/python/pkgmanager.cc
+++ b/python/pkgmanager.cc
@@ -97,13 +97,30 @@ static PyObject *PkgManagerFixMissing(PyObject *Self,PyObject *Args)
static PyMethodDef PkgManagerMethods[] =
{
- {"get_archives",PkgManagerGetArchives,METH_VARARGS,"Load the selected archives into the fetcher"},
- {"do_install",PkgManagerDoInstall,METH_VARARGS,"Do the actual install"},
- {"fix_missing",PkgManagerFixMissing,METH_VARARGS,"Fix the install if a pkg couldn't be downloaded"},
+ {"get_archives",PkgManagerGetArchives,METH_VARARGS,
+ "get_archives(fetcher: Acquire, list: SourceList, recs: PackageRecords) -> bool\n\n"
+ "Download the packages marked for installation via the Acquire object\n"
+ "'fetcher', using the information found in 'list' and 'recs'."},
+ {"do_install",PkgManagerDoInstall,METH_VARARGS,
+ "do_install(status_fd: int) -> int\n\n"
+ "Install the packages and return one of the class constants\n"
+ "RESULT_COMPLETED, RESULT_FAILED, RESULT_INCOMPLETE. The argument\n"
+ "status_fd can be used to specify a file descriptor where APT will\n"
+ "write status information on (see README.progress-reporting in the\n"
+ "apt source code for information what is written there)."},
+ {"fix_missing",PkgManagerFixMissing,METH_VARARGS,
+ "fix_missing() -> bool\n\n"
+ "Fix the installation if a package could not be downloaded."},
{}
};
+static const char *packagemanager_doc =
+ "PackageManager(depcache: apt_pkg.DepCache)\n\n"
+ "PackageManager objects allow the fetching of packages marked for\n"
+ "installation and the installation of those packages. The parameter\n"
+ "'depcache' specifies an apt_pkg.DepCache object where information\n"
+ "about the package selections is retrieved from.";
PyTypeObject PyPackageManager_Type =
{
PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -128,7 +145,7 @@ PyTypeObject PyPackageManager_Type =
0, // tp_as_buffer
(Py_TPFLAGS_DEFAULT | // tp_flags
Py_TPFLAGS_BASETYPE),
- "PackageManager Object", // tp_doc
+ packagemanager_doc, // tp_doc
0, // tp_traverse
0, // tp_clear
0, // tp_richcompare
diff --git a/python/pkgrecords.cc b/python/pkgrecords.cc
index a53af394..8d2cb502 100644
--- a/python/pkgrecords.cc
+++ b/python/pkgrecords.cc
@@ -49,7 +49,9 @@ static PyObject *PkgRecordsLookup(PyObject *Self,PyObject *Args)
static PyMethodDef PkgRecordsMethods[] =
{
- {"lookup",PkgRecordsLookup,METH_VARARGS,"Changes to a new package"},
+ {"lookup",PkgRecordsLookup,METH_VARARGS,
+ "lookup((packagefile: apt_pkg.PackageFile, index: int)) -> bool\n\n"
+ "Changes to a new package"},
{}
};
@@ -117,18 +119,35 @@ static PyObject *PkgRecordsGetRecord(PyObject *Self,void*) {
return PyString_FromStringAndSize(start,stop-start);
}
static PyGetSetDef PkgRecordsGetSet[] = {
- {"filename",PkgRecordsGetFileName},
- {"homepage",PkgRecordsGetHomepage},
- {"long_desc",PkgRecordsGetLongDesc},
- {"md5_hash",PkgRecordsGetMD5Hash},
- {"maintainer",PkgRecordsGetMaintainer},
- {"name",PkgRecordsGetName},
- {"record",PkgRecordsGetRecord},
- {"sha1_hash",PkgRecordsGetSHA1Hash},
- {"sha256_hash",PkgRecordsGetSHA256Hash},
- {"short_desc",PkgRecordsGetShortDesc},
- {"source_pkg",PkgRecordsGetSourcePkg},
- {"source_ver",PkgRecordsGetSourceVer},
+ {"filename",PkgRecordsGetFileName,0,
+ "The filename of the package, as stored in the 'Filename' field."},
+ {"homepage",PkgRecordsGetHomepage,0,
+ "The homepage of the package, as stored in the 'Homepage' field."},
+ {"long_desc",PkgRecordsGetLongDesc,0,
+ "The long description of the packages; i.e. all lines in the\n"
+ "'Description' field except for the first one."},
+ {"md5_hash",PkgRecordsGetMD5Hash,0,
+ "The MD5 hash value of the package, as stored in the 'MD5Sum' field."},
+ {"maintainer",PkgRecordsGetMaintainer,0,
+ "The maintainer of the package, as stored in the 'Maintainer' field."},
+ {"name",PkgRecordsGetName,0,
+ "The name of the package, as stored in the 'Package' field."},
+ {"record",PkgRecordsGetRecord,0,
+ "The raw record, suitable for parsing by apt_pkg.TagSection."},
+ {"sha1_hash",PkgRecordsGetSHA1Hash,0,
+ "The SHA1 hash value, as stored in the 'SHA1' field."},
+ {"sha256_hash",PkgRecordsGetSHA256Hash,0,
+ "The SHA256 hash value, as stored in the 'SHA256' field."},
+ {"short_desc",PkgRecordsGetShortDesc,0,
+ "The short description of the package, i.e. the first line of the\n"
+ "'Description' field."},
+ {"source_pkg",PkgRecordsGetSourcePkg,0,
+ "The name of the source package, if different from the name of the\n"
+ "binary package. This information is retrieved from the 'Source' field."},
+ {"source_ver",PkgRecordsGetSourceVer,0,
+ "The version of the source package, if it differs from the version\n"
+ "of the binary package. Just like 'source_pkg', this information\n"
+ "is retrieved from the 'Source' field."},
{}
};
@@ -144,6 +163,13 @@ static PyObject *PkgRecordsNew(PyTypeObject *type,PyObject *Args,PyObject *kwds)
GetCpp<pkgCache *>(Owner)));
}
+static const char *packagerecords_doc =
+ "PackageRecords(cache: apt_pkg.Cache)\n\n"
+ "Package Records contain information about packages. Those objects\n"
+ "can be used to retrieve information such as maintainer or filename\n"
+ "of a package. They can also be used to retrieve the raw records\n"
+ "of the packages (i.e. those stanzas stored in Packages files).";
+
PyTypeObject PyPackageRecords_Type =
{
PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -169,9 +195,9 @@ PyTypeObject PyPackageRecords_Type =
(Py_TPFLAGS_DEFAULT | // tp_flags
Py_TPFLAGS_BASETYPE |
Py_TPFLAGS_HAVE_GC),
- "Records Object", // tp_doc
- CppTraverse<PkgRecordsStruct>, // tp_traverse
- CppClear<PkgRecordsStruct>, // tp_clear
+ packagerecords_doc, // tp_doc
+ CppTraverse<PkgRecordsStruct>, // tp_traverse
+ CppClear<PkgRecordsStruct>, // tp_clear
0, // tp_richcompare
0, // tp_weaklistoffset
0, // tp_iter
diff --git a/python/pkgsrcrecords.cc b/python/pkgsrcrecords.cc
index 2bc75687..108eff7f 100644
--- a/python/pkgsrcrecords.cc
+++ b/python/pkgsrcrecords.cc
@@ -34,7 +34,12 @@ struct PkgSrcRecordsStruct
// PkgSrcRecords Class /*{{{*/
// ---------------------------------------------------------------------
-static char *doc_PkgSrcRecordsLookup = "xxx";
+static char *doc_PkgSrcRecordsLookup =
+ "lookup(name: str) -> bool\n\n"
+ "Lookup the source package with the given name. Each call moves\n"
+ "the position of the records parser forward. If there are no\n"
+ "records anymore, return None. If the lookup failed this way,\n"
+ "access to any of the attributes will result in an AttributeError.";
static PyObject *PkgSrcRecordsLookup(PyObject *Self,PyObject *Args)
{
PkgSrcRecordsStruct &Struct = GetCpp<PkgSrcRecordsStruct>(Self);
@@ -53,7 +58,10 @@ static PyObject *PkgSrcRecordsLookup(PyObject *Self,PyObject *Args)
return PyBool_FromLong(1);
}
-static char *doc_PkgSrcRecordsRestart = "Start Lookup from the beginning";
+static char *doc_PkgSrcRecordsRestart =
+ "restart()\n\n"
+ "Restart the lookup process. This moves the parser to the first\n"
+ "package and lookups can now be made just like on a new object.";
static PyObject *PkgSrcRecordsRestart(PyObject *Self,PyObject *Args)
{
PkgSrcRecordsStruct &Struct = GetCpp<PkgSrcRecordsStruct>(Self);
@@ -220,15 +228,27 @@ static PyObject *PkgSrcRecordsGetBuildDepends_old(PyObject *Self,void*) {
#endif
static PyGetSetDef PkgSrcRecordsGetSet[] = {
- {"binaries",PkgSrcRecordsGetBinaries},
- {"build_depends",PkgSrcRecordsGetBuildDepends},
- {"files",PkgSrcRecordsGetFiles},
- {"index",PkgSrcRecordsGetIndex},
- {"maintainer",PkgSrcRecordsGetMaintainer},
- {"package",PkgSrcRecordsGetPackage},
- {"record",PkgSrcRecordsGetRecord},
- {"section",PkgSrcRecordsGetSection},
- {"version",PkgSrcRecordsGetVersion},
+ {"binaries",PkgSrcRecordsGetBinaries,0,
+ "A list of the names of the binaries produced by this source package."},
+ {"build_depends",PkgSrcRecordsGetBuildDepends,0,
+ "A dictionary describing the build-time dependencies of the package,\n"
+ "the format is the same as used for apt_pkg.Version.depends_list_str."},
+ {"files",PkgSrcRecordsGetFiles,0,
+ "A list of tuples (md5: str, size: int, path: str, type: str), whereas\n"
+ "'type' can be 'diff' (includes .debian.tar.gz), 'dsc', 'tar'."},
+ {"index",PkgSrcRecordsGetIndex,0,
+ "The index file associated with this record as a list of\n"
+ "apt_pkg.IndexFile objects."},
+ {"maintainer",PkgSrcRecordsGetMaintainer,0,
+ "The maintainer of the package."},
+ {"package",PkgSrcRecordsGetPackage,0,
+ "The name of the source package."},
+ {"record",PkgSrcRecordsGetRecord,0,
+ "The raw record, suitable for parsing using apt_pkg.TagSection."},
+ {"section",PkgSrcRecordsGetSection,0,
+ "The section of the source package."},
+ {"version",PkgSrcRecordsGetVersion,0,
+ "The version of the source package."},
#ifdef COMPAT_0_7
{"BuildDepends",PkgSrcRecordsGetBuildDepends_old,0,"Deprecated function and deprecated output format."},
#endif
@@ -243,6 +263,11 @@ static PyObject *PkgSrcRecordsNew(PyTypeObject *type,PyObject *args,PyObject *kw
return HandleErrors(CppPyObject_NEW<PkgSrcRecordsStruct>(NULL, type));
}
+static const char *sourcerecords_doc =
+ "SourceRecords()\n\n"
+ "Provide an easy way to look up the records of source packages and\n"
+ "provide easy attributes for some widely used fields of the record.";
+
PyTypeObject PySourceRecords_Type =
{
PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -267,7 +292,7 @@ PyTypeObject PySourceRecords_Type =
0, // tp_as_buffer
(Py_TPFLAGS_DEFAULT | // tp_flags
Py_TPFLAGS_BASETYPE),
- "SourceRecords Object", // tp_doc
+ sourcerecords_doc, // tp_doc
0, // tp_traverse
0, // tp_clear
0, // tp_richcompare
diff --git a/python/policy.cc b/python/policy.cc
index 3e1ec589..40da931f 100644
--- a/python/policy.cc
+++ b/python/policy.cc
@@ -37,8 +37,8 @@ static PyObject *policy_new(PyTypeObject *type,PyObject *Args,
return CppPyObject_NEW<pkgPolicy*>(cache,&PyPolicy_Type,policy);
}
-static char *policy_get_priority_doc = "get_priority(package: apt_pkg.Package)"
- " -> int\n\n"
+static char *policy_get_priority_doc =
+ "get_priority(package: apt_pkg.Package) -> int\n\n"
"Return the priority of the package.";
PyObject *policy_get_priority(PyObject *self, PyObject *arg) {
@@ -52,8 +52,8 @@ PyObject *policy_get_priority(PyObject *self, PyObject *arg) {
}
}
-static char *policy_get_candidate_ver_doc = "get_match(package: apt_pkg.Package)"
- " -> apt_pkg.Version\n\n"
+static char *policy_get_candidate_ver_doc =
+ "get_match(package: apt_pkg.Package) -> apt_pkg.Version\n\n"
"Get the best package for the job.";
PyObject *policy_get_candidate_ver(PyObject *self, PyObject *arg) {
@@ -69,8 +69,8 @@ PyObject *policy_get_candidate_ver(PyObject *self, PyObject *arg) {
}
}
-static char *policy_get_match_doc = "get_match(package: apt_pkg.Package) -> "
- "apt_pkg.Version\n\n"
+static char *policy_get_match_doc =
+ "get_match(package: apt_pkg.Package) -> apt_pkg.Version\n\n"
"Return a matching version for the given package.";
static PyObject *policy_get_match(PyObject *self, PyObject *arg) {
@@ -84,9 +84,10 @@ static PyObject *policy_get_match(PyObject *self, PyObject *arg) {
return CppPyObject_NEW<pkgCache::VerIterator>(arg,&PyVersion_Type,ver);
}
-static char *policy_read_pinfile_doc = "read_pinfile(filename: str) -> bool\n\n"
- "Read the pin file given by filename (e.g. '/etc/apt/preferences') and\n"
- "add it to the policy.";
+static char *policy_read_pinfile_doc =
+ "read_pinfile(filename: str) -> bool\n\n"
+ "Read the pin file given by filename (e.g. '/etc/apt/preferences')\n"
+ "and add it to the policy.";
static PyObject *policy_read_pinfile(PyObject *self, PyObject *arg) {
if (!PyString_Check(arg))
@@ -97,9 +98,10 @@ static PyObject *policy_read_pinfile(PyObject *self, PyObject *arg) {
}
#if (APT_PKG_MAJOR >= 4 && APT_PKG_MINOR >= 8)
-static char *policy_read_pindir_doc = "read_pindir(dirname: str) -> bool\n\n"
- "Read the pin files in the given dir (e.g. '/etc/apt/preferences.d') and\n"
- "add them to the policy.";
+static char *policy_read_pindir_doc =
+ "read_pindir(dirname: str) -> bool\n\n"
+ "Read the pin files in the given dir (e.g. '/etc/apt/preferences.d')\n"
+ "and add them to the policy.";
static PyObject *policy_read_pindir(PyObject *self, PyObject *arg) {
if (!PyString_Check(arg))
@@ -110,8 +112,8 @@ static PyObject *policy_read_pindir(PyObject *self, PyObject *arg) {
}
#endif
-static char *policy_create_pin_doc = "create_pin(type: str, pkg: str, "
- "data: str, priority: int)\n\n"
+static char *policy_create_pin_doc =
+ "create_pin(type: str, pkg: str, data: str, priority: int)\n\n"
"Create a pin for the policy. The parameter 'type' refers to one of the\n"
"following strings: 'Version', 'Release', 'Origin'. The argument 'pkg'\n"
"is the name of the package, the parameter 'data' refers to the value\n"
@@ -154,7 +156,8 @@ static PyMethodDef policy_methods[] = {
{}
};
-static char *policy_doc = "Policy(cache)\n\n"
+static char *policy_doc =
+ "Policy(cache)\n\n"
"Representation of the policy of the Cache object given by cache. This\n"
"provides a superset of policy-related functionality compared to the\n"
"DepCache class. The DepCache can be used for most purposes, but there\n"
diff --git a/python/sourcelist.cc b/python/sourcelist.cc
index e42f6bb8..784b161e 100644
--- a/python/sourcelist.cc
+++ b/python/sourcelist.cc
@@ -21,7 +21,10 @@
// PkgsourceList Class /*{{{*/
// ---------------------------------------------------------------------
-static char *doc_PkgSourceListFindIndex = "xxx";
+static char *doc_PkgSourceListFindIndex =
+ "find_index(pkgfile: apt_pkg.PackageFile) -> apt_pkg.IndexFile\n\n"
+ "Return the index file for the given package file, or None if none\n"
+ "could be found.";
static PyObject *PkgSourceListFindIndex(PyObject *Self,PyObject *Args)
{
pkgSourceList *list = GetCpp<pkgSourceList*>(Self);
@@ -47,7 +50,10 @@ static PyObject *PkgSourceListFindIndex(PyObject *Self,PyObject *Args)
return Py_None;
}
-static char *doc_PkgSourceListReadMainList = "xxx";
+static char *doc_PkgSourceListReadMainList =
+ "read_main_list() -> bool\n\n"
+ "Read /etc/apt/sources.list and similar files to populate the list\n"
+ "of indexes.";
static PyObject *PkgSourceListReadMainList(PyObject *Self,PyObject *Args)
{
pkgSourceList *list = GetCpp<pkgSourceList*>(Self);
@@ -56,7 +62,11 @@ static PyObject *PkgSourceListReadMainList(PyObject *Self,PyObject *Args)
return HandleErrors(PyBool_FromLong(res));
}
-static char *doc_PkgSourceListGetIndexes = "Load the indexes into the fetcher";
+static char *doc_PkgSourceListGetIndexes =
+ "get_indexes(acquire: apt_pkg.Acquire[, all: bool=False]) -> bool\n\n"
+ "Add all indexes (i.e. stuff like Release files, Packages files)\n"
+ "to the Acquire object 'acquire'. If 'all' is True, all indexes\n"
+ "will be added, otherwise only changed indexes will be added.";
static PyObject *PkgSourceListGetIndexes(PyObject *Self,PyObject *Args)
{
pkgSourceList *list = GetCpp<pkgSourceList*>(Self);
@@ -110,6 +120,10 @@ static PyObject *PkgSourceListNew(PyTypeObject *type,PyObject *args,PyObject *kw
return CppPyObject_NEW<pkgSourceList*>(NULL, type,new pkgSourceList());
}
+static const char *sourcelist_doc =
+ "SourceList()\n\n"
+ "Represent the list of sources stored in /etc/apt/sources.list and\n"
+ "similar files.";
PyTypeObject PySourceList_Type =
{
PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -134,7 +148,7 @@ PyTypeObject PySourceList_Type =
0, // tp_as_buffer
(Py_TPFLAGS_DEFAULT | // tp_flags
Py_TPFLAGS_BASETYPE),
- "pkgSourceList Object", // tp_doc
+ sourcelist_doc, // tp_doc
0, // tp_traverse
0, // tp_clear
0, // tp_richcompare
diff --git a/python/tag.cc b/python/tag.cc
index c323aa42..99bb9b55 100644
--- a/python/tag.cc
+++ b/python/tag.cc
@@ -89,7 +89,10 @@ void TagFileFree(PyObject *Obj)
/*}}}*/
// Tag Section Wrappers /*{{{*/
-static char *doc_Find = "Find(Name) -> String/None";
+static char *doc_Find =
+ "find(name: str[, default = None]) -> str\n\n"
+ "Find the key given by 'name' and return the value. If the key can\n"
+ "not be found, return 'default'.";
static PyObject *TagSecFind(PyObject *Self,PyObject *Args)
{
char *Name = 0;
@@ -108,7 +111,10 @@ static PyObject *TagSecFind(PyObject *Self,PyObject *Args)
return PyString_FromStringAndSize(Start,Stop-Start);
}
-static char *doc_FindRaw = "FindRaw(Name) -> String/None";
+static char *doc_FindRaw =
+ "find_raw(name: str[, default = None] -> str\n\n"
+ "Same as find(), but returns the complete key : value field; instead of\n"
+ "just the value.";
static PyObject *TagSecFindRaw(PyObject *Self,PyObject *Args)
{
char *Name = 0;
@@ -131,7 +137,11 @@ static PyObject *TagSecFindRaw(PyObject *Self,PyObject *Args)
return PyString_FromStringAndSize(Start,Stop-Start);
}
-static char *doc_FindFlag = "FindFlag(Name) -> integer/none";
+static char *doc_FindFlag =
+ "find_flag(name: str) -> int\n\n"
+ "Return 1 if the value at the key is 'yes' or a similar value describing\n"
+ "a boolean true. If the field does not exist, or does not have such a\n"
+ "value, return 0.";
static PyObject *TagSecFindFlag(PyObject *Self,PyObject *Args)
{
char *Name = 0;
@@ -175,7 +185,9 @@ static Py_ssize_t TagSecLength(PyObject *Self)
}
// Look like a mapping
-static char *doc_Keys = "keys() -> List";
+static char *doc_Keys =
+ "keys() -> list\n\n"
+ "Return a list of all keys.";
static PyObject *TagSecKeys(PyObject *Self,PyObject *Args)
{
pkgTagSection &Tags = GetCpp<pkgTagSection>(Self);
@@ -200,7 +212,9 @@ static PyObject *TagSecKeys(PyObject *Self,PyObject *Args)
}
#if PY_MAJOR_VERSION < 3
-static char *doc_Exists = "Exists(Name) -> integer";
+static char *doc_Exists =
+ "has_key(name: str) -> bool\n\n"
+ "Return True if the key given by 'name' exists, False otherwise.";
static PyObject *TagSecExists(PyObject *Self,PyObject *Args)
{
char *Name = 0;
@@ -225,7 +239,9 @@ static int TagSecContains(PyObject *Self,PyObject *Arg)
return 1;
}
-static char *doc_Bytes = "Bytes() -> integer";
+static char *doc_Bytes =
+ "bytes() -> int\n\n"
+ "Return the number of bytes this section is large.";
static PyObject *TagSecBytes(PyObject *Self,PyObject *Args)
{
if (PyArg_ParseTuple(Args,"") == 0)
@@ -243,7 +259,9 @@ static PyObject *TagSecStr(PyObject *Self)
}
/*}}}*/
// TagFile Wrappers /*{{{*/
-static char *doc_Step = "Step() -> Integer\n0 means EOF.";
+static char *doc_Step =
+ "step() -> bool\n\n"
+ "Step forward in the file";
static PyObject *TagFileStep(PyObject *Self,PyObject *Args)
{
if (PyArg_ParseTuple(Args,"") == 0)
@@ -294,7 +312,9 @@ static PyObject *TagFileIter(PyObject *Self) {
return Self;
}
-static char *doc_Offset = "Offset() -> Integer";
+static char *doc_Offset =
+ "offset() -> int\n\n"
+ "Return the current offset.";
static PyObject *TagFileOffset(PyObject *Self,PyObject *Args)
{
if (PyArg_ParseTuple(Args,"") == 0)
@@ -302,7 +322,11 @@ static PyObject *TagFileOffset(PyObject *Self,PyObject *Args)
return Py_BuildValue("i",((TagFileData *)Self)->Object.Offset());
}
-static char *doc_Jump = "Jump(Offset) -> Integer";
+static char *doc_Jump =
+ "jump(offset: int) -> bool\n\n"
+ "Jump to the given offset, returns True on success. Note that jumping to\n"
+ "an offset is not very reliable, and the 'section' attribute does not\n"
+ "always point to the section one would expect it to.";
static PyObject *TagFileJump(PyObject *Self,PyObject *Args)
{
int Offset;
@@ -344,7 +368,7 @@ static PyObject *TagSecNew(PyTypeObject *type,PyObject *Args,PyObject *kwds) {
}
#ifdef COMPAT_0_7
-char *doc_ParseSection ="ParseSection(Text) -> TagSection() object. Deprecated.";
+char *doc_ParseSection = "ParseSection(Text) -> TagSection()\n\nDeprecated.";
PyObject *ParseSection(PyObject *self,PyObject *Args)
{
PyErr_WarnEx(PyExc_DeprecationWarning, "apt_pkg.ParseSection() is "
@@ -384,7 +408,7 @@ static PyObject *TagFileNew(PyTypeObject *type,PyObject *Args,PyObject *kwds)
return HandleErrors(New);
}
#ifdef COMPAT_0_7
-char *doc_ParseTagFile = "ParseTagFile(File) -> TagFile() object. Deprecated.";
+char *doc_ParseTagFile = "ParseTagFile(file) -> TagFile()\n\nDeprecated.";
PyObject *ParseTagFile(PyObject *self,PyObject *Args) {
PyErr_WarnEx(PyExc_DeprecationWarning, "apt_pkg.ParseTagFile() is "
"deprecated. Please see apt_pkg.TagFile() for the "
@@ -398,20 +422,19 @@ PyObject *ParseTagFile(PyObject *self,PyObject *Args) {
/* An interesting future extension would be to add a user settable
order list */
char *doc_RewriteSection =
-"RewriteSection(Section,Order,RewriteList) -> String\n"
+"rewrite_section(section: TagSection, order: list, rewrite_list: list) -> str\n"
"\n"
-"The section rewriter allows a section to be taken in, have fields added,\n"
-"removed or changed and then put back out. During this process the fields\n"
-"within the section are sorted to corrispond to a proper order. Order is a\n"
-"list of field names with their proper capitialization.\n"
-"apt_pkg.RewritePackageOrder and apt_pkg.RewriteSourceOrder are two predefined\n"
-"orders.\n"
-"RewriteList is a list of tuples. Each tuple is of the form:\n"
-" (Tag,NewValue[,RenamedTo])\n"
-"Tag specifies the tag in the source section. NewValue is the new value of\n"
-"that tag and the optional RenamedTo field can cause the tag to be changed.\n"
-"If NewValue is None then the tag is removed\n"
-"Ex. ('Source','apt','Package') is used for .dsc files.";
+"Rewrite the section given by 'section' using 'rewrite_list', and order the\n"
+"fields according to 'order'.\n\n"
+"The parameter 'order' is a list object containing the names of the fields\n"
+"in the order they should appear in the rewritten section.\n"
+"apt_pkg.REWRITE_PACKAGE_ORDER and apt_pkg.REWRITE_SOURCE_ORDER are two\n"
+"predefined lists for rewriting package and source sections, respectively\n\n"
+"The parameter 'rewrite_list' is a list of tuples of the form\n"
+"``(tag, newvalue[, renamed_to])``, whereas 'tag' describes the field which\n"
+"should be changed, 'newvalue' the value which should be inserted or None\n"
+"to delete the field, and the optional renamed_to can be used to rename the\n"
+"field.";
PyObject *RewriteSection(PyObject *self,PyObject *Args)
{
PyObject *Section;
@@ -487,11 +510,11 @@ PySequenceMethods TagSecSeqMeth = {0,0,0,0,0,0,0,TagSecContains,0,0};
PyMappingMethods TagSecMapMeth = {TagSecLength,TagSecMap,0};
-static char *doc_TagSec = "TagSection(text) -> Create a new object.\n\n"
+static char *doc_TagSec = "TagSection(text: str)\n\n"
"TagSection() objects provide methods to access rfc822-style formatted\n"
"header sections, like those in debian/control or Packages files.\n\n"
"TagSection() behave like read-only dictionaries and also provide access\n"
- "to the functions provided by the C++ class (e.g. Find)";
+ "to the functions provided by the C++ class (e.g. find)";
PyTypeObject PyTagSection_Type =
{
PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -556,12 +579,13 @@ static PyObject *TagFileGetSection(PyObject *Self,void*) {
}
static PyGetSetDef TagFileGetSet[] = {
- {"section",TagFileGetSection,0,"Return a TagSection.",0},
+ {"section",TagFileGetSection,0,
+ "The current section, as a TagSection object.",0},
{}
};
-static char *doc_TagFile = "TagFile(file) -> TagFile() object. \n\n"
+static char *doc_TagFile = "TagFile(file)\n\n"
"TagFile() objects provide access to debian control files, which consists\n"
"of multiple RFC822-like formatted sections.\n\n"
"To provide access to those sections, TagFile objects provide an iterator\n"
@@ -571,7 +595,7 @@ static char *doc_TagFile = "TagFile(file) -> TagFile() object. \n\n"
"used to navigate in the file; and offset() tells the current position.\n\n"
"It is important to not mix the use of both APIs, because this can have\n"
"unwanted effects.\n\n"
- "The parameter *file* refers to an object providing a fileno() method or\n"
+ "The parameter 'file' refers to an object providing a fileno() method or\n"
"a file descriptor (an integer)";
// Type for a Tag File
generated by cgit v1.2.3 (git 2.46.0) at 2026-05-10 16:40:24 +0000