From 506cb021d62e643fba38ddb4b84572a86cb3a3ba Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Mon, 13 Apr 2009 18:27:43 +0200 Subject: * python/tag.cc: Support 'key in mapping' for TagSections Support the replacement of mapping.has_key() for sections, and update the usage in apt/package.py and apt/debfile accordingly. This is implemented by extending the TagSecType with sequence methods, but only settings the contains method there. The TagSecGetAttr() function has been removed and replaced by the use of the tp_methods slot. --- doc/source/apt_pkg/cache.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc/source/apt_pkg/cache.rst') diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index af67d82f..146c2c2a 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -1199,6 +1199,10 @@ broken dependencies: Return the value of the field at *key*. If *key* is not available, raise :exc:`KeyError`. + .. describe:: key in section + + Return ``True`` if *section* has a key *key*, else ``False``. + .. method:: Bytes The number of bytes in the section. -- cgit v1.2.3 From ccd98916ba50c7583f354e0d3487ffb0830103f0 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Mon, 13 Apr 2009 20:00:09 +0200 Subject: * python/configuration.cc: Support the 'in' operator for Configuration Support the replacement of mapping.has_key() for Configuration,ConfigurationPtr and ConfigurationSub objects. This is implemented by extending the various types with the tp_as_sequence slot, which refers to a PySequenceMethods containing only this method. The CnfGetAttr() function has been removed and replaced by the use of the tp_method slot. This helps the py3k port because the previously used Py_FindMethod() is not avilable anymore. This completes the support of the 'in' operator in all python-apt objects, which makes it even easier to convert python-apt-using applications to py3k once python-apt supports it, as 2to3 converts 'm.has_key(k)' to 'k in m'. Also finalize the types in apt_pkgmodule.cc and add the new 'key in conf' description to the documentation. --- debian/changelog | 4 +-- doc/source/apt_pkg/cache.rst | 4 +++ python/apt_pkgmodule.cc | 3 ++ python/configuration.cc | 70 ++++++++++++++++++++++++++++++++++---------- 4 files changed, 64 insertions(+), 17 deletions(-) (limited to 'doc/source/apt_pkg/cache.rst') diff --git a/debian/changelog b/debian/changelog index 29927989..261ff7bd 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,7 +1,7 @@ python-apt (0.7.11) UNRELEASED; urgency=low - * python/tag.cc: - - Support 'key in mapping' for TagSections + * Support the 'in' operator (e.g. "k in d") in Configuration{,Ptr,Sub} + objects (e.g. apt_pkg.Config) and in TagSections (apt_pkg.ParseSection()) * Replace support for file objects with a more generic support for any object providing a fileno() method and for file descriptors (integers). * Add support for the Breaks fields diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 146c2c2a..3ecbf069 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -117,6 +117,10 @@ Classes in apt_pkg The Configuration objects store the configuration of apt. + .. describe:: key in conf + + Return ``True`` if *conf* has a key *key*, else ``False``. + .. describe:: conf[key] Return the value of the option given key *key*. If it does not diff --git a/python/apt_pkgmodule.cc b/python/apt_pkgmodule.cc index 10d98911..3d043179 100644 --- a/python/apt_pkgmodule.cc +++ b/python/apt_pkgmodule.cc @@ -475,6 +475,9 @@ extern "C" void initapt_pkg() // Finalize our types to add slots, etc. if (PyType_Ready(&TagSecType) == -1) return; if (PyType_Ready(&TagFileType) == -1) return; + if (PyType_Ready(&ConfigurationType) == -1) return; + if (PyType_Ready(&ConfigurationPtrType) == -1) return; + if (PyType_Ready(&ConfigurationSubType) == -1) return; // Initialize the module PyObject *Module = Py_InitModule("apt_pkg",methods); diff --git a/python/configuration.cc b/python/configuration.cc index 21f70bc1..a95ac029 100644 --- a/python/configuration.cc +++ b/python/configuration.cc @@ -128,6 +128,11 @@ static PyObject *CnfExists(PyObject *Self,PyObject *Args) return Py_BuildValue("i",(int)GetSelf(Self).Exists(Name)); } +static int CnfContains(PyObject *Self,PyObject *Arg) +{ + return (int)GetSelf(Self).Exists(PyString_AsString(Arg)); +} + static char *doc_Clear = "Clear(Name) -> None"; static PyObject *CnfClear(PyObject *Self,PyObject *Args) { @@ -470,34 +475,41 @@ static PyMethodDef CnfMethods[] = {} }; -// CnfGetAttr - Get an attribute - variable/method /*{{{*/ -// --------------------------------------------------------------------- -/* */ -static PyObject *CnfGetAttr(PyObject *Self,char *Name) -{ - return Py_FindMethod(CnfMethods,Self,Name); -} - // 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}; PyTypeObject ConfigurationType = { PyObject_HEAD_INIT(&PyType_Type) - 0, // ob_size + 0, // ob_size "Configuration", // tp_name sizeof(CppPyObject), // tp_basicsize 0, // tp_itemsize // Methods CppDealloc, // tp_dealloc 0, // tp_print - CnfGetAttr, // tp_getattr + 0, // tp_getattr 0, // tp_setattr 0, // tp_compare 0, // tp_repr 0, // tp_as_number - 0, // tp_as_sequence + &ConfigurationSeq, // tp_as_sequence &ConfigurationMap, // tp_as_mapping 0, // tp_hash + 0, // tp_call + 0, // tp_str + 0, // tp_getattro + 0, // tp_setattro + 0, // tp_as_buffer + Py_TPFLAGS_DEFAULT, // tp_flags + "Configuration Object", // tp_doc + 0, // tp_traverse + 0, // tp_clear + 0, // tp_richcompare + 0, // tp_weaklistoffset + 0, // tp_iter + 0, // tp_iternext + CnfMethods, // tp_methods }; PyTypeObject ConfigurationPtrType = @@ -510,14 +522,28 @@ PyTypeObject ConfigurationPtrType = // Methods (destructor)PyObject_Free, // tp_dealloc 0, // tp_print - CnfGetAttr, // tp_getattr + 0, // tp_getattr 0, // tp_setattr 0, // tp_compare 0, // tp_repr 0, // tp_as_number - 0, // tp_as_sequence + &ConfigurationSeq, // tp_as_sequence &ConfigurationMap, // tp_as_mapping 0, // tp_hash + 0, // tp_call + 0, // tp_str + 0, // tp_getattro + 0, // tp_setattro + 0, // tp_as_buffer + Py_TPFLAGS_DEFAULT, // tp_flags + "ConfigurationPtr Object", // tp_doc + 0, // tp_traverse + 0, // tp_clear + 0, // tp_richcompare + 0, // tp_weaklistoffset + 0, // tp_iter + 0, // tp_iternext + CnfMethods, // tp_methods }; PyTypeObject ConfigurationSubType = @@ -530,13 +556,27 @@ PyTypeObject ConfigurationSubType = // Methods CnfSubFree, // tp_dealloc 0, // tp_print - CnfGetAttr, // tp_getattr + 0, // tp_getattr 0, // tp_setattr 0, // tp_compare 0, // tp_repr 0, // tp_as_number - 0, // tp_as_sequence + &ConfigurationSeq, // tp_as_sequence &ConfigurationMap, // tp_as_mapping 0, // tp_hash + 0, // tp_call + 0, // tp_str + 0, // tp_getattro + 0, // tp_setattro + 0, // tp_as_buffer + Py_TPFLAGS_DEFAULT, // tp_flags + "ConfigurationSub Object", // tp_doc + 0, // tp_traverse + 0, // tp_clear + 0, // tp_richcompare + 0, // tp_weaklistoffset + 0, // tp_iter + 0, // tp_iternext + CnfMethods, // tp_methods }; -- cgit v1.2.3 From 8d59817045630f8cf695f9673bde484727189a49 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Mon, 13 Apr 2009 20:19:03 +0200 Subject: * doc/source/apt_pkg/cache.rst: Add .. versionadded:: 0.7.11 to the documentation --- doc/source/apt_pkg/cache.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc/source/apt_pkg/cache.rst') diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 3ecbf069..93f8dc2d 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -121,6 +121,8 @@ Classes in apt_pkg Return ``True`` if *conf* has a key *key*, else ``False``. + .. versionadded:: 0.7.11 + .. describe:: conf[key] Return the value of the option given key *key*. If it does not @@ -1207,6 +1209,8 @@ broken dependencies: Return ``True`` if *section* has a key *key*, else ``False``. + .. versionadded:: 0.7.11 + .. method:: Bytes The number of bytes in the section. -- cgit v1.2.3 From ae7f143f8162d10c7bd834e8877e42674fdb646f Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Mon, 13 Apr 2009 22:37:20 +0200 Subject: * doc: Documentation updates Extended the documentation, renamed 'Coding for python-apt' to 'Contributing to python-apt' and other stuff. --- apt/package.py | 221 +++++++++++++++++++++++++++------------- doc/source/apt_inst.rst | 40 ++++++-- doc/source/apt_pkg/cache.rst | 4 + doc/source/apt_pkg/index.rst | 233 ++++++++++++++++++++++++++++++++++--------- doc/source/coding.rst | 168 ------------------------------- doc/source/contributing.rst | 160 +++++++++++++++++++++++++++++ doc/source/index.rst | 2 +- 7 files changed, 535 insertions(+), 293 deletions(-) delete mode 100644 doc/source/coding.rst create mode 100644 doc/source/contributing.rst (limited to 'doc/source/apt_pkg/cache.rst') diff --git a/apt/package.py b/apt/package.py index e308da4b..5adef15c 100644 --- a/apt/package.py +++ b/apt/package.py @@ -42,7 +42,7 @@ def _(string): def _file_is_same(path, size, md5): - """Return True if the file is the same.""" + """Return ``True`` if the file is the same.""" if (os.path.exists(path) and os.path.getsize(path) == size and apt_pkg.md5sum(open(path)) == md5): return True @@ -96,7 +96,7 @@ class DeprecatedProperty(property): def __init__(self, fget=None, fset=None, fdel=None, doc=None): property.__init__(self, fget, fset, fdel, doc) - self.__doc__ = ':Deprecated: ' + (doc or fget.__doc__ or '') + self.__doc__ = (doc or fget.__doc__ or '') def __get__(self, obj, type=None): if obj is not None: @@ -168,21 +168,21 @@ class Record(object): yield key, self._rec[key] def get(self, key, default=None): - """Return record[key] if key in record, else `default`. + """Return record[key] if key in record, else *default*. - The parameter `default` must be either a string or None. + The parameter *default* must be either a string or None. """ return self._rec.get(key, default) def has_key(self, key): - """deprecated form of 'key in x'.""" + """deprecated form of ``key in x``.""" return key in self._rec class Version(object): """Representation of a package version. - :since: 0.7.9 + .. versionadded:: 0.7.9 """ def __init__(self, package, cand): @@ -352,26 +352,41 @@ class Version(object): @property def filename(self): - """Return the path to the file inside the archive.""" + """Return the path to the file inside the archive. + + .. versionadded:: 0.7.10 + """ return self._records.FileName @property def md5(self): - """Return the md5sum of the binary.""" + """Return the md5sum of the binary. + + .. versionadded:: 0.7.10 + """ return self._records.MD5Hash @property def sha1(self): - """Return the sha1sum of the binary.""" + """Return the sha1sum of the binary. + + .. versionadded:: 0.7.10 + """ return self._records.SHA1Hash @property def sha256(self): - """Return the sha1sum of the binary.""" + """Return the sha256sum of the binary. + + .. versionadded:: 0.7.10 + """ return self._records.SHA256Hash def _uris(self): - """Return an iterator over all available urls.""" + """Return an iterator over all available urls. + + .. versionadded:: 0.7.10 + """ for (packagefile, index) in self._cand.FileList: indexfile = self.package._pcache._list.FindIndex(packagefile) if indexfile: @@ -379,23 +394,31 @@ class Version(object): @property def uris(self): - """Return a list of all available uris for the binary.""" + """Return a list of all available uris for the binary. + + .. versionadded:: 0.7.10 + """ return list(self._uris()) @property def uri(self): - """Return a single URI for the binary.""" + """Return a single URI for the binary. + + .. versionadded:: 0.7.10 + """ return self._uris().next() def fetch_binary(self, destdir='', progress=None): """Fetch the binary version of the package. - The parameter 'destdir' specifies the directory where the package will + The parameter *destdir* specifies the directory where the package will be fetched to. - The parameter 'progress' may refer to an apt.progress.FetchProgress() + The parameter *progress* may refer to an apt.progress.FetchProgress() object. If not specified or None, apt.progress.TextFetchProgress() is used. + + .. versionadded:: 0.7.10 """ base = os.path.basename(self._records.FileName) destfile = os.path.join(destdir, base) @@ -415,18 +438,18 @@ class Version(object): def fetch_source(self, destdir="", progress=None, unpack=True): """Get the source code of a package. - The parameter 'destdir' specifies the directory where the source will + The parameter *destdir* specifies the directory where the source will be fetched to. - The parameter 'progress' may refer to an apt.progress.FetchProgress() + The parameter *progress* may refer to an apt.progress.FetchProgress() object. If not specified or None, apt.progress.TextFetchProgress() is used. - The parameter 'unpack' describes whether the source should be unpacked - (True) or not (False). By default, it is unpacked. + The parameter *unpack* describes whether the source should be unpacked + (``True``) or not (``False``). By default, it is unpacked. - If 'unpack' is True, the path to the extracted directory is returned. - Otherwise, the path to the .dsc file is returned. + If *unpack* is ``True``, the path to the extracted directory is + returned. Otherwise, the path to the .dsc file is returned. """ src = apt_pkg.GetPkgSrcRecords() acq = apt_pkg.GetAcquire(progress or apt.progress.TextFetchProgress()) @@ -490,7 +513,8 @@ class Package(object): def candidate(self): """Return the candidate version of the package. - :since: 0.7.9""" + .. versionadded:: 0.7.9 + """ cand = self._pcache._depcache.GetCandidateVer(self._pkg) if cand is not None: return Version(self, cand) @@ -499,7 +523,8 @@ class Package(object): def installed(self): """Return the currently installed version of the package. - :since: 0.7.9""" + .. versionadded:: 0.7.9 + """ if self._pkg.CurrentVer is not None: return Version(self, self._pkg.CurrentVer) @@ -525,42 +550,62 @@ class Package(object): def installedVersion(self): """Return the installed version as string. - Deprecated, please use installed.version instead.""" + .. deprecated:: 0.7.9""" return getattr(self.installed, 'version', None) @DeprecatedProperty def candidateVersion(self): - """Return the candidate version as string.""" + """Return the candidate version as string. + + .. deprecated:: 0.7.9""" return getattr(self.candidate, "version", None) @DeprecatedProperty def candidateDependencies(self): - """Return a list of candidate dependencies.""" + """Return a list of candidate dependencies. + + .. deprecated:: 0.7.9 + """ return getattr(self.candidate, "dependencies", None) @DeprecatedProperty def installedDependencies(self): - """Return a list of installed dependencies.""" + """Return a list of installed dependencies. + + .. deprecated:: 0.7.9 + """ return getattr(self.installed, 'dependencies', []) @DeprecatedProperty def architecture(self): - """Return the Architecture of the package""" + """Return the Architecture of the package. + + .. deprecated:: 0.7.9 + """ return getattr(self.candidate, "architecture", None) @DeprecatedProperty def candidateDownloadable(self): - """Return True if the candidate is downloadable.""" + """Return ``True`` if the candidate is downloadable. + + .. deprecated:: 0.7.9 + """ return getattr(self.candidate, "downloadable", None) @DeprecatedProperty def installedDownloadable(self): - """Return True if the installed version is downloadable.""" + """Return ``True`` if the installed version is downloadable. + + .. deprecated:: 0.7.9 + """ return getattr(self.installed, 'downloadable', False) @DeprecatedProperty def sourcePackageName(self): - """Return the source package name as string.""" + """Return the source package name as string. + + .. deprecated:: 0.7.9 + """ try: return self.candidate._records.SourcePkg or self._pkg.Name except AttributeError: @@ -571,7 +616,10 @@ class Package(object): @DeprecatedProperty def homepage(self): - """Return the homepage field as string.""" + """Return the homepage field as string. + + .. deprecated:: 0.7.9 + """ return getattr(self.candidate, "homepage", None) @property @@ -581,17 +629,27 @@ class Package(object): @DeprecatedProperty def priority(self): - """Return the priority (of the candidate version).""" + """Return the priority (of the candidate version). + + .. deprecated:: 0.7.9 + """ return getattr(self.candidate, "priority", None) @DeprecatedProperty def installedPriority(self): - """Return the priority (of the installed version).""" + """Return the priority (of the installed version). + + + .. deprecated:: 0.7.9 + """ return getattr(self.installed, 'priority', None) @DeprecatedProperty def summary(self): - """Return the short description (one line summary).""" + """Return the short description (one line summary). + + .. deprecated:: 0.7.9 + """ return getattr(self.candidate, "summary", None) @DeprecatedProperty @@ -602,44 +660,52 @@ class Package(object): (Chapter 5.6.13). See http://www.debian.org/doc/debian-policy/ch-controlfields.html for more information. + + .. deprecated:: 0.7.9 """ return getattr(self.candidate, "description", None) @DeprecatedProperty def rawDescription(self): - """return the long description (raw).""" + """return the long description (raw). + + .. deprecated:: 0.7.9""" return getattr(self.candidate, "raw_description", None) @DeprecatedProperty def candidateRecord(self): - """Return the Record of the candidate version of the package.""" + """Return the Record of the candidate version of the package. + + .. deprecated:: 0.7.9""" return getattr(self.candidate, "record", None) @DeprecatedProperty def installedRecord(self): - """Return the Record of the candidate version of the package.""" + """Return the Record of the candidate version of the package. + + .. deprecated:: 0.7.9""" return getattr(self.installed, 'record', '') # depcache states @property def markedInstall(self): - """Return True if the package is marked for install.""" + """Return ``True`` if the package is marked for install.""" return self._pcache._depcache.MarkedInstall(self._pkg) @property def markedUpgrade(self): - """Return True if the package is marked for upgrade.""" + """Return ``True`` if the package is marked for upgrade.""" return self._pcache._depcache.MarkedUpgrade(self._pkg) @property def markedDelete(self): - """Return True if the package is marked for delete.""" + """Return ``True`` if the package is marked for delete.""" return self._pcache._depcache.MarkedDelete(self._pkg) @property def markedKeep(self): - """Return True if the package is marked for keep.""" + """Return ``True`` if the package is marked for keep.""" return self._pcache._depcache.MarkedKeep(self._pkg) @property @@ -649,23 +715,23 @@ class Package(object): @property def markedReinstall(self): - """Return True if the package is marked for reinstall.""" + """Return ``True`` if the package is marked for reinstall.""" return self._pcache._depcache.MarkedReinstall(self._pkg) @property def isInstalled(self): - """Return True if the package is installed.""" + """Return ``True`` if the package is installed.""" return (self._pkg.CurrentVer is not None) @property def isUpgradable(self): - """Return True if the package is upgradable.""" + """Return ``True`` if the package is upgradable.""" return (self.isInstalled and self._pcache._depcache.IsUpgradable(self._pkg)) @property def isAutoRemovable(self): - """Return True if the package is no longer required. + """Return ``True`` if the package is no longer required. If the package has been installed automatically as a dependency of another package, and if no packages depend on it anymore, the package @@ -677,22 +743,35 @@ class Package(object): @DeprecatedProperty def packageSize(self): - """Return the size of the candidate deb package.""" + """Return the size of the candidate deb package. + + .. deprecated:: 0.7.9 + """ return getattr(self.candidate, "size", None) @DeprecatedProperty def installedPackageSize(self): - """Return the size of the installed deb package.""" + """Return the size of the installed deb package. + + .. deprecated:: 0.7.9 + """ return getattr(self.installed, 'size', 0) @DeprecatedProperty def candidateInstalledSize(self): - """Return the size of the candidate installed package.""" + """Return the size of the candidate installed package. + + .. deprecated:: 0.7.9 + """ return getattr(self.candidate, "installed_size", None) @DeprecatedProperty def installedSize(self): - """Return the size of the currently installed package.""" + """Return the size of the currently installed package. + + + .. deprecated:: 0.7.9 + """ return getattr(self.installed, 'installed_size', 0) @property @@ -717,15 +796,16 @@ class Package(object): Download the changelog of the package and return it as unicode string. - The parameter `uri` refers to the uri of the changelog file. It may + The parameter *uri* refers to the uri of the changelog file. It may contain multiple named variables which will be substitued. These variables are (src_section, prefix, src_pkg, src_ver). An example is - the Ubuntu changelog: + the Ubuntu changelog:: + "http://changelogs.ubuntu.com/changelogs/pool" \\ "/%(src_section)s/%(prefix)s/%(src_pkg)s" \\ "/%(src_pkg)s_%(src_ver)s/changelog" - The parameter `cancel_lock` refers to an instance of threading.Lock, + The parameter *cancel_lock* refers to an instance of threading.Lock, which if set, prevents the download. """ # Return a cached changelog if available @@ -866,14 +946,17 @@ class Package(object): @DeprecatedProperty def candidateOrigin(self): - """Return a list of Origin() objects for the candidate version.""" + """Return a list of `Origin()` objects for the candidate version. + + .. deprecated:: 0.7.9 + """ return getattr(self.candidate, "origins", None) @property def versions(self): """Return a list of versions. - :since: 0.7.9 + .. versionadded:: 0.7.9 """ return [Version(self, ver) for ver in self._pkg.VersionList] @@ -888,11 +971,11 @@ class Package(object): def markDelete(self, autoFix=True, purge=False): """Mark a package for install. - If autoFix is True, the resolver will be run, trying to fix broken - packages. This is the default. + If *autoFix* is ``True``, the resolver will be run, trying to fix + broken packages. This is the default. - If purge is True, remove the configuration files of the package as - well. The default is to keep the configuration. + If *purge* is ``True``, remove the configuration files of the package + as well. The default is to keep the configuration. """ self._pcache.cachePreChange() self._pcache._depcache.MarkDelete(self._pkg, purge) @@ -909,16 +992,16 @@ class Package(object): def markInstall(self, autoFix=True, autoInst=True, fromUser=True): """Mark a package for install. - If autoFix is True, the resolver will be run, trying to fix broken - packages. This is the default. + If *autoFix* is ``True``, the resolver will be run, trying to fix + broken packages. This is the default. - If autoInst is True, the dependencies of the packages will be installed - automatically. This is the default. + If *autoInst* is ``True``, the dependencies of the packages will be + installed automatically. This is the default. - If fromUser is True, this package will not be marked as automatically - installed. This is the default. Set it to False if you want to be able - to remove the package at a later stage if no other package depends on - it. + If *fromUser* is ``True``, this package will not be marked as + automatically installed. This is the default. Set it to False if you + want to be able to automatically remove the package at a later stage + when no other package depends on it. """ self._pcache.cachePreChange() self._pcache._depcache.MarkInstall(self._pkg, autoInst, fromUser) @@ -942,10 +1025,10 @@ class Package(object): def commit(self, fprogress, iprogress): """Commit the changes. - The parameter `fprogress` refers to a FetchProgress() object, as + The parameter *fprogress* refers to a FetchProgress() object, as found in apt.progress. - The parameter `iprogress` refers to an InstallProgress() object, as + The parameter *iprogress* refers to an InstallProgress() object, as found in apt.progress. """ self._pcache._depcache.Commit(fprogress, iprogress) diff --git a/doc/source/apt_inst.rst b/doc/source/apt_inst.rst index 97705f61..999d074e 100644 --- a/doc/source/apt_inst.rst +++ b/doc/source/apt_inst.rst @@ -11,7 +11,12 @@ Checking packages .. function:: arCheckMember(file, membername) Check if the member specified by the parameter *membername* exists in - the AR file referenced by the :class:`file` object *file*. + the AR file referenced by the parameter *file*, which may be a + :class:`file()` object, a file descriptor, or anything implementing a + :meth:`fileno` method. + + .. versionchanged:: 0.7.11 + Added support for file descriptors and objects implementing a :meth:`fileno` method. Listing contents @@ -19,8 +24,9 @@ Listing contents .. function:: debExtract(file, func, chunk) Call the function referenced by *func* for each member of the tar file - *chunk* which is contained in the AR file referenced by the file object - *file*. + *chunk* which is contained in the AR file referenced by the parameter + *file*, which may be a :class:`file()` object, a file descriptor, or + anything implementing a :meth:`fileno` method. An example would be:: @@ -28,12 +34,21 @@ Listing contents See :ref:`emulating-dpkg-contents` for a more detailed example. + .. versionchanged:: 0.7.11 + Added support for file descriptors and objects implementing a :meth:`fileno` method. + .. function:: tarExtract(file,func,comp) Call the function *func* for each member of the tar file *file*. - *Comp* is a string determining the compressor used. Possible options are - "lzma", "bzip2" and "gzip". + The parameter *comp* is a string determining the compressor used. Possible + options are "lzma", "bzip2" and "gzip". + + The parameter *file* may be a :class:`file()` object, a file descriptor, or + anything implementing a :meth:`fileno` method. + + .. versionchanged:: 0.7.11 + Added support for file descriptors and objects implementing a :meth:`fileno` method. Callback @@ -56,6 +71,9 @@ Extracting contents Extract the archive referenced by the :class:`file` object *file* into the directory specified by *rootdir*. + The parameter *file* may be a :class:`file()` object, a file descriptor, or + anything implementing a :meth:`fileno` method. + See :ref:`emulating-dpkg-extract` for an example. .. warning:: @@ -63,16 +81,24 @@ Extracting contents If the directory given by *rootdir* does not exist, the package is extracted into the current directory. + .. versionchanged:: 0.7.11 + Added support for file descriptors and objects implementing a :meth:`fileno` method. + .. function:: debExtractControl(file[, member='control']) - Return the indicated file from the control tar. The default is 'control'. + Return the indicated file as a string from the control tar. The default + is 'control'. + + The parameter *file* may be a :class:`file()` object, a file descriptor, or + anything implementing a :meth:`fileno` method. If you want to print the control file of a given package, you could do something like:: print debExtractControl(open("package.deb")) - :return: The contents of the file, as :class:`str`. + .. versionchanged:: 0.7.11 + Added support for file descriptors and objects implementing a :meth:`fileno` method. .. _emulating-dpkg-extract: diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 93f8dc2d..86515569 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -207,6 +207,8 @@ Classes in apt_pkg Return whether the configuration contains the key *key*. + .. deprecated:: 0.7.11 + .. method:: get(key[, default='']) This behaves just like :meth:`dict.get` and :meth:`Configuration.Find`, @@ -1234,6 +1236,8 @@ broken dependencies: Check whether the field with named by *key* exists. + .. deprecated:: 0.7.11 + .. method:: keys() Return a list of keys in the section. diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst index 6e7b772e..38310bb5 100644 --- a/doc/source/apt_pkg/index.rst +++ b/doc/source/apt_pkg/index.rst @@ -17,6 +17,8 @@ the beginning. Module Initialization --------------------- +Initialization is needed for most functions, but not for all of them. Some can +be called without having run init*(), but will not return the expected value. .. function:: initConfig @@ -89,9 +91,6 @@ Object initialization Return a new :class:`PkgSrcRecords` object. -.. function:: newConfiguration() - - Return a new :class:`Configuration` object. The Acquire interface @@ -164,46 +163,197 @@ of the ones provides in Python's :mod:`hashlib` module. Return the md5sum of the object. *object* may either be a string, in which case the md5sum of the string is returned, or a :class:`file()` - object, in which case the md5sum of its contents is returned. + object (or a file descriptor), in which case the md5sum of its contents is + returned. + + .. versionchanged:: 0.7.11 + Added support for using file descriptors. .. function:: sha1sum(object) Return the sha1sum of the object. *object* may either be a string, in which case the sha1sum of the string is returned, or a :class:`file()` - object, in which case the sha1sum of its contents is returned. + object (or a file descriptor), in which case the sha1sum of its contents + is returned. + + .. versionchanged:: 0.7.11 + Added support for using file descriptors. .. function:: sha256sum(object) Return the sha256sum of the object. *object* may either be a string, in which case the sha256sum of the string is returned, or a :class:`file()` - object, in which case the sha256sum of its contents is returned. + object (or a file descriptor), in which case the sha256sum of its contents + is returned. + + .. versionchanged:: 0.7.11 + Added support for using file descriptors. + +Debian control files +-------------------- +.. function:: ParseSection(text) + + Parse the string given in the parameter *text* and return a + :class:`TagSection` object. + +.. function:: ParseTagFile(file) + + Parse the given *file* and return a :class:`TagFile()` object. *file* may + be a :class:`file()` object, a file descriptor, or anything providing a + :meth:`fileno()` method. + + .. versionchanged:: 0.7.11 + Added support for using file descriptors. + +.. autofunction:: RewriteSection(section, order, rewrite_list) + +.. data:: RewritePackageOrder + + The order in which the information for binary packages should be rewritten, + i.e. the order in which the fields should appear. + +.. data:: RewriteSourceOrder + + The order in which the information for source packages should be rewritten, + i.e. the order in which the fields should appear. + +Dependencies +------------ +.. function:: CheckDep(pkgver, op, depver) + + Check that the dependency requirements consisting of op and depver can be + satisfied by the version pkgver. + + Example:: + + >>> bool(apt_pkg.CheckDep("1.0", ">=", "1")) + True + +.. function:: ParseDepends(depends) + + Parse the string *depends* which contains dependency information as + specified in Debian Policy, Section 7.1. + + Returns a list. The members of this list are lists themselves and contain + one or more tuples in the format ``(package,version,operation)`` for every + 'or'-option given, e.g.:: + + >>> apt_pkg.ParseDepends("PkgA (>= VerA) | PkgB (>= VerB)") + [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] + +.. function:: ParseSrcDepends(depends) + + Parse the string *depends* which contains dependency information as + specified in Debian Policy, Section 7.1. + + Returns a list. The members of this list are lists themselves and contain + one or more tuples in the format ``(package,version,operation)`` for every + 'or'-option given, e.g.:: + + >>> apt_pkg.ParseDepends("PkgA (>= VerA) | PkgB (>= VerB)") + [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] + + + Furthemore, this function also supports to limit the architectures, as + used in e.g. Build-Depends:: + + >>> apt_pkg.ParseSrcDepends("a (>= 01) [i386 amd64]") + [[('a', '01', '>=')]] + + +Configuration +------------- + +.. data:: Config + + A :class:`Configuration()`-like object with the default configuration. This + is implemented in the :class:`ConfigurationPtr` class, which has the same + API like the :class:`Configuration` class. + +.. function:: newConfiguration() + + Return a new :class:`Configuration` object. + +.. function:: ReadConfigFile(configuration, filename) + + Read the configuration file specified by the parameter *filename* and add + the settings therein to the :class:`Configuration()` object specified by + the parameter *configuration* + +.. function:: ReadConfigDir(configuration, dirname) + + Read configuration files in the directory specified by the parameter + *dirname* and add the settings therein to the :class:`Configuration()` + object specified by the parameter *configuration*. + +.. function:: ReadConfigFileISC(configuration, filename) + + Read the configuration file specified by the parameter *filename* and add + the settings therein to the :class:`Configuration()` object specified by + the parameter *configuration* + +.. function:: ParseCommandLine(configuration,options,argv) + + This function is like getopt except it manipulates a configuration space. + output is a list of non-option arguments (filenames, etc). *options* is a + list of tuples of the form ``(‘c’,”long-opt or None”, + ”Configuration::Variable”,”optional type”)``. + + Where ``type`` may be one of HasArg, IntLevel, Boolean, InvBoolean, + ConfigFile, or ArbItem. The default is Boolean. + +Locking +-------- + +.. function:: GetLock(filename) + + Create an empty file at the path specified by the parameter *filename* and + lock it. + + While the file is locked by a process, calling this function in another + process returns ``-1``. + + When the lock is not required anymore, the file descriptor should be closed + using :func:`os.close`. + +.. function:: PkgSystemLock() + + Lock the global pkgsystem. + +.. function:: PkgSystemUnLock() + + Unlock the global pkgsystem. Other functions ---------------- +.. function:: Base64Encode(string) + + Encode the given string using base64, e.g:: + + >>> apt_pkg.Base64Encode(u"A") + 'QQ==' -.. note:: - - This documentation is (in parts) created automatically, and still needs to - be improved. - -.. autofunction:: Base64Encode -.. autofunction:: CheckDep -.. autofunction:: CheckDomainList -.. autofunction:: DeQuoteString -.. autofunction:: GetLock - -.. autofunction:: ParseCommandLine -.. autofunction:: ParseDepends -.. autofunction:: ParseSection -.. autofunction:: ParseSrcDepends -.. autofunction:: ParseTagFile -.. autofunction:: PkgSystemLock -.. autofunction:: PkgSystemUnLock -.. autofunction:: QuoteString -.. autofunction:: ReadConfigFile -.. autofunction:: ReadConfigDir() -.. autofunction:: ReadConfigFileISC -.. autofunction:: RewriteSection + +.. function:: CheckDomainList(host, list) + + See if Host is in a ',' seperated list, e.g.:: + + apt_pkg.CheckDomainList("alioth.debian.org","debian.net,debian.org") + +.. function:: DeQuoteString(string) + + Dequote the string specified by the parameter *string*, e.g.:: + + >>> apt_pkg.DeQuoteString("%61%70%74%20is%20cool") + 'apt is cool' + +.. function:: QuoteString(string, repl) + + For every character listed in the string *repl*, replace all occurences in + the string *string* with the correct HTTP encoded value: + + >>> apt_pkg.QuoteString("apt is cool","apt") + '%61%70%74%20is%20cool' .. function:: SizeToStr(size) @@ -271,8 +421,6 @@ Other functions >>> apt_pkg.TimeToStr(3601) '1h0min1s' - - .. function:: UpstreamVersion(version) Return the string *version*, eliminating everything following the last @@ -305,23 +453,12 @@ Other functions ===== ============================================= -Data ------ - -.. data:: Config - - An :class:`Configuration()` object with the default configuration. Actually, - this is a bit different object, but it is compatible. - -.. data:: RewritePackageOrder - -.. data:: RewriteSourceOrder .. _CurStates: Package States -^^^^^^^^^^^^^^^ +--------------- .. data:: CurStateConfigFiles .. data:: CurStateHalfConfigured .. data:: CurStateHalfInstalled @@ -333,7 +470,7 @@ Package States Dependency types -^^^^^^^^^^^^^^^^ +---------------- .. data:: DepConflicts .. data:: DepDepends .. data:: DepObsoletes @@ -345,7 +482,7 @@ Dependency types .. _InstStates: Installed states -^^^^^^^^^^^^^^^^^ +----------------- .. data:: InstStateHold .. data:: InstStateHoldReInstReq .. data:: InstStateOk @@ -354,7 +491,7 @@ Installed states .. _Priorities: Priorities -^^^^^^^^^^ +---------- .. data:: PriExtra .. data:: PriImportant .. data:: PriOptional @@ -365,7 +502,7 @@ Priorities .. _SelStates: Select states -^^^^^^^^^^^^^^ +-------------- .. data:: SelStateDeInstall .. data:: SelStateHold .. data:: SelStateInstall @@ -374,7 +511,7 @@ Select states Build information -^^^^^^^^^^^^^^^^^ +----------------- .. data:: Date The date on which this extension has been compiled. diff --git a/doc/source/coding.rst b/doc/source/coding.rst deleted file mode 100644 index 1357ce14..00000000 --- a/doc/source/coding.rst +++ /dev/null @@ -1,168 +0,0 @@ -Coding for python-apt -====================== -Let's say you need a new feature, you can develop it, and you want to get it -included in python-apt. Then be sure to follow the following guidelines. - -Available branches -------------------- -First of all, let's talk a bit about the bzr branches of python-apt. In the -following parts, we will assume that you use bzr to create your changes and -submit them. - -**mvo:** http://people.ubuntu.com/~mvo/bzr/python-apt/mvo - This is Michael Vogt's branch. Most of the development of apt happens here, - as he is the lead maintainer of python-apt. - - This branch is also available from Launchpads super mirror, via - ``lp:python-apt``. Checkouts from Launchpad are generally faster and can - use the bzr protocoll. - - VCS-Browser: https://code.launchpad.net/~mvo/python-apt/python-apt--mvo - -**debian-sid:** http://bzr.debian.org/apt/python-apt/debian-sid - This is the official Debian branch of python-apt. All code which will be - uploaded to Debian is here. It is not as up-to-date as the mvo branch, - because this branch often gets updated just right before the release - happens. - - VCS-Browser: http://bzr.debian.org/loggerhead/apt/python-apt/debian-sid/changes - -**jak:** http://bzr.debian.org/users/jak/python-apt/jak - This is Julian Andres Klode's (the documentation author's) branch. This - is the place where cleanup and documentation updates happen. It is based - off debian-sid or mvo. - - VCS-Browser: http://bzr.debian.org/loggerhead/users/jak/python-apt/jak/changes - -**ubuntu:** ``lp:~ubuntu-core-dev/python-apt/ubuntu`` - This is the official Ubuntu development branch. The same notes apply as - for the debian-sid branch above. - - VCS-Browser: https://code.launchpad.net/~ubuntu-core-dev/python-apt/ubuntu - - -C++ Coding style ----------------- -When you work on the C++ code in the python/ directory, you should follow some -basic rules. - -The indentation of the code is a bit non-standard. We currently use 3 spaces -indentation for the C++ code. - -When you create new functions, you should follow some naming conventions. All -C++ functions are named according to the ``CamelCase`` convention. - -The resulting Python functions should be ``CamelCase`` as well in apt_pkg, or -``mixedCase`` in apt_inst. The same applies for variables, parameters, -attributes, etc. - -.. note:: - - This coding style guidelines are incomplete. If you have any questions - send an email to deity@lists.debian.org. - -.. note:: - - The coding style may be changed completely during the port to Python 3.0. - But this will not happen very soon. - - -Python Coding Style -------------------- -The coding style for all code written in python is :PEP:`8`. For modules added -from version 0.7.9 on, there are no exceptions. - -Modules introduced prior to 0.7.9 use mixedCase names for methods, functions -and variables. These names will be replaced by names conforming to :PEP:`8` -in a future release of python-apt. - -Therefore, try to reduce the introduction of the mixedName code to the absolute -minimum (sometimes you can also use shorter names). - -To prepare the port to Python 3.0, code should not use any functionality which -is deprecated as of Python 2.6. - -The has_key() functionality may be used only on TagSection objects; as they -provide no other way to do this. If someone is willing to adapt TagSection to -support ``key in mapping`` and ``iter(mapping)``, this would be great. - -.. note:: - - You can use the tool pep8.py from http://svn.browsershots.org/trunk/devtools/pep8/ - to validate your code. Please also run pylint, pychecker, and pyflakes and - fix all new **errors** they report (undefined names, etc.). - -Submitting your patch ---------------------- -First of all, the patch you create should be based against the debian-sid -branch of python-apt. - -Once you have made your change, check that it: - - * conforms to :PEP:`8` (checked with pep8.py). It should, at least not - introduce new errors. (and never have whitespace at end of line) - * produces no new errors in pychecker, pyflakes and pylint (unless you - can't fix them, but please tell so when requesting the merge, so it can - be fixed before hitting one of the main branches). - * does not change the behaviour of existing code in a non-compatible way. - -If your change follows all points of the checklist, you can commit it to your -repository. (You could commit it first, and check later, and then commit the -fixes, but commits should be logical and it makes no sense to have to commits -for one logical unit). - -Once you have made all your changes, you can run ``bzr send -o patch-name`` -to create a so called *merge-directive*, which contains your changes and -allows us to preserve the history of your changes. (But please replace patch-name -with something useful). - -Now report a bug against the python-apt package, attach the merge directive -you created in the previous step, and tag it with 'patch'. It might also be -a good idea to prefix the bug report with '[PATCH]'. - -If your patch introduces new functions, parameters, etc. , but does not update -the content of this documentation, please CC. jak@debian.org, and add a short -notice to the bug report. Also see `Documentation updates` - -Once your patch got merged, you can *pull* the branch into which it has been -merged into your local one. If you have made changes since you submitted your -patch, you may need to *merge* the branch instead. - -.. note:: - - If you plan to work on python-apt for a longer time, it may be a good - idea to publish your branch somewhere. Alioth (http://alioth.debian.org) - and Launchpad (https://launchpad.net) provide bzr hosting. You can also - use any webspace with ftp or sftp connection (for the upload). Then you do - not need to send *merge directives*, but you can point to your branch - instead. - - -Documentation updates ---------------------- -If you want to update the documentation, please follow the procedure as written -above. But please CC: jak@debian.org in the bug report. - -You can send your content in plain text, but reStructuredText is the preferred -format. I (Julian Andres Klode) will review your patch and will forward them to -Michael Vogt, for inclusion in his branch. On release, this will be merged into -the debian-sid branch. - - -Example patch session ----------------------- -In the following example, we edit a file, create a merge directive (an enhanced -patch), and report a wishlist bug with this patch against the python-apt -package:: - - user@pc:~$ bzr clone http://bzr.debian.org/apt/python-apt/debian-sid/ - user@pc:~$ cd debian-sid - user@pc:~/debian-sid$ editor FILES - user@pc:~/debian-sid$ pep8.py FILES # PEP 8 check, see above. - user@pc:~/debian-sid$ pylint -e FILES # Check with pylint - user@pc:~/debian-sid$ pyflakes FILES # Check with pyflakes - user@pc:~/debian-sid$ pychecker FILES # Check with pychecker - user@pc:~/debian-sid$ bzr commit - user@pc:~/debian-sid$ bzr send -o my-patch - user@pc:~/debian-sid$ reportbug --severity=wishlist --tag=patch --attach=my-patch python-apt - user@pc:~/debian-sid$ # Add --list-cc=jak@debian.org if you change docs. diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 00000000..04933b73 --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,160 @@ +Contributing to python-apt +========================== +Let's say you need a new feature, you can develop it, and you want to get it +included in python-apt. Then be sure to follow the following guidelines. + +Available branches +------------------- +First of all, let's talk a bit about the bzr branches of python-apt. In the +following parts, we will assume that you use bzr to create your changes and +submit them. + +**mvo:** http://people.ubuntu.com/~mvo/bzr/python-apt/mvo + This is Michael Vogt's branch. Most of the development of apt happens here, + as he is the lead maintainer of python-apt. + + This branch is also available from Launchpads super mirror, via + ``lp:python-apt``. Checkouts from Launchpad are generally faster and can + use the bzr protocoll. + + VCS-Browser: https://code.launchpad.net/~mvo/python-apt/python-apt--mvo + +**debian-sid:** http://bzr.debian.org/apt/python-apt/debian-sid + This is the official Debian branch of python-apt. All code which will be + uploaded to Debian is here. It is not as up-to-date as the mvo branch, + because this branch often gets updated just right before the release + happens. + + VCS-Browser: http://bzr.debian.org/loggerhead/apt/python-apt/debian-sid/changes + +**jak:** http://bzr.debian.org/users/jak/python-apt/jak + This is Julian Andres Klode's (the documentation author's) branch. This + is the place where cleanup and documentation updates happen. It is based + off debian-sid or mvo. + + VCS-Browser: http://bzr.debian.org/loggerhead/users/jak/python-apt/jak/changes + +**ubuntu:** ``lp:~ubuntu-core-dev/python-apt/ubuntu`` + This is the official Ubuntu development branch. The same notes apply as + for the debian-sid branch above. + + VCS-Browser: https://code.launchpad.net/~ubuntu-core-dev/python-apt/ubuntu + + +C++ Coding style +---------------- +When you work on the C++ code in the python/ directory, you should follow some +basic rules. + +The indentation of the code is a bit non-standard. We currently use 3 spaces +indentation for the C++ code. + +When you create new functions, you should follow some naming conventions. All +C++ functions are named according to the ``CamelCase`` convention. + +The resulting Python functions should be ``CamelCase`` as well in apt_pkg, or +``mixedCase`` in apt_inst. The same applies for variables, parameters, +attributes, etc. + +.. note:: + + This coding style guidelines are incomplete. If you have any questions + send an email to deity@lists.debian.org. + + +Python Coding Style +------------------- +The coding style for all code written in python is :PEP:`8`. For modules and +classes added from version 0.7.9 on, there are no exceptions. + +Classes introduced prior to 0.7.9 use mixedCase names for methods, functions +and variables. These names will be replaced by names conforming to :PEP:`8` +in a future release of python-apt. + +Therefore, try to reduce the introduction of the mixedName code to the absolute +minimum (sometimes you can also use shorter names). + +In order to make the automatic generation of Python 3 code using 2to possible, +code written in Python may not utilize any functionality unsupported by 2to3 or +deprecated as of Python 2.6. + +.. note:: + + You can use the tool pep8.py from http://svn.browsershots.org/trunk/devtools/pep8/ + to validate your code. Please also run pylint, pychecker, and pyflakes and + fix all new **errors** they report (undefined names, etc.). + +Submitting your patch +--------------------- +First of all, the patch you create should be based against the debian-sid +branch of python-apt. + +Once you have made your change, check that it: + + * conforms to :PEP:`8` (checked with pep8.py). It should, at least not + introduce new errors. (and never have whitespace at end of line) + * produces no new errors in pychecker, pyflakes and pylint (unless you + can't fix them, but please tell so when requesting the merge, so it can + be fixed before hitting one of the main branches). + * does not change the behaviour of existing code in a non-compatible way. + +If your change follows all points of the checklist, you can commit it to your +repository. (You could commit it first, and check later, and then commit the +fixes, but commits should be logical and it makes no sense to have to commits +for one logical unit). + +Once you have made all your changes, you can run ``bzr send -o patch-name`` +to create a so called *merge-directive*, which contains your changes and +allows us to preserve the history of your changes. (But please replace patch-name +with something useful). + +Now report a bug against the python-apt package, attach the merge directive +you created in the previous step, and tag it with 'patch'. It might also be +a good idea to prefix the bug report with '[PATCH]'. + +If your patch introduces new functions, parameters, etc. , but does not update +the content of this documentation, please CC. jak@debian.org, and add a short +notice to the bug report. Also see `Documentation updates` + +Once your patch got merged, you can *pull* the branch into which it has been +merged into your local one. If you have made changes since you submitted your +patch, you may need to *merge* the branch instead. + +.. note:: + + If you plan to work on python-apt for a longer time, it may be a good + idea to publish your branch somewhere. Alioth (http://alioth.debian.org) + and Launchpad (https://launchpad.net) provide bzr hosting. You can also + use any webspace with ftp or sftp connection (for the upload). Then you do + not need to send *merge directives*, but you can point to your branch + instead. + + +Documentation updates +--------------------- +If you want to update the documentation, please follow the procedure as written +above. But please CC: jak@debian.org in the bug report. + +You can send your content in plain text, but reStructuredText is the preferred +format. I (Julian Andres Klode) will review your patch and will forward them to +Michael Vogt, for inclusion in his branch. On release, this will be merged into +the debian-sid branch. + + +Example patch session +---------------------- +In the following example, we edit a file, create a merge directive (an enhanced +patch), and report a wishlist bug with this patch against the python-apt +package:: + + user@pc:~$ bzr clone http://bzr.debian.org/apt/python-apt/debian-sid/ + user@pc:~$ cd debian-sid + user@pc:~/debian-sid$ editor FILES + user@pc:~/debian-sid$ pep8.py FILES # PEP 8 check, see above. + user@pc:~/debian-sid$ pylint -e FILES # Check with pylint + user@pc:~/debian-sid$ pyflakes FILES # Check with pyflakes + user@pc:~/debian-sid$ pychecker FILES # Check with pychecker + user@pc:~/debian-sid$ bzr commit + user@pc:~/debian-sid$ bzr send -o my-patch + user@pc:~/debian-sid$ reportbug --severity=wishlist --tag=patch --attach=my-patch python-apt + user@pc:~/debian-sid$ # Add --list-cc=jak@debian.org if you change docs. diff --git a/doc/source/index.rst b/doc/source/index.rst index 23ea4cca..930ff55c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -24,7 +24,7 @@ Contents: apt_pkg/index apt_inst aptsources/index - coding + contributing -- cgit v1.2.3 From abc7c861e85265b0725aa82a51fe41f9183bc506 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Wed, 15 Apr 2009 20:23:04 +0200 Subject: * Upload as 0.7.90 to experimental This is the first pre-release of python-apt 0.8. It is completely backward compatible (even on Python 3), API changes will appear in 0.7.91. --- debian/changelog | 2 +- doc/source/apt_inst.rst | 10 +++++----- doc/source/apt_pkg/cache.rst | 8 ++++---- doc/source/apt_pkg/index.rst | 8 ++++---- 4 files changed, 14 insertions(+), 14 deletions(-) (limited to 'doc/source/apt_pkg/cache.rst') diff --git a/debian/changelog b/debian/changelog index d356c3cf..b2f2b965 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,4 +1,4 @@ -python-apt (0.7.11) UNRELEASED; urgency=low +python-apt (0.7.90) experimental; urgency=low * Introduce support for Python 3 (Closes: #523645) diff --git a/doc/source/apt_inst.rst b/doc/source/apt_inst.rst index 999d074e..cd371e36 100644 --- a/doc/source/apt_inst.rst +++ b/doc/source/apt_inst.rst @@ -15,7 +15,7 @@ Checking packages :class:`file()` object, a file descriptor, or anything implementing a :meth:`fileno` method. - .. versionchanged:: 0.7.11 + .. versionchanged:: 0.8.0 Added support for file descriptors and objects implementing a :meth:`fileno` method. @@ -34,7 +34,7 @@ Listing contents See :ref:`emulating-dpkg-contents` for a more detailed example. - .. versionchanged:: 0.7.11 + .. versionchanged:: 0.8.0 Added support for file descriptors and objects implementing a :meth:`fileno` method. .. function:: tarExtract(file,func,comp) @@ -47,7 +47,7 @@ Listing contents The parameter *file* may be a :class:`file()` object, a file descriptor, or anything implementing a :meth:`fileno` method. - .. versionchanged:: 0.7.11 + .. versionchanged:: 0.8.0 Added support for file descriptors and objects implementing a :meth:`fileno` method. @@ -81,7 +81,7 @@ Extracting contents If the directory given by *rootdir* does not exist, the package is extracted into the current directory. - .. versionchanged:: 0.7.11 + .. versionchanged:: 0.8.0 Added support for file descriptors and objects implementing a :meth:`fileno` method. .. function:: debExtractControl(file[, member='control']) @@ -97,7 +97,7 @@ Extracting contents print debExtractControl(open("package.deb")) - .. versionchanged:: 0.7.11 + .. versionchanged:: 0.8.0 Added support for file descriptors and objects implementing a :meth:`fileno` method. diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 86515569..a58f1356 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -121,7 +121,7 @@ Classes in apt_pkg Return ``True`` if *conf* has a key *key*, else ``False``. - .. versionadded:: 0.7.11 + .. versionadded:: 0.8.0 .. describe:: conf[key] @@ -207,7 +207,7 @@ Classes in apt_pkg Return whether the configuration contains the key *key*. - .. deprecated:: 0.7.11 + .. deprecated:: 0.8.0 .. method:: get(key[, default='']) @@ -1211,7 +1211,7 @@ broken dependencies: Return ``True`` if *section* has a key *key*, else ``False``. - .. versionadded:: 0.7.11 + .. versionadded:: 0.8.0 .. method:: Bytes @@ -1236,7 +1236,7 @@ broken dependencies: Check whether the field with named by *key* exists. - .. deprecated:: 0.7.11 + .. deprecated:: 0.8.0 .. method:: keys() diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst index 60c3ba9b..47923c23 100644 --- a/doc/source/apt_pkg/index.rst +++ b/doc/source/apt_pkg/index.rst @@ -166,7 +166,7 @@ of the ones provides in Python's :mod:`hashlib` module. object (or a file descriptor), in which case the md5sum of its contents is returned. - .. versionchanged:: 0.7.11 + .. versionchanged:: 0.8.0 Added support for using file descriptors. .. function:: sha1sum(object) @@ -176,7 +176,7 @@ of the ones provides in Python's :mod:`hashlib` module. object (or a file descriptor), in which case the sha1sum of its contents is returned. - .. versionchanged:: 0.7.11 + .. versionchanged:: 0.8.0 Added support for using file descriptors. .. function:: sha256sum(object) @@ -186,7 +186,7 @@ of the ones provides in Python's :mod:`hashlib` module. object (or a file descriptor), in which case the sha256sum of its contents is returned. - .. versionchanged:: 0.7.11 + .. versionchanged:: 0.8.0 Added support for using file descriptors. Debian control files @@ -202,7 +202,7 @@ Debian control files be a :class:`file()` object, a file descriptor, or anything providing a :meth:`fileno()` method. - .. versionchanged:: 0.7.11 + .. versionchanged:: 0.8.0 Added support for using file descriptors. .. autofunction:: RewriteSection(section, order, rewrite_list) -- cgit v1.2.3 From 071b059f8ccb35eaeb6c9457244f783ad69ba957 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sun, 19 Apr 2009 19:48:08 +0200 Subject: * doc: Update the documentation to the current state. --- doc/source/apt/index.rst | 2 - doc/source/apt_pkg.rst | 1740 +++++++++++++++++++++++++++++++++++++++++ doc/source/apt_pkg/cache.rst | 1243 ----------------------------- doc/source/apt_pkg/index.rst | 530 ------------- doc/source/index.rst | 22 +- doc/source/whatsnew/0.8.0.rst | 33 + doc/source/whatsnew/index.rst | 9 + 7 files changed, 1793 insertions(+), 1786 deletions(-) create mode 100644 doc/source/apt_pkg.rst delete mode 100644 doc/source/apt_pkg/cache.rst delete mode 100644 doc/source/apt_pkg/index.rst create mode 100644 doc/source/whatsnew/0.8.0.rst create mode 100644 doc/source/whatsnew/index.rst (limited to 'doc/source/apt_pkg/cache.rst') diff --git a/doc/source/apt/index.rst b/doc/source/apt/index.rst index 5047a0fd..9cd6ef45 100644 --- a/doc/source/apt/index.rst +++ b/doc/source/apt/index.rst @@ -11,8 +11,6 @@ with an easy-to-use interface. functions provided as deprecated ones. .. automodule:: apt - :members: - diff --git a/doc/source/apt_pkg.rst b/doc/source/apt_pkg.rst new file mode 100644 index 00000000..8c602f37 --- /dev/null +++ b/doc/source/apt_pkg.rst @@ -0,0 +1,1740 @@ +:mod:`apt_pkg` --- The low-level bindings for apt-pkg +===================================================== +.. module:: apt_pkg + +The apt_pkg extensions provides a more low-level way to work with apt. It can +do everything apt can, and is written in C++. It has been in python-apt since +the beginning. + + +Module Initialization +--------------------- + +Initialization is needed for most functions, but not for all of them. Some can +be called without having run init*(), but will not return the expected value. + +.. function:: initConfig + + Initialize the configuration of apt. This is needed for most operations. + +.. function:: initSystem + + Initialize the system. + +.. function:: init + + Deprecated function. Use initConfig() and initSystem() instead. + +Working with the cache +---------------------- +.. class:: Cache([progress]) + + Return a :class:`Cache()` object. The optional parameter *progress* + specifies an instance of :class:`apt.progress.OpProgress()` which will + display the open progress. + + .. describe:: cache[pkgname] + + Return the :class:`Package()` object for the package name given by + *pkgname*. + + .. method:: Close() + + Close the package cache. + + .. method:: Open([progress]) + + Open the package cache again. The parameter *progress* may be set to + an :class:`apt.progress.OpProgress()` object or `None`. + + .. method:: Update(progress, list) + + Update the package cache. + + The parameter *progress* points to an :class:`apt.progress.FetchProgress()` + object. The parameter *list* refers to a :class:`SourceList()` object. + + .. attribute:: DependsCount + + The total number of dependencies. + + .. attribute:: PackageCount + + The total number of packages available in the cache. + + .. attribute:: ProvidesCount + + The number of provided packages. + + .. attribute:: VerFileCount + + .. todo:: Seems to be some mixture of versions and pkgFile. + + .. attribute:: VersionCount + + The total number of package versions available in the cache. + + .. attribute:: PackageFileCount + + The total number of Packages files available (the Packages files + listing the packages). This is the same as the length of the list in + the attribute :attr:`FileList`. + + .. attribute:: FileList + + A list of :class:`PackageFile` objects. + +.. class:: DepCache(cache) + + Return a :class:`DepCache` object. The parameter *cache* specifies an + instance of :class:`Cache`. + + The DepCache object contains various methods to manipulate the cache, + to install packages, to remove them, and much more. + + .. method:: Commit(fprogress, iprogress) + + Apply all the changes made. + + The parameter *fprogress* has to be set to an instance of + apt.progress.FetchProgress or one of its subclasses. + + The parameter *iprogress* has to be set to an instance of + apt.progress.InstallProgress or one of its subclasses. + + .. method:: FixBroken() + + Try to fix all broken packages in the cache. + + .. method:: GetCandidateVer(pkg) + + Return the candidate version of the package, ie. the version that + would be installed normally. + + The parameter *pkg* refers to an :class:`Package` object, + available using the :class:`pkgCache`. + + This method returns a :class:`Version` object. + + .. method:: SetCandidateVer(pkg, version) + + The opposite of :meth:`pkgDepCache.GetCandidateVer`. Set the candidate + version of the :class:`Package` *pkg* to the :class:`Version` + *version*. + + + .. method:: Upgrade([distUpgrade=False]) + + Perform an upgrade. More detailed, this marks all the upgradable + packages for upgrade. You still need to call + :meth:`pkgDepCache.Commit` for the changes to apply. + + To perform a dist-upgrade, the optional parameter *distUpgrade* has + to be set to True. + + .. method:: FixBroken() + + Fix broken packages. + + .. method:: ReadPinFile() + + Read the policy, eg. /etc/apt/preferences. + + .. method:: MinimizeUpgrade() + + 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. + + .. todo:: + Explain better.. + + .. method:: MarkKeep(pkg) + + Mark the :class:`Package` *pkg* for keep. + + .. method:: MarkDelete(pkg[, purge]) + + Mark the :class:`Package` *pkg* for delete. If *purge* is True, + the configuration files will be removed as well. + + .. method:: MarkInstall(pkg[, autoInst=True[, fromUser=True]]) + + Mark the :class:`Package` *pkg* for install. + + If *autoInst* is ``True``, the dependencies of the package will be + installed as well. This is the default. + + If *fromUser* is ``True``, the package will be marked as manually + installed. This is the default. + + .. method:: SetReinstall(pkg) + + Set if the :class:`Package` *pkg* should be reinstalled. + + .. method:: IsUpgradable(pkg) + + Return ``1`` if the package is upgradable. + + The package can be upgraded by calling :meth:`pkgDepCache.MarkInstall`. + + .. method:: IsNowBroken(pkg) + + Return `1` if the package is broken now (including changes made, but + not committed). + + .. method:: IsInstBroken(pkg) + + Return ``1`` if the package is broken on the current install. This + takes changes which have not been committed not into effect. + + .. method:: IsGarbage(pkg) + + Return ``1`` if the package is garbage, ie. if it is automatically + installed and no longer referenced by other packages. + + .. method:: IsAutoInstalled(pkg) + + Return ``1`` if the package is automatically installed (eg. as the + dependency of another package). + + .. method:: MarkedInstall(pkg) + + Return ``1`` if the package is marked for install. + + .. method:: MarkedUpgrade(pkg) + + Return ``1`` if the package is marked for upgrade. + + .. method:: MarkedDelete(pkg) + + Return ``1`` if the package is marked for delete. + + .. method:: MarkedKeep(pkg) + + Return ``1`` if the package is marked for keep. + + .. method:: MarkedReinstall(pkg) + + Return ``1`` if the package should be installed. + + .. method:: MarkedDowngrade(pkg) + + Return ``1`` if the package should be downgraded. + + .. attribute:: KeepCount + + Integer, number of packages marked as keep + + .. attribute:: InstCount + + Integer, number of packages marked for installation. + + .. attribute:: DelCount + + Number of packages which should be removed. + + .. attribute:: BrokenCount + + Number of packages which are broken. + + .. attribute:: UsrSize + + The size required for the changes on the filesystem. If you install + packages, this is positive, if you remove them its negative. + + .. attribute:: DebSize + + The size of the packages which are needed for the changes to be + applied. + + +.. class:: PackageManager(depcache) + + Return a new :class:`PackageManager` object. The parameter *depcache* + specifies a :class:`DepCache` object. + + :class:`PackageManager` objects provide several methods and attributes, + which will be listed here: + + .. method:: GetArchives(fetcher, list, records) + + Add all the selected packages to the :class:`Acquire()` object + *fetcher*. + + The parameter *list* refers to a :class:`SourceList()` object. + + The parameter *records* refers to a :class:`PackageRecords()` object. + + .. method:: DoInstall() + + Install the packages. + + .. method:: FixMissing + + Fix the installation if a package could not be downloaded. + + .. attribute:: ResultCompleted + + A constant for checking whether the the result is 'completed'. + + Compare it against the return value of :meth:`PkgManager.GetArchives` + or :meth:`PkgManager.DoInstall`. + + .. attribute:: ResultFailed + + A constant for checking whether the the result is 'failed'. + + Compare it against the return value of :meth:`PkgManager.GetArchives` + or :meth:`PkgManager.DoInstall`. + + .. attribute:: ResultIncomplete + + A constant for checking whether the the result is 'incomplete'. + + Compare it against the return value of :meth:`PkgManager.GetArchives` + or :meth:`PkgManager.DoInstall`. + +Improve performance with :class:`ActionGroup` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. class:: ActionGroup(depcache) + + Create a new :class:`ActionGroup()` object for the :class:`DepCache` object + given by the parameter *depcache*. + + :class:`ActionGroup()` objects make operations on the cache faster by + delaying certain cleanup operations until the action group is released. + + ActionGroup is also a context manager and therefore supports the + :keyword:`with` statement. But because it becomes active as soon as it + is created, you should not create an ActionGroup() object before entering + the with statement. + + If you want to use ActionGroup as a with statement (which is recommended + because it makes it easier to see when an actiongroup is active), always + use the following form:: + + with apt_pkg.ActionGroup(depcache): + ... + + For code which has to run on Python versions prior to 2.5, you can also + use the traditional way:: + + actiongroup = apt_pkg.ActionGroup(depcache) + ... + actiongroup.release() + + :class:`ActionGroup` provides the following method: + + .. method:: release() + + Release the ActionGroup. This will reactive the collection of package + garbage. + +Resolving Dependencies +^^^^^^^^^^^^^^^^^^^^^^ + +.. class:: ProblemResolver(depcache) + + Return a new :class:`ProblemResolver` object. The parameter *depcache* + specifies a :class:`pkgDepCache` object as returned by :func:`GetDepCache`. + + The problem resolver helps when there are problems in the package + selection. An example is a package which conflicts with another, already + installed package. + + .. method:: Protect(pkg) + + Protect the :class:`Package()` object given by the parameter *pkg*. + + .. todo:: + + Really document it. + + .. method:: InstallProtect() + + Protect all installed packages from being removed. + + .. method:: Remove(pkg) + + Remove the :class:`Package()` object given by the parameter *pkg*. + + .. todo:: + + Really document it. + + .. method:: Clear(pkg) + + Reset the :class:`Package()` *pkg* to the default state. + + .. todo:: + + Really document it. + + .. method:: Resolve() + + Try to resolve problems by installing and removing packages. + + .. method:: ResolveByKeep() + + Try to resolve problems only by using keep. + + +:class:`PackageFile` +-------------------- +.. class:: PackageFile + + A :class:`PackageFile` represents a Packages file, eg. + /var/lib/dpkg/status. + + .. attribute:: Architecture + + The architecture of the package file. + + .. attribute:: Archive + + The archive (eg. unstable) + + .. attribute:: Component + + The component (eg. main) + + .. attribute:: FileName + + The name of the file. + + .. attribute:: ID + + The ID of the package. This is an integer which can be used to store + further information about the file [eg. as dictionary key]. + + .. attribute:: IndexType + + The sort of the index file. In normal cases, this is + 'Debian Package Index'. + + .. attribute:: Label + + The Label, as set in the Release file + + .. attribute:: NotAutomatic + + Whether packages from this list will be updated automatically. The + default for eg. example is 0 (aka false). + + .. attribute:: NotSource + + Whether the file has no source from which it can be updated. In such a + case, the value is 1; else 0. /var/lib/dpkg/status is 0 for example. + + Example:: + + for pkgfile in cache.FileList: + if pkgfile.NotSource: + print 'The file %s has no source.' % pkgfile.FileName + + .. attribute:: Origin + + The Origin, as set in the Release file + + .. attribute:: Site + + The hostname of the site. + + .. attribute:: Size + + The size of the file. + + .. attribute:: Version + + The version, as set in the release file (eg. "4.0" for "Etch") + + +Example +^^^^^^^ +.. literalinclude:: examples/cache-pkgfile.py + + +:class:`Package` +---------------- + +.. class:: Package + + The pkgCache::Package objects are an interface to package specific + features. + + + Attributes: + + .. attribute:: CurrentVer + + The version currently installed, or None. This returns a + :class:`Version` object. + + .. attribute:: ID + + The ID of the package. This can be used to store information about + the package. The ID is an int value. + + .. attribute:: Name + + This is the name of the package. + + .. attribute:: ProvidesList + + A list of packages providing this package. More detailed, this is a + list of tuples (str:pkgname, ????, :class:`Version`). + + If you want to check for check for virtual packages, the expression + ``pkg.ProvidesList and not pkg.VersionList`` helps you. It detects if + the package is provided by something else and is not available as a + real package. + + .. attribute:: RevDependsList + + An iterator of :class:`Dependency` objects for dependencies on this + package. + + .. attribute:: Section + + The section of the package, as specified in the record. The list of + possible sections is defined in the Policy. + + .. attribute:: VersionList + + A list of :class:`Version` objects for all versions available in the + cache. + + **States**: + + .. attribute:: SelectedState + + The state we want it to be, ie. if you mark a package for installation, + this is :attr:`apt_pkg.SelStateInstall`. + + See :ref:`SelStates` for a list of available states. + + .. attribute:: InstState + + The state the currently installed version is in. This is normally + :attr:`apt_pkg.InstStateOK`, unless the installation failed. + + See :ref:`InstStates` for a list of available states. + + .. attribute:: CurState + + The current state of the package (not installed, unpacked, installed, + etc). See :ref:`CurStates` for a list of available states. + + **Flags**: + + .. attribute:: Auto + + Whether the package was installed automatically as a dependency of + another package. (or marked otherwise as automatically installed) + + .. attribute:: Essential + + Whether the package is essential. + + .. attribute:: Important + + Whether the package is important. + +Example: +^^^^^^^^^ +.. literalinclude:: examples/cache-packages.py + + + +:class:`Version` +---------------- +.. class:: Version + + The version object contains all information related to a specific package + version. + + .. attribute:: VerStr + + The version, as a string. + + .. attribute:: Section + + The usual sections (eg. admin, net, etc.). Prefixed with the component + name for packages not in main (eg. non-free/admin). + + .. attribute:: Arch + + The architecture of the package, eg. amd64 or all. + + .. attribute:: FileList + + A list of (:class:`PackageFile`, int: index) tuples for all Package + files containing this version of the package. + + .. attribute:: DependsListStr + + A dictionary of dependencies. The key specifies the type of the + dependency ('Depends', 'Recommends', etc.). + + + The value is a list, containing items which refer to the or-groups of + dependencies. Each of these or-groups is itself a list, containing + tuples like ('pkgname', 'version', 'relation') for each or-choice. + + An example return value for a package with a 'Depends: python (>= 2.4)' + would be:: + + {'Depends': [ + [ + ('python', '2.4', '>=') + ] + ] + } + + The same for a dependency on A (>= 1) | B (>= 2):: + + {'Depends': [ + [ + ('A', '1', '>='), + ('B', '2', '>='), + ] + ] + } + + .. attribute:: DependsList + + This is basically the same as :attr:`Version.DependsListStr`, + but instead of the ('pkgname', 'version', 'relation') tuples, + it returns :class:`Dependency` objects, which can assist you with + useful functions. + + .. attribute:: ParentPkg + + The :class:`Package` object this version belongs to. + + .. attribute:: ProvidesList + + This returns a list of all packages provided by this version. Like + :attr:`Package.ProvidesList`, it returns a list of tuples + of the form ('virtualpkgname', ???, :class:`Version`), where as the + last item is the same as the object itself. + + .. attribute:: Size + + The size of the .deb file, in bytes. + + .. attribute:: InstalledSize + + The size of the package (in kilobytes), when unpacked on the disk. + + .. attribute:: Hash + + An integer hash value. + + .. attribute:: ID + + An integer id. + + .. attribute:: Priority + + The integer representation of the priority. This can be used to speed + up comparisons a lot, compared to :attr:`Version.PriorityStr`. + + The values are defined in the :mod:`apt_pkg` extension, see + :ref:`Priorities` for more information. + + .. attribute:: PriorityStr + + Return the priority of the package version, as a string, eg. + "optional". + + .. attribute:: Downloadable + + Whether this package can be downloaded from a remote site. + + .. attribute:: TranslatedDescription + + Return a :class:`Description` object. + + +:class:`Dependency` +------------------- +.. class:: Dependency + + Represent a dependency from one package to another one. + + .. method:: AllTargets + + A list of :class:`Version` objects which satisfy the dependency, + and do not conflict with already installed ones. + + From my experience, if you use this method to select the target + version, it is the best to select the last item unless any of the + other candidates is already installed. This leads to results being + very close to the normal package installation. + + .. method:: SmartTargetPkg + + Return a :class:`Version` object of a package which satisfies the + dependency and does not conflict with installed packages + (the 'natural target'). + + .. attribute:: TargetVer + + The target version of the dependency, as string. Empty string if the + dependency is not versioned. + + .. attribute:: TargetPkg + + The :class:`Package` object of the target package. + + .. attribute:: ParentVer + + The :class:`Version` object of the parent version, ie. the package + which declares the dependency. + + .. attribute:: ParentPkg + + The :class:`Package` object of the package which declares the + dependency. This is the same as using ParentVer.ParentPkg. + + .. attribute:: CompType + + The type of comparison (>=, ==, >>, <=), as string. + + .. attribute:: DepType + + The type of the dependency, as string, eg. "Depends". + + .. attribute:: ID + + The ID of the package, as integer. + +Example: Find all missing dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +With the help of Dependency.AllTargets(), you can easily find all packages with +broken dependencies: + +.. literalinclude:: examples/missing-deps.py + + +:class:`Description` +-------------------- +.. class:: Description + + Represent the description of the package. + + .. attribute:: LanguageCode + + The language code of the description + + .. attribute:: md5 + + The md5 hashsum of the description + + .. attribute:: FileList + + A list of tuples (:class:`PackageFile`, int: index). + + + +:class:`MetaIndex` +------------------ + +.. todo:: + + Complete them + +.. class:: MetaIndex + + .. attribute:: URI + .. attribute:: Dist + .. attribute:: IsTrusted + .. attribute:: IndexFiles + + +:class:`PackageIndexFile` +------------------------- + +.. class:: PackageIndexFile + + .. method:: ArchiveURI(path) + + Return the full url to path in the archive. + + .. attribute:: Label + + Return the Label. + + .. attribute:: Exists + + Return whether the file exists. + + .. attribute:: HasPackages + + Return whether the file has packages. + + .. attribute:: Size + + Size of the file + + .. attribute:: IsTrusted + + Whether we can trust the file. + + +Records +-------- + +.. class:: PackageRecords(cache) + + Create a new :class:`PackageRecords` object, for the packages in the cache + specified by the parameter *cache*. + + Provide access to the packages records. This provides very useful + attributes for fast (convient) access to some fields of the record. + + .. method:: Lookup(verfile_iter) + + Change the actual package to the package given by the verfile_iter. + + The parameter *verfile_iter* refers to a tuple consisting + of (:class:`PackageFile()`, int: index), as returned by various + attributes, including :attr:`Version.FileList`. + + Example (shortened):: + + cand = depcache.GetCandidateVer(cache['python-apt']) + records.Lookup(cand.FileList[0]) + # Now you can access the record + print records.SourcePkg # == python-apt + + .. attribute:: FileName + + Return the field 'Filename' of the record. This is the path to the + package, relative to the base path of the archive. + + .. attribute:: MD5Hash + + Return the MD5 hashsum of the package This refers to the field + 'MD5Sum' in the raw record. + + .. attribute:: SHA1Hash + + Return the SHA1 hashsum of the package. This refers to the field 'SHA1' + in the raw record. + + .. attribute:: SHA256Hash + + Return the SHA256 hashsum of the package. This refers to the field + 'SHA256' in the raw record. + + .. versionadded:: 0.7.9 + + .. attribute:: SourcePkg + + Return the source package. + + .. attribute:: SourceVer + + Return the source version. + + .. attribute:: Maintainer + + Return the maintainer of the package. + + .. attribute:: ShortDesc + + Return the short description. This is the summary on the first line of + the 'Description' field. + + .. attribute:: LongDesc + + Return the long description. These are lines 2-END from the + 'Description' field. + + .. attribute:: Name + + Return the name of the package. This is the 'Package' field. + + .. attribute:: Homepage + + Return the Homepage. This is the 'Homepage' field. + + .. attribute:: Record + + Return the whole record as a string. If you want to access fields of + the record not available as an attribute, you can use + :func:`apt_pkg.ParseSection` to parse the record and access the field + name. + + Example:: + + section = apt_pkg.ParseSection(records.Record) + print section['SHA256'] + + +.. class:: SourceRecords + + This represents the entries in the Sources files, ie. the dsc files of + the source packages. + + .. note:: + + If the Lookup failed, because no package could be found, no error is + raised. Instead, the attributes listed below are simply not existing + anymore (same applies when no Lookup has been made, or when it has + been restarted). + + .. method:: Lookup(pkgname) + + Lookup the record for the package named *pkgname*. To access all + available records, you need to call it multiple times. + + Imagine a package P with two versions X, Y. The first ``Lookup(P)`` + would set the record to version X and the second ``Lookup(P)`` to + version Y. + + .. method:: Restart() + + Restart the lookup. + + Imagine a package P with two versions X, Y. The first ``Lookup(P)`` + would set the record to version X and the second ``Lookup(P)`` to + version Y. + + If you now call ``Restart()``, the internal position will be cleared. + Now you can call ``Lookup(P)`` again to move to X. + + .. attribute:: Package + + The name of the source package. + + .. attribute:: Version + + A string describing the version of the source package. + + .. attribute:: Maintainer + + A string describing the name of the maintainer. + + .. attribute:: Section + + A string describing the section. + + .. attribute:: Record + + The whole record, as a string. You can use :func:`apt_pkg.ParseSection` + if you need to parse it. + + You need to parse the record if you want to access fields not available + via the attributes, eg. 'Standards-Version' + + .. attribute:: Binaries + + Return a list of strings describing the package names of the binaries + created by the source package. This matches the 'Binary' field in the + raw record. + + .. attribute:: Index + + The index in the Sources files. + + .. attribute:: Files + + The list of files. This returns a list of tuples with the contents + ``(str: md5, int: size, str: path, str:type)``. + + .. attribute:: BuildDepends + + Return the list of Build dependencies, as + ``(str: package, str: version, int: op, int: type)``. + + .. table:: Values of *op* + + ===== ============================================= + Value Meaning + ===== ============================================= + 0x0 No Operation (no versioned build dependency) + 0x10 | (or) - this will be added to the other values + 0x1 <= (less than or equal) + 0x2 >= (greater than or equal) + 0x3 << (less than) + 0x4 >> (greater than) + 0x5 == (equal) + 0x6 != (not equal) + ===== ============================================= + + .. table:: Values of *type* + + ===== =================== + Value Meaning + ===== =================== + 0 Build-Depends + 1 Build-Depends-Indep + 2 Build-Conflicts + 3 Build-Conflicts-Indep + ===== =================== + + **Example**: In the following content, we will imagine a + build-dependency:: + + Build-Depends: A (>= 1) | B (>= 1), C + + This results in:: + + [('A', '1', 18, 0), # 18 = 16 + 2 = 0x10 + 0x2 + ('B', '1', 2, 0), + ('C', '', 0, 0)] + + This is **not** the same as returned by + :func:`apt_pkg.ParseSrcDepends`. + + + +The Acquire interface +---------------------- +The Acquire Interface is responsible for all sorts of downloading in apt. All +packages, index files, etc. downloading is done using the Acquire functionality. + +The :mod:`apt_pkg` module provides a subset of this functionality which allows +you to implement file downloading in your applications. Together with the +:class:`PackageManager` class you can also fetch all the packages marked for +installation. + + +.. class:: Acquire([progress]) + + Return an :class:`Acquire` object. The parameter *progress* refers to + an :class:`apt.progress.FetchProgress()` object. + + Acquire objects maintaing a list of items which will be fetched or have + been fetched already during the lifetime of this object. To add new items + to this list, you can create new :class:`AcquireFile` objects which allow + you to add single files. + + Acquire items have multiple methods: + + .. method:: Acquire.Run() + + Fetch all the items which have been added by :func:`GetPkgAcqFile`. + + .. method:: Acquire.Shutdown() + + Shut the fetcher down. + + .. attribute:: Acquire.TotalNeeded + + The total amount of bytes needed (including those of files which are + already present) + + .. attribute:: Acquire.FetchNeeded + + The total amount of bytes which need to be fetched. + + .. attribute:: Acquire.PartialPresent + + Whether some files have been acquired already. (???) + +.. class:: AcquireItem + + The :class:`AcquireItem()` objects represent the items of a + :class:`Acquire` object. :class:`AcquireItem()` objects can not be created + by the user, they are solely available through the :attr:`Acquire.Items` + list of an :class:`Acquire` object. + + .. attribute:: ID + + The ID of the item. + + .. attribute:: Complete + + Is the item completely acquired? + + .. attribute:: Local + + Is the item a local file? + + .. attribute:: IsTrusted + + Can the file be trusted? + + .. attribute:: FileSize + + The size of the file, in bytes. + + .. attribute:: ErrorText + + The error message. For example, when a file does not exist on a http + server, this will contain a 404 error message. + + .. attribute:: DestFile + + The location the file is saved as. + + .. attribute:: DescURI + + The source location. + + **Status**: + + .. attribute:: Status + + Integer, representing the status of the item. + + .. attribute:: StatIdle + + Constant for comparing :attr:`AcquireItem.Status`. + + .. attribute:: StatFetching + + Constant for comparing :attr:`AcquireItem.Status` + + .. attribute:: StatDone + + Constant for comparing :attr:`AcquireItem.Status` + + .. attribute:: StatError + + Constant for comparing :attr:`AcquireItem.Status` + + .. attribute:: StatAuthError + + Constant for comparing :attr:`AcquireItem.Status` + + +.. class:: AcquireFile(owner, uri[, md5, size, descr, shortdescr, destdir, destfile]) + + Create a new :class:`AcquireFile()` object and register it with *acquire*, + so it will be fetched. AcquireFile objects provide no methods or attributes + and are completely useless at the moment. + + The parameter *owner* refers to an :class:`Acquire()` object as returned + by :func:`GetAcquire`. The file will be added to the Acquire queue + automatically. + + The parameter *uri* refers to the location of the file, any protocol + of apt is supported. + + The parameter *md5* refers to the md5sum of the file. This can be used + for checking the file. + + The parameter *size* can be used to specify the size of the package, + which can then be used to calculate the progress and validate the download. + + The parameter *descr* is a descripition of the download. It may be + used to describe the item in the progress class. *shortDescr* is the + short form of it. + + You can use *destdir* to manipulate the directory where the file will + be saved in. Instead of *destdir*, you can also specify the full path to + the file using the parameter *destfile*. You can not combine both. + + + + + + +Hash functions +-------------- +The apt_pkg module also provides several hash functions. If you develop +applications with python-apt it is often easier to use these functions instead +of the ones provides in Python's :mod:`hashlib` module. + +.. function:: md5sum(object) + + Return the md5sum of the object. *object* may either be a string, in + which case the md5sum of the string is returned, or a :class:`file()` + object (or a file descriptor), in which case the md5sum of its contents is + returned. + + .. versionchanged:: 0.8.0 + Added support for using file descriptors. + +.. function:: sha1sum(object) + + Return the sha1sum of the object. *object* may either be a string, in + which case the sha1sum of the string is returned, or a :class:`file()` + object (or a file descriptor), in which case the sha1sum of its contents + is returned. + + .. versionchanged:: 0.8.0 + Added support for using file descriptors. + +.. function:: sha256sum(object) + + Return the sha256sum of the object. *object* may either be a string, in + which case the sha256sum of the string is returned, or a :class:`file()` + object (or a file descriptor), in which case the sha256sum of its contents + is returned. + + .. versionchanged:: 0.8.0 + Added support for using file descriptors. + +Debian control files +-------------------- +Debian control files are files containing multiple stanzas of :RFC:`822`-style +header sections. They are widely used in the Debian community, and can represent +many kinds of information. One example for such a file is the +:file:`/var/lib/dpkg/status` file which contains a list of the currently +installed packages. + +The :mod:`apt_pkg` module provides two classes to read those files and parts +thereof and provides a function :func:`RewriteSection` which takes a +:class:`TagSection()` object and sorting information and outputs a sorted +section as a string. + +.. class:: TagFile(file) + + An object which represents a typical debian control file. Can be used for + Packages, Sources, control, Release, etc. + + An example for working with a TagFile could look like:: + + tagf = apt_pkg.TagFile(open('/var/lib/dpkg/status')) + tagf.Step() + print tagf.Section['Package'] + + .. method:: Step + + Step forward to the next section. This simply returns ``1`` if OK, and + ``0`` if there is no section + + .. method:: Offset + + Return the current offset (in bytes) from the beginning of the file. + + .. method:: Jump(offset) + + Jump back/forward to *offset*. Use ``Jump(0)`` to jump to the + beginning of the file again. + + .. attribute:: Section + + This is the current :class:`TagSection()` instance. + +.. class:: TagSection(text) + + Represent a single section of a debian control file. + + .. describe:: section[key] + + Return the value of the field at *key*. If *key* is not available, + raise :exc:`KeyError`. + + .. describe:: key in section + + Return ``True`` if *section* has a key *key*, else ``False``. + + .. versionadded:: 0.8.0 + + .. method:: Bytes + + The number of bytes in the section. + + .. method:: Find(key, default='') + + Return the value of the field at the key *key* if available, + else return *default*. + + .. method:: FindFlag(key) + + Find a yes/no value for the key *key*. An example for such a + field is 'Essential'. + + .. method:: get(key, default='') + + Return the value of the field at the key *key* if available, else + return *default*. + + .. method:: has_key(key) + + Check whether the field with named by *key* exists. + + .. deprecated:: 0.8.0 + + .. method:: keys() + + Return a list of keys in the section. + +.. autofunction:: RewriteSection(section, order, rewrite_list) + +.. data:: RewritePackageOrder + + The order in which the information for binary packages should be rewritten, + i.e. the order in which the fields should appear. + +.. data:: RewriteSourceOrder + + The order in which the information for source packages should be rewritten, + i.e. the order in which the fields should appear. + +Dependencies +------------ +.. function:: CheckDep(pkgver, op, depver) + + Check that the dependency requirements consisting of op and depver can be + satisfied by the version pkgver. + + Example:: + + >>> bool(apt_pkg.CheckDep("1.0", ">=", "1")) + True + +.. function:: ParseDepends(depends) + + Parse the string *depends* which contains dependency information as + specified in Debian Policy, Section 7.1. + + Returns a list. The members of this list are lists themselves and contain + one or more tuples in the format ``(package,version,operation)`` for every + 'or'-option given, e.g.:: + + >>> apt_pkg.ParseDepends("PkgA (>= VerA) | PkgB (>= VerB)") + [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] + +.. function:: ParseSrcDepends(depends) + + Parse the string *depends* which contains dependency information as + specified in Debian Policy, Section 7.1. + + Returns a list. The members of this list are lists themselves and contain + one or more tuples in the format ``(package,version,operation)`` for every + 'or'-option given, e.g.:: + + >>> apt_pkg.ParseDepends("PkgA (>= VerA) | PkgB (>= VerB)") + [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] + + + Furthemore, this function also supports to limit the architectures, as + used in e.g. Build-Depends:: + + >>> apt_pkg.ParseSrcDepends("a (>= 01) [i386 amd64]") + [[('a', '01', '>=')]] + + +Configuration +------------- + +.. class:: Configuration() + + Configuration() objects store the configuration of apt, mostly created from + the contents of :file:`/etc/apt.conf` and the files in + :file:`/etc/apt.conf.d`. + + .. describe:: key in conf + + Return ``True`` if *conf* has a key *key*, else ``False``. + + .. versionadded:: 0.8.0 + + .. describe:: conf[key] + + Return the value of the option given key *key*. If it does not + exist, raise :exc:`KeyError`. + + .. describe:: conf[key] = value + + Set the option at *key* to *value*. + + .. method:: Find(key[, default='']) + + Return the value for the given key *key*. This is the same as + :meth:`Configuration.get`. + + If *key* does not exist, return *default*. + + .. method:: FindFile(key[, default='']) + + Return the filename hold by the configuration at *key*. This formats the + filename correctly and supports the Dir:: stuff in the configuration. + + If *key* does not exist, return *default*. + + .. method:: FindDir(key[, default='/']) + + Return the absolute path to the directory specified in *key*. A + trailing slash is appended. + + If *key* does not exist, return *default*. + + .. method:: FindI(key[, default=0]) + + Return the integer value stored at *key*. + + If *key* does not exist, return *default*. + + .. method:: FindB(key[, default=0]) + + Return the boolean value stored at *key*. This returns an integer, but + it should be treated like True/False. + + If *key* does not exist, return *default*. + + .. method:: Set(key, value) + + Set the value of *key* to *value*. + + .. method:: Exists(key) + + Check whether the key *key* exists in the configuration. + + .. method:: SubTree(key) + + Return a sub tree starting at *key*. The resulting object can be used + like this one. + + .. method:: List([key]) + + List all items at *key*. Normally, return the keys at the top level, + eg. APT, Dir, etc. + + Use *key* to specify a key of which the childs will be returned. + + .. method:: ValueList([key]) + + Same as :meth:`Configuration.List`, but this time for the values. + + .. method:: MyTag() + + Return the tag name of the current tree. Normally this is an empty + string, but for subtrees it is the key of the subtree. + + .. method:: Clear(key) + + Clear the configuration. Remove all values and keys at *key*. + + .. method:: keys([key]) + + Return all the keys, recursive. If *key* is specified, ... (FIXME) + + .. method:: has_key(key) + + Return whether the configuration contains the key *key*. + + .. deprecated:: 0.8.0 + + .. method:: get(key[, default='']) + + This behaves just like :meth:`dict.get` and :meth:`Configuration.Find`, + it returns the value of key or if it does not exist, *default*. + +.. class:: ConfigurationPtr + + Behaves like a :class:`Configuration()` objects, but uses a pointer to the + underlying C++ object. This is used for the default configuration in the + :data:`Config` attribute of the module. + +.. class:: ConfigurationSub + + Behaves like a :class:`Configuration()` objects, but provides access to + a subsection of another Configuration-like object. This type of object is + returned by the :meth:`Configuration.SubTree()` method. + +.. data:: Config + + A :class:`ConfigurationPtr()` object with the default configuration. This + object is initialized by calling :func:`InitConfig`. + + +Modifying +^^^^^^^^^ + + +.. function:: ReadConfigFile(configuration, filename) + + Read the configuration file specified by the parameter *filename* and add + the settings therein to the :class:`Configuration()` object specified by + the parameter *configuration* + +.. function:: ReadConfigDir(configuration, dirname) + + Read configuration files in the directory specified by the parameter + *dirname* and add the settings therein to the :class:`Configuration()` + object specified by the parameter *configuration*. + +.. function:: ReadConfigFileISC(configuration, filename) + + Read the configuration file specified by the parameter *filename* and add + the settings therein to the :class:`Configuration()` object specified by + the parameter *configuration* + +.. function:: ParseCommandLine(configuration,options,argv) + + This function is like getopt except it manipulates a configuration space. + output is a list of non-option arguments (filenames, etc). *options* is a + list of tuples of the form ``(‘c’,”long-opt or None”, + ”Configuration::Variable”,”optional type”)``. + + Where ``type`` may be one of HasArg, IntLevel, Boolean, InvBoolean, + ConfigFile, or ArbItem. The default is Boolean. + +Locking +-------- + +.. function:: GetLock(filename) + + Create an empty file at the path specified by the parameter *filename* and + lock it. + + While the file is locked by a process, calling this function in another + process returns ``-1``. + + When the lock is not required anymore, the file descriptor should be closed + using :func:`os.close`. + +.. function:: PkgSystemLock() + + Lock the global pkgsystem. + +.. function:: PkgSystemUnLock() + + Unlock the global pkgsystem. + +Other classes +-------------- +.. class:: Cdrom() + + Return a Cdrom object with the following methods: + + .. method:: Ident(progress) + + Identify the cdrom. The parameter *progress* refers to an + :class:`apt.progress.CdromProgress()` object. + + .. method:: Add(progress) + + Add the cdrom to the sources.list file. The parameter *progress* + refers to an :class:`apt.progress.CdromProgress()` object. + +.. class:: SourceList + + This is for :file:`/etc/apt/sources.list`. + + .. method:: FindIndex(pkgfile) + + Return a :class:`PackageIndexFile` object for the :class:`PackageFile` + *pkgfile*. + + .. method:: ReadMainList + + Read the main list. + + .. method:: GetIndexes(acq[, all]) + + Add the index files to the :class:`Acquire()` object *acq*. If *all* is + given and ``True``, all files are fetched. + +String functions +---------------- +.. function:: Base64Encode(string) + + Encode the given string using base64, e.g:: + + >>> apt_pkg.Base64Encode(u"A") + 'QQ==' + + +.. function:: CheckDomainList(host, list) + + See if Host is in a ',' seperated list, e.g.:: + + apt_pkg.CheckDomainList("alioth.debian.org","debian.net,debian.org") + +.. function:: DeQuoteString(string) + + Dequote the string specified by the parameter *string*, e.g.:: + + >>> apt_pkg.DeQuoteString("%61%70%74%20is%20cool") + 'apt is cool' + +.. function:: QuoteString(string, repl) + + For every character listed in the string *repl*, replace all occurences in + the string *string* with the correct HTTP encoded value: + + >>> apt_pkg.QuoteString("apt is cool","apt") + '%61%70%74%20is%20cool' + +.. function:: SizeToStr(size) + + Return a string presenting the human-readable version of the integer + *size*. When calculating the units (k,M,G,etc.) the size is divided by the + factor 1000. + + Example:: + + >>> apt_pkg.SizeToStr(10000) + '10.0k' + +.. function:: StringToBool(input) + + Parse the string *input* and return one of **-1**, **0**, **1**. + + .. table:: Return values + + ===== ============================================= + Value Meaning + ===== ============================================= + -1 The string *input* is not recognized. + 0 The string *input* evaluates to **False**. + +1 The string *input* evaluates to **True**. + ===== ============================================= + + Example:: + + >>> apt_pkg.StringToBool("yes") + 1 + >>> apt_pkg.StringToBool("no") + 0 + >>> apt_pkg.StringToBool("not-recognized") + -1 + +.. function:: StrToTime(rfc_time) + + Convert the :rfc:`1123` conforming string *rfc_time* to the unix time, and + return the integer. This is the opposite of :func:`TimeRFC1123`. + + Example:: + + >> apt_pkg.StrToTime('Thu, 01 Jan 1970 00:00:00 GMT') + 0 + +.. function:: TimeRFC1123(seconds) + + Format the unix time specified by the integer *seconds*, according to the + requirements of :rfc:`1123`. + + Example:: + + >>> apt_pkg.TimeRFC1123(0) + 'Thu, 01 Jan 1970 00:00:00 GMT' + + +.. function:: TimeToStr(seconds) + + Format a given duration in a human-readable manner. The parameter *seconds* + refers to a number of seconds, given as an integer. The return value is a + string with a unit like 's' for seconds. + + Example:: + + >>> apt_pkg.TimeToStr(3601) + '1h0min1s' + +.. function:: UpstreamVersion(version) + + Return the string *version*, eliminating everything following the last + '-'. Thus, this should be equivalent to ``version.rsplit('-', 1)[0]``. + +.. function:: URItoFileName(uri) + + Take a string *uri* as parameter and return a filename which can be used to + store the file, based on the URI. + + Example:: + + >>> apt_pkg.URItoFileName('http://debian.org/index.html') + 'debian.org_index.html' + + +.. function:: VersionCompare(a, b) + + Compare two versions, *a* and *b*, and return an integer value which has + the same characteristic as the built-in :func:`cmp` function. + + .. table:: Return values + + ===== ============================================= + Value Meaning + ===== ============================================= + > 0 The version *a* is greater than version *b*. + = 0 Both versions are equal. + < 0 The version *a* is less than version *b*. + ===== ============================================= + + + + +Module Constants +---------------- +.. _CurStates: + +Package States +^^^^^^^^^^^^^^^ +.. data:: CurStateConfigFiles +.. data:: CurStateHalfConfigured +.. data:: CurStateHalfInstalled +.. data:: CurStateInstalled +.. data:: CurStateNotInstalled +.. data:: CurStateUnPacked + + + + +Dependency types +^^^^^^^^^^^^^^^^ +.. data:: DepConflicts +.. data:: DepDepends +.. data:: DepObsoletes +.. data:: DepPreDepends +.. data:: DepRecommends +.. data:: DepReplaces +.. data:: DepSuggests + +.. _InstStates: + +Installed states +^^^^^^^^^^^^^^^^ +.. data:: InstStateHold +.. data:: InstStateHoldReInstReq +.. data:: InstStateOk +.. data:: InstStateReInstReq + +.. _Priorities: + +Priorities +^^^^^^^^^^^ +.. data:: PriExtra +.. data:: PriImportant +.. data:: PriOptional +.. data:: PriRequired +.. data:: PriStandard + + +.. _SelStates: + +Select states +^^^^^^^^^^^^^ +.. data:: SelStateDeInstall +.. data:: SelStateHold +.. data:: SelStateInstall +.. data:: SelStatePurge +.. data:: SelStateUnknown + + +Build information +^^^^^^^^^^^^^^^^^ +.. data:: Date + + The date on which this extension has been compiled. + +.. data:: LibVersion + + The version of the apt_pkg library. This is **not** the version of apt, + nor the version of python-apt. + +.. data:: Time + + The time this extension has been built. + +.. data:: Version + + The version of apt (not of python-apt). + +.. data:: _COMPAT_0_7 + + A more or less internal variable defining whether this build provides an + API which is compatible to the one of python-apt 0.7. This is used in the + apt and aptsources packages to decide whether compatibility should be + enabled or not. diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst deleted file mode 100644 index a58f1356..00000000 --- a/doc/source/apt_pkg/cache.rst +++ /dev/null @@ -1,1243 +0,0 @@ -Classes in apt_pkg -================== - -.. todo:: - - This should be split and cleaned up a bit. - -:class:`Acquire` ----------------- -.. class:: Acquire - - .. method:: Run() - - Fetch all the items which have been added by - :func:`apt_pkg.GetPkgAcqFile`. - - .. method:: Shutdown - - Shut the fetcher down. - -:class:`PkgAcqFile` -------------------- -.. class:: PkgAcqFile - - This class provides no methods or attributes - -:class:`AcquireItem` ---------------------- - -.. class:: AcquireItem - - .. attribute:: ID - - The ID of the item. - - .. attribute:: Complete - - Is the item completely acquired? - - .. attribute:: Local - - Is the item a local file? - - .. attribute:: IsTrusted - - Can the file be trusted? - - .. attribute:: FileSize - - The size of the file, in bytes. - - .. attribute:: ErrorText - - The error message. For example, when a file does not exist on a http - server, this will contain a 404 error message. - - .. attribute:: DestFile - - The location the file is saved as. - - .. attribute:: DescURI - - The source location. - - **Status**: - - .. attribute:: Status - - Integer, representing the status of the item. - - .. attribute:: StatIdle - - Constant for comparing :attr:`AcquireItem.Status`. - - .. attribute:: StatFetching - - Constant for comparing :attr:`AcquireItem.Status` - - .. attribute:: StatDone - - Constant for comparing :attr:`AcquireItem.Status` - - .. attribute:: StatError - - Constant for comparing :attr:`AcquireItem.Status` - - .. attribute:: StatAuthError - - Constant for comparing :attr:`AcquireItem.Status` - -:class:`ActionGroup` --------------------- - -.. class:: ActionGroup - - Normally, apt checkes the package cache after every modification for - packages which are automatically installed but on which no package depends - anymore (it collects the package garbage). - - Using ActionGroups you can turn this off and therefore make your code - much faster. - - Initialize it using :func:`apt_pkg.GetPkgActionGroup`, eg:: - - apt_pkg.GetPkgActionGroup(depcache) - - .. method:: release - - Release the ActionGroup. This will reactive the collection of package - garbage. - - -:class:`Configuration` ----------------------- - -.. class:: Configuration - - The Configuration objects store the configuration of apt. - - .. describe:: key in conf - - Return ``True`` if *conf* has a key *key*, else ``False``. - - .. versionadded:: 0.8.0 - - .. describe:: conf[key] - - Return the value of the option given key *key*. If it does not - exist, raise :exc:`KeyError`. - - .. describe:: conf[key] = value - - Set the option at *key* to *value*. - - .. method:: Find(key[, default='']) - - Return the value for the given key *key*. This is the same as - :meth:`Configuration.get`. - - If *key* does not exist, return *default*. - - .. method:: FindFile(key[, default='']) - - Return the filename hold by the configuration at *key*. This formats the - filename correctly and supports the Dir:: stuff in the configuration. - - If *key* does not exist, return *default*. - - .. method:: FindDir(key[, default='/']) - - Return the absolute path to the directory specified in *key*. A - trailing slash is appended. - - If *key* does not exist, return *default*. - - .. method:: FindI(key[, default=0]) - - Return the integer value stored at *key*. - - If *key* does not exist, return *default*. - - .. method:: FindB(key[, default=0]) - - Return the boolean value stored at *key*. This returns an integer, but - it should be treated like True/False. - - If *key* does not exist, return *default*. - - .. method:: Set(key, value) - - Set the value of *key* to *value*. - - .. method:: Exists(key) - - Check whether the key *key* exists in the configuration. - - .. method:: SubTree(key) - - Return a sub tree starting at *key*. The resulting object can be used - like this one. - - .. method:: List([key]) - - List all items at *key*. Normally, return the keys at the top level, - eg. APT, Dir, etc. - - Use *key* to specify a key of which the childs will be returned. - - .. method:: ValueList([key]) - - Same as :meth:`Configuration.List`, but this time for the values. - - .. method:: MyTag() - - Return the tag name of the current tree. Normally this is an empty - string, but for subtrees it is the key of the subtree. - - .. method:: Clear(key) - - Clear the configuration. Remove all values and keys at *key*. - - .. method:: keys([key]) - - Return all the keys, recursive. If *key* is specified, ... (FIXME) - - .. method:: has_key(key) - - Return whether the configuration contains the key *key*. - - .. deprecated:: 0.8.0 - - .. method:: get(key[, default='']) - - This behaves just like :meth:`dict.get` and :meth:`Configuration.Find`, - it returns the value of key or if it does not exist, *default*. - - -:class:`pkgCache` ------------------ -.. class:: pkgCache - - The :class:`pkgCache` class prov - - .. describe:: cache[pkgname] - - Return the :class:`Package()` object for the package name given by - *pkgname*. - - .. method:: Close() - - Close the package cache. - - .. method:: Open([progress]) - - Open the package cache again. The parameter *progress* may be set to - an :class:`apt.progress.OpProgress()` object or `None`. - - .. method:: Update(progress, list) - - Update the package cache. - - The parameter *progress* points to an :class:`apt.progress.FetchProgress()` - object. - - The parameter *list* refers to an object as returned by - :func:`apt_pkg.GetPkgSourceList`. - - .. attribute:: DependsCount - - The total number of dependencies. - - .. attribute:: PackageCount - - The total number of packages available in the cache. - - .. attribute:: ProvidesCount - - The number of provided packages. - - .. attribute:: VerFileCount - - .. todo:: Seems to be some mixture of versions and pkgFile. - - .. attribute:: VersionCount - - The total number of package versions available in the cache. - - .. attribute:: PackageFileCount - - The total number of Packages files available (the Packages files - listing the packages). This is the same as the length of the list in - the attribute :attr:`FileList`. - - .. attribute:: FileList - - A list of :class:`PackageFile` objects. - - -:class:`PackageFile` --------------------- -.. class:: PackageFile - - A :class:`PackageFile` represents a Packages file, eg. - /var/lib/dpkg/status. - - .. attribute:: Architecture - - The architecture of the package file. - - .. attribute:: Archive - - The archive (eg. unstable) - - .. attribute:: Component - - The component (eg. main) - - .. attribute:: FileName - - The name of the file. - - .. attribute:: ID - - The ID of the package. This is an integer which can be used to store - further information about the file [eg. as dictionary key]. - - .. attribute:: IndexType - - The sort of the index file. In normal cases, this is - 'Debian Package Index'. - - .. attribute:: Label - - The Label, as set in the Release file - - .. attribute:: NotAutomatic - - Whether packages from this list will be updated automatically. The - default for eg. example is 0 (aka false). - - .. attribute:: NotSource - - Whether the file has no source from which it can be updated. In such a - case, the value is 1; else 0. /var/lib/dpkg/status is 0 for example. - - Example:: - - for pkgfile in cache.FileList: - if pkgfile.NotSource: - print 'The file %s has no source.' % pkgfile.FileName - - .. attribute:: Origin - - The Origin, as set in the Release file - - .. attribute:: Site - - The hostname of the site. - - .. attribute:: Size - - The size of the file. - - .. attribute:: Version - - The version, as set in the release file (eg. "4.0" for "Etch") - - -Example -^^^^^^^ -.. literalinclude:: ../examples/cache-pkgfile.py - - -:class:`Package` ----------------- - -.. class:: Package - - The pkgCache::Package objects are an interface to package specific - features. - - - Attributes: - - .. attribute:: CurrentVer - - The version currently installed, or None. This returns a - :class:`Version` object. - - .. attribute:: ID - - The ID of the package. This can be used to store information about - the package. The ID is an int value. - - .. attribute:: Name - - This is the name of the package. - - .. attribute:: ProvidesList - - A list of packages providing this package. More detailed, this is a - list of tuples (str:pkgname, ????, :class:`Version`). - - If you want to check for check for virtual packages, the expression - ``pkg.ProvidesList and not pkg.VersionList`` helps you. It detects if - the package is provided by something else and is not available as a - real package. - - .. attribute:: RevDependsList - - An iterator of :class:`Dependency` objects for dependencies on this - package. - - .. attribute:: Section - - The section of the package, as specified in the record. The list of - possible sections is defined in the Policy. - - .. attribute:: VersionList - - A list of :class:`Version` objects for all versions available in the - cache. - - **States**: - - .. attribute:: SelectedState - - The state we want it to be, ie. if you mark a package for installation, - this is :attr:`apt_pkg.SelStateInstall`. - - See :ref:`SelStates` for a list of available states. - - .. attribute:: InstState - - The state the currently installed version is in. This is normally - :attr:`apt_pkg.InstStateOK`, unless the installation failed. - - See :ref:`InstStates` for a list of available states. - - .. attribute:: CurState - - The current state of the package (not installed, unpacked, installed, - etc). See :ref:`CurStates` for a list of available states. - - **Flags**: - - .. attribute:: Auto - - Whether the package was installed automatically as a dependency of - another package. (or marked otherwise as automatically installed) - - .. attribute:: Essential - - Whether the package is essential. - - .. attribute:: Important - - Whether the package is important. - -Example: -^^^^^^^^^ -.. literalinclude:: ../examples/cache-packages.py - - - -:class:`Version` ----------------- -.. class:: Version - - The version object contains all information related to a specific package - version. - - .. attribute:: VerStr - - The version, as a string. - - .. attribute:: Section - - The usual sections (eg. admin, net, etc.). Prefixed with the component - name for packages not in main (eg. non-free/admin). - - .. attribute:: Arch - - The architecture of the package, eg. amd64 or all. - - .. attribute:: FileList - - A list of (:class:`PackageFile`, int: index) tuples for all Package - files containing this version of the package. - - .. attribute:: DependsListStr - - A dictionary of dependencies. The key specifies the type of the - dependency ('Depends', 'Recommends', etc.). - - - The value is a list, containing items which refer to the or-groups of - dependencies. Each of these or-groups is itself a list, containing - tuples like ('pkgname', 'version', 'relation') for each or-choice. - - An example return value for a package with a 'Depends: python (>= 2.4)' - would be:: - - {'Depends': [ - [ - ('python', '2.4', '>=') - ] - ] - } - - The same for a dependency on A (>= 1) | B (>= 2):: - - {'Depends': [ - [ - ('A', '1', '>='), - ('B', '2', '>='), - ] - ] - } - - .. attribute:: DependsList - - This is basically the same as :attr:`Version.DependsListStr`, - but instead of the ('pkgname', 'version', 'relation') tuples, - it returns :class:`Dependency` objects, which can assist you with - useful functions. - - .. attribute:: ParentPkg - - The :class:`Package` object this version belongs to. - - .. attribute:: ProvidesList - - This returns a list of all packages provided by this version. Like - :attr:`Package.ProvidesList`, it returns a list of tuples - of the form ('virtualpkgname', ???, :class:`Version`), where as the - last item is the same as the object itself. - - .. attribute:: Size - - The size of the .deb file, in bytes. - - .. attribute:: InstalledSize - - The size of the package (in kilobytes), when unpacked on the disk. - - .. attribute:: Hash - - An integer hash value. - - .. attribute:: ID - - An integer id. - - .. attribute:: Priority - - The integer representation of the priority. This can be used to speed - up comparisons a lot, compared to :attr:`Version.PriorityStr`. - - The values are defined in the :mod:`apt_pkg` extension, see - :ref:`Priorities` for more information. - - .. attribute:: PriorityStr - - Return the priority of the package version, as a string, eg. - "optional". - - .. attribute:: Downloadable - - Whether this package can be downloaded from a remote site. - - .. attribute:: TranslatedDescription - - Return a :class:`Description` object. - - -:class:`Dependency` -------------------- -.. class:: Dependency - - Represent a dependency from one package to another one. - - .. method:: AllTargets - - A list of :class:`Version` objects which satisfy the dependency, - and do not conflict with already installed ones. - - From my experience, if you use this method to select the target - version, it is the best to select the last item unless any of the - other candidates is already installed. This leads to results being - very close to the normal package installation. - - .. method:: SmartTargetPkg - - Return a :class:`Version` object of a package which satisfies the - dependency and does not conflict with installed packages - (the 'natural target'). - - .. attribute:: TargetVer - - The target version of the dependency, as string. Empty string if the - dependency is not versioned. - - .. attribute:: TargetPkg - - The :class:`Package` object of the target package. - - .. attribute:: ParentVer - - The :class:`Version` object of the parent version, ie. the package - which declares the dependency. - - .. attribute:: ParentPkg - - The :class:`Package` object of the package which declares the - dependency. This is the same as using ParentVer.ParentPkg. - - .. attribute:: CompType - - The type of comparison (>=, ==, >>, <=), as string. - - .. attribute:: DepType - - The type of the dependency, as string, eg. "Depends". - - .. attribute:: ID - - The ID of the package, as integer. - -Example: Find all missing dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -With the help of Dependency.AllTargets(), you can easily find all packages with -broken dependencies: - -.. literalinclude:: ../examples/missing-deps.py - - -:class:`Description` --------------------- -.. class:: Description - - Represent the description of the package. - - .. attribute:: LanguageCode - - The language code of the description - - .. attribute:: md5 - - The md5 hashsum of the description - - .. attribute:: FileList - - A list of tuples (:class:`PackageFile`, int: index). - - - -:class:`pkgDepCache` --------------------- -.. class:: pkgDepCache - - The pkgDepCache object contains various methods to manipulate the cache, - to install packages, to remove them, and much more. - - .. method:: Commit(fprogress, iprogress) - - Apply all the changes made. - - The parameter *fprogress* has to be set to an instance of - apt.progress.FetchProgress or one of its subclasses. - - The parameter *iprogress* has to be set to an instance of - apt.progress.InstallProgress or one of its subclasses. - - .. method:: FixBroken() - - Try to fix all broken packages in the cache. - - .. method:: GetCandidateVer(pkg) - - Return the candidate version of the package, ie. the version that - would be installed normally. - - The parameter *pkg* refers to an :class:`Package` object, - available using the :class:`pkgCache`. - - This method returns a :class:`Version` object. - - .. method:: SetCandidateVer(pkg, version) - - The opposite of :meth:`pkgDepCache.GetCandidateVer`. Set the candidate - version of the :class:`Package` *pkg* to the :class:`Version` - *version*. - - - .. method:: Upgrade([distUpgrade=False]) - - Perform an upgrade. More detailed, this marks all the upgradable - packages for upgrade. You still need to call - :meth:`pkgDepCache.Commit` for the changes to apply. - - To perform a dist-upgrade, the optional parameter *distUpgrade* has - to be set to True. - - .. method:: FixBroken() - - Fix broken packages. - - .. method:: ReadPinFile() - - Read the policy, eg. /etc/apt/preferences. - - .. method:: MinimizeUpgrade() - - 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. - - .. todo:: - Explain better.. - - .. method:: MarkKeep(pkg) - - Mark the :class:`Package` *pkg* for keep. - - .. method:: MarkDelete(pkg[, purge]) - - Mark the :class:`Package` *pkg* for delete. If *purge* is True, - the configuration files will be removed as well. - - .. method:: MarkInstall(pkg[, autoInst=True[, fromUser=True]]) - - Mark the :class:`Package` *pkg* for install. - - If *autoInst* is ``True``, the dependencies of the package will be - installed as well. This is the default. - - If *fromUser* is ``True``, the package will be marked as manually - installed. This is the default. - - .. method:: SetReinstall(pkg) - - Set if the :class:`Package` *pkg* should be reinstalled. - - .. method:: IsUpgradable(pkg) - - Return ``1`` if the package is upgradable. - - The package can be upgraded by calling :meth:`pkgDepCache.MarkInstall`. - - .. method:: IsNowBroken(pkg) - - Return `1` if the package is broken now (including changes made, but - not committed). - - .. method:: IsInstBroken(pkg) - - Return ``1`` if the package is broken on the current install. This - takes changes which have not been committed not into effect. - - .. method:: IsGarbage(pkg) - - Return ``1`` if the package is garbage, ie. if it is automatically - installed and no longer referenced by other packages. - - .. method:: IsAutoInstalled(pkg) - - Return ``1`` if the package is automatically installed (eg. as the - dependency of another package). - - .. method:: MarkedInstall(pkg) - - Return ``1`` if the package is marked for install. - - .. method:: MarkedUpgrade(pkg) - - Return ``1`` if the package is marked for upgrade. - - .. method:: MarkedDelete(pkg) - - Return ``1`` if the package is marked for delete. - - .. method:: MarkedKeep(pkg) - - Return ``1`` if the package is marked for keep. - - .. method:: MarkedReinstall(pkg) - - Return ``1`` if the package should be installed. - - .. method:: MarkedDowngrade(pkg) - - Return ``1`` if the package should be downgraded. - - .. attribute:: KeepCount - - Integer, number of packages marked as keep - - .. attribute:: InstCount - - Integer, number of packages marked for installation. - - .. attribute:: DelCount - - Number of packages which should be removed. - - .. attribute:: BrokenCount - - Number of packages which are broken. - - .. attribute:: UsrSize - - The size required for the changes on the filesystem. If you install - packages, this is positive, if you remove them its negative. - - .. attribute:: DebSize - - The size of the packages which are needed for the changes to be - applied. - - -:class:`MetaIndex` ------------------- - -.. todo:: - - Complete them - -.. class:: MetaIndex - - .. attribute:: URI - .. attribute:: Dist - .. attribute:: IsTrusted - .. attribute:: IndexFiles - - -:class:`PackageIndexFile` -------------------------- - -.. class:: PackageIndexFile - - .. method:: ArchiveURI(path) - - Return the full url to path in the archive. - - .. attribute:: Label - - Return the Label. - - .. attribute:: Exists - - Return whether the file exists. - - .. attribute:: HasPackages - - Return whether the file has packages. - - .. attribute:: Size - - Size of the file - - .. attribute:: IsTrusted - - Whether we can trust the file. - - -:class:`PkgManager` -------------------- - -.. class:: PkgManager - - Class, as returned by :func:`apt_pkg.GetPackageManager`. - - .. method:: GetArchives(fetcher, list, records) - - Add all the selected packages to the :class:`Acquire()` object - *fetcher*. - - The parameter *list* refers to a :class:`PkgSourceList()` object, as - returned by :func:`apt_pkg.GetPkgSourceList`. - - The parameter *records* refers to a :class:`pkgRecords()` object, as - returned by :func:`apt_pkg.GetPkgRecords`. - - .. method:: DoInstall() - - Install the packages. - - .. method:: FixMissing - - Fix the installation if a package could not be downloaded. - - .. attribute:: ResultCompleted - - A constant for checking whether the the result is 'completed'. - - Compare it against the return value of :meth:`PkgManager.GetArchives` - or :meth:`PkgManager.DoInstall`. - - .. attribute:: ResultFailed - - A constant for checking whether the the result is 'failed'. - - Compare it against the return value of :meth:`PkgManager.GetArchives` - or :meth:`PkgManager.DoInstall`. - - .. attribute:: ResultIncomplete - - A constant for checking whether the the result is 'incomplete'. - - Compare it against the return value of :meth:`PkgManager.GetArchives` - or :meth:`PkgManager.DoInstall`. - -:class:`pkgRecords` --------------------- - -.. class:: PkgRecords - - Provide access to the packages records. This provides very useful - attributes for fast (convient) access to some fields of the record. - - See :func:`apt_pkg.GetPkgRecords` for initialization. - - - .. method:: Lookup(verfile_iter) - - Change the actual package to the package given by the verfile_iter. - - The parameter *verfile_iter* refers to a tuple consisting - of (:class:`PackageFile()`, int: index), as returned by various - attributes, including :attr:`Version.FileList`. - - Example (shortened):: - - cand = depcache.GetCandidateVer(cache['python-apt']) - records.Lookup(cand.FileList[0]) - # Now you can access the record - print records.SourcePkg # == python-apt - - .. attribute:: FileName - - Return the field 'Filename' of the record. This is the path to the - package, relative to the base path of the archive. - - .. attribute:: MD5Hash - - Return the MD5 hashsum of the package This refers to the field - 'MD5Sum' in the raw record. - - .. attribute:: SHA1Hash - - Return the SHA1 hashsum of the package. This refers to the field 'SHA1' - in the raw record. - - .. attribute:: SHA256Hash - - Return the SHA256 hashsum of the package. This refers to the field - 'SHA256' in the raw record. - - .. versionadded:: 0.7.9 - - .. attribute:: SourcePkg - - Return the source package. - - .. attribute:: SourceVer - - Return the source version. - - .. attribute:: Maintainer - - Return the maintainer of the package. - - .. attribute:: ShortDesc - - Return the short description. This is the summary on the first line of - the 'Description' field. - - .. attribute:: LongDesc - - Return the long description. These are lines 2-END from the - 'Description' field. - - .. attribute:: Name - - Return the name of the package. This is the 'Package' field. - - .. attribute:: Homepage - - Return the Homepage. This is the 'Homepage' field. - - .. attribute:: Record - - Return the whole record as a string. If you want to access fields of - the record not available as an attribute, you can use - :func:`apt_pkg.ParseSection` to parse the record and access the field - name. - - Example:: - - section = apt_pkg.ParseSection(records.Record) - print section['SHA256'] - -:class:`PkgSrcRecords` ----------------------- - -.. class:: PkgSrcRecords - - This represents the entries in the Sources files, ie. the dsc files of - the source packages. - - .. note:: - - If the Lookup failed, because no package could be found, no error is - raised. Instead, the attributes listed below are simply not existing - anymore (same applies when no Lookup has been made, or when it has - been restarted). - - .. method:: Lookup(pkgname) - - Lookup the record for the package named *pkgname*. To access all - available records, you need to call it multiple times. - - Imagine a package P with two versions X, Y. The first ``Lookup(P)`` - would set the record to version X and the second ``Lookup(P)`` to - version Y. - - .. method:: Restart() - - Restart the lookup. - - Imagine a package P with two versions X, Y. The first ``Lookup(P)`` - would set the record to version X and the second ``Lookup(P)`` to - version Y. - - If you now call ``Restart()``, the internal position will be cleared. - Now you can call ``Lookup(P)`` again to move to X. - - .. attribute:: Package - - The name of the source package. - - .. attribute:: Version - - A string describing the version of the source package. - - .. attribute:: Maintainer - - A string describing the name of the maintainer. - - .. attribute:: Section - - A string describing the section. - - .. attribute:: Record - - The whole record, as a string. You can use :func:`apt_pkg.ParseSection` - if you need to parse it. - - You need to parse the record if you want to access fields not available - via the attributes, eg. 'Standards-Version' - - .. attribute:: Binaries - - Return a list of strings describing the package names of the binaries - created by the source package. This matches the 'Binary' field in the - raw record. - - .. attribute:: Index - - The index in the Sources files. - - .. attribute:: Files - - The list of files. This returns a list of tuples with the contents - ``(str: md5, int: size, str: path, str:type)``. - - .. attribute:: BuildDepends - - Return the list of Build dependencies, as - ``(str: package, str: version, int: op, int: type)``. - - .. table:: Values of *op* - - ===== ============================================= - Value Meaning - ===== ============================================= - 0x0 No Operation (no versioned build dependency) - 0x10 | (or) - this will be added to the other values - 0x1 <= (less than or equal) - 0x2 >= (greater than or equal) - 0x3 << (less than) - 0x4 >> (greater than) - 0x5 == (equal) - 0x6 != (not equal) - ===== ============================================= - - .. table:: Values of *type* - - ===== =================== - Value Meaning - ===== =================== - 0 Build-Depends - 1 Build-Depends-Indep - 2 Build-Conflicts - 3 Build-Conflicts-Indep - ===== =================== - - **Example**: In the following content, we will imagine a - build-dependency:: - - Build-Depends: A (>= 1) | B (>= 1), C - - This results in:: - - [('A', '1', 18, 0), # 18 = 16 + 2 = 0x10 + 0x2 - ('B', '1', 2, 0), - ('C', '', 0, 0)] - - This is **not** the same as returned by - :func:`apt_pkg.ParseSrcDepends`. - - -:class:`PkgSourceList` ------------------------ - -.. class:: PkgSourceList - - This is for :file:`/etc/apt/sources.list`. - - .. method:: FindIndex(pkgfile) - - Return a :class:`PackageIndexFile` object for the :class:`PackageFile` - *pkgfile*. - - .. method:: ReadMainList - - Read the main list. - - .. method:: GetIndexes(acq[, all]) - - Add the index files to the :class:`Acquire()` object *acq*. If *all* is - given and ``True``, all files are fetched. - - -:class:`ProblemResolver` ------------------------- -.. class:: ProblemResolver - - The problem resolver helps when there are problems in the package - selection. An example is a package which conflicts with another, already - installed package. - - .. method:: Protect(pkg) - - Protect the :class:`Package()` object given by the parameter *pkg*. - - .. todo:: - - Really document it. - - .. method:: InstallProtect() - - Protect all installed packages from being removed. - - .. method:: Remove(pkg) - - Remove the :class:`Package()` object given by the parameter *pkg*. - - .. todo:: - - Really document it. - - .. method:: Clear(pkg) - - Reset the :class:`Package()` *pkg* to the default state. - - .. todo:: - - Really document it. - - .. method:: Resolve() - - Try to resolve problems by installing and removing packages. - - .. method:: ResolveByKeep() - - Try to resolve problems only by using keep. - - -:class:`TagFile` ----------------- - -.. class:: TagFile - - An object which represents a typical debian control file. Can be used for - Packages, Sources, control, Release, etc. - - Use :func:`apt_pkg.ParseTagFile` to parse a file. - - .. method:: Step - - Step forward to the next section. This simply returns ``1`` if OK, and - ``0`` if there is no section - - .. method:: Offset - - Return the current offset (in bytes) from the beginning of the file. - - .. method:: Jump(offset) - - Jump back/forward to *offset*. Use ``Jump(0)`` to jump to the - beginning of the file again. - - .. attribute:: Section - - This is the current :class:`TagSection()` instance. - -:class:`TagSection` -------------------- - -.. class:: TagSection - - Represent a single section of a debian control file. - - .. describe:: section[key] - - Return the value of the field at *key*. If *key* is not available, - raise :exc:`KeyError`. - - .. describe:: key in section - - Return ``True`` if *section* has a key *key*, else ``False``. - - .. versionadded:: 0.8.0 - - .. method:: Bytes - - The number of bytes in the section. - - .. method:: Find(key, default='') - - Return the value of the field at the key *key* if available, - else return *default*. - - .. method:: FindFlag(key) - - Find a yes/no value for the key *key*. An example for such a - field is 'Essential'. - - .. method:: get(key, default='') - - Return the value of the field at the key *key* if available, else - return *default*. - - .. method:: has_key(key) - - Check whether the field with named by *key* exists. - - .. deprecated:: 0.8.0 - - .. method:: keys() - - Return a list of keys in the section. diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst deleted file mode 100644 index 47923c23..00000000 --- a/doc/source/apt_pkg/index.rst +++ /dev/null @@ -1,530 +0,0 @@ -:mod:`apt_pkg` --- The low-level bindings for apt-pkg -===================================================== -.. module:: apt_pkg - -The apt_pkg extensions provides a more low-level way to work with apt. It can -do everything apt can, and is written in C++. It has been in python-apt since -the beginning. - - -.. toctree:: - :maxdepth: 2 - :glob: - - * - - -Module Initialization ---------------------- - -Initialization is needed for most functions, but not for all of them. Some can -be called without having run init*(), but will not return the expected value. - -.. function:: initConfig - - Initialize the configuration of apt. This is needed for most operations. - -.. function:: initSystem - - Initialize the system. - -.. function:: init - - Deprecated function. Use initConfig() and initSystem() instead. - -Object initialization ----------------------- -.. function:: GetCache([progress]) - - Return a :class:`pkgCache` object. The optional parameter *progress* - specifies an instance of :class:`apt.progress.OpProgress()` which will - display the open progress. - -.. function:: GetCdrom() - - Return a Cdrom object with the following methods: - - .. method:: Cdrom.Ident(progress) - - Identify the cdrom. The parameter *progress* refers to an - :class:`apt.progress.CdromProgress()` object. - - .. method:: Cdrom.Add(progress) - - Add the cdrom to the sources.list file. The parameter *progress* - refers to an :class:`apt.progress.CdromProgress()` object. - - -.. function:: GetDepCache(cache) - - Return a :class:`pkgDepCache` object. The parameter *cache* specifies an - instance of :class:`pkgCache` (see :func:`GetCache()`). - - -.. function:: GetPkgSourceList() - - Return a :class:`PkgSourceList` object. - -.. function:: GetPackageManager(depcache) - - Return a new :class:`PkgManager` object. The parameter *depcache* specifies - a :class:`pkgDepCache` object as returned by :func:`GetDepCache`. - -.. function:: GetPkgActionGroup(depcache) - - Return a new :class:`ActionGroup` object. The parameter *depcache* - specifies a :class:`pkgDepCache` object as returned by :func:`GetDepCache`. - -.. function:: GetPkgProblemResolver(depcache) - - Return a new :class:`ProblemResolver` object. The parameter *depcache* - specifies a :class:`pkgDepCache` object as returned by :func:`GetDepCache`. - -.. function:: GetPkgRecords(cache) - - Return a new :class:`PkgRecords` object. - - The parameter *cache* refers to an :class:`pkgCache` object, as returned - by :func:`GetCache`. - -.. function:: GetPkgSrcRecords() - - Return a new :class:`PkgSrcRecords` object. - - - -The Acquire interface ----------------------- -.. function:: GetAcquire([progress]) - - Return an :class:`Acquire` object. This is a class which allows you - to fetch files, or archive contents. The parameter *progress* refers to - an :class:`apt.progress.FetchProgress()` object. - - Acquire items have multiple methods: - - .. method:: Acquire.Run() - - Fetch all the items which have been added by :func:`GetPkgAcqFile`. - - .. method:: Acquire.Shutdown() - - Shut the fetcher down. - - .. attribute:: Acquire.TotalNeeded - - The total amount of bytes needed (including those of files which are - already present) - - .. attribute:: Acquire.FetchNeeded - - The total amount of bytes which need to be fetched. - - .. attribute:: Acquire.PartialPresent - - Whether some files have been acquired already. (???) - - -.. function:: GetPkgAcqFile(aquire, uri[, md5, size, descr, shortDescr, destDir, destFile]) - - Create a new :class:`PkgAcqFile()` object and register it with *acquire*, - so it will be fetched. - - The parameter *acquire* refers to an :class:`Acquire()` object as returned - by :func:`GetAcquire`. The file will be added to the Acquire queue - automatically. - - The parameter *uri* refers to the location of the file, any protocol - of apt is supported. - - The parameter *md5* refers to the md5sum of the file. This can be used - for checking the file. - - The parameter *size* can be used to specify the size of the package, - which can then be used to calculate the progress and validate the download. - - The parameter *descr* is a descripition of the download. It may be - used to describe the item in the progress class. *shortDescr* is the - short form of it. - - You can use *destDir* to manipulate the directory where the file will - be saved in. Instead of *destDir*, you can also specify the full path to - the file using the parameter *destFile*. You can not combine both. - - - -Hash functions --------------- -The apt_pkg module also provides several hash functions. If you develop -applications with python-apt it is often easier to use these functions instead -of the ones provides in Python's :mod:`hashlib` module. - -.. function:: md5sum(object) - - Return the md5sum of the object. *object* may either be a string, in - which case the md5sum of the string is returned, or a :class:`file()` - object (or a file descriptor), in which case the md5sum of its contents is - returned. - - .. versionchanged:: 0.8.0 - Added support for using file descriptors. - -.. function:: sha1sum(object) - - Return the sha1sum of the object. *object* may either be a string, in - which case the sha1sum of the string is returned, or a :class:`file()` - object (or a file descriptor), in which case the sha1sum of its contents - is returned. - - .. versionchanged:: 0.8.0 - Added support for using file descriptors. - -.. function:: sha256sum(object) - - Return the sha256sum of the object. *object* may either be a string, in - which case the sha256sum of the string is returned, or a :class:`file()` - object (or a file descriptor), in which case the sha256sum of its contents - is returned. - - .. versionchanged:: 0.8.0 - Added support for using file descriptors. - -Debian control files --------------------- -.. function:: ParseSection(text) - - Parse the string given in the parameter *text* and return a - :class:`TagSection` object. - -.. function:: ParseTagFile(file) - - Parse the given *file* and return a :class:`TagFile()` object. *file* may - be a :class:`file()` object, a file descriptor, or anything providing a - :meth:`fileno()` method. - - .. versionchanged:: 0.8.0 - Added support for using file descriptors. - -.. autofunction:: RewriteSection(section, order, rewrite_list) - -.. data:: RewritePackageOrder - - The order in which the information for binary packages should be rewritten, - i.e. the order in which the fields should appear. - -.. data:: RewriteSourceOrder - - The order in which the information for source packages should be rewritten, - i.e. the order in which the fields should appear. - -Dependencies ------------- -.. function:: CheckDep(pkgver, op, depver) - - Check that the dependency requirements consisting of op and depver can be - satisfied by the version pkgver. - - Example:: - - >>> bool(apt_pkg.CheckDep("1.0", ">=", "1")) - True - -.. function:: ParseDepends(depends) - - Parse the string *depends* which contains dependency information as - specified in Debian Policy, Section 7.1. - - Returns a list. The members of this list are lists themselves and contain - one or more tuples in the format ``(package,version,operation)`` for every - 'or'-option given, e.g.:: - - >>> apt_pkg.ParseDepends("PkgA (>= VerA) | PkgB (>= VerB)") - [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] - -.. function:: ParseSrcDepends(depends) - - Parse the string *depends* which contains dependency information as - specified in Debian Policy, Section 7.1. - - Returns a list. The members of this list are lists themselves and contain - one or more tuples in the format ``(package,version,operation)`` for every - 'or'-option given, e.g.:: - - >>> apt_pkg.ParseDepends("PkgA (>= VerA) | PkgB (>= VerB)") - [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] - - - Furthemore, this function also supports to limit the architectures, as - used in e.g. Build-Depends:: - - >>> apt_pkg.ParseSrcDepends("a (>= 01) [i386 amd64]") - [[('a', '01', '>=')]] - - -Configuration -------------- - -.. data:: Config - - A :class:`Configuration()`-like object with the default configuration. This - is implemented in the :class:`ConfigurationPtr` class, which has the same - API like the :class:`Configuration` class. - -.. function:: newConfiguration() - - Return a new :class:`Configuration` object. - -.. function:: ReadConfigFile(configuration, filename) - - Read the configuration file specified by the parameter *filename* and add - the settings therein to the :class:`Configuration()` object specified by - the parameter *configuration* - -.. function:: ReadConfigDir(configuration, dirname) - - Read configuration files in the directory specified by the parameter - *dirname* and add the settings therein to the :class:`Configuration()` - object specified by the parameter *configuration*. - -.. function:: ReadConfigFileISC(configuration, filename) - - Read the configuration file specified by the parameter *filename* and add - the settings therein to the :class:`Configuration()` object specified by - the parameter *configuration* - -.. function:: ParseCommandLine(configuration,options,argv) - - This function is like getopt except it manipulates a configuration space. - output is a list of non-option arguments (filenames, etc). *options* is a - list of tuples of the form ``(‘c’,”long-opt or None”, - ”Configuration::Variable”,”optional type”)``. - - Where ``type`` may be one of HasArg, IntLevel, Boolean, InvBoolean, - ConfigFile, or ArbItem. The default is Boolean. - -Locking --------- - -.. function:: GetLock(filename) - - Create an empty file at the path specified by the parameter *filename* and - lock it. - - While the file is locked by a process, calling this function in another - process returns ``-1``. - - When the lock is not required anymore, the file descriptor should be closed - using :func:`os.close`. - -.. function:: PkgSystemLock() - - Lock the global pkgsystem. - -.. function:: PkgSystemUnLock() - - Unlock the global pkgsystem. - -Other functions ----------------- -.. function:: Base64Encode(string) - - Encode the given string using base64, e.g:: - - >>> apt_pkg.Base64Encode(u"A") - 'QQ==' - - -.. function:: CheckDomainList(host, list) - - See if Host is in a ',' seperated list, e.g.:: - - apt_pkg.CheckDomainList("alioth.debian.org","debian.net,debian.org") - -.. function:: DeQuoteString(string) - - Dequote the string specified by the parameter *string*, e.g.:: - - >>> apt_pkg.DeQuoteString("%61%70%74%20is%20cool") - 'apt is cool' - -.. function:: QuoteString(string, repl) - - For every character listed in the string *repl*, replace all occurences in - the string *string* with the correct HTTP encoded value: - - >>> apt_pkg.QuoteString("apt is cool","apt") - '%61%70%74%20is%20cool' - -.. function:: SizeToStr(size) - - Return a string presenting the human-readable version of the integer - *size*. When calculating the units (k,M,G,etc.) the size is divided by the - factor 1000. - - Example:: - - >>> apt_pkg.SizeToStr(10000) - '10.0k' - -.. function:: StringToBool(input) - - Parse the string *input* and return one of **-1**, **0**, **1**. - - .. table:: Return values - - ===== ============================================= - Value Meaning - ===== ============================================= - -1 The string *input* is not recognized. - 0 The string *input* evaluates to **False**. - +1 The string *input* evaluates to **True**. - ===== ============================================= - - Example:: - - >>> apt_pkg.StringToBool("yes") - 1 - >>> apt_pkg.StringToBool("no") - 0 - >>> apt_pkg.StringToBool("not-recognized") - -1 - -.. function:: StrToTime(rfc_time) - - Convert the :rfc:`1123` conforming string *rfc_time* to the unix time, and - return the integer. This is the opposite of :func:`TimeRFC1123`. - - Example:: - - >> apt_pkg.StrToTime('Thu, 01 Jan 1970 00:00:00 GMT') - 0 - -.. function:: TimeRFC1123(seconds) - - Format the unix time specified by the integer *seconds*, according to the - requirements of :rfc:`1123`. - - Example:: - - >>> apt_pkg.TimeRFC1123(0) - 'Thu, 01 Jan 1970 00:00:00 GMT' - - -.. function:: TimeToStr(seconds) - - Format a given duration in a human-readable manner. The parameter *seconds* - refers to a number of seconds, given as an integer. The return value is a - string with a unit like 's' for seconds. - - Example:: - - >>> apt_pkg.TimeToStr(3601) - '1h0min1s' - -.. function:: UpstreamVersion(version) - - Return the string *version*, eliminating everything following the last - '-'. Thus, this should be equivalent to ``version.rsplit('-', 1)[0]``. - -.. function:: URItoFileName(uri) - - Take a string *uri* as parameter and return a filename which can be used to - store the file, based on the URI. - - Example:: - - >>> apt_pkg.URItoFileName('http://debian.org/index.html') - 'debian.org_index.html' - - -.. function:: VersionCompare(a, b) - - Compare two versions, *a* and *b*, and return an integer value which has - the same characteristic as the built-in :func:`cmp` function. - - .. table:: Return values - - ===== ============================================= - Value Meaning - ===== ============================================= - > 0 The version *a* is greater than version *b*. - = 0 Both versions are equal. - < 0 The version *a* is less than version *b*. - ===== ============================================= - - - - -.. _CurStates: - -Package States ---------------- -.. data:: CurStateConfigFiles -.. data:: CurStateHalfConfigured -.. data:: CurStateHalfInstalled -.. data:: CurStateInstalled -.. data:: CurStateNotInstalled -.. data:: CurStateUnPacked - - - - -Dependency types ----------------- -.. data:: DepConflicts -.. data:: DepDepends -.. data:: DepObsoletes -.. data:: DepPreDepends -.. data:: DepRecommends -.. data:: DepReplaces -.. data:: DepSuggests - -.. _InstStates: - -Installed states ------------------ -.. data:: InstStateHold -.. data:: InstStateHoldReInstReq -.. data:: InstStateOk -.. data:: InstStateReInstReq - -.. _Priorities: - -Priorities ----------- -.. data:: PriExtra -.. data:: PriImportant -.. data:: PriOptional -.. data:: PriRequired -.. data:: PriStandard - - -.. _SelStates: - -Select states --------------- -.. data:: SelStateDeInstall -.. data:: SelStateHold -.. data:: SelStateInstall -.. data:: SelStatePurge -.. data:: SelStateUnknown - - -Build information ------------------ -.. data:: Date - - The date on which this extension has been compiled. - -.. data:: LibVersion - - The version of the apt_pkg library. This is **not** the version of apt, - nor the version of python-apt. - -.. data:: Time - - The time this extension has been built. - -.. data:: Version - - The version of apt (not of python-apt). diff --git a/doc/source/index.rst b/doc/source/index.rst index 930ff55c..2e05061a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,27 +1,27 @@ Welcome to python-apt's documentation! ====================================== -.. note:: +This is the official documentation for version |version| of the Python bindings +for Debian's famous APT package management. - This documentation can not be considered complete at the moment. But it - provides better documentation than the documentation available through - pydoc. +This documentation has been created by Sphinx, using reStructuredText files +written by Julian Andres Klode , and in case of the apt +package, from the documentation shipped in the modules. -.. note:: +Contents: - This documentation has been created by Sphinx, using reStructuredText files - written by Julian Andres Klode , and in case of the apt - package, from the documentation shipped in the modules. - +.. toctree:: + :hidden: -Contents: + whatsnew/index .. toctree:: :maxdepth: 2 + whatsnew/0.8.0 apt/index - apt_pkg/index + apt_pkg apt_inst aptsources/index contributing diff --git a/doc/source/whatsnew/0.8.0.rst b/doc/source/whatsnew/0.8.0.rst new file mode 100644 index 00000000..d1ac3ac5 --- /dev/null +++ b/doc/source/whatsnew/0.8.0.rst @@ -0,0 +1,33 @@ +What's New In python-apt 0.8 +============================ +Python-apt 0.8 is a new major release of the python bindings for the APT +package management libraries. It provides support for Python 3, new language +features and an API conforming to :PEP:`8`. + +Despite the many changes made in python-apt 0.8, the release still provides +backwards compatibility to the 0.7 series. This makes it possible to run your +old applications. Applications using the old API should be updated to the new +API, because the old one will be removed after some time. + +Support for Python 3 +-------------------- +Python-apt is the first Debian package to support the third major release of +Python. The port is straight forward and integrates as nicely in Python 3 as +the Python 2 builds integrate in Python 2. + +Real classes in :mod:`apt_pkg` +------------------------------ + +Complete rename of functions, methods and attributes +----------------------------------------------------- + +Supporting new language features like the :keyword:`with` statement +------------------------------------------------------------------- + +Other changes +------------- +This release of python-apt also features several other, smaller changes: + + * Reduced memory usage by creating Package() objects in apt.Cache() only + when needed. + * Support to set the candidate version in :class:`apt.package.Package` diff --git a/doc/source/whatsnew/index.rst b/doc/source/whatsnew/index.rst new file mode 100644 index 00000000..cc270a16 --- /dev/null +++ b/doc/source/whatsnew/index.rst @@ -0,0 +1,9 @@ +What's new in python-apt +======================== + +.. toctree:: + :maxdepth: 2 + :glob: + + * + -- cgit v1.2.3