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 DepCache and
PackageManager for such functionality.

The constructor takes an optional argument which must be a subclass of
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.

cache[pkgname]

Return the Package() object for the package name given by
pkgname. If pkgname includes a colon, the part after the colon
is used as the architecture.

cache[name, architecture]

Return the Package() object for the package with the given
name and architecture.

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.

(name, architecture) in cache

Check whether a package with the given name and architecture exists
in the cache.

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
apt.progress.base.AcquireProgress object which will display
the progress of fetching the index files. The parameter sources takes
a 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.

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:

list[index]

Get the Group object for the group at the position
given by index in the GroupList list.

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:

list[index]

Get the Package object for the package at the position
given by index in the PackageList list.

A DepCache object provides access to more information about the
objects made available by the 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
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.

Return the candidate version for the package given by the parameter
pkg as a Version object. The default candidate for a
package is the version with the highest pin, although a different
one may be set using set_candidate_ver(). If no candidate
can be found, return None instead.

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 Cache, this
function takes a single apt.progress.base.OpProgress
object to display progress information.

Set the candidate version of the package given by the Package
object pkg to the version given by the Version object
version and return True. If odd things happen, this function
may raise a SystemError exception, but this should not
happen in normal usage. See get_candidate_ver() for a way
to retrieve the candidate version of a package.

Mark the packages for upgrade under the same conditions
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 SystemError and
does not return False if an error occurred.

The following methods can mark a single package for installation,
removal, etc:

Install the packages and return one of the class constants
RESULT_COMPLETED, RESULT_FAILED,
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).

A constant for checking whether the result of the call to
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 _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
PackageManager to create the object.

Notify the package manager that the 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.

Notify the package manager that the 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.

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
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:

withapt_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, ActionGroup objects provide the
following method:

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 apt_pkg.DepCache to determine the
cache that shall be manipulated in order to resolve the problems.

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:

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).

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.

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 version_list property. Packages can be
installed and removed by a DepCache object.

A boolean value determining whether the list available via the
attribute provides_list has at least one element. This
value may be used in combination with has_versions to
check whether a package is virtual; that is, it has no versions
and is provided at least once:

A boolean value determining whether the list available via the
attribute version_list has at least one element. This
value may be used in combination with has_provides to
check whether a package is virtual; that is, it has no versions
and is provided at least once:

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 Version object.

This flag is here for compatibility purposes and does not appear to
be used anymore in APT. To find out whether a package is marked as
automatically installed, use DepCache.is_auto_installed()
instead.

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”.

This returns a list of all packages provided by this version. Like
Package.provides_list, it returns a list of tuples
of the form (‘virtualpkgname’, ‘’, Version), where as the
last item is the same as the object itself.

A list of Version objects which satisfy the dependency,
and do not conflict with already installed ones.

From my experience, if you use this method to select the target
version, it is the best to select the last item unless any of the
other candidates is already installed. This leads to results being
very close to the normal package installation.

With the help of Dependency.AllTargets(), you can easily find all packages with
broken dependencies:

#!/usr/bin/python"""Check the archive for missing dependencies"""importapt_pkgdeffmt_dep(dep):"""Format a Dependency object [of apt_pkg] as a string."""ret=dep.target_pkg.nameifdep.target_ver:ret+=" (%s%s)"%(dep.comp_type,dep.target_ver)returnretdefcheck_version(pkgver):"""Check the version of the package"""missing=[]foror_groupinpkgver.depends_list.get("Pre-Depends",[])+ \
pkgver.depends_list.get("Depends",[]):ifnotany(dep.all_targets()fordepinor_group):# If none of the or-choices can be satisfied, add it to missingmissing.append(or_group)ifmissing:print"Package:",pkgver.parent_pkg.nameprint"Version:",pkgver.ver_strprint"Missing:",print", ".join(" | ".join(fmt_dep(dep)fordepinor_group)foror_groupinmissing)printdefmain():"""The main function."""apt_pkg.init_config()apt_pkg.init_system()cache=apt_pkg.Cache()forpkginsorted(cache.packages,key=lambdapkg:pkg.name):# pkg is from a list of packages, sorted by name.forversioninpkg.version_list:# Check every versionforpfile,_inversion.file_list:if(pfile.origin=="Debian"andpfile.component=="main"andpfile.archive=="unstable"):# We only want packages from Debian unstable main.check_version(version)breakif__name__=="__main__":main()

Representation of the policy of the 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.

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.

#!/usr/bin/pythonimportapt_pkgdefmain():"""Example for PackageFile()"""apt_pkg.init()cache=apt_pkg.Cache()forpkgfileincache.file_list:print'Package-File:',pkgfile.filenameprint'Index-Type:',pkgfile.index_type# 'Debian Package Index'ifpkgfile.not_source:print'Source: None'else:ifpkgfile.site:# There is a source, and a site, print the siteprint'Source:',pkgfile.siteelse:# It seems to be a local repositoryprint'Source: Local package file'ifpkgfile.not_automatic:# The system won't be updated automatically (eg. experimental)print'Automatic: No'else:print'Automatic: Yes'printif__name__=='__main__':main()

