apt_pkg — The low-level bindings for 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.

apt_pkg.init_config()
Initialize the configuration of apt. This is needed for most operations.
apt_pkg.init_system()
Initialize the system.
apt_pkg.init()
A short cut to calling init_config() and init_system(). You can use this if you do not use the command line parsing facilities provided by parse_commandline(), otherwise call init_config(), parse the commandline afterwards and finally call init_system().

Working with the cache

class apt_pkg.Cache([progress])

Return a Cache() object. The optional parameter progress specifies an instance of apt.progress.OpProgress() which will display the open progress.

cache[pkgname]
Return the Package() object for the package name given by pkgname.
pkgname in cache
Check whether a package with the name given by pkgname exists in the cache.
update(progress, list[, pulse_interval])

Update the package cache.

The parameter progress points to an apt.progress.FetchProgress() object. The parameter list refers to a SourceList() object.

The optional parameter pulse_interval describes the interval between the calls to the FetchProgress.pulse() method.

depends_count
The total number of dependencies.
package_count
The total number of packages available in the cache.
packages
A sequence of Package objects.
provides_count
The number of provided packages.
ver_file_count

Todo

Seems to be some mixture of versions and pkgFile.

version_count
The total number of package versions available in the cache.
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 file_list.
file_list
A list of PackageFile objects.
class apt_pkg.DepCache(cache)

Return a DepCache object. The parameter cache specifies an instance of Cache.

The DepCache object contains various methods to manipulate the cache, to install packages, to remove them, and much more.

commit(fprogress, iprogress)

Apply all the changes made.

The parameter fprogress has to be set to an instance of apt.progress.FetchProgress or one of its subclasses.

The parameter iprogress has to be set to an instance of apt.progress.InstallProgress or one of its subclasses.

fix_broken()
Try to fix all broken packages in the cache.
get_candidate_ver(pkg)

Return the candidate version of the package, ie. the version that would be installed normally.

The parameter pkg refers to an Package object, available using the pkgCache.

This method returns a Version object.

set_candidate_ver(pkg, version)
The opposite of pkgDepCache.get_candidate_ver(). Set the candidate version of the Package pkg to the Version version.
upgrade([dist_upgrade=False])

Perform an upgrade. More detailed, this marks all the upgradable packages for upgrade. You still need to call pkgDepCache.commit() for the changes to apply.

To perform a dist-upgrade, the optional parameter dist_upgrade has to be set to True.

fix_broken()
Fix broken packages.
read_pinfile()
Read the policy, eg. /etc/apt/preferences.
minimize_upgrade()

Go over the entire set of packages and try to keep each package marked for upgrade. If a conflict is generated then the package is restored.

Todo

Explain better..

mark_auto(pkg)
Mark the Package pkg as automatically installed.
mark_keep(pkg)
Mark the Package pkg for keep.
mark_delete(pkg[, purge])
Mark the Package pkg for delete. If purge is True, the configuration files will be removed as well.
mark_install(pkg[, auto_inst=True[, from_user=True]])

Mark the Package pkg for install.

If auto_inst is True, the dependencies of the package will be installed as well. This is the default.

If from_user is True, the package will be marked as manually installed. This is the default.

set_reinstall(pkg)
Set if the Package pkg should be reinstalled.
is_upgradable(pkg)

Return 1 if the package is upgradable.

The package can be upgraded by calling pkgDepCache.MarkInstall().

is_now_broken(pkg)
Return 1 if the package is broken now (including changes made, but not committed).
is_inst_broken(pkg)
Return 1 if the package is broken on the current install. This takes changes which have not been committed not into effect.
is_garbage(pkg)
Return 1 if the package is garbage, ie. if it is automatically installed and no longer referenced by other packages.
is_auto_installed(pkg)
Return 1 if the package is automatically installed (eg. as the dependency of another package).
marked_install(pkg)
Return 1 if the package is marked for install.
marked_upgrade(pkg)
Return 1 if the package is marked for upgrade.
marked_delete(pkg)
Return 1 if the package is marked for delete.
marked_keep(pkg)
Return 1 if the package is marked for keep.
marked_reinstall(pkg)
Return 1 if the package should be installed.
marked_downgrade(pkg)
Return 1 if the package should be downgraded.
keep_count
Integer, number of packages marked as keep
inst_count
Integer, number of packages marked for installation.
del_count
Number of packages which should be removed.
broken_count
Number of packages which are broken.
usr_size
The size required for the changes on the filesystem. If you install packages, this is positive, if you remove them its negative.
deb_size
The size of the packages which are needed for the changes to be applied.
policy
The underlying Policy object used by the DepCache to select candidate versions.
class apt_pkg.PackageManager(depcache)

