From c3d6edddcdcd40ff7477430a20a3e3be7e188963 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Thu, 1 Apr 2010 18:26:37 +0200 Subject: python: Return bool instead of int to Python where possible, looks better. --- python/metaindex.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'python/metaindex.cc') diff --git a/python/metaindex.cc b/python/metaindex.cc index 2dcade7d..cb066980 100644 --- a/python/metaindex.cc +++ b/python/metaindex.cc @@ -27,7 +27,7 @@ static PyObject *MetaIndexGetDist(PyObject *Self,void*) { static PyObject *MetaIndexGetIsTrusted(PyObject *Self,void*) { metaIndex *meta = GetCpp(Self); - return Py_BuildValue("i",(meta->IsTrusted())); + return PyBool_FromLong((meta->IsTrusted())); } static PyObject *MetaIndexGetIndexFiles(PyObject *Self,void*) { -- cgit v1.2.3 From 17b0dc6856855f2cd46d234357f0de584db2019e Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Thu, 1 Apr 2010 19:55:13 +0200 Subject: python: Document every class, function, property. Finally, a complete reference to apt_pkg available via pydoc and __doc__ attributes. --- debian/changelog | 1 + python/acquire-item.cc | 60 ++++++++--- python/acquire.cc | 68 ++++++++---- python/apt_pkgmodule.cc | 166 ++++++++++++++++++++-------- python/arfile.cc | 19 ++-- python/cache.cc | 280 +++++++++++++++++++++++++++++++++++------------- python/configuration.cc | 119 +++++++++++++++----- python/depcache.cc | 172 ++++++++++++++++++++++------- python/indexfile.cc | 29 +++-- python/indexrecords.cc | 16 +-- python/metaindex.cc | 19 +++- python/pkgmanager.cc | 25 ++++- python/pkgrecords.cc | 58 +++++++--- python/pkgsrcrecords.cc | 49 ++++++--- python/policy.cc | 33 +++--- python/sourcelist.cc | 22 +++- python/tag.cc | 82 +++++++++----- 17 files changed, 893 insertions(+), 325 deletions(-) (limited to 'python/metaindex.cc') 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(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, // tp_traverse CppClear, // 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, // tp_traverse CppClear, // tp_clear 0, // tp_richcompare @@ -147,16 +156,21 @@ static PyObject *acquireitemdesc_get_owner(CppPyObject *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, // tp_traverse CppClear, // 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, // tp_traverse CppClear,// 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, // tp_traverse CppClear,// 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, // tp_traverse CppClear, // 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, // tp_traverse CppClear, // 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, // tp_traverse CppClear, // 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, // tp_traverse CppClear, // 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, // tp_traverse CppClear, // 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(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, // tp_traverse - CppClear, // tp_clear + packagerecords_doc, // tp_doc + CppTraverse, // tp_traverse + CppClear, // 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(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(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(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(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(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(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(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(Self); @@ -110,6 +120,10 @@ static PyObject *PkgSourceListNew(PyTypeObject *type,PyObject *args,PyObject *kw return CppPyObject_NEW(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(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 -- cgit v1.2.3 From 6a519d479e384b0c1044ee456b1b0fb90ab41248 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Wed, 21 Apr 2010 16:59:48 +0200 Subject: python: Commit documentation changes suggested by debian-l10n-english. --- python/acquire-item.cc | 39 ++++++++++++++++---------- python/acquire.cc | 50 ++++++++++++++++++++-------------- python/apt_instmodule.cc | 2 +- python/apt_pkgmodule.cc | 52 ++++++++++++++++++----------------- python/arfile.cc | 28 +++++++++---------- python/cache.cc | 71 ++++++++++++++++++++++++++---------------------- python/cdrom.cc | 9 ++++-- python/configuration.cc | 41 +++++++++++++++++----------- python/depcache.cc | 32 ++++++++++++++-------- python/hashes.cc | 5 ++-- python/indexrecords.cc | 6 ++-- python/lock.cc | 8 +++--- python/metaindex.cc | 5 ++-- python/pkgmanager.cc | 4 +-- python/pkgsrcrecords.cc | 6 ++-- python/policy.cc | 6 ++-- python/tag.cc | 23 ++++++++-------- python/tarfile.cc | 10 +++---- 18 files changed, 223 insertions(+), 174 deletions(-) (limited to 'python/metaindex.cc') diff --git a/python/acquire-item.cc b/python/acquire-item.cc index d8185ff1..4b7dc34d 100644 --- a/python/acquire-item.cc +++ b/python/acquire-item.cc @@ -130,24 +130,28 @@ static PyGetSetDef acquireitem_getset[] = { {"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"}, + "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"}, + "otherwise."}, {"filesize",acquireitem_get_filesize,NULL, - "The size of the file. If unknown, it is set to 0."}, + "The size of the file (number of bytes). If unknown, it is set to 0."}, {"id",acquireitem_get_id,acquireitem_set_id, "The ID of the item. An integer which can be set by progress classes."}, {"mode",acquireitem_get_mode,NULL, - "A string indicating the current mode e.g. 'Fetching'."}, + "A localized string such as 'Fetching' which indicates the current\n" + "mode."}, {"is_trusted",acquireitem_get_is_trusted,NULL, - "Whether the item is trusted or not."}, + "Whether the item is trusted or not. Only True for packages\n" + "which come from a repository signed with one of the keys in\n" + "APT's keyring."}, {"local",acquireitem_get_local,NULL, "Whether we are fetching a local item (copy:/) or not."}, {"partialsize",acquireitem_get_partialsize,NULL, - "The amount of data which has already been fetched."}, + "The amount of data which has already been fetched (number of bytes)."}, {"status",acquireitem_get_status,NULL, - "The status of the item."}, + "An integer representing the item's status which can be compared\n" + "against one of the STAT_* constants defined in this class."}, {} }; @@ -172,9 +176,11 @@ static void acquireitem_dealloc(PyObject *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."; + "Represent a single item to be fetched by an Acquire object.\n\n" + "It is not possible to construct instances of this class directly.\n" + "Prospective users should construct instances of a subclass such as\n" + "AcquireFile instead. It is not possible to create subclasses on the\n" + "Python level, only on the C++ level."; PyTypeObject PyAcquireItem_Type = { PyVarObject_HEAD_INIT(&PyType_Type, 0) "apt_pkg.AcquireItem", // tp_name @@ -246,13 +252,18 @@ static char *acquirefile_doc = "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" + "location. Normally, the file will be stored in the current directory\n" + "using the file name given in the URI. This directory can be changed\n" + "by passing the name of a directory to the 'destdir' parameter. It is\n" + "also possible to set a path to a file using the 'destfile' parameter,\n" + "but both cannot be specified together.\n" "\n" "The parameters 'short_descr' and 'descr' can be used to specify\n" "a short description and a longer description for the item. This\n" - "information is used by progress classes to refer to the item.\n" + "information is used by progress classes to refer to the item and\n" + "should be short, for example, package name as 'short_descr' and\n" + "and something like 'http://localhost sid/main python-apt 0.7.94.2'\n" + "as 'descr'." "\n" "The parameters 'md5' and 'size' are used to verify the resulting\n" "file. The parameter 'size' is also to calculate the total amount\n" diff --git a/python/acquire.cc b/python/acquire.cc index 27e592bc..6f9a1412 100644 --- a/python/acquire.cc +++ b/python/acquire.cc @@ -66,23 +66,24 @@ static PyObject *acquireworker_get_resumepoint(PyObject *self, void *closure) static PyGetSetDef acquireworker_getset[] = { {"current_item",acquireworker_get_current_item,0, - "The item currently fetched, as an apt_pkg.AcquireItemDesc object."}, + "The item currently being 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."}, + "The amount of data fetched so far for the current 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."}, + "The amount of data which was already available when the download was\n" + "started."}, {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"; + "Represent a sub-process responsible for fetching files from\n" + "remote locations. This sub-process uses 'methods' located in\n" + "the directory specified by the configuration option\n" + "Dir::Bin::Methods."; PyTypeObject PyAcquireWorker_Type = { PyVarObject_HEAD_INIT(&PyType_Type, 0) "apt_pkg.AcquireWorker", // tp_name @@ -157,7 +158,7 @@ static PyObject *acquireitemdesc_get_owner(CppPyObject *s static PyGetSetDef acquireitemdesc_getset[] = { {"uri",acquireitemdesc_get_uri,0, - "The URI from which to download this item."}, + "The URI from which this item would be downloaded."}, {"description",acquireitemdesc_get_description,0, "A string describing the item."}, {"shortdesc",acquireitemdesc_get_shortdesc,0, @@ -168,9 +169,9 @@ static PyGetSetDef acquireitemdesc_getset[] = { }; static char *acquireitemdesc_doc = - "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."; + "Provide the description of an item and the URI the item is\n" + "fetched from. Progress classes make use of such objects to\n" + "retrieve description and other information about an item."; PyTypeObject PyAcquireItemDesc_Type = { PyVarObject_HEAD_INIT(&PyType_Type, 0) "apt_pkg.AcquireItemDesc", // tp_name @@ -243,10 +244,15 @@ static PyObject *PkgAcquireShutdown(PyObject *Self,PyObject *Args) static PyMethodDef PkgAcquireMethods[] = { {"run",PkgAcquireRun,METH_VARARGS, "run() -> int\n\nRun the fetcher and return one of RESULT_CANCELLED,\n" - "RESULT_CONTINUE, RESULT_FAILED."}, + "RESULT_CONTINUE, RESULT_FAILED. RESULT_CONTINUE means that all items\n" + "which where queued prior to calling run() have been fetched\n" + "successfully. RESULT_CANCELLED means that the process was canceled\n" + "by the progress class. And RESULT_FAILED means a generic failure."}, {"shutdown",PkgAcquireShutdown, METH_VARARGS, "shutdown()\n\n" - "Shut the fetcher down, removing all items from it."}, + "Shut the fetcher down, removing all items from it. Future access to\n" + "queued AcquireItem objects will cause a segfault. The partial result\n" + "is kept on the disk and not removed and APT might reuse it."}, {} }; @@ -294,16 +300,17 @@ static PyObject *PkgAcquireGetItems(PyObject *Self,void*) static PyGetSetDef PkgAcquireGetSet[] = { {"fetch_needed",PkgAcquireGetFetchNeeded,0, - "The total amount of data to be fetched."}, + "The total amount of data to be fetched (number of bytes)."}, {"items",PkgAcquireGetItems,0, - "A list of all items as apt_pkg.AcquireItem objects."}, + "A list of all items as apt_pkg.AcquireItem objects, including already\n" + "fetched ones and to be fetched ones."}, {"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."}, + "The amount of data which is already available (number of bytes)."}, {"total_needed",PkgAcquireGetTotalNeeded,0, "The amount of data that needs to fetched plus the amount of data\n" - "which has already been fetched."}, + "which has already been fetched (number of bytes)."}, {} }; @@ -345,10 +352,11 @@ PyObject *PyAcquire_FromCpp(pkgAcquire *fetcher, bool Delete, PyObject *owner) { } static char *doc_PkgAcquire = - "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."; + "Acquire([progress: apt.progress.base.AcquireProgress])\n\n" + "Coordinate the retrieval of files via network or local file system\n" + "(using 'copy:/path/to/file' style URIs). The optional argument\n" + "'progress' takes an apt.progress.base.AcquireProgress object\n" + "which may report progress information."; PyTypeObject PyAcquire_Type = { PyVarObject_HEAD_INIT(&PyType_Type, 0) diff --git a/python/apt_instmodule.cc b/python/apt_instmodule.cc index b1038474..732f1bd0 100644 --- a/python/apt_instmodule.cc +++ b/python/apt_instmodule.cc @@ -168,7 +168,7 @@ static PyMethodDef *methods = 0; static const char *apt_inst_doc = - "Functions for working with AR,tar archives and .deb packages.\n\n" + "Functions for working with ar/tar archives and .deb packages.\n\n" "This module provides useful classes and functions to work with\n" "archives, modelled after the 'TarFile' class in the 'tarfile' module."; #define ADDTYPE(mod,name,type) { \ diff --git a/python/apt_pkgmodule.cc b/python/apt_pkgmodule.cc index e7023e4a..a1e9ada0 100644 --- a/python/apt_pkgmodule.cc +++ b/python/apt_pkgmodule.cc @@ -91,8 +91,8 @@ static char *doc_CheckDep = "Check that the given requirement is fulfilled; i.e. that the version\n" "string given by 'pkg_ver' matches the version string 'dep_ver' under\n" "the condition specified by the operator 'dep_op' (<,<=,=,>=,>).\n\n" - "This functions returns True if 'pkg_ver' matches 'dep_ver' under the\n" - "condition 'dep_op'; e.g. this returns True:\n\n" + "Return True if 'pkg_ver' matches 'dep_ver' under the\n" + "condition 'dep_op'; for example, this returns True:\n\n" " apt_pkg.check_dep('1', '<=', '2')"; static PyObject *CheckDep(PyObject *Self,PyObject *Args) { @@ -163,19 +163,21 @@ static const char *doc_ParseDepends = "parse_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 <,<=,=,>=,>."; +"these lists represents one or more options for an 'or' dependency in\n" +"the form of '(pkg, ver, comptype)' tuples. The tuple element 'pkg'\n" +"is the name of the package; the element 'ver' is the version, or ''\n" +"if no version was requested. The element 'ver' is a comparison\n" +"operator ('<', '<=', '=', '>=', or '>')."; 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 <,<=,=,>=,>." +"these lists represents one or more options for an 'or' dependency in\n" +"the form of '(pkg, ver, comptype)' tuples. The tuple element 'pkg'\n" +"is the name of the package; the element 'ver' is the version, or ''\n" +"if no version was requested. The element 'ver' is a comparison\n" +"operator ('<', '<=', '=', '>=', or '>')." "\n\n" "Dependencies may be restricted to certain architectures and the result\n" "only contains those dependencies for the architecture set in the\n" @@ -392,7 +394,7 @@ static PyObject *sha256sum(PyObject *Self,PyObject *Args) // --------------------------------------------------------------------- static char *doc_Init = "init()\n\n" -"Short hand for doing init_config() and init_system(). When working\n" +"Shorthand 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) @@ -423,7 +425,7 @@ static PyObject *InitConfig(PyObject *Self,PyObject *Args) static char *doc_InitSystem = "init_system()\n\n" -"Construct the underlying system."; +"Construct the apt_pkg system."; static PyObject *InitSystem(PyObject *Self,PyObject *Args) { if (PyArg_ParseTuple(Args,"") == 0) @@ -503,8 +505,8 @@ static PyMethodDef methods[] = // Internationalization. {"gettext",py_gettext,METH_VARARGS, "gettext(msg: str[, domain: str = 'python-apt']) -> str\n\n" - "Translate the given string. Much Faster than Python's version and only\n" - "does translations after setlocale() has been called."}, + "Translate the given string. This is much faster than Python's version\n" + "and only does translations after setlocale() has been called."}, // Tag File {"rewrite_section",RewriteSection,METH_VARARGS,doc_RewriteSection}, @@ -544,13 +546,13 @@ static PyMethodDef methods[] = "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 ' '."}, + "Escape the string 'string', replacing any character not allowed in a URL" + "or specified by 'repl' with its ASCII value preceded by a percent sign" + "(so for example ' ' becomes '%20')."}, {"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. ' ')."}, + "as '%20' with their decoded value (in this case, ' ')."}, {"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" @@ -565,12 +567,12 @@ static PyMethodDef methods[] = "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)."}, + "Encode the given bytestring into Base64. The input may not\n" + "contain a null byte character (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" + "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" @@ -578,7 +580,7 @@ static PyMethodDef methods[] = "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."}, + "Convert the given RFC 1123 formatted string to a Unix timestamp."}, // DEPRECATED #ifdef COMPAT_0_7 @@ -740,9 +742,9 @@ static struct _PyAptPkgAPIStruct API = { 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"; + "the functionality provided by the apt-pkg library. Typical uses might\n" + "include reading APT index files and configuration files and installing\n" + "or removing packages."; #if PY_MAJOR_VERSION >= 3 static struct PyModuleDef moduledef = { diff --git a/python/arfile.cc b/python/arfile.cc index 7ebf51f9..a279807d 100644 --- a/python/arfile.cc +++ b/python/arfile.cc @@ -82,12 +82,12 @@ static PyGetSetDef armember_getset[] = { {"size",armember_get_size,0,"The size of the files."}, {"start",armember_get_start,0, "The offset in the archive where the file starts."}, - {"uid",armember_get_uid,0,"The user id of the owner."}, + {"uid",armember_get_uid,0,"The user ID of the owner."}, {NULL} }; static const char *armember_doc = - "An ArMember object represents a single file within an AR archive. For\n" + "Represent a single file within an AR archive. For\n" "Debian packages this can be e.g. control.tar.gz. This class provides\n" "information about this file, such as the mode and size."; PyTypeObject PyArMember_Type = { @@ -141,7 +141,7 @@ struct PyArArchiveObject : public CppPyObject { static const char *ararchive_getmember_doc = "getmember(name: str) -> ArMember\n\n" - "Return a ArMember object for the member given by name. Raise\n" + "Return an ArMember object for the member given by 'name'. Raise\n" "LookupError if there is no ArMember with the given name."; static PyObject *ararchive_getmember(PyArArchiveObject *self, PyObject *arg) { @@ -239,7 +239,7 @@ 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\n" - "by 'target'. If the extraction failed, raise OSError. In case\n" + "by 'target'. If the extraction fails, 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."; @@ -261,9 +261,9 @@ static PyObject *ararchive_extract(PyArArchiveObject *self, PyObject *args) static const char *ararchive_extractall_doc = "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."; + "Extract all archive contents into the directory given by 'target'. If\n" + "the extraction fails, raise an error. Otherwise, return True if the\n" + "owner could be set or False if the owner could not be changed."; static PyObject *ararchive_extractall(PyArArchiveObject *self, PyObject *args) { @@ -310,7 +310,7 @@ static PyObject *ararchive_gettar(PyArArchiveObject *self, PyObject *args) static const char *ararchive_getmembers_doc = "getmembers() -> list\n\n" - "Return a list of all members in the AR archive."; + "Return a list of all members in the archive."; static PyObject *ararchive_getmembers(PyArArchiveObject *self) { PyObject *list = PyList_New(0); @@ -328,7 +328,7 @@ static PyObject *ararchive_getmembers(PyArArchiveObject *self) static const char *ararchive_getnames_doc = "getnames() -> list\n\n" - "Return a list of the names of all members in the AR archive."; + "Return a list of the names of all members in the archive."; static PyObject *ararchive_getnames(PyArArchiveObject *self) { PyObject *list = PyList_New(0); @@ -423,12 +423,12 @@ static PyMappingMethods ararchive_as_mapping = { static const char *ararchive_doc = "ArArchive(file: str/int/file)\n\n" - "An ArArchive object represents an archive in the 4.4 BSD AR format, \n" + "Represent an archive in the 4.4 BSD ar format,\n" "which is used for e.g. deb packages.\n\n" "The parameter 'file' may be a string specifying the path of a file, or\n" "a file-like object providing the fileno() method. It may also be an int\n" "specifying a file descriptor (returned by e.g. os.open()).\n" - "The recommended way is to pass in the path to the file."; + "The recommended way of using it is to pass in the path to the file."; PyTypeObject PyArArchive_Type = { PyVarObject_HEAD_INIT(&PyType_Type, 0) @@ -598,10 +598,10 @@ static const char *debfile_doc = "The parameter 'file' may be a string specifying the path of a file, or\n" "a file-like object providing the fileno() method. It may also be an int\n" "specifying a file descriptor (returned by e.g. os.open()).\n" - "The recommended way is to pass in the path to the file.\n\n" + "The recommended way of using it is to pass in the path to the file.\n\n" "It differs from ArArchive by providing the members 'control', 'data'\n" - "and 'version' for accessing the control.tar.gz,data.tar.{gz,bz2,lzma}\n" - ",debian-binary members in the archive."; + "and 'version' for accessing the control.tar.gz, data.tar.{gz,bz2,lzma},\n" + "and debian-binary members in the archive."; PyTypeObject PyDebFile_Type = { PyVarObject_HEAD_INIT(&PyType_Type, 0) diff --git a/python/cache.cc b/python/cache.cc index 4d7c347a..e31f6a65 100644 --- a/python/cache.cc +++ b/python/cache.cc @@ -85,6 +85,20 @@ static PyObject *CreateProvides(PyObject *Owner,pkgCache::PrvIterator I) // Cache Class /*{{{*/ // --------------------------------------------------------------------- + +static const char *cache_update_doc = + "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' can be used to specify an\n" + "apt.progress.base.AcquireProgress() object , which will report\n" + "progress information while the index files are being fetched.\n" + "The parameter 'sources', if provided, is an apt_pkg.SourcesList\n" + "object listing the remote repositories to be used.\n" + "The 'pulse_interval' parameter indicates how long (in microseconds)\n" + "to wait between calls to the pulse() method of the 'progress' object.\n" + "The default is 500000 microseconds."; static PyObject *PkgCacheUpdate(PyObject *Self,PyObject *Args) { PyObject *pyFetchProgressInst = 0; @@ -152,18 +166,7 @@ static PyObject *PkgCacheOpen(PyObject *Self,PyObject *Args) static PyMethodDef PkgCacheMethods[] = { - {"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." - }, + {"update",PkgCacheUpdate,METH_VARARGS,cache_update_doc}, #ifdef COMPAT_0_7 {"Open", PkgCacheOpen, METH_VARARGS, "Open the cache; deprecated and unsafe"}, @@ -231,7 +234,7 @@ static PyGetSetDef PkgCacheGetSet[] = { {"packages",PkgCacheGetPackages,0, "A list of apt_pkg.Package objects stored in the cache."}, {"provides_count",PkgCacheGetProvidesCount,0, - "The number of provided packages."}, + "Number of Provides relations described in the cache."}, {"ver_file_count",PkgCacheGetVerFileCount,0, "The number of (Version, PackageFile) relations."}, {"version_count",PkgCacheGetVersionCount,0, @@ -331,13 +334,17 @@ static Py_ssize_t CacheMapLen(PyObject *Self) } static char *doc_PkgCache = "Cache([progress]) -> Cache() object.\n\n" - "The cache provides access to the packages and other stuff.\n\n" + "The APT cache file contains a hash table mapping names of binary\n" + "packages to their metadata. A Cache object is the in-core\n" + "representation of the same. It provides access to APT’s idea of the\n" + "list of available packages.\n" "The optional parameter *progress* can be used to specify an \n" - "apt.progress.OpProgress() object (or similar) which displays\n" - "the opening progress. If not specified, the progress is\n" - "displayed in simple text form.\n\n" - "The cache can be used like a mapping of package names to Package\n" - "objects."; + "apt.progress.base.OpProgress() object (or similar) which reports\n" + "progress information while the cache is being opened. If this\n" + "parameter is not supplied, the progress will be reported in simple,\n" + "human-readable text to standard output.\n\n" + "The cache can be used like a mapping from package names to Package\n" + "objects (although only getting items is supported)."; static PySequenceMethods CacheSeq = {0,0,0,0,0,0,0,CacheContains,0,0}; static PyMappingMethods CacheMap = {CacheMapLen,CacheMapOp,0}; PyTypeObject PyCache_Type = @@ -568,17 +575,17 @@ static PyGetSetDef PackageGetSet[] = { {"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."}, + "where 'version' is an apt_pkg.Version object."}, {"selected_state",PackageGetSelectedState,0, - "The state of the selection; can be compared against the constants\n" + "The state of the selection, which 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" + "The state of the install, which 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" + "The current state, which 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."}, @@ -591,7 +598,7 @@ static PyGetSetDef PackageGetSet[] = { "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."}, + "flag set ('Important: yes' in the Packages file). No longer used."}, {"version_list",PackageGetVersionList,0, "A list of all apt_pkg.Version objects for this package."}, {"current_ver",PackageGetCurrentVer,0, @@ -949,12 +956,12 @@ static PyGetSetDef VersionGetSet[] = { "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" + "are 3-tuples of the form (name, version, operator); where 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" + "A list of tuples (packagefile: 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, @@ -966,13 +973,13 @@ static PyGetSetDef VersionGetSet[] = { {"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 priority of the package as an integer, which can be compared to\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" + "A list of all packages provided by this version. See\n" "Package.provides_list for a description of the format."}, {"section",VersionGetSection,0, "The section of this package version."}, @@ -1138,8 +1145,8 @@ static PyGetSetDef PackageFileGetSet[] = { {"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." }, + "Whether this package file lacks an active (sources.list) source;" + "packages listed in such a file cannot be downloaded."}, {"origin",PackageFile_GetOrigin,0, "The origin set in the release file."}, {"site",PackageFile_GetSite,0, @@ -1147,7 +1154,7 @@ static PyGetSetDef PackageFileGetSet[] = { {"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" + "The version set in the release file (e.g. '5.0.X' for lenny, where X\n" "is a point release)."}, {} }; @@ -1320,7 +1327,7 @@ static PyGetSetDef DependencyGetSet[] = { {"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"}, + "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, diff --git a/python/cdrom.cc b/python/cdrom.cc index 022a4b00..7f89e9d3 100644 --- a/python/cdrom.cc +++ b/python/cdrom.cc @@ -30,7 +30,7 @@ static char *cdrom_add_doc = "add(progress: apt_pkg.CdromProgress) -> bool\n\n" - "Add the given CD-ROM to the sources.list. Returns True on success, may\n" + "Add the given CD-ROM to the sources.list. Return True on success;\n" "raise an error on failure or return False."; static PyObject *cdrom_add(PyObject *Self,PyObject *Args) { @@ -51,8 +51,11 @@ static PyObject *cdrom_add(PyObject *Self,PyObject *Args) static char *cdrom_ident_doc = "ident(progress: apt_pkg.CdromProgress) -> str\n\n" - "Try to identify the CD-ROM and if successful return the identity as a\n" - "string. Otherwise, return None or raise an error."; + "Try to identify the CD-ROM and if successful return the hexadecimal\n" + "CDROM-ID (and a integer version suffix seperated by -) as a\n" + "string. Otherwise, return None or raise an error.\n\n" + "The ID is created by hashing all file and directory names on the\n" + "CD-ROM and appending the version."; static PyObject *cdrom_ident(PyObject *Self,PyObject *Args) { pkgCdrom &Cdrom = GetCpp(Self); diff --git a/python/configuration.cc b/python/configuration.cc index 1aff56fb..7c9ed7bc 100644 --- a/python/configuration.cc +++ b/python/configuration.cc @@ -51,7 +51,7 @@ static const char *doc_FindFile = "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" + "return value. For example, for:\n" "\n" " apt_pkg.config['Dir'] = 'a'\n" " apt_pkg.config['Dir::D'] = 'b'\n" @@ -85,7 +85,7 @@ static PyObject *CnfFindDir(PyObject *Self,PyObject *Args) static const char *doc_FindI = "find_i(key: str[, default: int = 0]) -> int\n\n" - "Same as find, but only for integer values."; + "Same as find, but for integer values."; static PyObject *CnfFindI(PyObject *Self,PyObject *Args) { char *Name = 0; @@ -97,7 +97,7 @@ static PyObject *CnfFindI(PyObject *Self,PyObject *Args) static const char *doc_FindB = "find_i(key: str[, default: bool = False]) -> bool\n\n" - "Same as find, but only for boolean values."; + "Same as find, but for boolean values; returns False on unknown values."; static PyObject *CnfFindB(PyObject *Self,PyObject *Args) { char *Name = 0; @@ -110,7 +110,7 @@ static PyObject *CnfFindB(PyObject *Self,PyObject *Args) 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" + "encode them using str(value) and then use find_i()/find_b()\n" "to retrieve their value again."; static PyObject *CnfSet(PyObject *Self,PyObject *Args) { @@ -142,7 +142,7 @@ static int CnfContains(PyObject *Self,PyObject *Arg) static const char *doc_Clear = "clear(key: str)\n\n" - "Unset the option at the given key and all sub options."; + "Remove the specified option and all sub-options."; static PyObject *CnfClear(PyObject *Self,PyObject *Args) { char *Name = 0; @@ -158,8 +158,9 @@ static PyObject *CnfClear(PyObject *Self,PyObject *Args) // The amazing narrowing search ability! 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" + + "Return a new apt_pkg.Configuration object with the given option\n" + "as its root. Example:\n\n" " apttree = config.subtree('APT')\n" " apttree['Install-Suggests'] = config['APT::Install-Suggests']"; static PyObject *CnfSubTree(PyObject *Self,PyObject *Args) @@ -181,7 +182,12 @@ static PyObject *CnfSubTree(PyObject *Self,PyObject *Args) // Return a list of items at a specific level static char *doc_List = "list([root: str]) -> list\n\n" - "Return a list of all items at the given root."; + "Return a list of all items at the given root, using their full\n" + "name. For example, in a configuration object where the options A,\n" + "B, and B::C are set, the following expressions evaluate to True:\n\n" + " conf.list() == ['A', 'B']\n" + " conf.list('A') == ['']\n" + " conf.list('B') == ['B::C']\n"; static PyObject *CnfList(PyObject *Self,PyObject *Args) { char *RootName = 0; @@ -324,8 +330,8 @@ static int CnfMapSet(PyObject *Self,PyObject *Arg,PyObject *Val) // Config file loaders /*{{{*/ 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."; + "Read the configuration file 'filename' and set the appropriate\n" + "options in the configuration object."; PyObject *LoadConfig(PyObject *Self,PyObject *Args) { char *Name = 0; @@ -403,7 +409,8 @@ char *doc_ParseCommandLine = "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."; +"in python-apt-doc and its tutorial on writing an apt-cdrom clone for more\n" +"details."; PyObject *ParseCommandLine(PyObject *Self,PyObject *Args) { PyObject *POList; @@ -531,11 +538,13 @@ 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."; + "Represent the configuration of APT by mapping option keys to\n" + "values and storing configuration parsed from files like\n" + "/etc/apt/apt.conf. The most important Configuration object\n" + "is apt_pkg.config which points to the global configuration\n" + "object. Other top-level Configuration objects can be created\n" + "by calling the constructor, but there is usually no reason to."; + PyTypeObject PyConfiguration_Type = { PyVarObject_HEAD_INIT(&PyType_Type, 0) diff --git a/python/depcache.cc b/python/depcache.cc index a9627037..cd098f2f 100644 --- a/python/depcache.cc +++ b/python/depcache.cc @@ -380,7 +380,6 @@ static PyObject *PkgDepCacheMarkAuto(PyObject *Self,PyObject *Args) return HandleErrors(Py_None); } - static PyObject *PkgDepCacheIsUpgradable(PyObject *Self,PyObject *Args) { pkgDepCache *depcache = GetCpp(Self); @@ -544,7 +543,8 @@ static PyMethodDef PkgDepCacheMethods[] = { {"init",PkgDepCacheInit,METH_VARARGS, "init(progress: apt.progress.base.OpProgress)\n\n" - "Initialize the depcache (done on construct automatically)"}, + "Initialize the depcache (done automatically when constructing\n" + "the object)."}, {"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" @@ -574,7 +574,7 @@ static PyMethodDef PkgDepCacheMethods[] = // Manipulators {"mark_keep",PkgDepCacheMarkKeep,METH_VARARGS, "mark_keep(pkg: apt_pkg.Package)\n\n" - "Mark package for keep"}, + "Mark package to be kept."}, {"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."}, @@ -590,7 +590,7 @@ static PyMethodDef PkgDepCacheMethods[] = "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)."}, + "Set whether the package should be reinstalled (reinstall = True or False)."}, // state information {"is_upgradable",PkgDepCacheIsUpgradable,METH_VARARGS, "is_upgradable(pkg: apt_pkg.Package) -> bool\n\n" @@ -684,7 +684,7 @@ static PyGetSetDef PkgDepCacheGetSet[] = { {"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."}, + "minus the Installed-Size of all packages for removal."}, {"policy",PkgDepCacheGetPolicy,0, "The apt_pkg.Policy object used by this cache."}, {} @@ -967,7 +967,11 @@ PyTypeObject PyProblemResolver_Type = // pkgActionGroup Class /*{{{*/ // --------------------------------------------------------------------- - +static const char *actiongroup_release_doc = + "release()\n\n" + "End the scope of this action group. If this is the only action\n" + "group bound to the cache, this will cause any deferred cleanup\n" + "actions to be performed."; static PyObject *PkgActionGroupRelease(PyObject *Self,PyObject *Args) { pkgDepCache::ActionGroup *ag = GetCpp(Self); @@ -978,11 +982,19 @@ static PyObject *PkgActionGroupRelease(PyObject *Self,PyObject *Args) return HandleErrors(Py_None); } +static const char *actiongroup__enter__doc = + "__enter__() -> ActionGroup\n\n" + "A dummy action which just returns the object itself, so it can\n" + "be used as a context manager."; static PyObject *PkgActionGroupEnter(PyObject *Self,PyObject *Args) { if (PyArg_ParseTuple(Args,"") == 0) return 0; return Self; } + +static const char *actiongroup__exit__doc = + "__exit__(*excinfo) -> bool\n\n" + "Same as release(), but for use as a context manager."; static PyObject *PkgActionGroupExit(PyObject *Self,PyObject *Args) { pkgDepCache::ActionGroup *ag = GetCpp(Self); ag->release(); @@ -991,11 +1003,9 @@ static PyObject *PkgActionGroupExit(PyObject *Self,PyObject *Args) { static PyMethodDef PkgActionGroupMethods[] = { - {"release", PkgActionGroupRelease, METH_VARARGS, "release()"}, - {"__exit__", PkgActionGroupExit, METH_VARARGS, "__exit__(...) -> " - "Release the action group, for 'with' statement."}, - {"__enter__", PkgActionGroupEnter, METH_VARARGS, "__enter__() -> " - "Enter, for the 'with' statement. Does nothing."}, + {"release", PkgActionGroupRelease, METH_VARARGS, actiongroup_release_doc}, + {"__enter__", PkgActionGroupEnter, METH_VARARGS, actiongroup__enter__doc}, + {"__exit__", PkgActionGroupExit, METH_VARARGS, actiongroup__exit__doc}, {} }; diff --git a/python/hashes.cc b/python/hashes.cc index d0b0fb0c..8cc86f4e 100644 --- a/python/hashes.cc +++ b/python/hashes.cc @@ -88,9 +88,8 @@ static char *hashes_doc = "Hashes([object: (bytes, file)])\n\n" "Calculate hashes for the given object. It can be used to create all\n" "supported hashes for a file.\n\n" - "The parameter *object* can be a bytes (3.X) / str (2.X) object, or an\n" - "object providing the fileno() method or an integer describing a file\n" - "descriptor."; + "The parameter 'object' can be a bytestring, an object providing the\n" + "fileno() method, or an integer describing a file descriptor."; PyTypeObject PyHashes_Type = { PyVarObject_HEAD_INIT(&PyType_Type, 0) diff --git a/python/indexrecords.cc b/python/indexrecords.cc index c5ebcfbc..d6a3263c 100644 --- a/python/indexrecords.cc +++ b/python/indexrecords.cc @@ -46,9 +46,9 @@ static PyObject *indexrecords_load(PyObject *self,PyObject *args) 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."; + "Look up the filename given by 'key' and return a tuple (hash, size),\n" + "where the first element 'hash' is an apt_pkg.HashString object\n" + "and the second element 'size' is an int object."; static PyObject *indexrecords_lookup(PyObject *self,PyObject *args) { const char *keyname; diff --git a/python/lock.cc b/python/lock.cc index fc78c0cb..2c957df1 100644 --- a/python/lock.cc +++ b/python/lock.cc @@ -78,11 +78,11 @@ static char *systemlock_doc = "SystemLock()\n\n" "Context manager for locking the package system. The lock is established\n" "as soon as the method __enter__() is called. It is released when\n" "__exit__() is called.\n\n" - "This should be used via the 'with' statement, e.g.::\n\n" + "This should be used via the 'with' statement, for example:\n\n" " with apt_pkg.SystemLock():\n" " ...\n\n" "Once the block is left, the lock is released automatically. The object\n" - "can be used multiple times::\n\n" + "can be used multiple times:\n\n" " lock = apt_pkg.SystemLock()\n" " with lock:\n" " ...\n" @@ -210,11 +210,11 @@ static char *filelock_doc = "SystemLock(filename: str)\n\n" "Context manager for locking using a file. The lock is established\n" "as soon as the method __enter__() is called. It is released when\n" "__exit__() is called.\n\n" - "This should be used via the 'with' statement, e.g.::\n\n" + "This should be used via the 'with' statement, for example:\n\n" " with apt_pkg.FileLock(filename):\n" " ...\n\n" "Once the block is left, the lock is released automatically. The object\n" - "can be used multiple times::\n\n" + "can be used multiple times:\n\n" " lock = apt_pkg.FileLock(filename)\n" " with lock:\n" " ...\n" diff --git a/python/metaindex.cc b/python/metaindex.cc index 66aa76fb..a00cf04e 100644 --- a/python/metaindex.cc +++ b/python/metaindex.cc @@ -71,9 +71,8 @@ static PyObject *MetaIndexRepr(PyObject *Self) 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."; + "Provide information on meta-indexes (i.e. Release files), such as\n" + "whether they are trusted or their URI."; PyTypeObject PyMetaIndex_Type = { diff --git a/python/pkgmanager.cc b/python/pkgmanager.cc index b501ee1a..95e8c27e 100644 --- a/python/pkgmanager.cc +++ b/python/pkgmanager.cc @@ -105,9 +105,9 @@ static PyMethodDef PkgManagerMethods[] = "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" + "status_fd can be used to specify a file descriptor that APT will\n" "write status information on (see README.progress-reporting in the\n" - "apt source code for information what is written there)."}, + "apt source code for information on what will be written there)."}, {"fix_missing",PkgManagerFixMissing,METH_VARARGS, "fix_missing() -> bool\n\n" "Fix the installation if a package could not be downloaded."}, diff --git a/python/pkgsrcrecords.cc b/python/pkgsrcrecords.cc index 108eff7f..aad3ef7e 100644 --- a/python/pkgsrcrecords.cc +++ b/python/pkgsrcrecords.cc @@ -36,9 +36,9 @@ struct PkgSrcRecordsStruct static char *doc_PkgSrcRecordsLookup = "lookup(name: str) -> bool\n\n" - "Lookup the source package with the given name. Each call moves\n" + "Look up 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" + "more records, 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) { @@ -231,7 +231,7 @@ static PyGetSetDef PkgSrcRecordsGetSet[] = { {"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" + "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" diff --git a/python/policy.cc b/python/policy.cc index 40da931f..7eccb30c 100644 --- a/python/policy.cc +++ b/python/policy.cc @@ -115,9 +115,9 @@ static PyObject *policy_read_pindir(PyObject *self, PyObject *arg) { 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" - "e.g. unstable for type='Release' and the other possible options. \n" + "strings 'Version', 'Release', or 'Origin'. The argument 'pkg' is the\n" + "name of the package. The parameter 'data' refers to the value\n" + "(e.g. 'unstable' for type='Release') and the other possible options.\n" "The parameter 'priority' gives the priority of the pin."; static PyObject *policy_create_pin(PyObject *self, PyObject *args) { diff --git a/python/tag.cc b/python/tag.cc index 99bb9b55..9fe12a1a 100644 --- a/python/tag.cc +++ b/python/tag.cc @@ -113,7 +113,7 @@ static PyObject *TagSecFind(PyObject *Self,PyObject *Args) 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" + "Same as find(), but returns the complete 'key: value' field; instead of\n" "just the value."; static PyObject *TagSecFindRaw(PyObject *Self,PyObject *Args) { @@ -139,7 +139,7 @@ static PyObject *TagSecFindRaw(PyObject *Self,PyObject *Args) 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" + "Return 1 if the key's value 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) @@ -324,9 +324,9 @@ static PyObject *TagFileOffset(PyObject *Self,PyObject *Args) 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."; + "Jump to the given offset; return True on success. Note that jumping to\n" + "an offset is not very reliable, and the 'section' attribute may point\n" + "to an unexpected section."; static PyObject *TagFileJump(PyObject *Self,PyObject *Args) { int Offset; @@ -431,7 +431,7 @@ char *doc_RewriteSection = "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" +"'(tag, newvalue[, renamed_to])', where '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."; @@ -511,8 +511,8 @@ PyMappingMethods TagSecMapMeth = {TagSecLength,TagSecMap,0}; 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" + "Provide methods to access RFC822-style header sections, like those\n" + "found 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)"; PyTypeObject PyTagSection_Type = @@ -586,13 +586,14 @@ static PyGetSetDef TagFileGetSet[] = { 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" + "TagFile() objects provide access to debian control files, which consist\n" + "of multiple RFC822-style sections.\n\n" "To provide access to those sections, TagFile objects provide an iterator\n" "which yields TagSection objects for each section.\n\n" "TagFile objects also provide another API which uses a shared TagSection\n" "object in the 'section' member. The functions step() and jump() can be\n" - "used to navigate in the file; and offset() tells the current position.\n\n" + "used to navigate within the file; offset() returns the current\n" + "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" diff --git a/python/tarfile.cc b/python/tarfile.cc index 6363af0f..215d3a8c 100644 --- a/python/tarfile.cc +++ b/python/tarfile.cc @@ -235,7 +235,7 @@ static PyMethodDef tarmember_methods[] = { {"ischr",tarmember_ischr,METH_NOARGS, "Determine whether the member is a character device."}, {"isdev",tarmember_isdev,METH_NOARGS, - "Determine whether the member is a device (block,character or FIFO)."}, + "Determine whether the member is a device (block, character or FIFO)."}, {"isdir",tarmember_isdir,METH_NOARGS, "Determine whether the member is a directory."}, {"isfifo",tarmember_isfifo,METH_NOARGS, @@ -252,7 +252,7 @@ static PyMethodDef tarmember_methods[] = { }; static PyGetSetDef tarmember_getset[] = { - {"gid",tarmember_get_gid,0,"The owner's group id"}, + {"gid",tarmember_get_gid,0,"The owner's group ID."}, {"linkname",tarmember_get_linkname,0,"The target of the link."}, {"major",tarmember_get_major,0,"The major ID of the device."}, {"minor",tarmember_get_minor,0,"The minor ID of the device."}, @@ -260,7 +260,7 @@ static PyGetSetDef tarmember_getset[] = { {"mtime",tarmember_get_mtime,0,"Last time of modification."}, {"name",tarmember_get_name,0,"The name of the file."}, {"size",tarmember_get_size,0,"The size of the file."}, - {"uid",tarmember_get_uid,0,"The owner's user id."}, + {"uid",tarmember_get_uid,0,"The owner's user ID."}, {NULL} }; @@ -375,11 +375,11 @@ static PyObject *tarfile_extractall(PyObject *self, PyObject *args) static const char *tarfile_go_doc = "go(callback: callable[, member: str]) -> True\n\n" - "Go through the archive and call the callable callback for each\n" + "Go through the archive and call the callable 'callback' for each\n" "member with 2 arguments. The first argument is the TarMember and\n" "the second one is the data, as bytes.\n\n" "The optional parameter 'member' can be used to specify the member for\n" - "which call the callback. If not specified, it will be called for all\n" + "which to call the callback. If not specified, it will be called for all\n" "members. If specified and not found, LookupError will be raised."; static PyObject *tarfile_go(PyObject *self, PyObject *args) { -- cgit v1.2.3