Provide further information about the packages in the 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.

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).

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
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 AttributeError

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.

Return a dictionary representing the build-time dependencies of the
package. The format is the same as for Version.depends_list_str
and possible keys being "Build-Depends", "Build-Depends-Indep",
"Build-Conflicts" or "Build-Conflicts-Indep".

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 apt_pkg module provides a subset of this functionality which allows
you to implement file downloading in your applications. Together with the
PackageManager class you can also fetch all the packages marked for
installation.

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 AcquireFile objects which allow
you to add single files.

Shut the fetcher down. This removes all items from the queue and
makes all AcquireItem, AcquireWorker,
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:

A list of 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,
shutdown() or by deleting an AcquireFile object.)

An AcquireItem object represents a single item of an Acquire
object. It is an abstract class to represent various types of items
which are implemented as subclasses. The only exported subclass is
AcquireFile which can be used to fetch files.

The ID of the item. This attribute is normally set to 0, users may
set a custom value here, for instance in an overridden
apt.progress.base.AcquireProgress.fetch() method (the progress
class could keep a counter, increase it by one for every fetch()
call and assign the current value to this attribute).

Create a new 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 Acquire() object as returned
by GetAcquire(). The file will be added to the Acquire queue
automatically.

The parameter uri refers to the location of the file, any protocol
of apt is supported.

The parameter md5 refers to the md5sum of the file. This can be used
for checking the file.

The parameter size can be used to specify the size of the package,
which can then be used to calculate the progress and validate the download.

The parameter descr is a 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 AcquireItem
and thus inherits all its attributes.

An 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 Acquire.workers.

Objects of this type provide several attributes which give information
about the worker’s current activity.

Calculate all supported hashes of the object. object may either be a
string, in which cases the hashes of the string are calculated; or a
file() object or file descriptor, in which case the hashes of
its contents is calculated. The calculated hashes are then available via
attributes:

HashString objects store the type of a hash and the corresponding hash.
They are used by e.g 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")

str(hashstring)

Convert the HashString to a string by joining the hash type and the
hash using ‘:’, e.g. "MD5Sum:d41d8cd98f00b204e9800998ecf8427e".

Return the md5sum of the object. object may either be a string, in
which case the md5sum of the string is returned, or a file()
object (or a file descriptor), in which case the md5sum of its contents is
returned.

Return the sha1sum of the object. object may either be a string, in
which case the sha1sum of the string is returned, or a file()
object (or a file descriptor), in which case the sha1sum of its contents
is returned.

Return the sha256sum of the object. object may either be a string, in
which case the sha256sum of the string is returned, or a file()
object (or a file descriptor), in which case the sha256sum of its contents
is returned.

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
/var/lib/dpkg/status file which contains a list of the currently
installed packages.

The apt_pkg module provides two classes to read those files and parts
thereof and provides a function RewriteSection() which takes a
TagSection() object and sorting information and outputs a sorted
section as a string.

A TagFile is its own iterator. This method is part of the iterator
protocol and returns a TagSection object for the next
section in the file. If there is no further section, this method
raises the 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 TagSection object which is exposed
through the section attribute. This object is modified by calls
to step() and 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:

The parameter rewrite_list is a list of tuples of the form
(tag,newvalue[,renamed_to]), where tag describes the field which
should be changed, newvalue the value which should be inserted or
None to delete the field, and the optional renamed_to can be used
to rename the field.

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 Version.depends_list_str.

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.

Note

The behavior of this function is different than the behavior of the
old function ParseDepends(), because the third field
operation uses > instead of >> and < instead of << which
is specified in control files.

The behavior of this function is different than the behavior of the
old function ParseDepends(), because the third field
operation uses > instead of >> and < instead of << which
is specified in control files.

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 apt.conf(5) manual page.

The most important Configuration object is the one available by the
module’s 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 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 dict.

key in conf

Return True if conf has a key key, else False.

conf[key]

Return the value of the option given key key. If it does not
exist, raise KeyError.

Locate the given key using 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:

Option

Value

Dir

/

Dir::Etc

etc/apt/

Dir::Etc::main

apt.conf

A call to 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 find_dir() does exactly the same thing as
find_file(), but adds a trailing forward slash before
returning the value.

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.

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.

Set the option named key to the value given by the argument
value. It is possible to store objects of the types int
and bool by calling str() on them to convert them
to a string object. They can then be retrieved again by using the
methods find_i() or find_b().

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
init_config() function.

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.

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’.

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).

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:

withapt_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:

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:

withapt_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)withlock:...withlock:...

For Python versions prior to 2.5, similar functionality is provided by the
following three functions:

Lock the global pkgsystem. The lock should be released by calling
pkgsystem_unlock() again. If this function is called n-times, the
pkgsystem_unlock() function must be called n-times as well to release
all acquired locks.

A Cdrom object identifies Debian installation media and adds them to
/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 Writing your own apt-cdrom.

The 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.

Search for a Debian installation media and add it to the list of
sources stored in /etc/apt/sources.list. On success, the
boolean value True is returned. If the process failed or was
canceled by the progress class, SystemError is raised or
False is returned.

Add all indexes to the 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.