diff options
Diffstat (limited to 'doc/source/library/apt_pkg.rst')
| -rw-r--r-- | doc/source/library/apt_pkg.rst | 2904 |
1 files changed, 2904 insertions, 0 deletions
diff --git a/doc/source/library/apt_pkg.rst b/doc/source/library/apt_pkg.rst new file mode 100644 index 0000000..4290180 --- /dev/null +++ b/doc/source/library/apt_pkg.rst @@ -0,0 +1,2904 @@ +: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:: init_config + + Initialize the configuration of apt. This is needed for most operations. + +.. function:: init_system + + Initialize the system. + +.. function:: init + + A short cut to calling :func:`init_config` and :func:`init_system`. You + can use this if you do not use the command line parsing facilities provided + by :func:`parse_commandline`, otherwise call :func:`init_config`, parse + the commandline afterwards and finally call :func:`init_system`. + + +Exceptions +---------- +.. autoclass:: Error + +.. autoclass:: CacheMismatchError + + +Working with the cache +---------------------- +.. class:: Cache([progress: apt.progress.base.OpProgress]) + + A Cache object represents the cache used by APT which contains information + about packages. The object itself provides no means to modify the cache or + the installed packages, see the classes :class:`DepCache` and + :class:`PackageManager` for such functionality. + + The constructor takes an optional argument which must be a subclass of + :class:`apt.progress.base.OpProgress`. This object will then be used to + display information during the cache opening process (or possible creation + of the cache). It may also be ``None``, in which case no progress will + be emitted. If not given, progress will be printed to standard output. + + .. note:: + + The cache supports colon-separated name:architecture pairs. For + normal architectures, they are equal to a (name, architecture) + tuple. For the "any" architecture behavior is different, as + "name:any" is equivalent to ("name:any", "any"). This is done so + that "name:any" matches all packages with that name which have + Multi-Arch: allowed set. + + .. describe:: cache[pkgname] + + Return the :class:`Package()` object for the package name given by + *pkgname*. If *pkgname* includes a colon, the part after the colon + is used as the architecture. + + .. describe:: cache[name, architecture] + + Return the :class:`Package()` object for the package with the given + name and architecture. + + .. versionadded: 0.8.0 + + .. describe:: pkgname in cache + + Check whether a package with the name given by *pkgname* exists in + the cache for the native architecture. If *pkgname* includes a + colon, the part after the colon is used as the architecture. + + .. describe:: (name, architecture) in cache + + Check whether a package with the given name and architecture exists + in the cache. + + .. versionadded: 0.8.0 + + .. method:: update(progress, sources [, pulse_interval]) -> bool + + Update the index files used by the cache. A call to this method + does not affect the current Cache object, instead a new one + should be created in order to use the changed index files. + + The parameter *progress* takes an + :class:`apt.progress.base.AcquireProgress` object which will display + the progress of fetching the index files. The parameter *sources* takes + a :class:`SourceList` object which lists the sources. The parameter + *progress* takes an integer describing the interval (in microseconds) + in which the pulse() method of the *progress* object will be called. + + .. attribute:: depends_count + + The total number of dependencies stored in the cache. + + .. attribute:: file_list + + A list of all :class:`PackageFile` objects stored in the cache. + + .. attribute:: group_count + + The number of groups in the cache. + + .. versionadded: 0.8.0 + + .. attribute:: groups + + A sequence of :class:`Group` objects, implemented as a + :class:`GroupList` object. + + .. versionadded: 0.8.0 + + .. class:: GroupList + + A simple sequence-like object which only provides a length and + an implementation of ``__getitem__`` for accessing groups at + a certain index. Apart from being iterable, it can be used in + the following ways: + + .. versionadded: 0.8.0 + + .. describe:: list[index] + + Get the :class:`Group` object for the group at the position + given by *index* in the GroupList *list*. + + .. describe:: len(list) + + Return the length of the GroupList object *list*. + + + .. attribute:: is_multi_arch + + An attribute determining whether the cache supports multi-arch. + + .. versionadded: 0.8.0 + + .. attribute:: package_count + + The total number of packages available in the cache. This value is + equal to the length of the list provided by the :attr:`packages` + attribute. + + .. attribute:: package_file_count + + 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:`file_list`. + + .. attribute:: packages + + A sequence of :class:`Package` objects, implemented as a + :class:`PackageList` object. + + .. class:: PackageList + + A simple sequence-like object which only provides a length and + an implementation of ``__getitem__`` for accessing packages at + a certain index. Apart from being iterable, it can be used in + the following ways: + + .. describe:: list[index] + + Get the :class:`Package` object for the package at the position + given by *index* in the PackageList *list*. + + .. describe:: len(list) + + Return the length of the PackageList object *list*. + + .. attribute:: provides_count + + The number of provided packages. + + .. attribute:: ver_file_count + + The total number of ``(Version, PackageFile)`` relations stored in + the cache. + + .. attribute:: version_count + + The total number of package versions available in the cache. + +Managing the cache with :class:`DepCache` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. class:: DepCache(cache: apt_pkg.Cache) + + A DepCache object provides access to more information about the + objects made available by the :class:`Cache` object as well as + means to mark packages for removal and installation, among other + actions. + + The constructor takes a single argument which specifies the + :class:`Cache` object the new object shall be related to. While + it is theoretically possible to create multiple DepCache objects + for the same cache, they will not be independent from each other + since they all access the same underlying C++ object. + + Objects of this type provide several methods. Most of those methods + are safe to use and should never raise any exception (all those + methods for requesting state information or marking changes). If a + method is expected to raise an exception, it will be stated in the + description. + + If an object of a different cache is passed, :class:`CacheMismatchError` + is raised. + + .. method:: commit(acquire_progress, install_progress) + + Commit all marked changes, while reporting the progress of + fetching packages via the :class:`apt.progress.base.AcquireProgress` + object given by *acquire_progress* and reporting the installation + of the package using the :class:`apt.progress.base.InstallProgress` + object given by *install_progress*. + + If this fails, an exception of the type :exc:`SystemError` will + be raised. + + .. method:: fix_broken() -> bool + + Try to fix all broken packages in the cache and return ``True`` in + case of success. If an error occurred, a :exc:`SystemError` + exception is raised. + + .. method:: get_candidate_ver(pkg: Package) -> Version + + Return the candidate version for the package given by the parameter + *pkg* as a :class:`Version` object. The default candidate for a + package is the version with the highest pin, although a different + one may be set using :meth:`set_candidate_ver`. If no candidate + can be found, return ``None`` instead. + + .. method:: init(progress: apt.progress.base.OpProgress) + + Initialize the DepCache. This is done automatically when the + cache is opened, but sometimes it may be useful to reinitialize + the DepCache. Like the constructor of :class:`Cache`, this + function takes a single :class:`apt.progress.base.OpProgress` + object to display progress information. + + .. method:: read_pinfile(file: str) + + A proxy function which calls the method :meth:`Policy.read_pinfile` of + the :class:`Policy` object used by this object. This method raises + a :exc:`SystemError` exception if the file could not be parsed. + + .. method:: set_candidate_ver(pkg: Package, version: Version) -> bool + + Set the candidate version of the package given by the :class:`Package` + object *pkg* to the version given by the :class:`Version` object + *version* and return ``True``. If odd things happen, this function + may raise a :exc:`SystemError` exception, but this should not + happen in normal usage. See :meth:`get_candidate_ver` for a way + to retrieve the candidate version of a package. + + .. method:: upgrade([dist_upgrade=False]) -> bool + + Mark the packages for upgrade under the same conditions + :program:`apt-get` does. If *dist_upgrade* is ``True``, also + allow packages to be upgraded if they require installation/removal + of other packages; just like apt-get dist-upgrade. + + Despite returning a boolean value, this raises :exc:`SystemError` and + does not return ``False`` if an error occurred. + + The following methods can mark a single package for installation, + removal, etc: + + .. method:: mark_auto(pkg: Package) + + Mark the :class:`Package` *pkg* as automatically installed. + + .. method:: mark_keep(pkg: Package) + + Mark the :class:`Package` *pkg* for keep. + + .. method:: mark_delete(pkg: Package[, purge]) + + Mark the :class:`Package` *pkg* for delete. If *purge* is True, + the configuration files will be removed as well. + + .. method:: mark_install(pkg: Package[, auto_inst=True[, from_user=True]]) + + Mark the :class:`Package` *pkg* for install, and, if *auto_inst* + is ``True``, its dependencies as well. If *from_user* is ``True``, + the package will **not** be marked as automatically installed. + + .. method:: set_reinstall(pkg: Package) + + Set if the :class:`Package` *pkg* should be reinstalled. + + The following methods can be used to check the state of a package: + + .. method:: is_auto_installed(pkg: Package) -> bool + + Return ``True`` if the package is automatically installed, that + is, as a dependency of another package. + + .. method:: is_garbage(pkg: Package) -> bool + + Return ``True`` if the package is garbage, that is, if it was + automatically installed and no longer referenced by other packages. + + .. method:: is_inst_broken(pkg: Package) -> bool + + Return ``True`` if the package is broken on the current install. This + takes changes which have not been marked not into account. + + .. method:: is_now_broken(pkg: Package) -> bool + + Return ``True`` if the package is now broken, that is, if the package + is broken if the marked changes are applied. + + .. method:: is_upgradable(pkg: Package) -> bool + + Return ``True`` if the package is upgradable, the package can then + be marked for upgrade by calling the method :meth:`mark_install`. + + .. method:: marked_delete(pkg: Package) -> bool + + Return ``True`` if the package is marked for delete. + + .. method:: marked_downgrade(pkg: Package) -> bool + + Return ``True`` if the package should be downgraded. + + .. method:: marked_install(pkg: Package) -> bool + + Return ``True`` if the package is marked for install. + + .. method:: marked_keep(pkg: Package) -> bool + + Return ``True`` if the package is marked for keep. + + .. method:: marked_reinstall(pkg: Package) -> bool + + Return ``True`` if the package should be reinstalled. + + .. method:: marked_upgrade(pkg: Package) -> bool + + Return ``True`` if the package is marked for upgrade. + + .. method:: phasing_applied(pkg: Package) -> bool + + Return ``True`` if the package update is being phased. + + DepCache objects also provide several attributes containing information + on the marked changes: + + .. attribute:: keep_count + + Integer, number of packages marked as keep + + .. attribute:: inst_count + + Integer, number of packages marked for installation. + + .. attribute:: del_count + + Number of packages which should be removed. + + .. attribute:: broken_count + + Number of packages which are broken. + + .. attribute:: usr_size + + The size required for the changes on the filesystem. If you install + packages, this is positive, if you remove them its negative. + + .. attribute:: deb_size + + The size of the packages which are needed for the changes to be + applied. + + .. attribute:: policy + + The underlying :class:`Policy` object used by the :class:`DepCache` to + select candidate versions. + +Installing with :class:`PackageManager` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. class:: PackageManager(depcache) + + Abstraction of a package manager. This object takes care of retrieving + packages, ordering the installation, and calling the package manager to + do the actual installation. + + .. method:: get_archives(fetcher, list, records) -> bool + + Add all packages marked for installation (or upgrade, anything + which needs a download) to the :class:`Acquire` object referenced + by *fetcher*. + + The parameter *list* specifies a :class:`SourceList` object which + is used to retrieve the information about the archive URI for the + packages which will be fetched. + + The parameter *records* takes a :class:`PackageRecords` object which + will be used to look up the file name of the package. + + .. method:: do_install(status_fd: int) -> int + + Install the packages and return one of the class constants + :attr:`RESULT_COMPLETED`, :attr:`RESULT_FAILED`, + :attr:`RESULT_INCOMPLETE`. The argument *status_fd* can be used + to specify a file descriptor that APT will write status information + on (see README.progress-reporting in the apt source code for + information on what will be written there). + + .. method:: fix_missing() -> bool + + Fix the installation if a package could not be downloaded. + + .. attribute:: RESULT_COMPLETED + + A constant for checking whether the result of the call to + :meth:`do_install` is 'failed'. + + .. attribute:: RESULT_FAILED + + A constant for checking whether the result of the call to + :meth:`do_install` is 'failed'. + + .. attribute:: RESULT_INCOMPLETE + + A constant for checking whether the result of the call to + :meth:`do_install` is 'incomplete'. + + All instances of this class also support the following methods: + + .. note:: + + This methods are provided mainly for subclassing purposes + and should not be used in most programs. This class is a + subclass of an internal :class:`_PackageManager` which does + not provide that methods. As the public C++ API creates such + an object without those methods, you should not rely on those + methods to be available unless you used the constructor of + :class:`PackageManager` to create the object. + + .. method:: configure(pkg: Package) -> bool + + Notify the package manager that the :class:`Package` given + by *pkg* is to be configured. Must return a ``True`` value + or ``None`` to continue, or a value which is ``False`` if + evaluated as boolean to abort. + + .. versionadded:: 0.8.0 + + .. method:: install(pkg: Package, filename: str) -> bool + + Notify the package manager that the :class:`Package` given + by *pkg* is to be installed from the .deb located at + *filename*. Must return a ``True`` value or ``None`` to + continue, or a value which is ``False`` if evaluated as + boolean to abort. + + + .. versionadded:: 0.8.0 + + .. method:: remove(pkg: Package, purge: bool) -> bool + + Notify the package manager that the :class:`Package` given + by *pkg* is to be removed. If *purge* is ``True``, the package + shall be purged. Must return a ``True`` value or ``None`` to + continue, or a value which is ``False`` if evaluated as boolean + to abort. + + + .. versionadded:: 0.8.0 + + .. method:: go(status_fd: int) -> bool + + Start dpkg, writing status information to the file descriptor + given by *status_fd*. Must return a ``True`` value or ``None`` to + continue, or a value which is ``False`` if evaluated as boolean + to abort. + + .. versionadded:: 0.8.0 + + .. method:: reset() + + Reset the package manager for a new round. + + .. versionadded:: 0.8.0 + + +Installation ordering with :class:`OrderList` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. class:: OrderList(depcache: DepCache) + + Represent a :c:type:`pkgOrderList`, used for installation + ordering. This class provides several methods and attributes, + is complicated and should not be used by normal programs. + + .. versionadded:: 0.8.0 + + This class is a sequence and supports the following operations: + + .. describe:: list[index] + + Get the package at the given index in the list. Negative + index is supported. + + .. describe:: len(list) + + The length of the list. + + It also supports the append() method from :class:`list`: + + .. method:: append(pkg: Package) + + Append a new package to the end of the list. Please note that + you may not append a package twice, as only as much packages + as in the cache can be added. + + The class also defines several specific attributes and methods, + to be described hereinafter. + + .. method:: score(pkg: Package) + + Return the score of the package. Packages are basically + ordered by descending score. + + This class allows flags to be set on packages. Those flags are: + + .. attribute:: FLAG_ADDED + .. attribute:: FLAG_ADD_PENDING + .. attribute:: FLAG_IMMEDIATE + .. attribute:: FLAG_LOOP + .. attribute:: FLAG_UNPACKED + .. attribute:: FLAG_CONFIGURED + .. attribute:: FLAG_REMOVED + .. attribute:: FLAG_STATES_MASK + + Same as ``FLAG_UNPACKED | FLAG_CONFIGURED | FLAG_REMOVED`` + + .. attribute:: FLAG_IN_LIST + .. attribute:: FLAG_AFTER + + The methods to work with those flags are: + + .. method:: flag(pkg: Package, flag: int[, unset_flags: int]) + + Flag a package. Sets the flags given in *flag* and unsets + any flags given in *unset_flags*. + + .. method:: is_flag(pkg: Package, flag: int) + + Check whether the flags in *flag* are set for the package. + + .. method:: wipe_flags(flags: int) + + Remove the flags in *flags* from all packages. + + .. method:: is_missing(pkg: Package) + + Check if the package is missing (not really usable right now) + + .. method:: is_now(pkg: Package) + + Check if the package is flagged for any state but removal. + + The following methods for ordering are provided: + + .. method:: order_critical() + + Order the packages for critical unpacking; that is, only + respect pre-dependencies. + + .. method:: order_unpack() + + Order the packages for unpacking, repecting Pre-Depends and + Conflicts. + + .. method:: order_configure() + + Order the packages for configuration, respecting Depends. + +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. + + An action group 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. Thus, you should 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() + + In addition to the methods required to implement the context + manager interface, :class:`ActionGroup` objects provide the + following method: + + .. method:: release() + + Release the ActionGroup. This will reactive the collection of package + garbage. + +Resolving Dependencies with :class:`ProblemResolver` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. class:: ProblemResolver(depcache: DepCache) + + ProblemResolver objects take care of resolving problems with + dependencies. They mark packages for installation/removal and + try to satisfy all dependencies. The constructor takes a single + argument of the type :class:`apt_pkg.DepCache` to determine the + cache that shall be manipulated in order to resolve the problems. + + .. method:: clear(pkg: Package) + + Revert the action of calling :meth:`protect` or :meth:`remove` on + a package, resetting it to the default state. + + .. method:: install_protect() + + Mark all protected packages for installation. + + .. method:: protect(pkg: Package) + + Mark the package given by *pkg* as protected; that is, its state + will not be changed. + + .. method:: remove(pkg: Package) + + Mark the package given by *pkg* for removal in the resolver. + + .. method:: resolve([fix_broken: bool = True]) -> bool + + Try to intelligently resolve problems by installing and removing + packages. If *fix_broken* is ``True``, apt will try to repair broken + dependencies of installed packages. + + .. method:: resolve_by_keep() -> bool + + Try to resolve the problems without installing or removing packages. + + .. method:: keep_phased_updates() -> bool + + Hold back upgrades to phased versions of already installed + packages, unless they are security updates. + +:class:`Group` of packages with the same name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. class:: Group(cache: Cache, name: str) + + .. versionadded:: 0.8.0 + + A collection of packages in which all packages have the same name. Groups + are used in multi-arch environments, where two or more packages have the + same name, but different architectures. + + Group objects provide the following parts for sequential access: + + .. describe:: group[index] + + Get the package at the given **index** in the group. + + .. note:: + Groups are internally implemented using a linked list. The object + keeps a pointer to the current object and the first object, so + access to the first element, or accesses in order have a + complexity of O(1). Random-access complexity is ranges from + O(1) to O(n). + + Group objects also provide special methods to find single packages: + + .. method:: find_package(architecture: str) -> Package + + Find a package with the groups name and the architecture given + in the argument *architecture*. If no such package exists, return + ``None``. + + .. method:: find_preferred_package(prefer_nonvirtual: bool = True) -> Package + + Find the preferred package. This is the package of the native + architecture (specified in ``APT::Architecture``) if available, + or the package from the first foreign architecture. If no package + could be found, return ``None`` + + If **prefer_nonvirtual** is ``True``, the preferred package + will be a non-virtual package, if one exists. + + +:class:`Package` information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. class:: Package + + Represent a package. A package is uniquely identified by its name and + architecture and each package can have zero or more versions which can be + accessed via the :attr:`version_list` property. Packages can be + installed and removed by a :class:`DepCache` object. + + Attributes: + + .. attribute: architecture + + The architecture of the package. This is relevant on multi-arch + systems only. Please note that if a package is Architecture: all, + this value is not "all", but the architecture of the package file + it comes from. + + .. versionadded:: 0.7.100.3 + + .. attribute:: current_ver + + The version currently installed as a :class:`Version` object, or None + if the package is not installed. + + .. method:: get_fullname([pretty: bool = False]) -> str + + Get the full name of the package, including the architecture. If + *pretty* is ``True``, the architecture is omitted for native packages, + that is, an amd64 "apt" package on an amd64 system would give "apt". + + .. versionadded:: 0.7.100.3 + + .. attribute:: has_provides + + A boolean value determining whether the list available via the + attribute :attr:`provides_list` has at least one element. This + value may be used in combination with :attr:`has_versions` to + check whether a package is virtual; that is, it has no versions + and is provided at least once:: + + pkg.has_provides and not pkg.has_versions + + .. attribute:: has_versions + + A boolean value determining whether the list available via the + attribute :attr:`version_list` has at least one element. This + value may be used in combination with :attr:`has_provides` to + check whether a package is virtual; that is, it has no versions + and is provided at least once:: + + pkg.has_provides and not pkg.has_versions + + .. 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:: provides_list + + A list of all package versions providing this package. Each element + of the list is a triplet, where the first element is the name of the + provided package, the second element the provided version (empty + string), and the third element the version providing this package + as a :class:`Version` object. + + .. attribute:: rev_depends_list + + An iterator of :class:`Dependency` objects for dependencies on this + package. The returned iterator is implemented by the class + :class:`DependencyList`: + + .. class:: DependencyList + + A simple list-like type for representing multiple dependency + objects in an efficient manner; without having to generate + all Dependency objects in advance. + + .. describe:: list[index] + + Return the item at the position *index* in the list. + + .. method:: __len__() + + The length of the list. This method should not be used + irectly, instead Python's built-in function :func:`len` + should be used. + + .. attribute:: section + + The section of the package, as specified in the record. The list of + possible sections is defined in the Policy. This is a string. + + .. deprecated:: 1.0 + + A package can have multiple versions with different sections, so + the section information should be accessed from the version class. + + .. attribute:: version_list + + A list of :class:`Version` objects for all versions of this package + available in the cache. + + **States**: + + .. attribute:: selected_state + + The state we want it to be, ie. if you mark a package for installation, + this is :attr:`apt_pkg.SELSTATE_INSTALL`. + + See :ref:`SelStates` for a list of available states. + + .. attribute:: inst_state + + The state the currently installed version is in. This is normally + :attr:`apt_pkg.INSTSTATE_OK`, unless the installation failed. + + See :ref:`InstStates` for a list of available states. + + .. attribute:: current_state + + The current state of the package (not installed, unpacked, installed, + etc). See :ref:`CurStates` for a list of available states. + + **Flags**: + + .. attribute:: essential + + Whether the package has the 'Essential' flag set; that is, + whether it has a field 'Essential: yes' in its record. + + .. attribute:: important + + Whether the package has the (obsolete) 'Important' flag set; that is, + whether it has a field 'Important: yes' in its record. + +Example: +~~~~~~~~~ +.. literalinclude:: ../examples/cache-packages.py + + + +:class:`Version` +^^^^^^^^^^^^^^^^^ +.. class:: Version + + The version object contains all information related to a specific package + version. + + .. attribute:: arch + + The architecture of the package, eg. amd64 or all. + + .. attribute:: depends_list + + This is basically the same as :attr:`depends_list_str`, + but instead of the ('pkgname', 'version', 'relation') tuples, + it returns :class:`Dependency` objects, which can assist you with + useful functions. + + .. attribute:: depends_list_str + + 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', '>='), + ] + ] + } + + The comparison operators are not the Debian ones, but the standard + comparison operators as used in languages such as C and Python. This + means that '>' means "larger than" and '<' means "less than". + + .. attribute:: downloadable + + Whether this package can be downloaded from a remote site. + + .. attribute:: file_list + + A list of (:class:`PackageFile`, int: index) tuples for all Package + files containing this version of the package. + + .. attribute:: hash + + An integer hash value used for the internal storage. + + .. attribute:: id + + A numeric identifier which uniquely identifies this version in all + versions in the cache. + + .. attribute:: installed_size + + The size of the package (in kilobytes), when unpacked on the disk. + + .. attribute:: multi_arch + + The multi-arch state of the package. Can be one of the following + attributes. + + .. attribute:: MULTI_ARCH_NO + + No multi-arch + + .. attribute:: MULTI_ARCH_ALL + + An ``Architecture: all`` package + + + .. attribute:: MULTI_ARCH_FOREIGN + + Can satisfy dependencies of foreign-architecture + packages + + .. attribute:: MULTI_ARCH_ALL_FOREIGN + + :attr:`MULTI_ARCH_FOREIGN` for ``Architecture: all`` + packages. + + .. attribute:: MULTI_ARCH_SAME + + Multiple versions from different architectures may be + installed in parallel, but may only satisfy dependencies + of packages from the same architecture + + .. attribute:: MULTI_ARCH_ALLOWED + + Installation in parallel and satisfying ``pkg:any`` + style dependencies is allowed. + + .. attribute:: MULTI_ARCH_ALL_ALLOWED + + :attr:`MULTI_ARCH_ALLOWED` for ``Architecture: all`` + packages. + + + + + .. attribute:: parent_pkg + + The :class:`Package` object this version belongs to. + + .. attribute:: priority + + The integer representation of the priority. This can be used to speed + up comparisons a lot, compared to :attr:`priority_str`. + + The values are defined in the :mod:`apt_pkg` extension, see + :ref:`Priorities` for more information. + + .. attribute:: priority_str + + Return the priority of the package version, as a string, eg. + "optional". + + .. attribute:: provides_list + + This returns a list of all packages provided by this version. Like + :attr:`Package.provides_list`, 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:: section + + The usual sections (eg. admin, net, etc.). Prefixed with the component + name for packages not in main (eg. non-free/admin). + + .. attribute:: size + + The size of the .deb file, in bytes. + + .. attribute:: translated_description + + Return a :class:`Description` object for the translated description + of this package version. + + .. attribute:: is_security_update + + Whether this version is a security update. + + .. attribute:: ver_str + + The version, as a string. + + + +:class:`Dependency` +^^^^^^^^^^^^^^^^^^^^ +.. class:: Dependency + + Represent a dependency from one package to another one. + + .. method:: all_targets + + A list of all possible target :class:`Version` objects which satisfy + this dependency. + + .. attribute:: comp_type + + The type of comparison (<,<=,=,!=,>=,>,), as string. Note that the + empty string is a valid string as well, if no version is specified. + + .. attribute:: dep_type + + The type of the dependency, as string, eg. "Depends". + + .. attribute:: dep_type_enum + + The type of the dependency, as an integer which can be compared to + one of the TYPE_* constants below. + + .. attribute:: dep_type_untranslated + + The type of the depndency, as an untranslated string. + + .. attribute:: id + + The ID of the package, as integer. + + .. attribute:: parent_pkg + + The :class:`Package` object of the package which declares the + dependency. This is the same as using ParentVer.ParentPkg. + + .. attribute:: parent_ver + + The :class:`Version` object of the parent version, ie. the package + which declares the dependency. + + .. attribute:: target_pkg + + The :class:`Package` object of the target package. + + .. attribute:: target_ver + + The target version of the dependency, as string. Empty string if the + dependency is not versioned. + + The following constants describe all values the attribute *dep_type_enum* + can take: + + .. attribute:: TYPE_CONFLICTS + + Constant for checking against dep_type_enum + + .. attribute:: TYPE_DEPENDS + + Constant for checking against dep_type_enum + + .. attribute:: TYPE_DPKG_BREAKS + + Constant for checking against dep_type_enum + + .. attribute:: TYPE_ENHANCES + + Constant for checking against dep_type_enum + + .. attribute:: TYPE_OBSOLETES + + Constant for checking against dep_type_enum + + .. attribute:: TYPE_PREDEPENDS + + Constant for checking against dep_type_enum + + .. attribute:: TYPE_RECOMMENDS + + Constant for checking against dep_type_enum + + .. attribute:: TYPE_REPLACES + + Constant for checking against dep_type_enum + + .. attribute:: TYPE_SUGGESTS + + Constant for checking against dep_type_enum + +Example: Find all missing dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +With the help of Dependency.all_targets(), 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:: language_code + + The language code of the description; or, if the description + is untranslated, an empty string. + + .. attribute:: md5 + + The MD5 checksum of the description. + + .. attribute:: file_list + + A list of tuples ``(packagefile: PackageFile, index: int)``. + +Package Pinning with :class:`Policy` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. class:: Policy(cache: apt_pkg.Cache) + + Representation of the policy of the :class:`Cache` object given by + *cache*. This provides a superset of policy-related functionality + compared to the *DepCache* class. The DepCache can be used for most + purposes, but there may be some cases where a special policy class + is needed. + + .. method:: create_pin(type: str, pkg: str, data: str, priority: int) + + Create a pin for the policy. The parameter *type* refers to one of the + strings 'Version', 'Release', or 'Origin'. The argument *pkg* is the + name of the package. The parameter *data* refers to the value (such + as 'unstable' for type='Release') and the other possible options. + The parameter 'priority' gives the priority of the pin. + + .. automethod:: init_defaults + + .. method:: get_candidate_ver(package: apt_pkg.Package) -> apt_pkg.Version + + Get the best package for the job; that is, the package with the + highest pin priority. + + .. method:: get_priority(package: Union[apt_pkg.Version, apt_pkg.PackageFile]) -> int + + Get the pin priority of the package, version, or package file + given by *package*. + + .. versionchanged:: 1.7 + + Introduce support for per-version pins. Deprecated support + for :class:`apt_pkg.Package`. + + .. method:: read_pindir(dirname: str) -> bool + + Read the pin files in the given dir (e.g. '/etc/apt/preferences.d') + and add them to the policy. + + .. method:: read_pinfile(filename: str) -> bool + + Read the pin file given by *filename* (e.g. '/etc/apt/preferences') + and add it to the policy. + + +Index Files +------------- + +.. class:: MetaIndex + + Represent a Release file as stored in the cache. + + .. attribute:: uri + + The URI the meta index file is located at, as a string. + + .. attribute:: dist + + The distribution stored in the meta index, as a string. + + .. attribute:: is_trusted + + A boolean value determining whether the meta index can be trusted. This + is ``True`` for signed Release files. + + .. attribute:: index_files + + A list of all :class:`IndexFile` objects associated with this meta + index. + + +.. class:: IndexFile + + Represent an index file, that is, package indexes, translation indexes, + and source indexes. + + .. method:: archive_uri(path: str) -> str + + Return the URI to the given path in the archive. + + .. attribute:: label + + The label of the index file. + + .. attribute:: describe + + A string describing this object. + + .. attribute:: exists + + A boolean value determining whether the index file exists. + + .. attribute:: has_packages + + A boolean value determining whether the index file has packages. + + .. attribute:: size + + The size of the file, measured in bytes. + + .. attribute:: is_trusted + + A boolean value determining whether the file can be trusted; that is, + because it is from a source with a GPG signed Release file. + + + +.. class:: PackageFile + + Provide access to an index file stored in the cache, such as + :file:`/var/lib/dpkg/status`. + + .. attribute:: architecture + + The architecture of the package file. This attribute normally + contains an empty string and is thus not very useful. + + .. attribute:: archive + + The archive of the package file as set in the Release file via + the "Suite" field. If there is no Release file, this is an empty + string. + + .. attribute:: component + + The component of the package file, if it is provided by a repository + using the dists/ hierarchy. For other packages files, this property + is an empty string. + + .. attribute:: filename + + The path to the file on the local filesystem. + + .. 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:: index_type + + A string describing the type of index. Known values are + "Debian Package Index", "Debian Translation Index", and + "Debian dpkg status file". + + .. attribute:: label + + The label of the package file as set in the release file + via the 'Label' field. If there is no Release file, this + attribute is an empty string. + + .. attribute:: not_automatic + + Whether packages from this list will be updated automatically. The + default for example is False. + + .. attribute:: not_source + + Whether the file has no source from which it can be updated. In such a + case, the value is ``True``; else ``False``. For example, it is + ``False`` for :file:`/var/lib/dpkg/status`. + + Example:: + + for pkgfile in cache.file_list: + if pkgfile.not_source: + 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") + + +The following example shows how to use PackageFile: + +.. literalinclude:: ../examples/cache-pkgfile.py + + +Records (Release files, Packages, Sources) +------------------------------------------ + +.. class:: IndexRecords() + + Represent a Release file and provide means to read information from + the file. This class provides several methods: + + .. method:: get_dist() -> str + + Return the distribution set in the Release file. + + .. method:: load(filename: str) + + Load the file located at the path given by *filename*. + + .. method:: lookup(key: str) -> (HashString, int) + + Look up the filename given by *key* and return a tuple (hash, size), + where the first element *hash* is a :class:`HashString` object + and the second element *size* is an int object. + + +.. class:: PackageRecords(cache: apt_pkg.Cache) + + Provide further information about the packages in the :class:`Cache` object + *cache*. This efficiently parses the package files to provide information + not available in the cache, such as maintainer, hash sums, description, + and the file name of the package. It also provides the complete record + of the package. + + .. method:: lookup(verfile_iter: (PackageFile, int)) -> bool + + 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 + ``file_list`` attributes such as :attr:`Version.file_list`. + + Example (shortened):: + + cand = depcache.get_candidate_ver(cache['python-apt']) + records.lookup(cand.file_list[0]) + # Now you can access the record + print(records.source_pkg) # == python-apt + + .. describe:: section[key] + + Return the value of the field at *key*. If *key* is not available, + raise :exc:`KeyError`. + Raises AttributeError if not yet looked up. + + .. versionadded:: 1.7 + + .. describe:: key in section + + Return ``True`` if *section* has a key *key*, else ``False``. + Raises AttributeError if not yet looked up. + + .. versionadded:: 1.7 + + .. 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:: hashes + + A :class:`apt_pkg.HashStringList` of all hashes. + + .. versionadded:: 1.1 + + .. attribute:: md5_hash + + Return the MD5 hashsum of the package This refers to the field + 'MD5Sum' in the raw record. + + .. deprecated:: 1.1 + + Use :attr:`hashes` instead. + + .. attribute:: sha1_hash + + Return the SHA1 hashsum of the package. This refers to the field 'SHA1' + in the raw record. + + .. deprecated:: 1.1 + + Use :attr:`hashes` instead. + + .. attribute:: sha256_hash + + Return the SHA256 hashsum of the package. This refers to the field + 'SHA256' in the raw record. + + .. versionadded:: 0.7.9 + + .. deprecated:: 1.1 + + Use :attr:`hashes` instead. + + .. attribute:: source_pkg + + The name of the source package, if different from the name of the + binary package. This information is retrieved from the 'Source' field. + + .. attribute:: source_ver + + The version of the source package, if it differs from the version + of the binary package. Just like 'source_pkg', this information + is retrieved from the 'Source' field. + + .. attribute:: maintainer + + Return the maintainer of the package. + + .. attribute:: short_desc + + Return the short description. This is the summary on the first line of + the 'Description' field. + + .. attribute:: long_desc + + 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 + :class:`apt_pkg.TagSection` to parse the record and access the field + name. + + .. deprecated:: 1.7 + + This property can be considered deprecated for simple string + lookups, as keys can now be looked up in the record itself. + + Example:: + + section = apt_pkg.TagSection(records.record) + print(section['SHA256']) # Use records.sha256_hash instead + +.. class:: SourceRecords + + Provide an easy way to look up the records of source packages and + provide easy attributes for some widely used fields of the record. + + .. 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: str) -> bool + + Look up the source package with the given name. Each call moves + the position of the records parser forward. If there are no + more records, return None. If the lookup failed this way, + access to any of the attributes will result in an + :exc:`AttributeError`. + + 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. A third call would return ``None`` and access to any + of the below attributes will result in an :exc:`AttributeError` + + .. method:: restart() + + Restart the lookup process. This moves the parser to the first + package and lookups can now be made just like on a new object. + + 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:: 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:: build_depends + + Return a dictionary representing the build-time dependencies of the + package. The format is the same as for :attr:`Version.depends_list_str` + and possible keys being ``"Build-Depends"``, ``"Build-Depends-Indep"``, + ``"Build-Conflicts"`` or ``"Build-Conflicts-Indep"``. + + .. attribute:: files + + The list of files. This returns a list of :class:`SourceRecordsFile` + + .. versionchanged:: 1.6 + + Used to be a list of tuples, see :class:`SourceRecordFile` for the tuple + layout. + + .. attribute:: index + + A list of :class:`IndexFile` objects associated with this + source package record. + + .. attribute:: maintainer + + A string describing the name of the maintainer. + + .. attribute:: package + + The name of the source package. + + .. 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 to access + fields not available via the attributes such as 'Standards-Version' + + .. attribute:: section + + A string describing the section. + + .. attribute:: version + + A string describing the version of the source package. + +.. class:: SourceRecordsFile + + Represents a file in a source record. + + .. versionadded:: 1.6 + + Before 1.6, this was a tuple `(md5, size, path, type)`. + + .. attribute:: hashes + + A :class:`HashStringList` of the file's hashes. + + .. attribute:: path + + The path to the file + + .. attribute:: size + + The size of the file + + .. attribute:: type + + The type of the file. Can be 'diff' (includes .debian.tar.gz), 'dsc', or 'tar'. + +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: apt.progress.base.AcquireProgress]) + + Coordinate the retrieval of files via network or local file system + (using ``copy://path/to/file`` style URIs). Items can be added to + an Acquire object using various means such as creating instances + of :class:`AcquireFile` or the methods :meth:`SourceList.get_indexes` + and :meth:`PackageManager.get_archives`. + + Acquire objects maintain 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. + + The constructor takes an optional parameter *progress* which takes an + :class:`apt.progress.base.AcquireProgress` object. This object may then + report progress information (see :mod:`apt.progress.text` for reporting + progress to a I/O stream). + + Acquire items have two methods to start and stop the fetching: + + .. method:: run() -> int + + Fetch all the items which have been added by :class:`AcquireFile` and + return one of the constants :attr:`RESULT_CANCELLED`, + :attr:`RESULT_CONTINUE`, :attr:`RESULT_FAILED` to describe the + result of the run. + + .. method:: shutdown() + + Shut the fetcher down. This removes all items from the queue and + makes all :class:`AcquireItem`, :class:`AcquireWorker`, + :class:`AcquireItemDesc` objects useless. Accessing an object of one + of those types can cause a segfault then. + + Removing an item does not mean that the already fetched data will + be removed from the destination. Instead, APT might use the partial + result and continue from thereon. + + Furthermore, they provide three attributes which provide information + on how much data is already available and how much data still needs + to be fetched: + + .. attribute:: fetch_needed + + The amount of data that has to be fetched in order to fetch all + queued items. + + .. attribute:: partial_present + + The amount of data which is already available. + + .. attribute:: total_needed + + The total amount of bytes needed (including those of files which are + already present). + + They also provide two attributes representing the items being processed + and the workers fetching them: + + .. attribute:: items + + A list of :class:`AcquireItem` objects which are attached to the + to this Acquire object. This includes all items ever attached to + this object (except if they were removed using, for example, + :meth:`shutdown()` or by deleting an :class:`AcquireFile` object.) + + .. attribute:: workers + + A list of :class:`AcquireWorker` objects which are currently active + on this instance. + + The Acquire class comes with three constants which represents the results + of the :meth:`run` method: + + .. attribute:: RESULT_CANCELLED + + The fetching has been aborted, e.g. due to a progress class returning + ``False`` in its :meth:`pulse()` method. + + .. attribute:: RESULT_CONTINUE + + All items have been fetched successfully or failed transiently + and the process has not been canceled. + + You need to look at the status of each item and check if it has not + failed transiently to discover errors like a Not Found when acquiring + packages. + + .. attribute:: RESULT_FAILED + + An item failed to fetch due to some reasons. + + +.. class:: AcquireItem + + An AcquireItem object represents a single item of an :class:`Acquire` + object. It is an abstract class to represent various types of items + which are implemented as subclasses. The only exported subclass is + :class:`AcquireFile` which can be used to fetch files. + + .. attribute:: complete + + A boolean value which is True only if the item has been + fetched successfully. + + .. attribute:: desc_uri + + An URI describing where the item is located at. + + .. attribute:: destfile + + The path to the local location where the fetched data will be + stored at. + + .. attribute:: error_text + + The error message. For example, when a file does not exist on a HTTP + server, this will contain a 404 error message. + + .. attribute:: filesize + + The size of the file, in bytes. If the size of the to be fetched file + is unknown, this attribute is set to ``0``. + + .. attribute:: id + + The ID of the item. This attribute is normally set to ``0``, users may + set a custom value here, for instance in an overridden + :meth:`apt.progress.base.AcquireProgress.fetch` method (the progress + class could keep a counter, increase it by one for every :meth:`fetch` + call and assign the current value to this attribute). + + .. attribute:: is_trusted + + A boolean value determining whether the file is trusted. Only ``True`` + if the item represents a package coming from a repository which is + signed by one of the keys in APT's keyring. + + .. attribute:: local + + A boolean value determining whether this file is locally available + (``True``) or whether it has to be fetched from a remote source + (``False``). + + .. attribute:: mode + + Old name for active_subprocess + + .. deprecated:: 1.0 + + .. attribute:: active_subprocess + + The name of the active subprocess (for instance, 'gzip', 'rred' or 'gpgv'). + + .. versionadded:: 1.0 + + **Status**: + + The following attribute represents the status of the item. This class + provides several constants for comparing against this value which are + listed here as well. + + .. attribute:: status + + Integer, representing the status of the item. This attribute can be + compared against the following constants to gain useful information + on the item's status. + + .. attribute:: STAT_AUTH_ERROR + + An authentication error occurred while trying to fetch the item. + + .. attribute:: STAT_DONE + + The item is completely fetched and there have been no problems + while fetching the item. + + .. attribute:: STAT_ERROR + + An error occurred while trying to fetch the item. This error is + normally not related to authentication problems, as thus are + dealt with using :attr:`STAT_AUTH_ERROR`. + + .. attribute:: STAT_FETCHING + + The item is being fetched currently. + + .. attribute:: STAT_IDLE + + The item is yet to be fetched. + + .. attribute:: STAT_TRANSIENT_NETWORK_ERROR + + There was a network error. + + +.. class:: AcquireFile(owner, uri[, hash, size, descr, short_descr, destdir, destfile]) + + Create a new :class:`AcquireFile()` object and register it with *acquire*, + so it will be fetched. You must always keep around a reference to the + object, otherwise it will be removed from the Acquire queue again. + + 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 *hash* refers to the hash of the file. If this is set + libapt will check the file after downloading. This should be an instance + of :class:`apt_pkg.HashStringList`. + + 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 description of the download. It may be + used to describe the item in the progress class. *short_descr* is the + short form of it. + + The parameters *descr* and *short_descr* can be used to specify + descriptions for the item. The string passed to *descr* should + describe the file and its origin (e.g. "http://localhost sid/main + python-apt 0.7.94.2") and the string passed to *short_descr* should + be one word such as the name of a package. + + Normally, the file will be stored in the current directory using the + file name given in the URI. This directory can be changed by passing + the name of a directory to the *destdir* parameter. It is also possible + to set a path to a file using the *destfile* parameter, but both can + not be specified together. + + In terms of attributes, this class is a subclass of :class:`AcquireItem` + and thus inherits all its attributes. + + .. versionchanged:: 1.9.1 + + The *hash* parameter now accepts an :class:`apt_pkg.HashStringList`, + the old *md5* parameter has been removed. + +.. class:: AcquireWorker + + An :class:`AcquireWorker` object represents a sub-process responsible for + fetching files from remote locations. There is no possibility to create + instances of this class from within Python, but a list of objects of + currently active workers is provided by :attr:`Acquire.workers`. + + Objects of this type provide several attributes which give information + about the worker's current activity. + + .. attribute:: current_item + + The item which is currently being fetched. This returns an + :class:`AcquireItemDesc` object. + + .. attribute:: current_size + + How many bytes of the file have been downloaded. Zero if the current + progress of the file cannot be determined. + + .. attribute:: resumepoint + + The amount of data which was already available when the download was + started. + + .. attribute:: status + + The most recent (localized) status string received from the + sub-process. + + .. attribute:: total_size + + The total number of bytes to be downloaded for the item. Zero if the + total size is unknown. + +.. class:: AcquireItemDesc + + An :class:`AcquireItemDesc` object stores information about the item which + can be used to describe the item. Objects of this class are used in the + progress classes, see the :class:`apt.progress.base.AcquireProgress` + documentation for information how. + + .. attribute:: description + + The long description given to the item. + + .. attribute:: owner + + The :class:`AcquireItem` object owning this object. + + .. attribute:: shortdesc + + A short description which has been given to this item. + + .. attribute:: uri + + The URI from which this item would be downloaded. + + +Hashes +------ +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. + +The module provides the two classes :class:`Hashes` and :class:`HashString` for +generic hash support: + +.. autoclass:: Hashes + :members: + +.. class:: HashString(type: str[, hash: str]) + + HashString objects store the type of a hash and the corresponding hash. + They are used by e.g :meth:`IndexRecords.lookup`. The first parameter, + *type* refers to one of "MD5Sum", "SHA1" and "SHA256". The second parameter + *hash* is the corresponding hash. + + You can also use a combined form by passing a string with type and hash + separated by a colon as the only argument. For example:: + + HashString("MD5Sum:d41d8cd98f00b204e9800998ecf8427e") + + + .. describe:: str(hashstring) + + Convert the HashString to a string by joining the hash type and the + hash using ':', e.g. ``"MD5Sum:d41d8cd98f00b204e9800998ecf8427e"``. + + .. attribute:: hashtype + + The type of the hash, as a string. This may be "MD5Sum", "SHA1", + "SHA256" or "SHA512". + + .. autoattribute:: hashvalue + + .. autoattribute:: usable + + .. method:: verify_file(filename: str) -> bool + + Verify that the file given by the parameter *filename* matches the + hash stored in this object. + +.. autoclass:: HashStringList + :members: + + .. describe:: len(list) + + Return the length of the list + + .. describe:: list[index] + + Get the :class:`HashString` object at the specified index. + +The :mod:`apt_pkg` module also provides the functions :func:`md5sum`, +:func:`sha1sum` and :func:`sha256sum` for creating a single hash from a +:class:`bytes` or :class:`file` object: + +.. 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.7.100 + Added support for using file descriptors. + + .. deprecated:: 1.9 + + Use :class:`apt_pkg.Hashes` instead. This function will be removed + in a later release. + +.. 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.7.100 + Added support for using file descriptors. + + .. deprecated:: 1.9 + + Use :class:`apt_pkg.Hashes` instead. This function will be removed + in a later release. + +.. 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.7.100 + Added support for using file descriptors. + + .. deprecated:: 1.9 + + Use :class:`apt_pkg.Hashes` instead. This function will be removed + in a later release. + +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, bytes: bool = False) + + An object which represents a typical debian control file. Can be used for + Packages, Sources, control, Release, etc. + + The *file* argument shall be a path name or an open file object. The + argument *bytes* specifies whether the file shall be represented using + bytes (``True``) or unicode (``False``) strings. + + It is a context manager that can be used with a with statement or the + :meth:`close` method. + + .. describe:: with TagFile(...) as ...: + + Use the :class:`TagFile` as a context manager. This will automatically + close the file after the body finished execution. + + .. versionadded:: 1.0 + + .. method:: close() + + Close the file. It's recommended to use the context manager + instead (that is, the `with` statement). + + .. versionadded:: 1.0 + + It provides two kinds of API which should not be used together: + + The first API implements the iterator protocol and should be used whenever + possible because it has less side effects than the other one. It may be + used e.g. with a for loop:: + + with apt_pkg.TagFile('/var/lib/dpkg/status') as tagfile: + for section in tagfile: + print(section['Package']) + + .. versionchanged:: 0.7.100 + Added support for using gzip files, via :class:`gzip.GzipFile` or any + file containing a compressed gzip stream. + + .. versionadded:: 0.8.5 + + Added support for using bytes instead of str in Python 3 + + .. method:: next() + + A TagFile is its own iterator. This method is part of the iterator + protocol and returns a :class:`TagSection` object for the next + section in the file. If there is no further section, this method + raises the :exc:`StopIteration` exception. + + From Python 3 on, this method is not available anymore, and the + global function ``next()`` replaces it. + + The second API uses a shared :class:`TagSection` object which is exposed + through the :attr:`section` attribute. This object is modified by calls + to :meth:`step` and :meth:`jump`. This API provides more control and may + use less memory, but is not recommended because it works by modifying + one object. It can be used like this:: + + with apt_pkg.TagFile('/var/lib/dpkg/status') as tagf: + tagf.step() + print tagf.section['Package'] + + .. method:: step() -> bool + + Step forward to the next section. This simply returns ``True`` if OK, + and ``False`` if there is no section. + + .. method:: offset() -> int + + Return the current offset (in bytes) from the beginning of the file. + + .. method:: jump(offset) -> bool + + Jump back/forward to *offset*. Use ``jump(0)`` to jump to the + beginning of the file again. Returns ``True`` if a section could + be parsed or ``False`` if not. + + .. 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.7.100 + + .. method:: bytes() -> int + + The number of bytes in the section. + + .. method:: find(key: str, default: str = '') -> str + + Return the value of the field at the key *key* if available, + else return *default*. + + .. method:: find_flag(key: str) -> bool + + Find a yes/no value for the key *key*. An example for such a + field is 'Essential'. + + .. method:: find_raw(key: str, default: str = '') -> str + + Similar to :meth:`find`, but instead of returning just the value, + it returns the complete field consisting of 'key: value'. + + .. method:: get(key: str, default: str = '') + + Return the value of the field at the key *key* if available, else + return *default*. + + .. method:: keys() + + Return a list of keys in the section. + + + .. automethod:: write + + +A function can be rewritten by using tag classes: + +.. autoclass:: Tag + :members: + + The following static members can be used to determine the meaning of + :attr:`action`: + + .. data:: REWRITE + + Change the field value to the value of :attr:`data` + + .. data:: RENAME + + Rename the tag to a new tag stored in :attr:`data`. + + .. data:: REMOVE + + Remove the tag. + + Apart from this, the class provides access to several attributes. + +.. autoclass:: TagRewrite + +.. autoclass:: TagRemove + +.. autoclass:: TagRename + +Pre-defined ordering for tag sections are: + +.. data:: REWRITE_PACKAGE_ORDER + + The order in which the information for binary packages should be rewritten, + i.e. the order in which the fields should appear. + +.. data:: REWRITE_SOURCE_ORDER + + The order in which the information for source packages should be rewritten, + i.e. the order in which the fields should appear. + + +Dependencies +------------ +.. function:: check_dep(pkgver: str, op: str, depver: str) -> bool + + Check that the given requirement is fulfilled; that is, that the version + string given by *pkg_ver* matches the version string *dep_ver* under + the condition specified by the operator 'dep_op' (<,<=,=,>=,>). + + Return True if *pkg_ver* matches *dep_ver* under the condition 'dep_op'; + for example:: + + >>> apt_pkg.check_dep("1.0", ">=", "1") + True + +The following two functions provide the ability to parse dependencies. They +use the same format as :attr:`Version.depends_list_str`. + +.. function:: parse_depends(depends, strip_multiarch=True, architecture) + + 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.parse_depends("PkgA (>= VerA) | PkgB (>= VerB)") + [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] + + Note that multiarch dependency information is stripped off by default. + You can force the full dependency info (including the multiarch info) + by passing "False" as a additional parameter to this function. + + You can specify an optional argument *architecture* that treats the given + architecture as the native architecture for purposes of parsing the + dependency. + + .. note:: + + The behavior of this function is different than the behavior of the + old function :func:`ParseDepends()`, because the third field + ``operation`` uses `>` instead of `>>` and `<` instead of `<<` which + is specified in control files. + + +.. function:: parse_src_depends(depends, strip_multiarch=True, architecture) + + 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.parse_depends("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.parse_src_depends("a (>= 01) [i386 amd64]") + [[('a', '01', '>=')]] + + Note that multiarch dependency information is stripped off by default. + You can force the full dependency info (including the multiarch info) + by passing "False" as a additional parameter to this function. + + You can specify an optional argument *architecture* that treats the given + architecture as the native architecture for purposes of parsing the + dependency. + + .. note:: + + The behavior of this function is different than the behavior of the + old function :func:`ParseDepends()`, because the third field + ``operation`` uses `>` instead of `>>` and `<` instead of `<<` which + is specified in control files. + + +Configuration and Command-line parsing +-------------------------------------- + +.. class:: Configuration() + + Provide access to and manipulation of APT's configuration which is + used by many classes and functions in this module to define their + behavior. There are options to install recommends, change the root + directory and much more. For an (incomplete) list of available options, + see the :manpage:`apt.conf(5)` manual page. + + The most important Configuration object is the one available by the + module's :attr:`apt_pkg.config` attribute. It stores the global + configuration which affects the behavior of most functions and is + initialized by a call to the function :func:`init_config`. While + possible, it is generally not needed to create other instances of + this class. + + For accessing and manipulating the configuration space, objects + of this type provide an interface which resembles Python mapping + types like :class:`dict`. + + .. 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 + exist, raise :exc:`KeyError`. + + .. describe:: conf[key] = value + + Set the option at *key* to *value*. + + .. describe del conf[key] + + Delete the option with the name *key* in the configuration object + *conf*. + + .. method:: get(key[, default='']) -> str + + Find the value for the given key and return it. If the given key does + not exist, return *default* instead. + + In addition, they provide methods to resemble the interface provided + by the C++ class and some more mapping methods which have been enhanced + to support some more advanced configuration features: + + .. method:: clear(key: str) + + Remove the option at *key* and all of its children. + + .. method:: dump() -> str + + Return a string containing the values in the configuration object, + in the standard :manpage:`apt.conf(5)` format. + + .. versionadded:: 0.7.100 + + .. method:: exists(key) + + Check whether an option named *key* exists in the configuration. + + .. method:: find(key[, default='']) -> str + + Return the value stored at the option named *key*, or the value + given by the string *default* if the option in question is not + set. + + .. method:: find_b(key[, default=False]) -> bool + + Return the boolean value stored at *key*, or the value given by + the :class:`bool` object *default* if the requested option is + not set. + + .. method:: find_file(key[, default='']) -> str + find_dir(key[, default='/']) -> str + + Locate the given key using :meth:`find` and return the path to the + file/directory. This uses a special algorithms which moves upwards + in the configuration space and prepends the values of the options + to the result. These methods are generally used for the options + stored in the 'Dir' section of the configuration. + + As an example of how this works, take a look at the following options + and their values: + + .. table:: + + ============== =========================== + Option Value + ============== =========================== + Dir / + Dir::Etc etc/apt/ + Dir::Etc::main apt.conf + ============== =========================== + + A call to :meth:`find_file` would now return ``/etc/apt/apt.conf`` + because it prepends the values of "Dir::Etc" and "Dir" to the value + of "Dir::Etc::main":: + + >>> apt_pkg.config.find_file("Dir::Etc::main") + '/etc/apt/apt.conf' + + If the special configuration variable "RootDir" is set, this value + would be prepended to every return value, even if the path is already + absolute. If not, the function ends as soon as an absolute path is + created (once an option with a value starting with "/" is read). + + The method :meth:`find_dir` does exactly the same thing as + :meth:`find_file`, but adds a trailing forward slash before + returning the value. + + .. method:: find_i(key[, default=0]) -> int + + Return the integer value stored at *key*, or the value given by + the integer *default* if the requested option is not set. + + .. method:: keys([key]) + + Return a recursive list of all configuration options or, if *key* + is given, a list of all its children. This method is comparable + to the **keys** method of a mapping object, but additionally + provides the parameter *key*. + + .. method:: list([key]) + + Return a non-recursive list of all configuration options. If *key* + is not given, this returns a list of options like "Apt", "Dir", and + similar. If *key* is given, a list of the names of its child options + will be returned instead. + + .. method:: my_tag() + + Return the tag name of the current tree. Normally (for + :data:`apt_pkg.config`) this is an empty string, but for + sub-trees it is the key of the sub-tree. + + .. method:: set(key: str, value: str) + + Set the option named *key* to the value given by the argument + *value*. It is possible to store objects of the types :class:`int` + and :class:`bool` by calling :func:`str` on them to convert them + to a string object. They can then be retrieved again by using the + methods :meth:`find_i` or :meth:`find_b`. + + .. method:: subtree(key) + + Return a new apt_pkg.Configuration object which starts at the + given option. Example:: + + apttree = config.subtree('APT') + apttree['Install-Suggests'] = config['APT::Install-Suggests'] + + The configuration space is shared with the main object which means + that all modifications in one object appear in the other one as + well. + + .. method:: value_list([key]) + + This is the opposite of the :meth:`list` method in that it returns the + values instead of the option names. + +.. data:: config + + This variable contains the global configuration which is used by + all classes and functions in this module. After importing the + module, this object should be initialized by calling the module's + :func:`init_config` function. + +.. function:: read_config_file(configuration: Configuration, filename: str) + + Read the configuration file *filename* and set the appropriate + options in the configuration object *configuration*. + +.. function:: read_config_dir(configuration, dirname) + + Read all configuration files in the dir given by 'dirname' in the + correct order. + + +.. function:: read_config_file_isc(configuration, filename) + + Read the configuration file *filename* and set the appropriate + options in the configuration object *configuration*. This function + requires a slightly different format than APT configuration files, + if you are unsure, do not use it. + +.. function:: parse_commandline(configuration, options, argv) + + Parse the command line in *argv* into the configuration space. The + list *options* contains a list of 3-tuples or 4-tuples in the form:: + + (short_option: str, long_option: str, variable: str[, type: str]) + + The element *short_option* is one character, the *long_option* element + is the name of the long option, the element *variable* the name of the + configuration option the result will be stored in and *type* is one of + 'HasArg', 'IntLevel', 'Boolean', 'InvBoolean', 'ConfigFile', + 'ArbItem'. The default type is 'Boolean'. + + .. table:: Overview of all possible types + + =========== ===================================================== + Type What happens if the option is given + =========== ===================================================== + HasArg The argument given to the option is stored in + the target. + IntLevel The integer value in the target is increased by one + Boolean The target variable is set to True. + InvBoolean The target variable is set to False. + ConfigFile The file given as an argument to this option is read + in and all configuration options are added to the + configuration object (APT's '-c' option). + ArbItem The option takes an argument *key*=*value*, and the + configuration option at *key* is set to the value + *value* (APT's '-o' option). + =========== ===================================================== + + +Locking +-------- +When working on the global cache, it is important to lock the cache so other +programs do not modify it. This module provides two context managers for +locking the package system or file-based locking. + +.. class:: SystemLock + + Context manager for locking the package system. The lock is established + as soon as the method __enter__() is called. It is released when + __exit__() is called. If the lock can not be acquired or can not be + released an exception is raised. + + This should be used via the 'with' statement. For example:: + + with apt_pkg.SystemLock(): + ... # Do your stuff here. + ... # Now it's unlocked again + + Once the block is left, the lock is released automatically. The object + can be used multiple times:: + + lock = apt_pkg.SystemLock() + with lock: + ... + with lock: + ... + +.. class:: FileLock(filename: str) + + Context manager for locking using a file. The lock is established + as soon as the method __enter__() is called. It is released when + __exit__() is called. If the lock can not be acquired or can not be + released, an exception is raised. + + This should be used via the 'with' statement. For example:: + + with apt_pkg.FileLock(filename): + ... + + Once the block is left, the lock is released automatically. The object + can be used multiple times:: + + lock = apt_pkg.FileLock(filename) + with lock: + ... + with lock: + ... + +For Python versions prior to 2.5, similar functionality is provided by the +following three functions: + +.. function:: get_lock(filename: str, errors=False) -> int + + Create an empty file at the path specified by the parameter *filename* and + lock it. If this fails and *errors* is **True**, the function raises an + error. If *errors* is **False**, the function returns -1. + + The lock can be acquired multiple times within the same process, and can be + released by calling :func:`os.close` on the return value which is the file + descriptor of the created file. + +.. function:: pkgsystem_lock() + + Lock the global pkgsystem. The lock should be released by calling + :func:`pkgsystem_unlock` again. If this function is called n-times, the + :func:`pkgsystem_unlock` function must be called n-times as well to release + all acquired locks. + +.. function:: pkgsystem_unlock() + + Unlock the global pkgsystem. This reverts the effect of + :func:`pkgsystem_lock`. + +Since version 1.7, APT switches to the frontend locking approach where +dpkg has two lock files, :file:`lock-frontend` and :file:`lock`, the +latter being called the inner lock in apt. +When running dpkg, the inner lock must be released before calling dpkg +and reacquired afterwards. When not using APT functions to run dpkg, +the variable `DPKG_FRONTEND_LOCKED` must be set to tell dpkg to not +acquire the :file:`lock-frontend` lock. +These functions usually do not need to be used by external code. + +.. function:: pkgsystem_unlock_inner() + + Release the :file:`lock` lock file to allow dpkg to be run. + + .. versionadded:: 1.7 + +.. function:: pkgsystem_lock_inner() + + Release the :file:`lock` lock file after a dpkg run. + + .. versionadded:: 1.7 + +.. function:: pkgsystem_is_locked() + + Returns true if the global lock is hold. Can be used to check whether + :meth:`pkgsystem_unlock_inner` needs to be called. + + .. versionadded:: 1.7 + + + +Other classes +-------------- +.. class:: Cdrom() + + A Cdrom object identifies Debian installation media and adds them to + :file:`/etc/apt/sources.list`. The C++ version of this class is used by + the apt-cdrom tool and using this class, you can re-implement apt-cdrom + in Python, see :doc:`../tutorials/apt-cdrom`. + + The class :class:`apt.cdrom.Cdrom` is a subclass of this class and + provides some additional functionality for higher level use and some + shortcuts for setting some related configuration options. + + This class provides two functions which take an instance of + :class:`apt.progress.base.CdromProgress` as their argument. + + .. method:: add(progress: apt.progress.base.CdromProgress) -> bool + + Search for a Debian installation media and add it to the list of + sources stored in :file:`/etc/apt/sources.list`. On success, the + boolean value ``True`` is returned. If the process failed or was + canceled by the progress class, :exc:`SystemError` is raised or + ``False`` is returned. + + .. method:: ident(progress: apt.progress.base.CdromProgress) -> str + + Identify the installation media and return a string which describes + its identity. If no media could be identified, :exc:`SystemError` is + raised or ``None`` is returned. + +.. class:: SourceList + + Represent the list of sources stored in files such as + :file:`/etc/apt/sources.list`. + + .. method:: find_index(pkgfile: PackageFile) -> IndexFile + + Return the :class:`IndexFile` object for the :class:`PackageFile` + object given by the argument *pkgfile*. If no index could be found, + return ``None``. + + .. method:: get_indexes(acquire: Acquire[, all: bool = False]) -> bool + + Add all indexes to the :class:`Acquire` object given by the argument + *acquire*. If *all* is ``True``, all indexes will be added, otherwise + only the meta indexes (Release files) will be added and others are + fetched as needed. + + .. method:: read_main_list() -> bool + + Read the files configured in Dir::Etc::SourceList and + Dir::Etc::sourceparts; that is (on normal system), + :file:`/etc/apt/sources.list` and the files in + :file:`/etc/apt/sources.list.d`. + + .. attribute:: list + + A list of :class:`MetaIndex` objects. + +String functions +---------------- +.. function:: base64_encode(value: bytes) -> str + + Encode the given bytes string (which may not contain a null byte) + using base64, for example, on Python 3 and newer:: + + >>> apt_pkg.base64_encode(b"A") + 'QQ==' + + on Python versions prior to 3, the 'b' before the string has to be + omitted. + +.. function:: check_domain_list(host, list) + + See if the host name given by *host* is one of the domains given in the + comma-separated list *list* or a subdomain of one of them. + + >>> apt_pkg.check_domain_list("alioth.debian.org","debian.net,debian.org") + True + +.. function:: dequote_string(string: str) + + Dequote the string specified by the parameter *string*, e.g.:: + + >>> apt_pkg.dequote_string("%61%70%74%20is%20cool") + 'apt is cool' + +.. function:: quote_string(string, repl) + + Escape the string *string*, replacing any character not allowed in a URL + or specified by *repl* with its ASCII value preceded by a percent sign + (so for example ' ' becomes '%20'). + + >>> apt_pkg.quote_string("apt is cool","apt") + '%61%70%74%20is%20cool' + +.. function:: size_to_str(size: int) + + Return a string describing the size in a human-readable manner using + SI prefix and base-10 units, e.g. '1k' for 1000, '1M' for 1000000, etc. + + Example:: + + >>> apt_pkg.size_to_str(10000) + '10.0k' + +.. function:: string_to_bool(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.string_to_bool("yes") + 1 + >>> apt_pkg.string_to_bool("no") + 0 + >>> apt_pkg.string_to_bool("not-recognized") + -1 + + +.. function:: str_to_time(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.str_to_time('Thu, 01 Jan 1970 00:00:00 GMT') + 0 + +.. function:: time_rfc1123(seconds: int) -> str + + Format the unix time specified by the integer *seconds*, according to the + requirements of :rfc:`1123`. + + Example:: + + >>> apt_pkg.time_rfc1123(0) + 'Thu, 01 Jan 1970 00:00:00 GMT' + + +.. function:: time_to_str(seconds: int) -> str + + 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.time_to_str(3601) + '1h0min1s' + +.. function:: upstream_version(version: str) -> str + + Return the upstream version for the Debian package version given by + *version*. + +.. function:: uri_to_filename(uri: str) -> str + + 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.uri_to_filename('http://debian.org/index.html') + 'debian.org_index.html' + + +.. function:: version_compare(a: str, b: str) -> int + + Compare two versions, *a* and *b*, and return an integer value which has + the same meaning as the built-in :func:`cmp` function's return value has, + see the following table for details. + + .. 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:: CURSTATE_CONFIG_FILES + + Only the configuration files of the package exist on the system. + +.. data:: CURSTATE_HALF_CONFIGURED + + The package is unpacked and configuration has been started, but not + yet completed. + +.. data:: CURSTATE_HALF_INSTALLED + + The installation of the package has been started, but not completed. + +.. data:: CURSTATE_INSTALLED + + The package is unpacked, configured and OK. + +.. data:: CURSTATE_NOT_INSTALLED + + The package is not installed. + +.. data:: CURSTATE_UNPACKED + + The package is unpacked, but not configured. + +.. _InstStates: + +Installed states +^^^^^^^^^^^^^^^^ +.. data:: INSTSTATE_HOLD + + The package is put on hold. + +.. data:: INSTSTATE_HOLD_REINSTREQ + + The package is put on hold, but broken and has to be reinstalled. + +.. data:: INSTSTATE_OK + + The package is OK. + +.. data:: INSTSTATE_REINSTREQ + + The package is broken and has to be reinstalled. + +.. _Priorities: + +Priorities +^^^^^^^^^^^ +.. data:: PRI_EXTRA + + The integer representation of the priority 'extra'. + +.. data:: PRI_IMPORTANT + + The integer representation of the priority 'important'. + +.. data:: PRI_OPTIONAL + + The integer representation of the priority 'optional'. + +.. data:: PRI_REQUIRED + + The integer representation of the priority 'required'. + +.. data:: PRI_STANDARD + + The integer representation of the priority 'standard'. + + +.. _SelStates: + +Package selection states +^^^^^^^^^^^^^^^^^^^^^^^^ +.. data:: SELSTATE_DEINSTALL + + The package is selected for deinstallation. + +.. data:: SELSTATE_HOLD + + The package is marked to be on hold and will not be modified. + +.. data:: SELSTATE_INSTALL + + The package is selected for installation. + +.. data:: SELSTATE_PURGE + + The package is selected to be purged. + +.. data:: SELSTATE_UNKNOWN + + The package is in an unknown state. + + +Build information +^^^^^^^^^^^^^^^^^ +.. data:: DATE + + The date on which this extension has been compiled. + +.. data:: LIB_VERSION + + 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). |