From 6a806f0570599e8f5e9438c9623d496df75571d4 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Fri, 9 Jan 2009 21:52:07 +0100 Subject: * Introduce the new documentation and add 0.7.9~exp2 to changelog. The new documentation is built using sphinx (>= 0.5) [other versions may work too, but let's be safe]. --- doc/source/apt_pkg/cache.rst | 95 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 doc/source/apt_pkg/cache.rst (limited to 'doc/source/apt_pkg/cache.rst') diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst new file mode 100644 index 00000000..abb0fab2 --- /dev/null +++ b/doc/source/apt_pkg/cache.rst @@ -0,0 +1,95 @@ +Low-Level Cache Handling +=========================== + +.. class:: Acquire + + .. method:: Run() + + Fetch all the items which have been added by + :func:`apt_pkg.GetPkgAcqFile`. + + .. method:: Shutdown + + Shut the fetcher down. + +.. class:: pkgCache + + The :class:`pkgCache` class prov + + .. 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`. + + .. method:: __getitem__(item) + + Return an :class:`pkgCachePackage` object for the package with the given + name. + +.. class:: pkgCachePackage + + The pkgCache::Package objects are an interface to package specific + features. + + + Attributes: + + .. attribute:: Name + + This is the name of the package. + + .. attribute:: Section + + The section of the package, as specified in the record. The list of + possible sections is defined in the Policy. + + .. attribute:: ID + + The ID of the package. This can be used to store information about + the package. The ID is an int value. + + +Working with dependencies +------------------------- +.. 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:`pkgCachePackage` object, + available using the :class:`pkgCache`. + + This method returns a :class:`pkgCacheVersion` object. -- cgit v1.2.3 From 513093cd51f95a8d014cd5436d3fff8556e10ced Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sat, 10 Jan 2009 18:14:11 +0100 Subject: * doc/: Heavily improve documentation Complete the documentation of pkgCache, pkgDepCache, pkgCache::Package. Introduce new documentation for pkgCache::Version, pkgCache::Dependency, pkgCache::PackageFile, pkgcache::Description. There is also an example now which checks for missing dependencies. --- doc/source/apt/debfile.rst | 6 +- doc/source/apt_pkg/cache.rst | 532 +++++++++++++++++++++++++++++++++- doc/source/apt_pkg/index.rst | 24 +- doc/source/conf.py | 5 +- doc/source/examples/cache-packages.py | 22 ++ doc/source/examples/cache-pkgfile.py | 29 ++ doc/source/examples/missing-deps.py | 51 ++++ 7 files changed, 655 insertions(+), 14 deletions(-) create mode 100644 doc/source/examples/cache-packages.py create mode 100644 doc/source/examples/cache-pkgfile.py create mode 100644 doc/source/examples/missing-deps.py (limited to 'doc/source/apt_pkg/cache.rst') diff --git a/doc/source/apt/debfile.rst b/doc/source/apt/debfile.rst index 70c39087..c0146df9 100644 --- a/doc/source/apt/debfile.rst +++ b/doc/source/apt/debfile.rst @@ -21,8 +21,10 @@ Binary packages If you specify ``cache`` it has to point to an :class:`apt.cache.Cache()` object. - All methods except for :meth:`open()` and the attribute :attr:`filelist` have been - introduced in version 0.7.9. + .. versionchanged:: 0.7.9 + Introduce all new methods (everything except for :meth:`open()` and + :attr:`filelist`) + Source packages ---------------- diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index abb0fab2..81ee2a8e 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -1,5 +1,10 @@ -Low-Level Cache Handling -=========================== +Classes in apt_pkg +================== + +.. todo:: + + This should be split and cleaned up a bit. + .. class:: Acquire @@ -12,6 +17,9 @@ Low-Level Cache Handling Shut the fetcher down. + +The cache +--------- .. class:: pkgCache The :class:`pkgCache` class prov @@ -37,10 +45,121 @@ Low-Level Cache Handling .. method:: __getitem__(item) - Return an :class:`pkgCachePackage` object for the package with the given + Return an :class:`Package` object for the package with the given name. -.. class:: pkgCachePackage + .. 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. + + +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: + + .. code-block:: python + + 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 + + +A Package +--------- + +.. class:: Package The pkgCache::Package objects are an interface to package specific features. @@ -48,23 +167,285 @@ Low-Level Cache Handling 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 + + + +Version, as returned by eg. :meth:`pkgDepCache.GetCandidateVer` +--------------------------------------------------------------- +.. 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: + + .. code-block:: python + + {'Depends': [ + [ + ('python', '2.4', '>=') + ] + ] + } + + The same for a dependency on A (>= 1) | B (>= 2): + + .. code-block:: python + + {'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 - The ID of the package. This can be used to store information about - the package. The ID is an int value. + 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. + + +The Dependency class +-------------------- +.. 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 -Working with dependencies -------------------------- + 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 + + +The Description class +--------------------- +.. 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). + + + +The pkgDepCache wrapper +----------------------- .. class:: pkgDepCache The pkgDepCache object contains various methods to manipulate the cache, @@ -89,7 +470,138 @@ Working with dependencies Return the candidate version of the package, ie. the version that would be installed normally. - The parameter ``pkg`` refers to an :class:`pkgCachePackage` object, + The parameter ``pkg`` refers to an :class:`Package` object, available using the :class:`pkgCache`. - This method returns a :class:`pkgCacheVersion` object. + 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. diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst index 5f23df31..1c5866a9 100644 --- a/doc/source/apt_pkg/index.rst +++ b/doc/source/apt_pkg/index.rst @@ -83,6 +83,20 @@ The Acquire interface 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]) The parameter ``acquire`` refers to an :class:`Acquire()` object as returned @@ -184,6 +198,8 @@ Data .. data:: RewriteSourceOrder +.. _CurStates: + Package States ^^^^^^^^^^^^^^^ .. data:: CurStateConfigFiles @@ -206,6 +222,8 @@ Dependency types .. data:: DepReplaces .. data:: DepSuggests +.. _InstStates: + Installed states ^^^^^^^^^^^^^^^^^ .. data:: InstStateHold @@ -213,6 +231,7 @@ Installed states .. data:: InstStateOk .. data:: InstStateReInstReq +.. _Priorities: Priorities ^^^^^^^^^^ @@ -222,7 +241,10 @@ Priorities .. data:: PriRequired .. data:: PriStandard -Dselect states + +.. _SelStates: + +Select states ^^^^^^^^^^^^^^ .. data:: SelStateDeInstall .. data:: SelStateHold diff --git a/doc/source/conf.py b/doc/source/conf.py index 907e2275..bb8056ad 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -30,7 +30,8 @@ if os.path.exists("../../build"): # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', 'sphinx.ext.todo'] intersphinx_mapping = {'http://docs.python.org/': None} # Add any paths that contain templates here, relative to this directory. @@ -193,3 +194,5 @@ latex_documents = [ # If false, no module index is generated. #latex_use_modindex = True + +todo_include_todos = True diff --git a/doc/source/examples/cache-packages.py b/doc/source/examples/cache-packages.py new file mode 100644 index 00000000..1abe7cf2 --- /dev/null +++ b/doc/source/examples/cache-packages.py @@ -0,0 +1,22 @@ +#!/usr/bin/python +"""Example for packages. Print all essential and important packages""" + +import apt_pkg + + +def main(): + """Main.""" + apt_pkg.InitConfig() + apt_pkg.InitSystem() + cache = apt_pkg.GetCache() + print "Essential packages:" + for pkg in cache.Packages: + if pkg.Essential: + print " ", pkg.Name + print "Important packages:" + for pkg in cache.Packages: + if pkg.Important: + print " ", pkg.Name + +if __name__ == "__main__": + main() diff --git a/doc/source/examples/cache-pkgfile.py b/doc/source/examples/cache-pkgfile.py new file mode 100644 index 00000000..f25975d3 --- /dev/null +++ b/doc/source/examples/cache-pkgfile.py @@ -0,0 +1,29 @@ +#!/usr/bin/python +import apt_pkg + + +def main(): + """Example for PackageFile()""" + apt_pkg.init() + cache = apt_pkg.GetCache() + for pkgfile in cache.FileList: + print 'Package-File:', pkgfile.FileName + print 'Index-Type:', pkgfile.IndexType # 'Debian Package Index' + if pkgfile.NotSource: + print 'Source: None' + else: + if pkgfile.Site: + # There is a source, and a site, print the site + print 'Source:', pkgfile.Site + else: + # It seems to be a local repository + print 'Source: Local package file' + if pkgfile.NotAutomatic: + # The system won't be updated automatically (eg. experimental) + print 'Automatic: No' + else: + print 'Automatic: Yes' + print + +if __name__ == '__main__': + main() diff --git a/doc/source/examples/missing-deps.py b/doc/source/examples/missing-deps.py new file mode 100644 index 00000000..0870eb98 --- /dev/null +++ b/doc/source/examples/missing-deps.py @@ -0,0 +1,51 @@ +#!/usr/bin/python +"""Check the archive for missing dependencies""" +import apt_pkg + + +def fmt_dep(dep): + """Format a Dependency object [of apt_pkg] as a string.""" + ret = dep.TargetPkg.Name + if dep.TargetVer: + ret += " (%s %s)" % (dep.CompType, dep.TargetVer) + return ret + +def check_version(pkgver): + """Check the version of the package""" + missing = [] + + for or_group in pkgver.DependsList.get("Pre-Depends", []) + \ + pkgver.DependsList.get("Depends", []): + if not any(dep.AllTargets() for dep in or_group): + # If none of the or-choices can be satisfied, add it to missing + missing.append(or_group) + + if missing: + print "Package:", pkgver.ParentPkg.Name + print "Version:", pkgver.VerStr + print "Missing:", + print ", ".join(" | ".join(fmt_dep(dep) for dep in or_group) + for or_group in missing) + print + + +def main(): + """The main function.""" + apt_pkg.InitConfig() + apt_pkg.InitSystem() + + cache = apt_pkg.GetCache() + + for pkg in sorted(cache.Packages, key=lambda pkg: pkg.Name): + # pkg is from a list of packages, sorted by name. + for version in pkg.VersionList: + # Check every version + for pfile, _ in version.FileList: + if (pfile.Origin == "Debian" and pfile.Component == "main" and + pfile.Archive == "unstable"): + # We only want packages from Debian unstable main. + check_version(version) + break + +if __name__ == "__main__": + main() -- cgit v1.2.3 From d388a868fc8671d71accec63d35165201dbfced2 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sat, 10 Jan 2009 21:07:54 +0100 Subject: * doc/source/apt_pkg/cache.rst: Add PkgAcqFile, AcquireItem, and Configuration Not documented: MetaIndex PackageIndexFile PkgManager PkgRecords PkgSourceList PkgSrcRecords ProblemResolver TagFile TagSection (9) --- doc/source/apt_pkg/cache.rst | 175 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 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 81ee2a8e..2f4fb2d6 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -17,6 +17,181 @@ Classes in apt_pkg Shut the fetcher down. +.. class:: PkgAcqFile + + This class provides no methods or attributes + +.. 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` + +ActionGroup --- brings eg. big speedup +-------------------------------------- + +.. 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: + + .. code-block: python + + apt_pkg.GetPkgActionGroup(depcache) + + .. method:: release + + Release the ActionGroup. This will reactive the collection of package + garbage. + + +Configuration +-------------- + +.. class:: Configuration + + The Configuration objects store the configuration of apt. + + .. method:: Find(key[, default='']) + + Return the value for the given 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 given 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``. + + .. 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``. The cache --------- -- cgit v1.2.3 From cdc861975216d0a27bccc16aebdf1684a963727d Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sun, 11 Jan 2009 17:01:05 +0100 Subject: * doc/source/apt_pkg/cache.rst: Add the last classes There is no description for MetaIndex yet, but this will be added soon. --- doc/source/apt_pkg/cache.rst | 441 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 435 insertions(+), 6 deletions(-) (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 2f4fb2d6..81fb0026 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -113,6 +113,15 @@ Configuration The Configuration objects store the configuration of apt. + .. 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. This is the same as @@ -193,12 +202,18 @@ Configuration This behaves just like :meth:`dict.get` and :meth:`Configuration.Find`, it returns the value of key or if it does not exist, ``default``. + The cache --------- .. 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. @@ -218,11 +233,6 @@ The cache The parameter ``list`` refers to an object as returned by :func:`apt_pkg.GetPkgSourceList`. - .. method:: __getitem__(item) - - Return an :class:`Package` object for the package with the given - name. - .. attribute:: DependsCount The total number of dependencies. @@ -243,7 +253,7 @@ The cache The total number of package versions available in the cache. - .. attribute:: PackageFileCount + .. 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 @@ -780,3 +790,422 @@ The pkgDepCache wrapper The size of the packages which are needed for the changes to be applied. + + +MetaIndex +--------- + +.. todo:: + + Complete them + +.. class:: MetaIndex + + .. attribute:: URI + .. attribute:: Dist + .. attribute:: IsTrusted + .. attribute:: IndexFiles + + +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. + + +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`. + +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): + + .. code-block:: python + + 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:: 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: + + .. code-block:: python + + section = apt_pkg.ParseSection(records.Record) + print section['SHA256'] + +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: + + .. code-block:: python + + [('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` + + .. todo:: + + Describe it. + + +:class:`ProblemResolver` --- Resolve problems + + 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. + + +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. + +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`. + + .. 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 ``field`` if available, else return + ``default``. + + .. method:: has_key(key) + + Check whether the field with named by ``key`` exists. + + .. method:: keys() + + Return a list of keys in the section. -- cgit v1.2.3 From c8215a931b11db1b85b977920c720479de7bf902 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sun, 11 Jan 2009 17:36:10 +0100 Subject: doc/source/**.rst: rst Style changes. This changes our style to match the Python documentation. --- doc/source/apt/cache.rst | 16 +++-- doc/source/apt/debfile.rst | 2 +- doc/source/apt_inst.rst | 38 +++++----- doc/source/apt_pkg/cache.rst | 160 ++++++++++++++++++++----------------------- 4 files changed, 103 insertions(+), 113 deletions(-) (limited to 'doc/source/apt_pkg/cache.rst') diff --git a/doc/source/apt/cache.rst b/doc/source/apt/cache.rst index f3ba7d52..d96cba97 100644 --- a/doc/source/apt/cache.rst +++ b/doc/source/apt/cache.rst @@ -7,14 +7,17 @@ The Cache class .. autoclass:: Cache :members: + :undoc-members: + + .. describe:: cache[pkgname] + + Return a :class:`Package()` for the package with the name *pkgname*. Example ^^^^^^^ The following example shows how to load the cache, update it, and upgrade -all the packages on the system. - -.. code-block:: python +all the packages on the system:: import apt import apt.progress @@ -40,12 +43,18 @@ Working with Filters -------------------- .. autoclass:: Filter :members: + :inherited-members: + :undoc-members: .. autoclass:: MarkedChangesFilter :members: + :inherited-members: + :undoc-members: .. autoclass:: FilteredCache :members: + :inherited-members: + :undoc-members: Example @@ -65,6 +74,5 @@ packages whose state has been changed, eg. packages marked for installation:: Exceptions ---------- .. autoexception:: FetchCancelledException - :members: .. autoexception:: FetchFailedException .. autoexception:: LockFailedException diff --git a/doc/source/apt/debfile.rst b/doc/source/apt/debfile.rst index c0146df9..7133b5a8 100644 --- a/doc/source/apt/debfile.rst +++ b/doc/source/apt/debfile.rst @@ -18,7 +18,7 @@ Binary packages It provides methods and attributes to get a list of the files in the package, to install the package and much more. - If you specify ``cache`` it has to point to an :class:`apt.cache.Cache()` + If you specify *cache* it has to point to an :class:`apt.cache.Cache()` object. .. versionchanged:: 0.7.9 diff --git a/doc/source/apt_inst.rst b/doc/source/apt_inst.rst index b405b9f4..97705f61 100644 --- a/doc/source/apt_inst.rst +++ b/doc/source/apt_inst.rst @@ -10,21 +10,19 @@ 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``. + Check if the member specified by the parameter *membername* exists in + the AR file referenced by the :class:`file` object *file*. 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``. + 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*. - An example would be: - - .. code-block:: python + An example would be:: debExtract(open("package.deb"), my_callback, "data.tar.gz") @@ -32,9 +30,9 @@ Listing contents .. function:: tarExtract(file,func,comp) - Call the function ``func`` for each member of the tar file ``file``. + Call the function *func* for each member of the tar file *file*. - ``Comp`` is a string determining the compressor used. Possible options are + *Comp* is a string determining the compressor used. Possible options are "lzma", "bzip2" and "gzip". @@ -43,11 +41,11 @@ Callback Both of these functions expect a callback with the signature ``(what, name, link, mode, uid, gid, size, mtime, major, minor)``. -The parameter ``what`` describes the type of the member. It can be ``FILE``, -``DIR``, or ``HARDLINK``. +The parameter *what* describes the type of the member. It can be 'FILE', +'DIR', or 'HARDLINK'. -The parameter ``name`` refers to the name of the member. In case of links, -``link`` refers to the target of the link. +The parameter *name* refers to the name of the member. In case of links, +*link* refers to the target of the link. Extracting contents @@ -55,14 +53,14 @@ Extracting contents .. function:: debExtractArchive(file, rootdir) - Extract the archive referenced by the :class:`file` object ``file`` - into the directory specified by ``rootdir``. + Extract the archive referenced by the :class:`file` object *file* + into the directory specified by *rootdir*. See :ref:`emulating-dpkg-extract` for an example. .. warning:: - If the directory given by ``rootdir`` does not exist, the package is + If the directory given by *rootdir* does not exist, the package is extracted into the current directory. .. function:: debExtractControl(file[, member='control']) @@ -70,9 +68,7 @@ Extracting contents Return the indicated file from the control tar. The default is 'control'. If you want to print the control file of a given package, you could do - something like: - - .. code-block:: python + something like:: print debExtractControl(open("package.deb")) @@ -84,7 +80,7 @@ Extracting contents Example: Emulating :program:`dpkg` :option:`--extract` ------------------------------------------------------- Here is a code snippet which emulates dpkg -x. It can be run as -``tool pkg.deb outdir``. +:program:`tool` :option:`pkg.deb` :option:`outdir`. .. literalinclude:: examples/dpkg-extract.py diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 81fb0026..65887dbf 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -94,9 +94,7 @@ ActionGroup --- brings eg. big speedup Using ActionGroups you can turn this off and therefore make your code much faster. - Initialize it using :func:`apt_pkg.GetPkgActionGroup`, eg: - - .. code-block: python + Initialize it using :func:`apt_pkg.GetPkgActionGroup`, eg:: apt_pkg.GetPkgActionGroup(depcache) @@ -115,66 +113,66 @@ Configuration .. describe:: conf[key] - Return the value of the option given key ``key``. If it does not + 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``. + Set the option at *key* to *value*. .. method:: Find(key[, default='']) - Return the value for the given key. This is the same as + Return the value for the given key *key*. This is the same as :meth:`Configuration.get`. - If ``key`` does not exist, return ``default``. + If *key* does not exist, return *default*. .. method:: FindFile(key[, default='']) - Return the filename hold by the configuration at key. This formats the + 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``. + 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. + Return the absolute path to the directory specified in *key*. A + trailing slash is appended. - If ``key`` does not exist, return ``default``. + If *key* does not exist, return *default*. .. method:: FindI(key[, default=0]) - Return the integer value stored at key. + Return the integer value stored at *key*. - If ``key`` does not exist, return ``default``. + If *key* does not exist, return *default*. .. method:: FindB(key[, default=0]) - Return the boolean value stored at key. This returns an integer, but + 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``. + If *key* does not exist, return *default*. .. method:: Set(key, value) - Set the value of ``key`` to ``value``. + Set the value of *key* to *value*. .. method:: Exists(key) - Check whether the given key exists in the configuration. + 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 + 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, + 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. + Use *key* to specify a key of which the childs will be returned. .. method:: ValueList([key]) @@ -187,20 +185,20 @@ Configuration .. method:: Clear(key) - Clear the configuration. Remove all values and keys at ``key``. + Clear the configuration. Remove all values and keys at *key*. .. method:: keys([key]) - Return all the keys, recursive. If ``key`` is specified, ... (FIXME) + Return all the keys, recursive. If *key* is specified, ... (FIXME) .. method:: has_key(key) - Return whether the configuration contains the key ``key``. + Return whether the configuration contains the key *key*. .. 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``. + it returns the value of key or if it does not exist, *default*. The cache @@ -220,17 +218,17 @@ The cache .. method:: Open([progress]) - Open the package cache again. The parameter ``progress`` may be set to + 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()` + The parameter *progress* points to an :class:`apt.progress.FetchProgress()` object. - The parameter ``list`` refers to an object as returned by + The parameter *list* refers to an object as returned by :func:`apt_pkg.GetPkgSourceList`. .. attribute:: DependsCount @@ -311,9 +309,7 @@ PackageFile 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: - - .. code-block:: python + Example:: for pkgfile in cache.FileList: if pkgfile.NotSource: @@ -469,9 +465,7 @@ Version, as returned by eg. :meth:`pkgDepCache.GetCandidateVer` tuples like ('pkgname', 'version', 'relation') for each or-choice. An example return value for a package with a 'Depends: python (>= 2.4)' - would be: - - .. code-block:: python + would be:: {'Depends': [ [ @@ -480,9 +474,7 @@ Version, as returned by eg. :meth:`pkgDepCache.GetCandidateVer` ] } - The same for a dependency on A (>= 1) | B (>= 2): - - .. code-block:: python + The same for a dependency on A (>= 1) | B (>= 2):: {'Depends': [ [ @@ -640,10 +632,10 @@ The pkgDepCache wrapper Apply all the changes made. - The parameter ``fprogress`` has to be set to an instance of + 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 + The parameter *iprogress* has to be set to an instance of apt.progress.InstallProgress or one of its subclasses. .. method:: FixBroken() @@ -655,7 +647,7 @@ The pkgDepCache wrapper Return the candidate version of the package, ie. the version that would be installed normally. - The parameter ``pkg`` refers to an :class:`Package` object, + The parameter *pkg* refers to an :class:`Package` object, available using the :class:`pkgCache`. This method returns a :class:`Version` object. @@ -663,8 +655,8 @@ The pkgDepCache wrapper .. method:: SetCandidateVer(pkg, version) The opposite of :meth:`pkgDepCache.GetCandidateVer`. Set the candidate - version of the :class:`Package` ``pkg`` to the :class:`Version` - ``version``. + version of the :class:`Package` *pkg* to the :class:`Version` + *version*. .. method:: Upgrade([distUpgrade=False]) @@ -673,7 +665,7 @@ The pkgDepCache wrapper 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 perform a dist-upgrade, the optional parameter *distUpgrade* has to be set to True. .. method:: FixBroken() @@ -694,30 +686,30 @@ The pkgDepCache wrapper .. method:: MarkKeep(pkg) - Mark the :class:`Package` ``pkg`` for keep. + Mark the :class:`Package` *pkg* for keep. .. method:: MarkDelete(pkg[, purge]) - Mark the :class:`Package` ``pkg`` for delete. If ``purge`` is True, + 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. + Mark the :class:`Package` *pkg* for install. - If ``autoInst`` is True, the dependencies of the package will be + 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 + 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. + Set if the :class:`Package` *pkg* should be reinstalled. .. method:: IsUpgradable(pkg) - Return `1` if the package is upgradable. + Return ``1`` if the package is upgradable. The package can be upgraded by calling :meth:`pkgDepCache.MarkInstall`. @@ -728,42 +720,42 @@ The pkgDepCache wrapper .. 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. + 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 + 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 + 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. + Return ``1`` if the package is marked for install. .. method:: MarkedUpgrade(pkg) - Return `1` if the package is marked for upgrade. + Return ``1`` if the package is marked for upgrade. .. method:: MarkedDelete(pkg) - Return `1` if the package is marked for delete. + Return ``1`` if the package is marked for delete. .. method:: MarkedKeep(pkg) - Return `1` if the package is marked for keep. + Return ``1`` if the package is marked for keep. .. method:: MarkedReinstall(pkg) - Return `1` if the package should be installed. + Return ``1`` if the package should be installed. .. method:: MarkedDowngrade(pkg) - Return `1` if the package should be downgraded. + Return ``1`` if the package should be downgraded. .. attribute:: KeepCount @@ -847,12 +839,12 @@ PkgManager .. method:: GetArchives(fetcher, list, records) Add all the selected packages to the :class:`Acquire()` object - ``fetcher``. + *fetcher*. - The parameter ``list`` refers to a :class:`pkgSourceList()` object, as + 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 + The parameter *records* refers to a :class:`pkgRecords()` object, as returned by :func:`apt_pkg.GetPkgRecords`. .. method:: DoInstall() @@ -899,13 +891,11 @@ pkgRecords Change the actual package to the package given by the verfile_iter. - The parameter ``verfile_iter`` refers to a tuple consisting + 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): - - .. code-block:: python + Example (shortened):: cand = depcache.GetCandidateVer(cache['python-apt']) records.Lookup(cand.FileList[0]) @@ -964,9 +954,7 @@ pkgRecords :func:`apt_pkg.ParseSection` to parse the record and access the field name. - Example: - - .. code-block:: python + Example:: section = apt_pkg.ParseSection(records.Record) print section['SHA256'] @@ -988,7 +976,7 @@ PkgSrcRecords .. method:: Lookup(pkgname) - Lookup the record for the package named ``pkgname``. To access all + 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)`` @@ -1050,7 +1038,7 @@ PkgSrcRecords Return the list of Build dependencies, as ``str: package, str: version, int: op, int: type)``. - .. table:: Values of ``op`` + .. table:: Values of *op* ===== ============================================= Value Meaning @@ -1065,7 +1053,7 @@ PkgSrcRecords 0x6 != (not equal) ===== ============================================= - .. table:: Values of ``type`` + .. table:: Values of *type* ===== =================== Value Meaning @@ -1081,9 +1069,7 @@ PkgSrcRecords Build-Depends: A (>= 1) | B (>= 1), C - This results in: - - .. code-block:: python + This results in:: [('A', '1', 18, 0), # 18 = 16 + 2 = 0x10 + 0x2 ('B', '1', 2, 0), @@ -1108,7 +1094,7 @@ PkgSrcRecords .. method:: Protect(pkg) - Protect the :class:`Package()` object given by the parameter ``pkg``. + Protect the :class:`Package()` object given by the parameter *pkg*. .. todo:: @@ -1120,7 +1106,7 @@ PkgSrcRecords .. method:: Remove(pkg) - Remove the :class:`Package()` object given by the parameter ``pkg``. + Remove the :class:`Package()` object given by the parameter *pkg*. .. todo:: @@ -1128,7 +1114,7 @@ PkgSrcRecords .. method:: Clear(pkg) - Reset the :class:`Package()` ``pkg`` to the default state. + Reset the :class:`Package()` *pkg* to the default state. .. todo:: @@ -1164,7 +1150,7 @@ TagFile .. method:: Jump(offset) - Jump back/forward to ``offset``. Use ``Jump(0)`` to jump to the + Jump back/forward to *offset*. Use ``Jump(0)`` to jump to the beginning of the file again. .. attribute:: Section @@ -1180,7 +1166,7 @@ TagSection .. describe:: section[key] - Return the value of the field at ``key``. If ``key`` is not available, + Return the value of the field at *key*. If *key* is not available, raise :exc:`KeyError`. .. method:: Bytes @@ -1189,22 +1175,22 @@ TagSection .. method:: Find(key, default='') - Return the value of the field at the key ``key`` if available, - else return ``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 + 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 ``field`` if available, else return - ``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. + Check whether the field with named by *key* exists. .. method:: keys() -- cgit v1.2.3 From 0998ee54b5b56d7ca91310d28f73028cfc0e036c Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sun, 11 Jan 2009 18:30:58 +0100 Subject: * doc/: Small updates, add PkgSourceList --- doc/source/apt_pkg/cache.rst | 99 +++++++++++++++++++++++++++----------------- doc/source/index.rst | 3 ++ 2 files changed, 64 insertions(+), 38 deletions(-) (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 65887dbf..0a02c47c 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -5,7 +5,8 @@ Classes in apt_pkg This should be split and cleaned up a bit. - +:class:`Acquire` +---------------- .. class:: Acquire .. method:: Run() @@ -17,10 +18,15 @@ Classes in apt_pkg Shut the fetcher down. +:class:`PkgAcqFile` +------------------- .. class:: PkgAcqFile This class provides no methods or attributes +:class:`AcquireItem` +--------------------- + .. class:: AcquireItem .. attribute:: ID @@ -82,8 +88,8 @@ Classes in apt_pkg Constant for comparing :attr:`AcquireItem.Status` -ActionGroup --- brings eg. big speedup --------------------------------------- +:class:`ActionGroup` +-------------------- .. class:: ActionGroup @@ -104,8 +110,8 @@ ActionGroup --- brings eg. big speedup garbage. -Configuration --------------- +:class:`Configuration` +---------------------- .. class:: Configuration @@ -201,8 +207,8 @@ Configuration it returns the value of key or if it does not exist, *default*. -The cache ---------- +:class:`pkgCache` +----------------- .. class:: pkgCache The :class:`pkgCache` class prov @@ -262,8 +268,8 @@ The cache A list of :class:`PackageFile` objects. -PackageFile ------------- +:class:`PackageFile` +-------------------- .. class:: PackageFile A :class:`PackageFile` represents a Packages file, eg. @@ -337,8 +343,8 @@ Example .. literalinclude:: ../examples/cache-pkgfile.py -A Package ---------- +:class:`Package` +---------------- .. class:: Package @@ -429,8 +435,8 @@ Example: -Version, as returned by eg. :meth:`pkgDepCache.GetCandidateVer` ---------------------------------------------------------------- +:class:`Version` +---------------- .. class:: Version The version object contains all information related to a specific package @@ -540,8 +546,8 @@ Version, as returned by eg. :meth:`pkgDepCache.GetCandidateVer` Return a :class:`Description` object. -The Dependency class --------------------- +:class:`Dependency` +------------------- .. class:: Dependency Represent a dependency from one package to another one. @@ -601,8 +607,8 @@ broken dependencies: .. literalinclude:: ../examples/missing-deps.py -The Description class ---------------------- +:class:`Description` +-------------------- .. class:: Description Represent the description of the package. @@ -621,8 +627,8 @@ The Description class -The pkgDepCache wrapper ------------------------ +:class:`pkgDepCache` +-------------------- .. class:: pkgDepCache The pkgDepCache object contains various methods to manipulate the cache, @@ -784,8 +790,8 @@ The pkgDepCache wrapper applied. -MetaIndex ---------- +:class:`MetaIndex` +------------------ .. todo:: @@ -799,8 +805,8 @@ MetaIndex .. attribute:: IndexFiles -PackageIndexFile ----------------- +:class:`PackageIndexFile` +------------------------- .. class:: PackageIndexFile @@ -829,8 +835,8 @@ PackageIndexFile Whether we can trust the file. -PkgManager ----------- +:class:`PkgManager` +------------------- .. class:: PkgManager @@ -841,7 +847,7 @@ PkgManager Add all the selected packages to the :class:`Acquire()` object *fetcher*. - The parameter *list* refers to a :class:`pkgSourceList()` object, as + 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 @@ -876,8 +882,8 @@ PkgManager Compare it against the return value of :meth:`PkgManager.GetArchives` or :meth:`PkgManager.DoInstall`. -pkgRecords ------------ +:class:`pkgRecords` +-------------------- .. class:: PkgRecords @@ -959,8 +965,8 @@ pkgRecords section = apt_pkg.ParseSection(records.Record) print section['SHA256'] -PkgSrcRecords -------------- +:class:`PkgSrcRecords` +---------------------- .. class:: PkgSrcRecords @@ -1036,7 +1042,7 @@ PkgSrcRecords .. attribute:: BuildDepends Return the list of Build dependencies, as - ``str: package, str: version, int: op, int: type)``. + ``(str: package, str: version, int: op, int: type)``. .. table:: Values of *op* @@ -1080,13 +1086,30 @@ PkgSrcRecords :class:`PkgSourceList` +----------------------- + +.. class:: PkgSourceList + + This is for :file:`/etc/apt/sources.list`. - .. todo:: + .. method:: FindIndex(pkgfile) - Describe it. + Return a :class:`PackageIndexFile` object for the :class:`PackageFile` + *pkgfile*. + .. method:: ReadMainList -:class:`ProblemResolver` --- Resolve problems + 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 @@ -1129,8 +1152,8 @@ PkgSrcRecords Try to resolve problems only by using keep. -TagFile -------- +:class:`TagFile` +---------------- .. class:: TagFile @@ -1157,8 +1180,8 @@ TagFile This is the current :class:`TagSection()` instance. -TagSection ----------- +:class:`TagSection` +------------------- .. class:: TagSection diff --git a/doc/source/index.rst b/doc/source/index.rst index d7c425bd..23ea4cca 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -36,3 +36,6 @@ Indices and tables * :ref:`search` +TODO +====== +.. todolist:: -- cgit v1.2.3 From 2e980f4f190abb787f9aa9939a404875905d651c Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sun, 11 Jan 2009 20:02:29 +0100 Subject: * Add support for PkgRecords.SHA256Hash (Closes: #456113) --- debian/changelog | 3 ++- doc/source/apt_pkg/cache.rst | 5 +++++ python/pkgrecords.cc | 2 ++ 3 files changed, 9 insertions(+), 1 deletion(-) (limited to 'doc/source/apt_pkg/cache.rst') diff --git a/debian/changelog b/debian/changelog index fbf665cd..49236999 100644 --- a/debian/changelog +++ b/debian/changelog @@ -30,8 +30,9 @@ python-apt (0.7.9~exp2) experimental; urgency=low * Merge Ben Finney's whitespace changes (Closes: #481563) * Merge Ben Finney's do not use has_key() (Closes: #481878) * Do not use deprecated form of raise statement (Closes: #494259) + * Add support for PkgRecords.SHA256Hash (Closes: #456113) - -- Julian Andres Klode Sun, 11 Jan 2009 19:55:11 +0100 + -- Julian Andres Klode Sun, 11 Jan 2009 20:01:59 +0100 python-apt (0.7.9~exp1) experimental; urgency=low diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 0a02c47c..6e924aeb 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -923,6 +923,11 @@ broken dependencies: 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. + .. attribute:: SourcePkg Return the source package. diff --git a/python/pkgrecords.cc b/python/pkgrecords.cc index 18240ce0..5359ee6f 100644 --- a/python/pkgrecords.cc +++ b/python/pkgrecords.cc @@ -65,6 +65,8 @@ static PyObject *PkgRecordsAttr(PyObject *Self,char *Name) return CppPyString(Struct.Last->MD5Hash()); else if (strcmp("SHA1Hash",Name) == 0) return CppPyString(Struct.Last->SHA1Hash()); + else if (strcmp("SHA256Hash",Name) == 0) + return CppPyString(Struct.Last->SHA256Hash()); else if (strcmp("SourcePkg",Name) == 0) return CppPyString(Struct.Last->SourcePkg()); else if (strcmp("SourceVer",Name) == 0) -- cgit v1.2.3 From eb32fb89da3e3e1ff4a9668aaed6d533f04e9ee7 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sun, 11 Jan 2009 20:48:40 +0100 Subject: * doc/source/apt_pkg/cache.rst: Mention the SHA256Hash is new in 0.7.9 --- doc/source/apt_pkg/cache.rst | 2 ++ 1 file changed, 2 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 6e924aeb..af67d82f 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -928,6 +928,8 @@ broken dependencies: 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. -- cgit v1.2.3