# `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()`.

## Exceptions

class apt_pkg.Error

  Exception class for most python-apt exceptions.

  This class replaces the use of `SystemError` in previous versions of python-apt. It inherits from `SystemError`, so make sure to catch this class first.

  Added in version 1.1.

class apt_pkg.CacheMismatchError

  Raised when passing an object from a different cache to `apt_pkg.DepCache` methods

  Added in version 1.6.1.

## Working with the cache

class apt_pkg.Cache([progress: apt.progress.base.OpProgress])

  A Cache object represents the cache used by APT which contains information about packages. The object itself provides no means to modify the cache or the installed packages, see the classes `DepCache` and `PackageManager` for such functionality.

  The constructor takes an optional argument which must be a subclass of `apt.progress.base.OpProgress`. This object will then be used to display information during the cache opening process (or possible creation of the cache). It may also be `None`, in which case no progress will be emitted. If not given, progress will be printed to standard output.

  Note

  The cache supports colon-separated name:architecture pairs. For normal architectures, they are equal to a (name, architecture) tuple. For the “any” architecture behavior is different, as “name:any” is equivalent to (“name:any”, “any”). This is done so that “name:any” matches all packages with that name which have Multi-Arch: allowed set.

  cache[pkgname]

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

  cache[name, architecture]

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

  pkgname in cache

    Check whether a package with the name given by pkgname exists in the cache for the native architecture. If pkgname includes a colon, the part after the colon is used as the architecture.

  (name, architecture) in cache

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

  update(progress, sources[, pulse_interval]) → bool

    Update the index files used by the cache. A call to this method does not affect the current Cache object, instead a new one should be created in order to use the changed index files.

    The parameter progress takes an `apt.progress.base.AcquireProgress` object which will display the progress of fetching the index files. The parameter sources takes a `SourceList` object which lists the sources. The parameter progress takes an integer describing the interval (in microseconds) in which the pulse() method of the progress object will be called.

  depends_count

    The total number of dependencies stored in the cache.

  file_list

    A list of all `PackageFile` objects stored in the cache.

  group_count

    The number of groups in the cache.

  groups

    A sequence of `Group` objects, implemented as a `GroupList` object.

    class GroupList

      A simple sequence-like object which only provides a length and an implementation of `__getitem__` for accessing groups at a certain index. Apart from being iterable, it can be used in the following ways:

      list[index]

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

      len(list)

        Return the length of the GroupList object list.

  is_multi_arch

    An attribute determining whether the cache supports multi-arch.

  package_count

    The total number of packages available in the cache. This value is equal to the length of the list provided by the `packages` attribute.

  package_file_count

    The total number of Packages files available (the Packages files listing the packages). This is the same as the length of the list in the attribute `file_list`.

  packages

    A sequence of `Package` objects, implemented as a `PackageList` object.

    class PackageList

      A simple sequence-like object which only provides a length and an implementation of `__getitem__` for accessing packages at a certain index. Apart from being iterable, it can be used in the following ways:

      list[index]

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

      len(list)

        Return the length of the PackageList object list.

  provides_count

    The number of provided packages.

  ver_file_count

    The total number of `(Version, PackageFile)` relations stored in the cache.

  version_count

    The total number of package versions available in the cache.

### Managing the cache with `DepCache`

class apt_pkg.DepCache(cache: apt_pkg.Cache)

  A DepCache object provides access to more information about the objects made available by the `Cache` object as well as means to mark packages for removal and installation, among other actions.

  The constructor takes a single argument which specifies the `Cache` object the new object shall be related to. While it is theoretically possible to create multiple DepCache objects for the same cache, they will not be independent from each other since they all access the same underlying C++ object.

  Objects of this type provide several methods. Most of those methods are safe to use and should never raise any exception (all those methods for requesting state information or marking changes). If a method is expected to raise an exception, it will be stated in the description.

  If an object of a different cache is passed, `CacheMismatchError` is raised.

  commit(acquire_progress, install_progress)

    Commit all marked changes, while reporting the progress of fetching packages via the `apt.progress.base.AcquireProgress` object given by acquire_progress and reporting the installation of the package using the `apt.progress.base.InstallProgress` object given by install_progress.

    If this fails, an exception of the type `SystemError` will be raised.

  fix_broken() → bool

    Try to fix all broken packages in the cache and return `True` in case of success. If an error occurred, a `SystemError` exception is raised.

  get_candidate_ver(pkg: Package) → Version

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

  init(progress: apt.progress.base.OpProgress)

    Initialize the DepCache. This is done automatically when the cache is opened, but sometimes it may be useful to reinitialize the DepCache. Like the constructor of `Cache`, this function takes a single `apt.progress.base.OpProgress` object to display progress information.

  read_pinfile(file: str)

    A proxy function which calls the method `Policy.read_pinfile()` of the `Policy` object used by this object. This method raises a `SystemError` exception if the file could not be parsed.

  set_candidate_ver(pkg: Package, version: Version) → bool

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

  upgrade([dist_upgrade=False]) → bool

    Mark the packages for upgrade under the same conditions apt-get does. If dist_upgrade is `True`, also allow packages to be upgraded if they require installation/removal of other packages; just like apt-get dist-upgrade.

    Despite returning a boolean value, this raises `SystemError` and does not return `False` if an error occurred.

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

  mark_auto(pkg: Package)

    Mark the `Package` pkg as automatically installed.

  mark_keep(pkg: Package)

    Mark the `Package` pkg for keep.

  mark_delete(pkg: Package[, purge])

    Mark the `Package` pkg for delete. If purge is True, the configuration files will be removed as well.

  mark_install(pkg: Package[, auto_inst=True[, from_user=True]])

    Mark the `Package` pkg for install, and, if auto_inst is `True`, its dependencies as well. If from_user is `True`, the package will not be marked as automatically installed.

  set_reinstall(pkg: Package)

    Set if the `Package` pkg should be reinstalled.

  The following methods can be used to check the state of a package:

  is_auto_installed(pkg: Package) → bool

    Return `True` if the package is automatically installed, that is, as a dependency of another package.

  is_garbage(pkg: Package) → bool

    Return `True` if the package is garbage, that is, if it was automatically installed and no longer referenced by other packages.

  is_inst_broken(pkg: Package) → bool

    Return `True` if the package is broken on the current install. This takes changes which have not been marked not into account.

  is_now_broken(pkg: Package) → bool

    Return `True` if the package is now broken, that is, if the package is broken if the marked changes are applied.

  is_upgradable(pkg: Package) → bool

    Return `True` if the package is upgradable, the package can then be marked for upgrade by calling the method `mark_install()`.

  marked_delete(pkg: Package) → bool

    Return `True` if the package is marked for delete.

  marked_downgrade(pkg: Package) → bool

    Return `True` if the package should be downgraded.

  marked_install(pkg: Package) → bool

    Return `True` if the package is marked for install.

  marked_keep(pkg: Package) → bool

    Return `True` if the package is marked for keep.

  marked_reinstall(pkg: Package) → bool

    Return `True` if the package should be reinstalled.

  marked_upgrade(pkg: Package) → bool

    Return `True` if the package is marked for upgrade.

  phasing_applied(pkg: Package) → bool

    Return `True` if the package update is being phased.

  DepCache objects also provide several attributes containing information on the marked changes:

  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.

