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.
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.
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
#!/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()
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.
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’
Return the list of Build dependencies, as (str: package, str: version, int: op, int: type).
| Value | Meaning |
|---|---|
| 0x0 | No Operation (no versioned build dependency) |
| 0x10 | (or) - this will be added to the other values
|
| 0x1 | <= (less than or equal) |
| 0x2 | >= (greater than or equal) |
| 0x3 | << (less than) |
| 0x4 | >> (greater than) |
| 0x5 | == (equal) |
| 0x6 | != (not equal) |
| Value | Meaning |
|---|---|
| 0 | Build-Depends |
| 1 | Build-Depends-Indep |
| 2 | Build-Conflicts |
| 3 | Build-Conflicts-Indep |
Example: In the following content, we will imagine a build-dependency:
Build-Depends: A (>= 1) | B (>= 1), C
This results in:
[('A', '1', 18, 0), # 18 = 16 + 2 = 0x10 + 0x2
('B', '1', 2, 0),
('C', '', 0, 0)]
This is not the same as returned by apt_pkg.ParseSrcDepends().
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:
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. AcquireFile objects provide no methods or attributes and are completely useless at the moment.
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.
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.
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.
An example for working with a TagFile could look like:
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.
Check whether the field with named by key exists.
Deprecated since version 0.8.0.
RewriteSection(Section,Order,RewriteList) -> String
The section rewriter allows a section to be taken in, have fields added, removed or changed and then put back out. During this process the fields within the section are sorted to corrispond to a proper order. Order is a list of field names with their proper capitialization. apt_pkg.RewritePackageOrder and apt_pkg.RewriteSourceOrder are two predefined orders. RewriteList is a list of tuples. Each tuple is of the form:
(Tag,NewValue[,RenamedTo])
Tag specifies the tag in the source section. NewValue is the new value of that tag and the optional RenamedTo field can cause the tag to be changed. If NewValue is None then the tag is removed Ex. (‘Source’,’apt’,’Package’) is used for .dsc files.
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
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', '>=')]]
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', '>=')]]
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 True if conf has a key key, else False.
New in version 0.8.0.
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.
Return whether the configuration contains the key key.
Deprecated since version 0.8.0.
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.
Create an empty file at the path specified by the parameter filename and lock it.
While the file is locked by a process, calling this function in another process returns -1.
When the lock is not required anymore, the file descriptor should be closed using os.close().
Return a Cdrom object with the following methods:
This is for /etc/apt/sources.list.
Encode the given string using base64, e.g:
>>> apt_pkg.base64_encode(u"A")
'QQ=='
See if Host is in a ‘,’ seperated 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'