|
: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. |
|
|
|
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. |
|
|
|
: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:: 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.AllTargets(), you can easily find all packages with |
|
broken dependencies: |
|
|
|
.. literalinclude:: ../examples/missing-deps.py |
|
|
|
|
|
:class:`Description` |
|
^^^^^^^^^^^^^^^^^^^^^ |
|
.. class:: Description |
|
|
|
Represent the description of the package. |
|
|
|
.. attribute:: 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). |
|
|