### Installing with `PackageManager`

class apt_pkg.PackageManager(depcache)

  Abstraction of a package manager. This object takes care of retrieving packages, ordering the installation, and calling the package manager to do the actual installation.

  get_archives(fetcher, list, records) → bool

    Add all packages marked for installation (or upgrade, anything which needs a download) to the `Acquire` object referenced by fetcher.

    The parameter list specifies a `SourceList` object which is used to retrieve the information about the archive URI for the packages which will be fetched.

    The parameter records takes a `PackageRecords` object which will be used to look up the file name of the package.

  do_install(status_fd: int) → int

    Install the packages and return one of the class constants `RESULT_COMPLETED`, `RESULT_FAILED`, `RESULT_INCOMPLETE`. The argument status_fd can be used to specify a file descriptor that APT will write status information on (see README.progress-reporting in the apt source code for information on what will be written there).

  fix_missing() → bool

    Fix the installation if a package could not be downloaded.

  RESULT_COMPLETED

    A constant for checking whether the result of the call to `do_install()` is ‘failed’.

  RESULT_FAILED

    A constant for checking whether the result of the call to `do_install()` is ‘failed’.

  RESULT_INCOMPLETE

    A constant for checking whether the result of the call to `do_install()` is ‘incomplete’.

  All instances of this class also support the following methods:

  Note

  This methods are provided mainly for subclassing purposes and should not be used in most programs. This class is a subclass of an internal `_PackageManager` which does not provide that methods. As the public C++ API creates such an object without those methods, you should not rely on those methods to be available unless you used the constructor of `PackageManager` to create the object.

  configure(pkg: Package) → bool

    Notify the package manager that the `Package` given by pkg is to be configured. Must return a `True` value or `None` to continue, or a value which is `False` if evaluated as boolean to abort.

    Added in version 0.8.0.

  install(pkg: Package, filename: str) → bool

    Notify the package manager that the `Package` given by pkg is to be installed from the .deb located at filename. Must return a `True` value or `None` to continue, or a value which is `False` if evaluated as boolean to abort.

    Added in version 0.8.0.

  remove(pkg: Package, purge: bool) → bool

    Notify the package manager that the `Package` given by pkg is to be removed. If purge is `True`, the package shall be purged. Must return a `True` value or `None` to continue, or a value which is `False` if evaluated as boolean to abort.

    Added in version 0.8.0.

  go(status_fd: int) → bool

    Start dpkg, writing status information to the file descriptor given by status_fd. Must return a `True` value or `None` to continue, or a value which is `False` if evaluated as boolean to abort.

    Added in version 0.8.0.

  reset()

    Reset the package manager for a new round.

    Added in version 0.8.0.

### Installation ordering with `OrderList`

class apt_pkg.OrderList(depcache: DepCache)

  Represent a `pkgOrderList`, used for installation ordering. This class provides several methods and attributes, is complicated and should not be used by normal programs.

  Added in version 0.8.0.

  This class is a sequence and supports the following operations:

  list[index]

    Get the package at the given index in the list. Negative index is supported.

  len(list)

    The length of the list.

  It also supports the append() method from `list`:

  append(pkg: Package)

    Append a new package to the end of the list. Please note that you may not append a package twice, as only as much packages as in the cache can be added.

  The class also defines several specific attributes and methods, to be described hereinafter.

  score(pkg: Package)

    Return the score of the package. Packages are basically ordered by descending score.

  This class allows flags to be set on packages. Those flags are:

  FLAG_ADDED
  FLAG_ADD_PENDING
  FLAG_IMMEDIATE
  FLAG_LOOP
  FLAG_UNPACKED
  FLAG_CONFIGURED
  FLAG_REMOVED
  FLAG_STATES_MASK

    Same as `FLAG_UNPACKED | FLAG_CONFIGURED | FLAG_REMOVED`

  FLAG_IN_LIST
  FLAG_AFTER

  The methods to work with those flags are:

  flag(pkg: Package, flag: int[, unset_flags: int])

    Flag a package. Sets the flags given in flag and unsets any flags given in unset_flags.

  is_flag(pkg: Package, flag: int)

    Check whether the flags in flag are set for the package.

  wipe_flags(flags: int)

    Remove the flags in flags from all packages.

  is_missing(pkg: Package)

    Check if the package is missing (not really usable right now)

  is_now(pkg: Package)

    Check if the package is flagged for any state but removal.

  The following methods for ordering are provided:

  order_critical()

    Order the packages for critical unpacking; that is, only respect pre-dependencies.

  order_unpack()

    Order the packages for unpacking, repecting Pre-Depends and Conflicts.

  order_configure()

    Order the packages for configuration, respecting Depends.

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

  An action group is also a context manager and therefore supports the `with` statement. But because it becomes active as soon as it is created, you should not create an ActionGroup() object before entering the with statement. Thus, you should always use the following form:

      with apt_pkg.ActionGroup(depcache):
          ...

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

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

  In addition to the methods required to implement the context manager interface, `ActionGroup` objects provide the following method:

  release()

    Release the ActionGroup. This will reactive the collection of package garbage.

### Resolving Dependencies with `ProblemResolver`

class apt_pkg.ProblemResolver(depcache: DepCache)

  ProblemResolver objects take care of resolving problems with dependencies. They mark packages for installation/removal and try to satisfy all dependencies. The constructor takes a single argument of the type `apt_pkg.DepCache` to determine the cache that shall be manipulated in order to resolve the problems.

  clear(pkg: Package)

    Revert the action of calling `protect()` or `remove()` on a package, resetting it to the default state.

  install_protect()

    Mark all protected packages for installation.

  protect(pkg: Package)

    Mark the package given by pkg as protected; that is, its state will not be changed.

  remove(pkg: Package)

    Mark the package given by pkg for removal in the resolver.

  resolve([fix_broken: bool = True]) → bool

    Try to intelligently resolve problems by installing and removing packages. If fix_broken is `True`, apt will try to repair broken dependencies of installed packages.

  resolve_by_keep() → bool

    Try to resolve the problems without installing or removing packages.

  keep_phased_updates() → bool

    Hold back upgrades to phased versions of already installed packages, unless they are security updates.