Return a new PackageManager object. The parameter depcache specifies a DepCache object.

PackageManager objects provide several methods and attributes, which will be listed here:

get_archives(fetcher, list, records)

Add all the selected packages to the Acquire() object fetcher.

The parameter list refers to a SourceList() object.

The parameter records refers to a PackageRecords() object.

do_install()
Install the packages.
fix_missing()
Fix the installation if a package could not be downloaded.
RESULT_COMPLETED

A constant for checking whether the the result is ‘completed’.

Compare it against the return value of PackageManager.get_archives() or PackageManager.do_install().

RESULT_FAILED

A constant for checking whether the the result is ‘failed’.

Compare it against the return value of PackageManager.get_archives() or PackageManager.do_install().

RESULT_INCOMPLETE

A constant for checking whether the the result is ‘incomplete’.

Compare it against the return value of PackageManager.get_archives() or PackageManager.do_install().

Improve performance with ActionGroup

class apt_pkg.ActionGroup(depcache)

Create a new ActionGroup() object for the DepCache object given by the parameter depcache.

ActionGroup() objects make operations on the cache faster by delaying certain cleanup operations until the action group is released.

ActionGroup is also a context manager and therefore supports the with statement. But because it becomes active as soon as it is created, you should not create an ActionGroup() object before entering the with statement.

If you want to use ActionGroup as a with statement (which is recommended because it makes it easier to see when an actiongroup is active), always use the following form:

with apt_pkg.ActionGroup(depcache):
    ...

For code which has to run on Python versions prior to 2.5, you can also use the traditional way:

actiongroup = apt_pkg.ActionGroup(depcache)
...
actiongroup.release()

ActionGroup provides the following method:

release()
Release the ActionGroup. This will reactive the collection of package garbage.

Resolving Dependencies

class apt_pkg.ProblemResolver(depcache)

Return a new ProblemResolver object. The parameter depcache specifies a pDepCache object.

The problem resolver helps when there are problems in the package selection. An example is a package which conflicts with another, already installed package.

protect(pkg)

Protect the Package() object given by the parameter pkg.

Todo

Really document it.

install_protect()
Protect all installed packages from being removed.
remove(pkg)

Remove the Package() object given by the parameter pkg.

Todo

Really document it.

clear(pkg)

Reset the Package() pkg to the default state.

Todo

Really document it.

resolve()
Try to resolve problems by installing and removing packages.
resolve_by_keep()
Try to resolve problems only by using keep.

Package

class apt_pkg.Package

The pkgCache::Package objects are an interface to package specific features.

Attributes:

current_ver
The version currently installed, or None. This returns a Version object.
id
The ID of the package. This can be used to store information about the package. The ID is an int value.
name
This is the name of the package.
provides_list

A list of packages providing this package. More detailed, this is a list of tuples (str:pkgname, ????, Version).

If you want to check for check for virtual packages, the expression pkg.provides_list and not pkg._version_list helps you. It detects if the package is provided by something else and is not available as a real package.

rev_depends_list
An iterator of Dependency objects for dependencies on this package.
section
The section of the package, as specified in the record. The list of possible sections is defined in the Policy.
version_list
A list of Version objects for all versions available in the cache.

States:

selected_state

The state we want it to be, ie. if you mark a package for installation, this is apt_pkg.SELSTATE_INSTALL.

See Select states for a list of available states.

inst_state

The state the currently installed version is in. This is normally apt_pkg.INSTSTATE_OK, unless the installation failed.

See Installed states for a list of available states.

current_state
The current state of the package (not installed, unpacked, installed, etc). See Package States for a list of available states.

Flags:

auto
Whether the package was installed automatically as a dependency of another package. (or marked otherwise as automatically installed)
essential
Whether the package is essential.
important
Whether the package is important.

Example:

#!/usr/bin/python
"""Example for packages. Print all essential and important packages"""

import apt_pkg


