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.
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.
Return a Cache() object. The optional parameter progress specifies an instance of apt.progress.OpProgress() which will display the open progress.
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.
Todo
Seems to be some mixture of versions and pkgFile.
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.
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.
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.
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.
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 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.
Return 1 if the package is upgradable.
The package can be upgraded by calling pkgDepCache.MarkInstall().
Return a new PackageManager object. The parameter depcache specifies a DepCache object.
PackageManager objects provide several methods and attributes, which will be listed here:
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.
A constant for checking whether the the result is ‘completed’.
Compare it against the return value of PackageManager.get_archives() or PackageManager.do_install().
A constant for checking whether the the result is ‘failed’.
Compare it against the return value of PackageManager.get_archives() or PackageManager.do_install().
A constant for checking whether the the result is ‘incomplete’.
Compare it against the return value of PackageManager.get_archives() or PackageManager.do_install().
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:
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.
The pkgCache::Package objects are an interface to package specific features.
Attributes:
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.
States:
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.
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.
Flags:
#!/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()
The version object contains all information related to a specific package version.
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 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.
Represent a dependency from one package to another one.
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"""
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()
Represent the description of the package.
Todo
Complete them
A PackageFile represents a Packages file, eg. /var/lib/dpkg/status.
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
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()
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.
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
Return the SHA256 hashsum of the package. This refers to the field ‘SHA256’ in the raw record.
New in version 0.7.9.
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
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 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 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.
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’
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.
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:
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.
Status:
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.
An AcquireWorker object represents a subprocess responsible for fetching files from remote locations. This class is not instanciable from Python.
An AcquireItemDesc object stores information about the item which can be used to describe the item.
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:
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.
Periodically invoked while the Acquire process is underway.
Return False if the user asked to cancel the whole Acquire process.
There are also some data descriptors:
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:
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.
The apt_pkg module also provides the functions md5sum(), sha1sum() and sha256sum() for creating a single hash from a bytes or file 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.
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.
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 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.
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']
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']
Represent a single section of a debian control file.
Return True if section has a key key, else False.
New in version 0.8.0.
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.
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.
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.
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() objects store the configuration of apt, mostly created from the contents of /etc/apt.conf and the files in /etc/apt.conf.d.
Return the value for the given key key. This is the same as Configuration.get().
If key does not exist, return 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.
Return the absolute path to the directory specified in key. A trailing slash is appended.
If key does not exist, return default.
Return the integer value stored at key.
If key does not exist, return default.
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.
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.
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.
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.
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:
...
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:
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.
Return a Cdrom object with the following methods:
Encode the given string using base64, e.g:
>>> apt_pkg.base64_encode(u"A")
'QQ=='
See if Host is in a ‘,’ separated list, e.g.:
apt_pkg.check_domain_list("alioth.debian.org","debian.net,debian.org")
Dequote the string specified by the parameter string, e.g.:
>>> apt_pkg.dequote_string("%61%70%74%20is%20cool")
'apt is cool'
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'
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'
Parse the string input and return one of -1, 0, 1.
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
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
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'
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'
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'