### `Group` of packages with the same name

class apt_pkg.Group(cache: Cache, name: str)

  Added in version 0.8.0.

  A collection of packages in which all packages have the same name. Groups are used in multi-arch environments, where two or more packages have the same name, but different architectures.

  Group objects provide the following parts for sequential access:

  group[index]

    Get the package at the given index in the group.

    Note

    Groups are internally implemented using a linked list. The object keeps a pointer to the current object and the first object, so access to the first element, or accesses in order have a complexity of O(1). Random-access complexity is ranges from O(1) to O(n).

  Group objects also provide special methods to find single packages:

  find_package(architecture: str) → Package

    Find a package with the groups name and the architecture given in the argument architecture. If no such package exists, return `None`.

  find_preferred_package(prefer_nonvirtual: bool = True) → Package

    Find the preferred package. This is the package of the native architecture (specified in `APT::Architecture`) if available, or the package from the first foreign architecture. If no package could be found, return `None`

    If prefer_nonvirtual is `True`, the preferred package will be a non-virtual package, if one exists.

### `Package` information

class apt_pkg.Package

  Represent a package. A package is uniquely identified by its name and architecture and each package can have zero or more versions which can be accessed via the `version_list` property. Packages can be installed and removed by a `DepCache` object.

  > Attributes:

  > current_ver

  >   The version currently installed as a `Version` object, or None if the package is not installed.

  > get_fullname([pretty: bool = False]) → str

  >   Get the full name of the package, including the architecture. If pretty is `True`, the architecture is omitted for native packages, that is, an amd64 “apt” package on an amd64 system would give “apt”.

  >   Added in version 0.7.100.3.

  > has_provides

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

  >       pkg.has_provides and not pkg.has_versions

  > has_versions

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

  >       pkg.has_provides and not pkg.has_versions

  > 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 all package versions providing this package. Each element of the list is a triplet, where the first element is the name of the provided package, the second element the provided version (empty string), and the third element the version providing this package as a `Version` object.

  > rev_depends_list

  >   An iterator of `Dependency` objects for dependencies on this package. The returned iterator is implemented by the class `DependencyList`:

  >   class DependencyList

  >     A simple list-like type for representing multiple dependency objects in an efficient manner; without having to generate all Dependency objects in advance.

  >     list[index]

  >       Return the item at the position index in the list.

  >     __len__()

  >       The length of the list. This method should not be used irectly, instead Python’s built-in function `len()` should be used.

  > section

  >   The section of the package, as specified in the record. The list of possible sections is defined in the Policy. This is a string.

  >   Deprecated since version 1.0: A package can have multiple versions with different sections, so the section information should be accessed from the version class.

  > version_list

  >   A list of `Version` objects for all versions of this package available in the cache, ordered highest to lowest.

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

  > essential

  >   Whether the package has the ‘Essential’ flag set; that is, whether it has a field ‘Essential: yes’ in its record.

  > important

  >   Whether the package has the (obsolete) ‘Important’ flag set; that is, whether it has a field ‘Important: yes’ in its record.

#### Example:

    #!/usr/bin/python3
    """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.

  arch

    The architecture of the package, eg. amd64 or all.

  depends_list

    This is basically the same as `depends_list_str`, but instead of the (‘pkgname’, ‘version’, ‘relation’) tuples, it returns `Dependency` objects, which can assist you with useful functions.

  depends_list_str

    A dictionary of dependencies. The key specifies the type of the dependency (‘Depends’, ‘Recommends’, etc.).

    The value is a list, containing items which refer to the or-groups of dependencies. Each of these or-groups is itself a list, containing tuples like (‘pkgname’, ‘version’, ‘relation’) for each or-choice.

    An example return value for a package with a ‘Depends: python (>= 2.4)’ would be:

        {'Depends': [
                        [
                         ('python', '2.4', '>=')
                        ]
                    ]
        }

    The same for a dependency on A (>= 1) | B (>= 2):

        {'Depends': [
                        [
                            ('A', '1', '>='),
                            ('B', '2', '>='),
                        ]
                    ]
        }

    The comparison operators are not the Debian ones, but the standard comparison operators as used in languages such as C and Python. This means that ‘>’ means “larger than” and ‘<’ means “less than”.

  downloadable

    Whether this package can be downloaded from a remote site.

  file_list

    A list of (`PackageFile`, int: index) tuples for all Package files containing this version of the package.

  hash

    An integer hash value used for the internal storage.

  id

    A numeric identifier which uniquely identifies this version in all versions in the cache.

  installed_size

    The size of the package (in kilobytes), when unpacked on the disk.

  multi_arch

    The multi-arch state of the package. Can be one of the following attributes.

    > MULTI_ARCH_NO

    >   No multi-arch

    > MULTI_ARCH_ALL

    >   An `Architecture: all` package

    > MULTI_ARCH_FOREIGN

    >   Can satisfy dependencies of foreign-architecture packages

    > MULTI_ARCH_ALL_FOREIGN

    >   `MULTI_ARCH_FOREIGN` for `Architecture: all` packages.

    > MULTI_ARCH_SAME

    >   Multiple versions from different architectures may be installed in parallel, but may only satisfy dependencies of packages from the same architecture

    > MULTI_ARCH_ALLOWED

    >   Installation in parallel and satisfying `pkg:any` style dependencies is allowed.

    > MULTI_ARCH_ALL_ALLOWED

    >   `MULTI_ARCH_ALLOWED` for `Architecture: all` packages.

  parent_pkg

    The `Package` object this version belongs to.

  priority

    The integer representation of the priority. This can be used to speed up comparisons a lot, compared to `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”.

  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.

  section

    The usual sections (eg. admin, net, etc.). Prefixed with the component name for packages not in main (eg. non-free/admin).

  size

    The size of the .deb file, in bytes.

  translated_description

    Return a `Description` object for the translated description of this package version.

  is_security_update

    Whether this version is a security update.

  ver_str

    The version, as a string.

### `Dependency`

class apt_pkg.Dependency

  Represent a dependency from one package to another one.

  all_targets()

    A list of all possible target `Version` objects which satisfy this dependency.

  comp_type

    The type of comparison (<,<=,=,!=,>=,>,), as string. Note that the empty string is a valid string as well, if no version is specified.

  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.

  parent_pkg

    The `Package` object of the package which declares the dependency. This is the same as using ParentVer.ParentPkg.

  parent_ver

    The `Version` object of the parent version, ie. the package which declares the dependency.

  target_pkg

    The `Package` object of the target package.

  target_ver

    The target version of the dependency, as string. Empty string if the dependency is not versioned.

  The following constants describe all values the attribute dep_type_enum can take:

  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.all_targets(), you can easily find all packages with broken dependencies:

    #!/usr/bin/python3
    """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 += f" ({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; or, if the description is untranslated, an empty string.

  md5

    The MD5 checksum of the description.

  file_list

    A list of tuples `(packagefile: PackageFile, index: int)`.