def main():
    """Main."""
    apt_pkg.init_config()
    apt_pkg.init_system()
    cache = apt_pkg.Cache()
    print "Essential packages:"
    for pkg in cache.packages:
        if pkg.essential:
            print " ", pkg.name
    print "Important packages:"
    for pkg in cache.packages:
        if pkg.important:
            print " ", pkg.name

if __name__ == "__main__":
    main()

Version

class apt_pkg.Version

The version object contains all information related to a specific package version.

ver_str
The version, as a string.
section
The usual sections (eg. admin, net, etc.). Prefixed with the component name for packages not in main (eg. non-free/admin).
arch
The architecture of the package, eg. amd64 or all.
file_list
A list of (PackageFile, int: index) tuples for all Package files containing this version of the package.
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', '>='),
                ]
            ]
}
depends_list
This is basically the same as Version.DependsListStr, but instead of the (‘pkgname’, ‘version’, ‘relation’) tuples, it returns Dependency objects, which can assist you with useful functions.
parent_pkg
The Package object this version belongs to.
provides_list
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.
size
The size of the .deb file, in bytes.
installed_size
The size of the package (in kilobytes), when unpacked on the disk.
hash
An integer hash value.
id
An integer id.
priority

The integer representation of the priority. This can be used to speed up comparisons a lot, compared to Version.priority_str.

The values are defined in the apt_pkg extension, see Priorities for more information.

priority_str
Return the priority of the package version, as a string, eg. “optional”.
downloadable
Whether this package can be downloaded from a remote site.
translated_description
Return a Description object.

Dependency

class apt_pkg.Dependency

Represent a dependency from one package to another one.

all_targets()

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.

smart_target_pkg()
Return a Version object of a package which satisfies the dependency and does not conflict with installed packages (the ‘natural target’).
target_ver
The target version of the dependency, as string. Empty string if the dependency is not versioned.
target_pkg
The Package object of the target package.
parent_ver
The Version object of the parent version, ie. the package which declares the dependency.
parent_pkg
The Package object of the package which declares the dependency. This is the same as using ParentVer.ParentPkg.
comp_type
The type of comparison (>=, ==, >>, <=), as string.
dep_type
The type of the dependency, as string, eg. “Depends”.
dep_type_enum
The type of the dependency, as an integer which can be compared to one of the TYPE_* constants below.
dep_type_untranslated
The type of the depndency, as an untranslated string.
id
The ID of the package, as integer.
TYPE_CONFLICTS
Constant for checking against dep_type_enum
TYPE_DEPENDS
Constant for checking against dep_type_enum
TYPE_DPKG_BREAKS
Constant for checking against dep_type_enum
TYPE_ENHANCES
Constant for checking against dep_type_enum
TYPE_OBSOLETES
Constant for checking against dep_type_enum
TYPE_PREDEPENDS
Constant for checking against dep_type_enum
TYPE_RECOMMENDS
Constant for checking against dep_type_enum
TYPE_REPLACES
Constant for checking against dep_type_enum
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:

#!/usr/bin/python
"""Check the archive for missing dependencies"""
import apt_pkg


def fmt_dep(dep):
    """Format a Dependency object [of apt_pkg] as a string."""
    ret = dep.target_pkg.name
    if dep.target_ver:
        ret += " (%s %s)" % (dep.comp_type, dep.target_ver)
    return ret


def check_version(pkgver):
    """Check the version of the package"""
    missing = []

    for or_group in pkgver.depends_list.get("Pre-Depends", []) + \
                    pkgver.depends_list.get("Depends", []):
        if not any(dep.all_targets() for dep in or_group):
            # If none of the or-choices can be satisfied, add it to missing
            missing.append(or_group)

    if missing:
        print "Package:", pkgver.parent_pkg.name
        print "Version:", pkgver.ver_str
        print "Missing:",
        print ", ".join(" | ".join(fmt_dep(dep) for dep in or_group)
                        for or_group in missing)
        print


def main():
    """The main function."""
    apt_pkg.init_config()
    apt_pkg.init_system()

    cache = apt_pkg.Cache()

    for pkg in sorted(cache.packages, key=lambda pkg: pkg.name):
        # pkg is from a list of packages, sorted by name.
        for version in pkg.version_list:
            # Check every version
            for pfile, _ in version.file_list:
                if (pfile.origin == "Debian" and pfile.component == "main" and
                    pfile.archive == "unstable"):
                    # We only want packages from Debian unstable main.
                    check_version(version)
                    break