### Package Pinning with `Policy`

class apt_pkg.Policy(cache: apt_pkg.Cache)

  Representation of the policy of the `Cache` object given by cache. This provides a superset of policy-related functionality compared to the DepCache class. The DepCache can be used for most purposes, but there may be some cases where a special policy class is needed.

  create_pin(type: str, pkg: str, data: str, priority: int)

    Create a pin for the policy. The parameter type refers to one of the strings ‘Version’, ‘Release’, or ‘Origin’. The argument pkg is the name of the package. The parameter data refers to the value (such as ‘unstable’ for type=’Release’) and the other possible options. The parameter ‘priority’ gives the priority of the pin.

  init_defaults()

    Initialize defaults. Needed after calling `create_pin()` with an empty pkg argument

  get_candidate_ver(package: apt_pkg.Package) → apt_pkg.Version

    Get the best package for the job; that is, the package with the highest pin priority.

  get_priority(package: apt_pkg.Version | apt_pkg.PackageFile) → int

    Get the pin priority of the package, version, or package file given by package.

    Changed in version 1.7: Introduce support for per-version pins. Deprecated support for `apt_pkg.Package`.

  read_pindir(dirname: str) → bool

    Read the pin files in the given dir (e.g. ‘/etc/apt/preferences.d’) and add them to the policy.

  read_pinfile(filename: str) → bool

    Read the pin file given by filename (e.g. ‘/etc/apt/preferences’) and add it to the policy.

## Index Files

class apt_pkg.MetaIndex

  Represent a Release file as stored in the cache.

  > uri

  >   The URI the meta index file is located at, as a string.

  > dist

  >   The distribution stored in the meta index, as a string.

  > is_trusted

  >   A boolean value determining whether the meta index can be trusted. This is `True` for signed Release files.

  > index_files

  >   A list of all `IndexFile` objects associated with this meta index.

class apt_pkg.IndexFile

  Represent an index file, that is, package indexes, translation indexes, and source indexes.

  archive_uri(path: str) → str

    Return the URI to the given path in the archive.

  label

    The label of the index file.

  describe

    A string describing this object.

  exists

    A boolean value determining whether the index file exists.

  has_packages

    A boolean value determining whether the index file has packages.

  size

    The size of the file, measured in bytes.

  is_trusted

    A boolean value determining whether the file can be trusted; that is, because it is from a source with a GPG signed Release file.

class apt_pkg.PackageFile

  Provide access to an index file stored in the cache, such as `/var/lib/dpkg/status`.

  architecture

    The architecture of the package file. This attribute normally contains an empty string and is thus not very useful.

  archive

    The archive of the package file as set in the Release file via the “Suite” field. If there is no Release file, this is an empty string.

  component

    The component of the package file, if it is provided by a repository using the dists/ hierarchy. For other packages files, this property is an empty string.

  filename

    The path to the file on the local filesystem.

  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

    A string describing the type of index. Known values are “Debian Package Index”, “Debian Translation Index”, and “Debian dpkg status file”.

  label

    The label of the package file as set in the release file via the ‘Label’ field. If there is no Release file, this attribute is an empty string.

  not_automatic

    Whether packages from this list will be updated automatically. The default for example is False.

  not_source

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

    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/python3
    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 (Release files, Packages, Sources)

class apt_pkg.IndexRecords

  Represent a Release file and provide means to read information from the file. This class provides several methods:

  get_dist() → str

    Return the distribution set in the Release file.

  load(filename: str)

    Load the file located at the path given by filename.

  lookup(key: str)

    Look up the filename given by key and return a tuple (hash, size), where the first element hash is a `HashString` object and the second element size is an int object.

class apt_pkg.PackageRecords(cache: apt_pkg.Cache)

  Provide further information about the packages in the `Cache` object cache. This efficiently parses the package files to provide information not available in the cache, such as maintainer, hash sums, description, and the file name of the package. It also provides the complete record of the package.

  lookup(verfile_iter: PackageFile, int) → bool

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

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

    Example (shortened):

        cand = depcache.get_candidate_ver(cache['python-apt'])
        records.lookup(cand.file_list[0])
        # Now you can access the record
        print(records.source_pkg) # == python-apt

  section[key]

    Return the value of the field at key. If key is not available, raise `KeyError`. Raises AttributeError if not yet looked up.

    Added in version 1.7.

  key in section

    > Return `True` if section has a key key, else `False`. Raises AttributeError if not yet looked up.

    Added in version 1.7.

  filename

    Return the field ‘Filename’ of the record. This is the path to the package, relative to the base path of the archive.

  hashes

    A `apt_pkg.HashStringList` of all hashes.

    Added in version 1.1.

  md5_hash

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

    Deprecated since version 1.1: Use `hashes` instead.

  sha1_hash

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

    Deprecated since version 1.1: Use `hashes` instead.

  sha256_hash

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

    Added in version 0.7.9.

    Deprecated since version 1.1: Use `hashes` instead.

  source_pkg

    The name of the source package, if different from the name of the binary package. This information is retrieved from the ‘Source’ field.

  source_ver

    The version of the source package, if it differs from the version of the binary package. Just like ‘source_pkg’, this information is retrieved from the ‘Source’ field.

  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.

    Deprecated since version 1.7: This property can be considered deprecated for simple string lookups, as keys can now be looked up in the record itself.

    Example:

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

class apt_pkg.SourceRecords

  Provide an easy way to look up the records of source packages and provide easy attributes for some widely used fields of the record.

  Note

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

  lookup(pkgname: str) → bool

    Look up the source package with the given name. Each call moves the position of the records parser forward. If there are no more records, return None. If the lookup failed this way, access to any of the attributes will result in an `AttributeError`.

    Imagine a package P with two versions X, Y. The first `lookup(P)` would set the record to version X and the second `lookup(P)` to version Y. A third call would return `None` and access to any of the below attributes will result in an `AttributeError`

  restart()

    Restart the lookup process. This moves the parser to the first package and lookups can now be made just like on a new object.

    Imagine a package P with two versions X, Y. The first `Lookup(P)` would set the record to version X and the second `Lookup(P)` to version Y. If you now call `restart()`, the internal position will be cleared. Now you can call `lookup(P)` again to move to X.

  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.

  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"`.

  files

    The list of files. This returns a list of `SourceRecordsFile`

    Changed in version 1.6: Used to be a list of tuples, see `SourceRecordFile` for the tuple layout.

  index

    A list of `IndexFile` objects associated with this source package record.

  maintainer

    A string describing the name of the maintainer.

  package

    The name of the source package.

  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 to access fields not available via the attributes such as ‘Standards-Version’

  section

    A string describing the section.

  version

    A string describing the version of the source package.

class apt_pkg.SourceRecordsFile

  Represents a file in a source record.

  Added in version 1.6: Before 1.6, this was a tuple (md5, size, path, type).

  hashes

    A `HashStringList` of the file’s hashes.

  path

    The path to the file

  size

    The size of the file

  type

    The type of the file. Can be ‘diff’ (includes .debian.tar.gz), ‘dsc’, or ‘tar’.

## The Acquire interface

The Acquire Interface is responsible for all sorts of downloading in apt. All packages, index files, etc. downloading is done using the Acquire functionality.

The `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: apt.progress.base.AcquireProgress])

  Coordinate the retrieval of files via network or local file system (using `copy://path/to/file` style URIs). Items can be added to an Acquire object using various means such as creating instances of `AcquireFile` or the methods `SourceList.get_indexes()` and `PackageManager.get_archives()`.

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

  The constructor takes an optional parameter progress which takes an `apt.progress.base.AcquireProgress` object. This object may then report progress information (see `apt.progress.text` for reporting progress to a I/O stream).

  Acquire items have two methods to start and stop the fetching:

  run() → int

    Fetch all the items which have been added by `AcquireFile` and return one of the constants `RESULT_CANCELLED`, `RESULT_CONTINUE`, `RESULT_FAILED` to describe the result of the run.

  shutdown()

    Shut the fetcher down. This removes all items from the queue and makes all `AcquireItem`, `AcquireWorker`, `AcquireItemDesc` objects useless. Accessing an object of one of those types can cause a segfault then.

    Removing an item does not mean that the already fetched data will be removed from the destination. Instead, APT might use the partial result and continue from thereon.

  Furthermore, they provide three attributes which provide information on how much data is already available and how much data still needs to be fetched:

  fetch_needed

    The amount of data that has to be fetched in order to fetch all queued items.

  partial_present

    The amount of data which is already available.

  total_needed

    The total amount of bytes needed (including those of files which are already present).

  They also provide two attributes representing the items being processed and the workers fetching them:

  items

    A list of `AcquireItem` objects which are attached to the to this Acquire object. This includes all items ever attached to this object (except if they were removed using, for example, `shutdown()` or by deleting an `AcquireFile` object.)

  workers

    A list of `AcquireWorker` objects which are currently active on this instance.

  The Acquire class comes with three constants which represents the results of the `run()` method:

  RESULT_CANCELLED

    The fetching has been aborted, e.g. due to a progress class returning `False` in its `pulse()` method.

  RESULT_CONTINUE

    All items have been fetched successfully or failed transiently and the process has not been canceled.

    You need to look at the status of each item and check if it has not failed transiently to discover errors like a Not Found when acquiring packages.

  RESULT_FAILED

    An item failed to fetch due to some reasons.

class apt_pkg.AcquireItem

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

  complete

    A boolean value which is True only if the item has been fetched successfully.

  desc_uri

    An URI describing where the item is located at.

  destfile

    The path to the local location where the fetched data will be stored at.

  error_text

    The error message. For example, when a file does not exist on a HTTP server, this will contain a 404 error message.

  filesize

    The size of the file, in bytes. If the size of the to be fetched file is unknown, this attribute is set to `0`.

  id

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

  is_trusted

    A boolean value determining whether the file is trusted. Only `True` if the item represents a package coming from a repository which is signed by one of the keys in APT’s keyring.

  local

    A boolean value determining whether this file is locally available (`True`) or whether it has to be fetched from a remote source (`False`).

  mode

    Old name for active_subprocess

    Deprecated since version 1.0.

  active_subprocess

    The name of the active subprocess (for instance, ‘gzip’, ‘rred’ or ‘gpgv’).

    Added in version 1.0.

  Status:

  The following attribute represents the status of the item. This class provides several constants for comparing against this value which are listed here as well.

  status

    Integer, representing the status of the item. This attribute can be compared against the following constants to gain useful information on the item’s status.

  STAT_AUTH_ERROR

    An authentication error occurred while trying to fetch the item.

  STAT_DONE

    The item is completely fetched and there have been no problems while fetching the item.

  STAT_ERROR

    An error occurred while trying to fetch the item. This error is normally not related to authentication problems, as thus are dealt with using `STAT_AUTH_ERROR`.

  STAT_FETCHING

    The item is being fetched currently.

  STAT_IDLE

    The item is yet to be fetched.

  STAT_TRANSIENT_NETWORK_ERROR

    There was a network error.