if __name__ == "__main__":
    main()

Description

class apt_pkg.Description

Represent the description of the package.

language_code
The language code of the description
md5
The md5 hashsum of the description
file_list
A list of tuples (PackageFile, int: index).

Index Files

Todo

Complete them

class apt_pkg.MetaIndex
uri
dist
is_trusted
index_files
class apt_pkg.IndexFile
archive_uri(path)
Return the full url to path in the archive.
label
Return the Label.
describe
A description of the IndexFile.
exists
Return whether the file exists.
has_packages
Return whether the file has packages.
size
Size of the file
is_trusted
Whether we can trust the file.
class apt_pkg.PackageFile

A PackageFile represents a Packages file, eg. /var/lib/dpkg/status.

architecture
The architecture of the package file.
archive
The archive (eg. unstable)
component
The component (eg. main)
filename
The name of the file.
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].
index_type
The sort of the index file. In normal cases, this is ‘Debian Package Index’.
label
The Label, as set in the Release file
not_automatic
Whether packages from this list will be updated automatically. The default for eg. example is 0 (aka false).
not_source

Whether the file has no source from which it can be updated. In such a case, the value is 1; else 0. /var/lib/dpkg/status is 0 for example.

Example:

for pkgfile in cache.file_list:
    if pkgfile.not_source:
        print 'The file %s has no source.' % pkgfile.filename
origin
The Origin, as set in the Release file
site
The hostname of the site.
size
The size of the file.
version
The version, as set in the release file (eg. “4.0” for “Etch”)

The following example shows how to use PackageFile:

#!/usr/bin/python
import apt_pkg


def main():
    """Example for PackageFile()"""
    apt_pkg.init()
    cache = apt_pkg.Cache()
    for pkgfile in cache.file_list:
        print 'Package-File:', pkgfile.filename
        print 'Index-Type:', pkgfile.index_type # 'Debian Package Index'
        if pkgfile.not_source:
            print 'Source: None'
        else:
            if pkgfile.site:
                # There is a source, and a site, print the site
                print 'Source:', pkgfile.site
            else:
                # It seems to be a local repository
                print 'Source: Local package file'
        if pkgfile.not_automatic:
            # The system won't be updated automatically (eg. experimental)
            print 'Automatic: No'
        else:
            print 'Automatic: Yes'
        print

if __name__ == '__main__':
    main()

Records

class apt_pkg.PackageRecords(cache)

Create a new PackageRecords object, for the packages in the cache specified by the parameter cache.

Provide access to the packages records. This provides very useful attributes for fast (convient) access to some fields of the record.

lookup(verfile_iter)

Change the actual package to the package given by the verfile_iter.

The parameter verfile_iter refers to a tuple consisting of (PackageFile(), int: index), as returned by various attributes, including Version.file_list.

Example (shortened):

cand = depcache.GetCandidateVer(cache['python-apt'])
records.Lookup(cand.FileList[0])
# Now you can access the record
print records.SourcePkg # == python-apt
filename
Return the field ‘Filename’ of the record. This is the path to the package, relative to the base path of the archive.
md5_hash
Return the MD5 hashsum of the package This refers to the field ‘MD5Sum’ in the raw record.
sha1_hash
Return the SHA1 hashsum of the package. This refers to the field ‘SHA1’ in the raw record.
sha256_hash

Return the SHA256 hashsum of the package. This refers to the field ‘SHA256’ in the raw record.

New in version 0.7.9.

source_pkg
Return the source package.
source_ver
Return the source version.
maintainer
Return the maintainer of the package.
short_desc
Return the short description. This is the summary on the first line of the ‘Description’ field.
long_desc
Return the long description. These are lines 2-END from the ‘Description’ field.
name
Return the name of the package. This is the ‘Package’ field.
homepage
Return the Homepage. This is the ‘Homepage’ field.
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 apt_pkg.TagSection to parse the record and access the field name.

Example:

section = apt_pkg.TagSection(records.record)
print section['SHA256'] # Use records.sha256_hash instead
class apt_pkg.SourceRecords

This represents the entries in the Sources files, ie. the dsc files of the source packages.

Note