class apt_pkg.AcquireFile(owner, uri[, hash, 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 hash refers to the hash of the file. If this is set libapt will check the file after downloading. This should be an instance of `apt_pkg.HashStringList`.

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

  The parameter descr is a description of the download. It may be used to describe the item in the progress class. short_descr is the short form of it.

  The parameters descr and short_descr can be used to specify descriptions for the item. The string passed to descr should describe the file and its origin (e.g. “http://localhost sid/main python-apt 0.7.94.2”) and the string passed to short_descr should be one word such as the name of a package.

  Normally, the file will be stored in the current directory using the file name given in the URI. This directory can be changed by passing the name of a directory to the destdir parameter. It is also possible to set a path to a file using the destfile parameter, but both can not be specified together.

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

  Changed in version 1.9.1: The hash parameter now accepts an `apt_pkg.HashStringList`, the old md5 parameter has been removed.

class apt_pkg.AcquireWorker

  An `AcquireWorker` object represents a sub-process responsible for fetching files from remote locations. There is no possibility to create instances of this class from within Python, but a list of objects of currently active workers is provided by `Acquire.workers`.

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

  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 data which was already available when the download was started.

  status

    The most recent (localized) status string received from the sub-process.

  total_size

    The total number of bytes to be downloaded for the item. 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. Objects of this class are used in the progress classes, see the `apt.progress.base.AcquireProgress` documentation for information how.

  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 this item would be downloaded.

## Hashes

The apt_pkg module also provides several hash functions. If you develop applications with python-apt it is often easier to use these functions instead of the ones provides in Python’s `hashlib` module.

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

class apt_pkg.Hashes([object: (bytes, file)])

  Calculate hashes for the given object. It can be used to create all supported hashes for a file.

  The parameter object can be a bytestring, an object providing the fileno() method, or an integer describing a file descriptor.

  hashes

    A `HashStringList` of all hashes.

    Added in version 1.1.

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.

  You can also use a combined form by passing a string with type and hash separated by a colon as the only argument. For example:

      HashString("MD5Sum:d41d8cd98f00b204e9800998ecf8427e")

  str(hashstring)

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

  hashtype

    The type of the hash, as a string. This may be “MD5Sum”, “SHA1”, “SHA256” or “SHA512”.

  hashvalue

    The value of the hash, as a hexadecimal string

    Added in version 1.9.0.

  usable

    True if the hashstring is a trusted hash type.

  verify_file(filename: str) → bool

    Verify that the file given by the parameter filename matches the hash stored in this object.

class apt_pkg.HashStringList

  Manage a list of HashStrings.

  The list knows which hash is the best and provides convenience methods for file verification.

  Added in version 1.1.

  len(list)

    Return the length of the list

  list[index]

    Get the `HashString` object at the specified index.

  append(object: HashString)

    Append the given HashString to this list.

  file_size

    If a file size is part of the list, return it, otherwise 0.

  find(type: str = '') → HashString

    Find a hash of the given type, or the best one, if the argument is empty or not specified.

  usable

    True if at least one safe/trusted hash is in the list.

  verify_file(filename: str) → bool

    Verify that the file with the given name matches all hashes in the list.

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.7.100: Added support for using file descriptors.

  Deprecated since version 1.9: Use `apt_pkg.Hashes` instead. This function will be removed in a later release.

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.7.100: Added support for using file descriptors.

  Deprecated since version 1.9: Use `apt_pkg.Hashes` instead. This function will be removed in a later release.

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.7.100: Added support for using file descriptors.

  Deprecated since version 1.9: Use `apt_pkg.Hashes` instead. This function will be removed in a later release.

## Debian control files

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

  An object which represents a typical debian control file. Can be used for Packages, Sources, control, Release, etc.

  The file argument shall be a path name or an open file object. The argument bytes specifies whether the file shall be represented using bytes (`True`) or unicode (`False`) strings.

  It is a context manager that can be used with a with statement or the `close()` method.

  with TagFile(...) as ...:

    Use the `TagFile` as a context manager. This will automatically close the file after the body finished execution.

    Added in version 1.0.

  close()

    Close the file. It’s recommended to use the context manager instead (that is, the with statement).

    Added in version 1.0.

  It provides two kinds of API which should not be used together:

  The first API implements the iterator protocol and should be used whenever possible because it has less side effects than the other one. It may be used e.g. with a for loop:

      with apt_pkg.TagFile('/var/lib/dpkg/status') as tagfile:
          for section in tagfile:
              print(section['Package'])

  Changed in version 0.7.100: Added support for using gzip files, via `gzip.GzipFile` or any file containing a compressed gzip stream.

  Added in version 0.8.5: Added support for using bytes instead of str in Python 3

  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:

      with apt_pkg.TagFile('/var/lib/dpkg/status') as tagf:
          tagf.step()
          print tagf.section['Package']

  step() → bool

    Step forward to the next section. This simply returns `True` if OK, and `False` if there is no section.

  offset() → int

    Return the current offset (in bytes) from the beginning of the file.

  jump(offset) → bool

    Jump back/forward to offset. Use `jump(0)` to jump to the beginning of the file again. Returns `True` if a section could be parsed or `False` if not.

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

    Added in version 0.7.100.

  bytes() → int

    The number of bytes in the section.

  find(key: str, default: str = '') → str

    Return the value of the field at the key key if available, else return default.

  find_flag(key: str) → bool

    Find a yes/no value for the key key. An example for such a field is ‘Essential’.

  find_raw(key: str, default: str = '') → str

    Similar to `find()`, but instead of returning just the value, it returns the complete field consisting of ‘key: value’.

  get(key: str, default: str = '')

    Return the value of the field at the key key if available, else return default.

  keys()

    Return a list of keys in the section.

  write(file: int, order: List[str], rewrite: List[Tag]) → None

    Rewrites the section into the given file descriptor, which should be a file descriptor or an object providing a fileno() method.

    Added in version 1.9.0.

A function can be rewritten by using tag classes:

class apt_pkg.Tag

  Identify actions to be executed on a task

  This is used in conjunction with `TagSection.write()` to rewrite a tag section into a new one.

  This class is abstract, use one of the subclasses: `TagRewrite`, `TagRemove`, `TagRename`

  Added in version 1.1.

  The following static members can be used to determine the meaning of `action`:

  REWRITE

    Change the field value to the value of `data`

  RENAME

    Rename the tag to a new tag stored in `data`.

  REMOVE

    Remove the tag.

  Apart from this, the class provides access to several attributes.

  action

    The action to perform.

  data

    The data to write instead (for REWRITE), or the new tag name (RENAME)

  name

    The name of the tag to perform the action on.

class apt_pkg.TagRewrite(name: str, data: str)

  Change the value of the tag to the string passed in data

  Added in version 1.1.

class apt_pkg.TagRemove(name: str)

  Remove the tag name from the tag section

  Added in version 1.1.

class apt_pkg.TagRename(old_name: str, new_name: str)

  Rename the tag old_name to new_name

  Added in version 1.1.

Pre-defined ordering for tag sections are:

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: str, op: str, depver: str) → bool

  Check that the given requirement is fulfilled; that is, that the version string given by pkg_ver matches the version string dep_ver under the condition specified by the operator ‘dep_op’ (<,<=,=,>=,>).

  Return True if pkg_ver matches dep_ver under the condition ‘dep_op’; for example:

      >>> apt_pkg.check_dep("1.0", ">=", "1")
      True

The following two functions provide the ability to parse dependencies. They use the same format as `Version.depends_list_str`.

apt_pkg.parse_depends(depends, strip_multiarch=True, architecture)

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

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

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

  Note that multiarch dependency information is stripped off by default. You can force the full dependency info (including the multiarch info) by passing “False” as a additional parameter to this function.

  You can specify an optional argument architecture that treats the given architecture as the native architecture for purposes of parsing the dependency.

  Note

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

apt_pkg.parse_src_depends(depends, strip_multiarch=True, architecture)

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

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

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

  Furthemore, this function also supports to limit the architectures, as used in e.g. Build-Depends:

      >>> apt_pkg.parse_src_depends("a (>= 01) [i386 amd64]")
      [[('a', '01', '>=')]]

  Note that multiarch dependency information is stripped off by default. You can force the full dependency info (including the multiarch info) by passing “False” as a additional parameter to this function.

  You can specify an optional argument architecture that treats the given architecture as the native architecture for purposes of parsing the dependency.

  Note

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

## Configuration and Command-line parsing

class apt_pkg.Configuration

  Provide access to and manipulation of APT’s configuration which is used by many classes and functions in this module to define their behavior. There are options to install recommends, change the root directory and much more. For an (incomplete) list of available options, see the apt.conf(5) manual page.

  The most important Configuration object is the one available by the module’s `apt_pkg.config` attribute. It stores the global configuration which affects the behavior of most functions and is initialized by a call to the function `init_config()`. While possible, it is generally not needed to create other instances of this class.

  For accessing and manipulating the configuration space, objects of this type provide an interface which resembles Python mapping types like `dict`.

  key in conf

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

  conf[key]

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

  conf[key] = value

    Set the option at key to value.

  get(key[, default='']) → str

    Find the value for the given key and return it. If the given key does not exist, return default instead.

  In addition, they provide methods to resemble the interface provided by the C++ class and some more mapping methods which have been enhanced to support some more advanced configuration features:

  clear(key: str)

    Remove the option at key and all of its children.

  dump() → str

    Return a string containing the values in the configuration object, in the standard apt.conf(5) format.

    Added in version 0.7.100.

  exists(key)

    Check whether an option named key exists in the configuration.

  find(key[, default='']) → str

    Return the value stored at the option named key, or the value given by the string default if the option in question is not set.

  find_b(key[, default=False]) → bool

    Return the boolean value stored at key, or the value given by the `bool` object default if the requested option is not set.

  find_file(key[, default='']) → str
  find_dir(key[, default='/']) → str

    Locate the given key using `find()` and return the path to the file/directory. This uses a special algorithms which moves upwards in the configuration space and prepends the values of the options to the result. These methods are generally used for the options stored in the ‘Dir’ section of the configuration.

    As an example of how this works, take a look at the following options and their values:

    Option | Value
    --- | ---
    Dir | /
    Dir::Etc | etc/apt/
    Dir::Etc::main | apt.conf

    A call to `find_file()` would now return `/etc/apt/apt.conf` because it prepends the values of “Dir::Etc” and “Dir” to the value of “Dir::Etc::main”:

        >>> apt_pkg.config.find_file("Dir::Etc::main")
        '/etc/apt/apt.conf'

    If the special configuration variable “RootDir” is set, this value would be prepended to every return value, even if the path is already absolute. If not, the function ends as soon as an absolute path is created (once an option with a value starting with “/” is read).

    The method `find_dir()` does exactly the same thing as `find_file()`, but adds a trailing forward slash before returning the value.

  find_i(key[, default=0]) → int

    Return the integer value stored at key, or the value given by the integer default if the requested option is not set.

  keys([key])

    Return a recursive list of all configuration options or, if key is given, a list of all its children. This method is comparable to the keys method of a mapping object, but additionally provides the parameter key.

  list([key])

    Return a non-recursive list of all configuration options. If key is not given, this returns a list of options like “Apt”, “Dir”, and similar. If key is given, a list of the names of its child options will be returned instead.

  my_tag()

    Return the tag name of the current tree. Normally (for `apt_pkg.config`) this is an empty string, but for sub-trees it is the key of the sub-tree.

  set(key: str, value: str)

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

  subtree(key)

    Return a new apt_pkg.Configuration object which starts at the given option. Example:

        apttree = config.subtree('APT')
        apttree['Install-Suggests'] = config['APT::Install-Suggests']

    The configuration space is shared with the main object which means that all modifications in one object appear in the other one as well.

  value_list([key])

    This is the opposite of the `list()` method in that it returns the values instead of the option names.

apt_pkg.config

  This variable contains the global configuration which is used by all classes and functions in this module. After importing the module, this object should be initialized by calling the module’s `init_config()` function.

apt_pkg.read_config_file(configuration: Configuration, filename: str)

  Read the configuration file filename and set the appropriate options in the configuration object configuration.

apt_pkg.read_config_dir(configuration, dirname)

  Read all configuration files in the dir given by ‘dirname’ in the correct order.

apt_pkg.read_config_file_isc(configuration, filename)

  Read the configuration file filename and set the appropriate options in the configuration object configuration. This function requires a slightly different format than APT configuration files, if you are unsure, do not use it.

apt_pkg.parse_commandline(configuration, options, argv)

  Parse the command line in argv into the configuration space. The list options contains a list of 3-tuples or 4-tuples in the form:

      (short_option: str, long_option: str, variable: str[, type: str])

  The element short_option is one character, the long_option element is the name of the long option, the element variable the name of the configuration option the result will be stored in and type is one of ‘HasArg’, ‘IntLevel’, ‘Boolean’, ‘InvBoolean’, ‘ConfigFile’, ‘ArbItem’. The default type is ‘Boolean’.

  Overview of all possible types
  Type | What happens if the option is given
  --- | ---
  HasArg | The argument given to the option is stored in the target.
  IntLevel | The integer value in the target is increased by one
  Boolean | The target variable is set to True.
  InvBoolean | The target variable is set to False.
  ConfigFile | The file given as an argument to this option is read in and all configuration options are added to the configuration object (APT’s ‘-c’ option).
  ArbItem | The option takes an argument key*=*value, and the configuration option at key is set to the value value (APT’s ‘-o’ option).

## Locking

When working on the global cache, it is important to lock the cache so other programs do not modify it. This module provides two context managers for locking the package system or file-based locking.

class 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. For example:

      with apt_pkg.SystemLock():
          ... # Do your stuff here.
      ... # Now it's unlocked again

  Once the block is left, the lock is released automatically. The object can be used multiple times:

      lock = apt_pkg.SystemLock()
      with lock:
          ...
      with lock:
          ...

class 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. For example:

      with apt_pkg.FileLock(filename):
          ...

  Once the block is left, the lock is released automatically. The object can be used multiple times:

      lock = apt_pkg.FileLock(filename)
      with lock:
          ...
      with lock:
          ...

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

apt_pkg.get_lock(filename: str, errors=False) → int

  Create an empty file at the path specified by the parameter filename and lock it. If this fails and errors is True, the function raises an error. If errors is False, the function returns -1.

  The lock can be acquired multiple times within the same process, and can be released by calling `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_lock()`.

Since version 1.7, APT switches to the frontend locking approach where dpkg has two lock files, `lock-frontend` and `lock`, the latter being called the inner lock in apt. When running dpkg, the inner lock must be released before calling dpkg and reacquired afterwards. When not using APT functions to run dpkg, the variable DPKG_FRONTEND_LOCKED must be set to tell dpkg to not acquire the `lock-frontend` lock. These functions usually do not need to be used by external code.

apt_pkg.pkgsystem_unlock_inner()

  Release the `lock` lock file to allow dpkg to be run.

  Added in version 1.7.

apt_pkg.pkgsystem_lock_inner()

  Release the `lock` lock file after a dpkg run.

  Added in version 1.7.

apt_pkg.pkgsystem_is_locked()

  Returns true if the global lock is hold. Can be used to check whether `pkgsystem_unlock_inner()` needs to be called.

  Added in version 1.7.

## Other classes

class apt_pkg.Cdrom

  A Cdrom object identifies Debian installation media and adds them to `/etc/apt/sources.list`. The C++ version of this class is used by the apt-cdrom tool and using this class, you can re-implement apt-cdrom in Python, see Writing your own apt-cdrom.

  The class `apt.cdrom.Cdrom` is a subclass of this class and provides some additional functionality for higher level use and some shortcuts for setting some related configuration options.

  This class provides two functions which take an instance of `apt.progress.base.CdromProgress` as their argument.

  add(progress: apt.progress.base.CdromProgress) → bool

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

  ident(progress: apt.progress.base.CdromProgress) → str

    Identify the installation media and return a string which describes its identity. If no media could be identified, `SystemError` is raised or `None` is returned.

class apt_pkg.SourceList

  Represent the list of sources stored in files such as `/etc/apt/sources.list`.

  find_index(pkgfile: PackageFile) → IndexFile

    Return the `IndexFile` object for the `PackageFile` object given by the argument pkgfile. If no index could be found, return `None`.

  get_indexes(acquire: Acquire[, all: bool = False]) → bool

    Add all indexes to the `Acquire` object given by the argument acquire. If all is `True`, all indexes will be added, otherwise only the meta indexes (Release files) will be added and others are fetched as needed.

  read_main_list() → bool

    Read the files configured in Dir::Etc::SourceList and Dir::Etc::sourceparts; that is (on normal system), `/etc/apt/sources.list` and the files in `/etc/apt/sources.list.d`.

  list

    A list of `MetaIndex` objects.

## String functions

apt_pkg.base64_encode(value: bytes) → str

  Encode the given bytes string (which may not contain a null byte) using base64, for example, on Python 3 and newer:

      >>> apt_pkg.base64_encode(b"A")
      'QQ=='

  on Python versions prior to 3, the ‘b’ before the string has to be omitted.

apt_pkg.check_domain_list(host, list)

  See if the host name given by host is one of the domains given in the comma-separated list list or a subdomain of one of them.

      >>> apt_pkg.check_domain_list("alioth.debian.org","debian.net,debian.org")
      True

apt_pkg.dequote_string(string: str)

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

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

apt_pkg.quote_string(string, repl)

  Escape the string string, replacing any character not allowed in a URL or specified by repl with its ASCII value preceded by a percent sign (so for example ‘ ‘ becomes ‘%20’).

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

apt_pkg.size_to_str(size: int)

  Return a string describing the size in a human-readable manner using SI prefix and base-10 units, e.g. ‘1k’ for 1000, ‘1M’ for 1000000, etc.

  Example:

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

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: int) → str

  Format the unix time specified by the integer seconds, according to the requirements of RFC 1123.

  Example:

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

apt_pkg.time_to_str(seconds: int) → str

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

  Example:

      >>> apt_pkg.time_to_str(3601)
      '1h0min1s'

apt_pkg.upstream_version(version: str) → str

  Return the upstream version for the Debian package version given by version.

apt_pkg.uri_to_filename(uri: str) → str

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

  Example:

      >>> apt_pkg.uri_to_filename('http://debian.org/index.html')
      'debian.org_index.html'

apt_pkg.version_compare(a: str, b: str) → int

  Compare two versions, a and b, and return an integer value which has the same meaning as the built-in `cmp()` function’s return value has, see the following table for details.

  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

  Only the configuration files of the package exist on the system.

apt_pkg.CURSTATE_HALF_CONFIGURED

  The package is unpacked and configuration has been started, but not yet completed.

apt_pkg.CURSTATE_HALF_INSTALLED

  The installation of the package has been started, but not completed.

apt_pkg.CURSTATE_INSTALLED

  The package is unpacked, configured and OK.

apt_pkg.CURSTATE_NOT_INSTALLED

  The package is not installed.

apt_pkg.CURSTATE_UNPACKED

  The package is unpacked, but not configured.

### Installed states

apt_pkg.INSTSTATE_HOLD

  The package is put on hold.

apt_pkg.INSTSTATE_HOLD_REINSTREQ

  The package is put on hold, but broken and has to be reinstalled.

apt_pkg.INSTSTATE_OK

  The package is OK.

apt_pkg.INSTSTATE_REINSTREQ

  The package is broken and has to be reinstalled.

### Priorities

apt_pkg.PRI_EXTRA

  The integer representation of the priority ‘extra’.

apt_pkg.PRI_IMPORTANT

  The integer representation of the priority ‘important’.

apt_pkg.PRI_OPTIONAL

  The integer representation of the priority ‘optional’.

apt_pkg.PRI_REQUIRED

  The integer representation of the priority ‘required’.

apt_pkg.PRI_STANDARD

  The integer representation of the priority ‘standard’.

### Package selection states

apt_pkg.SELSTATE_DEINSTALL

  The package is selected for deinstallation.

apt_pkg.SELSTATE_HOLD

  The package is marked to be on hold and will not be modified.

apt_pkg.SELSTATE_INSTALL

  The package is selected for installation.

apt_pkg.SELSTATE_PURGE

  The package is selected to be purged.

apt_pkg.SELSTATE_UNKNOWN

  The package is in an unknown state.

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