If the Lookup failed, because no package could be found, no error is raised. Instead, the attributes listed below are simply not existing anymore (same applies when no Lookup has been made, or when it has been restarted).

lookup(pkgname)

Lookup the record for the package named pkgname. To access all available records, you need to call it multiple times.

Imagine a package P with two versions X, Y. The first lookup(P) would set the record to version X and the second lookup(P) to version Y.

restart()

Restart the lookup.

Imagine a package P with two versions X, Y. The first Lookup(P) would set the record to version X and the second Lookup(P) to version Y.

If you now call restart(), the internal position will be cleared. Now you can call lookup(P) again to move to X.

package
The name of the source package.
version
A string describing the version of the source package.
maintainer
A string describing the name of the maintainer.
section
A string describing the section.
record

The whole record, as a string. You can use apt_pkg.ParseSection() if you need to parse it.

You need to parse the record if you want to access fields not available via the attributes, eg. ‘Standards-Version’

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.
index
The index in the Sources files.
files
The list of files. This returns a list of tuples with the contents (str: md5, int: size, str: path, str:type).
build_depends
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

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.

class apt_pkg.Acquire([progress])

Return an Acquire object. The parameter progress refers to an apt.progress.FetchProgress() object.

Acquire objects maintaing a list of items which will be fetched or have been fetched already during the lifetime of this object. To add new items to this list, you can create new AcquireFile objects which allow you to add single files.

Acquire items have multiple methods and attributes:

run()
Fetch all the items which have been added by AcquireFile.
shutdown()
Shut the fetcher down.
total_needed
The total amount of bytes needed (including those of files which are already present)
fetch_needed
The total amount of bytes which need to be fetched.
partial_present
Whether some files have been acquired already. (???)
items
A list of AcquireItem objects which are attached to the queue of this object.
workers
A list of AcquireWorker objects which are currently active on this instance.
class apt_pkg.AcquireItem

The AcquireItem() objects represent the items of a Acquire object. AcquireItem() objects can not be created by the user, they are solely available through the Acquire.items list of an Acquire object.

id
The ID of the item.
complete
Is the item completely acquired?
local
Is the item a local file?
mode
A string indicating the current mode e.g. "Fetching".
is_trusted
Can the file be trusted?
filesize
The size of the file, in bytes.
error_text
The error message. For example, when a file does not exist on a http server, this will contain a 404 error message.
destfile
The location the file is saved as.
desc_uri
The source location.

Status:

status
Integer, representing the status of the item.
STAT_IDLE
Constant for comparing AcquireItem.status.
STAT_FETCHING
Constant for comparing AcquireItem.status
STAT_DONE
Constant for comparing AcquireItem.status
STAT_ERROR
Constant for comparing AcquireItem.status
STAT_AUTH_ERROR
Constant for comparing AcquireItem.status
class apt_pkg.AcquireFile(owner, uri[, md5, size, descr, short_descr, destdir, destfile])

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 descripition of the download. It may be used to describe the item in the progress class. short_descr is the short form of it.

You can use destdir to manipulate the directory where the file will be saved in. Instead of destdir, you can also specify the full path to the file using the parameter destfile. You can not combine both.

In terms of attributes, this class is a subclass of AcquireItem and thus inherits all its attributes.

class apt_pkg.AcquireWorker

An AcquireWorker object represents a subprocess responsible for fetching files from remote locations. This class is not instanciable from Python.

current_item
The item which is currently being fetched. This returns an AcquireItemDesc object.
current_size
How many bytes of the file have been downloaded. Zero if the current progress of the file cannot be determined.
resumepoint
The amount of the file that was already downloaded prior to starting this worker.
status
The most recent status string received from the subprocess.
total_size
The total number of bytes to be downloaded. Zero if the total size is unknown.
class apt_pkg.AcquireItemDesc

An AcquireItemDesc object stores information about the item which can be used to describe the item.

description
The long description given to the item.
owner
The AcquireItem object owning this object.
shortdesc
A short description which has been given to this item.
uri
The URI from which to download this item.
class apt_pkg.AcquireProgress

A monitor object for downloads controlled by the Acquire class. This is an mostly abstract class. You should subclass it and implement the methods to get something useful.

Methods defined here:

done(item: AcquireItemDesc)
Invoked when an item is successfully and completely fetched.
fail(item: AcquireItemDesc)
Invoked when the process of fetching an item encounters a fatal error.
fetch(item: AcquireItemDesc)
Invoked when some of an item’s data is fetched.
ims_hit(item: AcquireItemDesc)
Invoked when an item is confirmed to be up-to-date. For instance, when an HTTP download is informed that the file on the server was not modified.
media_change(media: str, drive: str) → bool

Invoked when the user should be prompted to change the inserted removable media.

This method should not return until the user has confirmed to the user interface that the media change is complete.

The parameter media is the name of the media type that should be changed, the parameter drive is the identifying name of the drive whose media should be changed.

Return True if the user confirms the media change, False if it is cancelled.

pulse(owner: Acquire) → bool

Periodically invoked while the Acquire process is underway.

Return False if the user asked to cancel the whole Acquire process.

start()
Invoked when the Acquire process starts running.
stop()
Invoked when the Acquire process stops running.

There are also some data descriptors:

current_bytes
The number of bytes fetched.
current_cps
The current rate of download, in bytes per second.
current_items
The number of items that have been successfully downloaded.
elapsed_time
The amount of time that has elapsed since the download started.
fetched_bytes
The total number of bytes accounted for by items that were successfully fetched.
last_bytes
The number of bytes fetched as of the previous call to pulse(), including local items.
total_bytes
The total number of bytes that need to be fetched. This member is inaccurate, as new items might be enqueued while the download is in progress!
total_items
The total number of items that need to be fetched. This member is inaccurate, as new items might be enqueued while the download is in progress!

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 hashlib module.

The module provides the two classes Hashes and HashString for generic hash support:

class apt_pkg.Hashes(object)

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:

md5
The MD5 hash of the data, as string.
sha1
The SHA1 hash of the data, as string.
sha256
The SHA256 hash of the data, as string.
class apt_pkg.HashString(type: str, hash: str)

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.

str(hashstring)
Convert the HashString to a string by joining the hash type and the hash using ‘:’, e.g. "MD5Sum:d41d8cd98f00b204e9800998ecf8427e".
hashtype
The type of the hash. This may be MD5Sum, SHA1 or SHA256.
verify_file(filename: str) → bool
Verify that the file given by the parameter filename matches the hash stored in this object.

The apt_pkg module also provides the functions md5sum(), sha1sum() and sha256sum() for creating a single hash from a bytes or file object:

apt_pkg.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 file() object (or a file descriptor), in which case the md5sum of its contents is returned.

Changed in version 0.8.0: Added support for using file descriptors.

apt_pkg.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 file() object (or a file descriptor), in which case the sha1sum of its contents is returned.

Changed in version 0.8.0: Added support for using file descriptors.

apt_pkg.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 file() object (or a file descriptor), in which case the sha256sum of its contents is returned.

Changed in version 0.8.0: Added support for using file descriptors.

Debian control files

Debian control files are files containing multiple stanzas of RFC 822-style header sections. They are widely used in the Debian community, and can represent many kinds of information. One example for such a file is the /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.

class apt_pkg.TagFile(file)

An object which represents a typical debian control file. Can be used for Packages, Sources, control, Release, etc. Such an object 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:

tagf = apt_pkg.TagFile(open('/var/lib/dpkg/status'))
for section in tagfile:
    print section['Package']
next()

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:

tagf = apt_pkg.TagFile(open('/var/lib/dpkg/status'))
tagf.step()
print tagf.section['Package']
step()
Step forward to the next section. This simply returns 1 if OK, and 0 if there is no section.
offset()
Return the current offset (in bytes) from the beginning of the file.
jump(offset)
Jump back/forward to offset. Use jump(0) to jump to the beginning of the file again.
section
This is the current TagSection() instance.
class apt_pkg.TagSection(text)

Represent a single section of a debian control file.

section[key]
Return the value of the field at key. If key is not available, raise KeyError.
key in section
Return True if section has a key key, else False.

New in version 0.8.0.

bytes()
The number of bytes in the section.
find(key, default='')
Return the value of the field at the key key if available, else return default.
find_flag(key)
Find a yes/no value for the key key. An example for such a field is ‘Essential’.
get(key, default='')
Return the value of the field at the key key if available, else return default.
keys()
Return a list of keys in the section.
apt_pkg.rewrite_section(section: TagSection, order: list, rewrite_list: list) → str

Rewrite the section given by section using rewrite_list, and order the fields according to order.

The parameter order is a list object containing the names of the fields in the order they should appear in the rewritten section. apt_pkg.REWRITE_PACKAGE_ORDER and apt_pkg.REWRITE_SOURCE_ORDER are two predefined lists for rewriting package and source sections, respectively.

The parameter rewrite_list is a list of tuples of the form (tag, newvalue[, renamed_to]), whereas 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.

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

apt_pkg.check_dep(pkgver, op, depver)

Check that the dependency requirements consisting of op and depver can be satisfied by the version pkgver.

Example:

>>> bool(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.

apt_pkg.parse_depends(depends)

Parse the string depends which contains dependency information as specified in Debian Policy, Section 7.1.

Returns a list. The members of this list are lists themselves and contain one or more tuples in the format (package,version,operation) for every ‘or’-option given, e.g.:

>>> apt_pkg.parse_depends("PkgA (>= VerA) | PkgB (>= VerB)")
[[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]]

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.

apt_pkg.parse_src_depends(depends)

Parse the string depends which contains dependency information as specified in Debian Policy, Section 7.1.

Returns a list. The members of this list are lists themselves and contain one or more tuples in the format (package,version,operation) for every ‘or’-option given, e.g.:

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

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.

Configuration

class apt_pkg.Configuration

Configuration() objects store the configuration of apt, mostly created from the contents of /etc/apt.conf and the files in /etc/apt.conf.d.

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.
conf[key] = value
Set the option at key to value.
find(key[, default=''])

Return the value for the given key key. This is the same as Configuration.get().

If key does not exist, return default.

find_file(key[, default=''])

Return the filename hold by the configuration at key. This formats the filename correctly and supports the Dir:: stuff in the configuration.

If key does not exist, return default.

find_dir(key[, default='/'])

Return the absolute path to the directory specified in key. A trailing slash is appended.

If key does not exist, return default.

find_i(key[, default=0])

Return the integer value stored at key.

If key does not exist, return default.

find_b(key[, default=0])

Return the boolean value stored at key. This returns an integer, but it should be treated like True/False.

If key does not exist, return default.

set(key, value)
Set the value of key to value.
exists(key)
Check whether the key key exists in the configuration.
subtree(key)
Return a sub tree starting at key. The resulting object can be used like this one.
list([key])

List all items at key. Normally, return the keys at the top level, eg. APT, Dir, etc.

Use key to specify a key of which the childs will be returned.

value_list([key])
Same as Configuration.list(), but this time for the values.
my_tag()
Return the tag name of the current tree. Normally this is an empty string, but for subtrees it is the key of the subtree.
clear(key)
Clear the configuration. Remove all values and keys at key.
keys([key])
Return all the keys, recursive. If key is specified, ... (FIXME)
get(key[, default=''])
This behaves just like dict.get() and Configuration.find(), it returns the value of key or if it does not exist, default.
apt_pkg.config
A Configuration() object with the default configuration. This object is initialized by calling init_config().
apt_pkg.read_config_file(configuration, filename)
Read the configuration file specified by the parameter filename and add the settings therein to the Configuration() object specified by the parameter configuration
apt_pkg.read_config_dir(configuration, dirname)
Read configuration files in the directory specified by the parameter dirname and add the settings therein to the Configuration() object specified by the parameter configuration.
apt_pkg.read_config_file_isc(configuration, filename)
Read the configuration file specified by the parameter filename and add the settings therein to the Configuration() object specified by the parameter configuration
apt_pkg.parse_commandline(configuration, options, argv)

This function is like getopt except it manipulates a configuration space. output is a list of non-option arguments (filenames, etc). options is a list of tuples of the form ('c',"long-opt or None", "Configuration::Variable","optional type").

Where type may be one of HasArg, IntLevel, Boolean, InvBoolean, ConfigFile, or ArbItem. The default is Boolean.

Locking

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 apt_pkg.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, e.g.:

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 apt_pkg.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, e.g.:

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:

apt_pkg.get_lock(filename, 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 os.close() on the return value which is the file descriptor of the created file.

apt_pkg.pkgsystem_lock()
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.
apt_pkg.pkgsystem_unlock()
Unlock the global pkgsystem. This reverts the effect of pkgsystem_unlock().

Other classes

class apt_pkg.Cdrom

Return a Cdrom object with the following methods:

ident(progress)
Identify the cdrom. The parameter progress refers to an apt.progress.CdromProgress() object.
add(progress)
Add the cdrom to the sources.list file. The parameter progress refers to an apt.progress.CdromProgress() object.
class apt_pkg.SourceList

This is for /etc/apt/sources.list.

find_index(pkgfile)
Return a IndexFile object for the PackageFile pkgfile.
read_main_list()
Read the main list.
get_indexes(acq[, all])
Add the index files to the Acquire() object acq. If all is given and True, all files are fetched.
list
A list of MetaIndex objects.

String functions

apt_pkg.base64_encode(string)

Encode the given string using base64, e.g:

>>> apt_pkg.base64_encode(u"A")
'QQ=='
apt_pkg.check_domain_list(host, list)

See if Host is in a ‘,’ separated list, e.g.:

apt_pkg.check_domain_list("alioth.debian.org","debian.net,debian.org")
apt_pkg.dequote_string(string)

Dequote the string specified by the parameter string, e.g.:

>>> apt_pkg.dequote_string("%61%70%74%20is%20cool")
'apt is cool'
apt_pkg.quote_string(string, repl)

For every character listed in the string repl, replace all occurences in the string string with the correct HTTP encoded value:

>>> apt_pkg.quote_string("apt is cool","apt")
'%61%70%74%20is%20cool'
apt_pkg.size_to_str(size)

Return a string presenting the human-readable version of the integer size. When calculating the units (k,M,G,etc.) the size is divided by the factor 1000.

Example:

>>> apt_pkg.size_to_str(10000)
'10.0k'
apt_pkg.string_to_bool(input)

Parse the string input and return one of -1, 0, 1.

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
apt_pkg.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 TimeRFC1123().

Example:

>> apt_pkg.str_to_time('Thu, 01 Jan 1970 00:00:00 GMT')
0
apt_pkg.time_rfc1123(seconds)

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'
apt_pkg.time_to_str(seconds)

Format a given duration in a human-readable manner. The parameter seconds refers to a number of seconds, given as an integer. The return value is a string with a unit like ‘s’ for seconds.

Example:

>>> apt_pkg.time_to_str(3601)
'1h0min1s'
apt_pkg.upstream_version(version)
Return the string version, eliminating everything following the last ‘-‘. Thus, this should be equivalent to version.rsplit('-', 1)[0].
apt_pkg.uri_to_filename(uri)

Take a string uri as parameter and return a filename which can be used to store the file, based on the URI.

Example:

>>> apt_pkg.uri_to_filename('http://debian.org/index.html')
'debian.org_index.html'
apt_pkg.version_compare(a, b)

Compare two versions, a and b, and return an integer value which has the same characteristic as the built-in cmp() function.

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

Package States

apt_pkg.CURSTATE_CONFIG_FILES
apt_pkg.CURSTATE_HALF_CONFIGURED
apt_pkg.CURSTATE_HALF_INSTALLED
apt_pkg.CURSTATE_INSTALLED
apt_pkg.CURSTATE_NOT_INSTALLED
apt_pkg.CURSTATE_UNPACKED

Installed states

apt_pkg.INSTSTATE_HOLD
apt_pkg.INSTSTATE_HOLD_REINSTREQ
apt_pkg.INSTSTATE_OK
apt_pkg.INSTSTATE_REINSTREQ

Priorities

apt_pkg.PRI_EXTRA
apt_pkg.PRI_IMPORTANT
apt_pkg.PRI_OPTIONAL
apt_pkg.PRI_REQUIRED
apt_pkg.PRI_STANDARD

Select states

apt_pkg.SELSTATE_DEINSTALL
apt_pkg.SELSTATE_HOLD
apt_pkg.SELSTATE_INSTALL
apt_pkg.SELSTATE_PURGE
apt_pkg.SELSTATE_UNKNOWN

Build information

apt_pkg.DATE
The date on which this extension has been compiled.
apt_pkg.LIB_VERSION
The version of the apt_pkg library. This is not the version of apt, nor the version of python-apt.
apt_pkg.TIME
The time this extension has been built.
apt_pkg.VERSION
The version of apt (not of python-apt).