path: root/doc/source/apt_pkg.rst

:mod:`apt_pkg` --- The low-level bindings for apt-pkg
=====================================================
.. module:: 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.

.. function:: init_config

    Initialize the configuration of apt. This is needed for most operations.

.. function:: init_system

    Initialize the system.

.. function:: init

    Deprecated function. Use init_config() and init_system() instead.

Working with the cache
----------------------
.. class:: Cache([progress])

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

    .. describe:: cache[pkgname]

        Return the :class:`Package()` object for the package name given by
        *pkgname*.

    .. method:: close()

        Close the package cache.

    .. method:: open([progress])

        Open the package cache again. The parameter *progress* may be set to
        an :class:`apt.progress.OpProgress()` object or `None`.

    .. method:: update(progress, list)

        Update the package cache.

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

    .. attribute:: depends_count

        The total number of dependencies.

    .. attribute:: package_count

        The total number of packages available in the cache.

    .. attribute:: provides_count

        The number of provided packages.

    .. attribute:: ver_file_count

        .. todo:: Seems to be some mixture of versions and pkgFile.

    .. attribute:: version_count

        The total number of package versions available in the cache.

    .. 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 :attr:`file_list`.

    .. attribute:: file_list

        A list of :class:`PackageFile` objects.

.. class:: DepCache(cache)

    Return a :class:`DepCache` object. The parameter *cache* specifies an
    instance of :class:`Cache`.

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

    .. method:: commit(fprogress, iprogress)

        Apply all the changes made.

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

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

    .. method:: fix_broken()

        Try to fix all broken packages in the cache.

    .. method:: get_candidate_ver(pkg)

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

        The parameter *pkg* refers to an :class:`Package` object,
        available using the :class:`pkgCache`.

        This method returns a :class:`Version` object.

    .. method:: set_candidate_ver(pkg, version)

        The opposite of :meth:`pkgDepCache.get_candidate_ver`. Set the candidate
        version of the :class:`Package` *pkg* to the :class:`Version`
        *version*.


    .. method:: upgrade([dist_upgrade=False])

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

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

    .. method:: fix_broken()

        Fix broken packages.

    .. method:: read_pin_file()

        Read the policy, eg. /etc/apt/preferences.

    .. method:: minimize_upgrade()

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

        .. todo::
            Explain better..

    .. method:: mark_keep(pkg)

        Mark the :class:`Package` *pkg* for keep.

    .. method:: mark_delete(pkg[, purge])

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

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

        Mark the :class:`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.

    .. method:: set_reinstall(pkg)

        Set if the :class:`Package` *pkg* should be reinstalled.

    .. method:: is_upgradable(pkg)

        Return ``1`` if the package is upgradable.

        The package can be upgraded by calling :meth:`pkgDepCache.MarkInstall`.

    .. method:: is_now_broken(pkg)

        Return `1` if the package is broken now (including changes made, but
        not committed).

    .. method:: is_inst_broken(pkg)

        Return ``1`` if the package is broken on the current install. This
        takes changes which have not been committed not into effect.

    .. method:: is_garbage(pkg)

        Return ``1`` if the package is garbage, ie. if it is automatically
        installed and no longer referenced by other packages.

    .. method:: is_auto_installed(pkg)

        Return ``1``  if the package is automatically installed (eg. as the
        dependency of another package).

    .. method:: marked_install(pkg)

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

    .. method:: marked_upgrade(pkg)

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

    .. method:: marked_delete(pkg)

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

    .. method:: marked_keep(pkg)

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

    .. method:: marked_reinstall(pkg)

        Return ``1`` if the package should be installed.

    .. method:: marked_downgrade(pkg)

        Return ``1`` if the package should be downgraded.

    .. attribute:: keep_count

        Integer, number of packages marked as keep

    .. attribute:: inst_count

        Integer, number of packages marked for installation.

    .. attribute:: del_count

        Number of packages which should be removed.

    .. attribute:: broken_count

        Number of packages which are broken.

    .. attribute:: usr_size

        The size required for the changes on the filesystem. If you install
        packages, this is positive, if you remove them its negative.

    .. attribute:: deb_size

        The size of the packages which are needed for the changes to be
        applied.


.. class:: PackageManager(depcache)

    Return a new :class:`PackageManager` object. The parameter *depcache*
    specifies a :class:`DepCache` object.

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

    .. method:: get_archives(fetcher, list, records)

        Add all the selected packages to the :class:`Acquire()` object
        *fetcher*.

        The parameter *list* refers to a :class:`SourceList()` object.

        The parameter *records* refers to a :class:`PackageRecords()` object.

    .. method:: do_install()

        Install the packages.

    .. method:: fix_missing

        Fix the installation if a package could not be downloaded.

    .. attribute:: result_completed

        A constant for checking whether the the result is 'completed'.

        Compare it against the return value of :meth:`PackageManager.get_archives`
        or :meth:`PackageManager.do_install`.

    .. attribute:: result_failed

        A constant for checking whether the the result is 'failed'.

        Compare it against the return value of :meth:`PackageManager.get_archives`
        or :meth:`PackageManager.do_install`.

    .. attribute:: result_incomplete

        A constant for checking whether the the result is 'incomplete'.

        Compare it against the return value of :meth:`PackageManager.get_archives`
        or :meth:`PackageManager.do_install`.

Improve performance with :class:`ActionGroup`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. class:: ActionGroup(depcache)

    Create a new :class:`ActionGroup()` object for the :class:`DepCache` object
    given by the parameter *depcache*.

    :class:`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
    :keyword:`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()

    :class:`ActionGroup` provides the following method:

    .. method:: release()

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

Resolving Dependencies
^^^^^^^^^^^^^^^^^^^^^^

.. class:: ProblemResolver(depcache)

    Return a new :class:`ProblemResolver` object. The parameter *depcache*
    specifies a :class:`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.

    .. method:: protect(pkg)

        Protect the :class:`Package()` object given by the parameter *pkg*.

        .. todo::

            Really document it.

    .. method:: install_protect()

        Protect all installed packages from being removed.

    .. method:: remove(pkg)

        Remove the :class:`Package()` object given by the parameter *pkg*.

        .. todo::

            Really document it.

    .. method:: clear(pkg)

        Reset the :class:`Package()` *pkg* to the default state.

        .. todo::

            Really document it.

    .. method:: resolve()

        Try to resolve problems by installing and removing packages.

    .. method:: resolve_by_keep()

        Try to resolve problems only by using keep.


:class:`PackageFile`
--------------------
.. class:: PackageFile

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

    .. attribute:: architecture

        The architecture of the package file.

    .. attribute:: archive

        The archive (eg. unstable)

    .. attribute:: component

        The component (eg. main)

    .. attribute:: filename

        The name of the file.

    .. attribute:: 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].

    .. attribute:: index_type

        The sort of the index file. In normal cases, this is
        'Debian Package Index'.

    .. attribute:: label

        The Label, as set in the Release file

    .. attribute:: not_automatic

        Whether packages from this list will be updated automatically. The
        default for eg. example is 0 (aka false).

    .. attribute:: not_source

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

        Example::

            for pkgfile in cache.file_list:
                if pkgfile.not_source:
                    print 'The file %s has no source.' % pkgfile.filename

    .. attribute:: origin

        The Origin, as set in the Release file

    .. attribute:: site

        The hostname of the site.

    .. attribute:: size

        The size of the file.

    .. attribute:: version

        The version, as set in the release file (eg. "4.0" for "Etch")


Example
^^^^^^^
.. literalinclude:: examples/cache-pkgfile.py


:class:`Package`
----------------

.. class:: Package

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


    Attributes:

    .. attribute:: current_ver

        The version currently installed, or None. This returns a
        :class:`Version` object.

    .. attribute:: id

        The ID of the package. This can be used to store information about
        the package. The ID is an int value.

    .. attribute:: name

        This is the name of the package.

    .. attribute:: provides_list

        A list of packages providing this package. More detailed, this is a
        list of tuples (str:pkgname, ????, :class:`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.

    .. attribute:: rev_depends_list

        An iterator of :class:`Dependency` objects for dependencies on this
        package.

    .. attribute:: section

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

    .. attribute:: version_list

        A list of :class:`Version` objects for all versions available in the
        cache.

    **States**:

    .. attribute:: selected_state

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

        See :ref:`SelStates` for a list of available states.

    .. attribute:: inst_state

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

        See :ref:`InstStates` for a list of available states.

    .. attribute:: cur_state

        The current state of the package (not installed, unpacked, installed,
        etc). See :ref:`CurStates` for a list of available states.

    **Flags**:

    .. attribute:: auto

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

    .. attribute:: essential

        Whether the package is essential.

    .. attribute:: important

        Whether the package is important.

Example:
^^^^^^^^^
.. literalinclude:: examples/cache-packages.py



:class:`Version`
----------------
.. class:: Version

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

    .. attribute:: ver_str

        The version, as a string.

    .. attribute:: section

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

    .. attribute:: arch

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

    .. attribute:: file_list

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

    .. attribute:: 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', '>='),
                            ]
                        ]
            }

    .. attribute:: depends_list

        This is basically the same as :attr:`Version.DependsListStr`,
        but instead of the ('pkgname', 'version', 'relation') tuples,
        it returns :class:`Dependency` objects, which can assist you with
        useful functions.

    .. attribute:: parent_pkg

        The :class:`Package` object this version belongs to.

    .. attribute:: provides_list

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

    .. attribute:: size

        The size of the .deb file, in bytes.

    .. attribute:: installed_size

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

    .. attribute:: hash

        An integer hash value.

    .. attribute:: id

        An integer id.

    .. attribute:: priority

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

        The values are defined in the :mod:`apt_pkg` extension, see
        :ref:`Priorities` for more information.

    .. attribute:: priority_str

        Return the priority of the package version, as a string, eg.
        "optional".

    .. attribute:: downloadable

        Whether this package can be downloaded from a remote site.

    .. attribute:: translated_description

        Return a :class:`Description` object.


:class:`Dependency`
-------------------
.. class:: Dependency

    Represent a dependency from one package to another one.

    .. method:: all_targets

        A list of :class:`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.

    .. method:: smart_target_pkg

        Return a :class:`Version` object of a package which satisfies the
        dependency and does not conflict with installed packages
        (the 'natural target').

    .. attribute:: target_ver

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

    .. attribute:: target_pkg

        The :class:`Package` object of the target package.

    .. attribute:: parent_ver

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

    .. attribute:: parent_pkg

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

    .. attribute:: comp_type

        The type of comparison (>=, ==, >>, <=), as string.

    .. attribute:: dep_type

        The type of the dependency, as string, eg. "Depends".

    .. attribute:: id

        The ID of the package, as integer.

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

.. literalinclude:: examples/missing-deps.py


:class:`Description`
--------------------
.. class:: Description

    Represent the description of the package.

    .. attribute:: language_code

        The language code of the description

    .. attribute:: md5

        The md5 hashsum of the description

    .. attribute:: file_list

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



:class:`MetaIndex`
------------------

.. todo::

    Complete them

.. class:: MetaIndex

    .. attribute:: uri
    .. attribute:: dist
    .. attribute:: is_trusted
    .. attribute:: index_files


:class:`PackageIndexFile`
-------------------------

.. class:: PackageIndexFile

    .. method:: archive_uri(path)

        Return the full url to path in the archive.

    .. attribute:: label

        Return the Label.

    .. attribute:: exists

        Return whether the file exists.

    .. attribute:: has_packages

        Return whether the file has packages.

    .. attribute:: size

        Size of the file

    .. attribute:: is_trusted

        Whether we can trust the file.


Records
--------

.. class:: PackageRecords(cache)

    Create a new :class:`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.

    .. method:: lookup(verfile_iter)

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

        The parameter *verfile_iter* refers to a tuple consisting
        of (:class:`PackageFile()`, int: index), as returned by various
        attributes, including :attr:`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

    .. attribute:: filename

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

    .. attribute:: md5_hash

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

    .. attribute:: sha1_hash

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

    .. attribute:: sha256_hash

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

        .. versionadded:: 0.7.9

    .. attribute:: source_pkg

        Return the source package.

    .. attribute:: source_ver

        Return the source version.

    .. attribute:: maintainer

        Return the maintainer of the package.

    .. attribute:: short_desc

        Return the short description. This is the summary on the first line of
        the 'Description' field.

    .. attribute:: long_desc

        Return the long description. These are lines 2-END from the
        'Description' field.

    .. attribute:: name

        Return the name of the package. This is the 'Package' field.

    .. attribute:: homepage

        Return the Homepage. This is the 'Homepage' field.

    .. attribute:: 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
        :class:`apt_pkg.TagSection` to parse the record and access the field
        name.

        Example::

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


.. class:: SourceRecords

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

    .. note::

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

    .. method:: lookup(pkgname)

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

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

    .. method:: restart()

        Restart the lookup.

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

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

    .. attribute:: package

        The name of the source package.

    .. attribute:: version

        A string describing the version of the source package.

    .. attribute:: maintainer

        A string describing the name of the maintainer.

    .. attribute:: section

        A string describing the section.

    .. attribute:: record

        The whole record, as a string. You can use :func:`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'

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

    .. attribute:: index

        The index in the Sources files.

    .. attribute:: files

        The list of files. This returns a list of tuples with the contents
        ``(str: md5, int: size, str: path, str:type)``.

    .. attribute:: build_depends

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

    .. attribute:: BuildDepends

        Return the list of Build dependencies, as
        ``(str: package, str: version, int: op, int: type)``. This is a
        completely deprecated format

        .. table:: Values of *op*

            ===== =============================================
            Value      Meaning
            ===== =============================================
            0x00  No Operation (no versioned build dependency)
            0x10  | (or) - this will be added to the other values
            0x01  <= (less than or equal)
            0x02  >= (greater than or equal)
            0x03  << (less than)
            0x04  >> (greater than)
            0x05   = (equal)
            0x06  != (not equal)
            ===== =============================================

        .. table:: Values of *type*

            ===== ===================
            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
        :func:`apt_pkg.ParseSrcDepends`.



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


.. class:: Acquire([progress])

    Return an :class:`Acquire` object. The parameter *progress* refers to
    an :class:`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 :class:`AcquireFile` objects which allow
    you to add single files.

    Acquire items have multiple methods:

    .. method:: run()

        Fetch all the items which have been added by :class:`AcquireFile`.

    .. method:: shutdown()

        Shut the fetcher down.

    .. attribute:: total_needed

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

    .. attribute:: fetch_needed

        The total amount of bytes which need to be fetched.

    .. attribute:: partial_present

        Whether some files have been acquired already. (???)

.. class:: AcquireItem

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

    .. attribute:: id

        The ID of the item.

    .. attribute:: complete

        Is the item completely acquired?

    .. attribute:: local

        Is the item a local file?

    .. attribute:: is_trusted

        Can the file be trusted?

    .. attribute:: file_size

        The size of the file, in bytes.

    .. attribute:: error_text

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

    .. attribute:: dest_file

        The location the file is saved as.

    .. attribute:: desc_uri

        The source location.

    **Status**:

    .. attribute:: status

        Integer, representing the status of the item.

    .. attribute:: stat_idle

        Constant for comparing :attr:`AcquireItem.status`.

    .. attribute:: stat_fetching

        Constant for comparing :attr:`AcquireItem.status`

    .. attribute:: stat_done

        Constant for comparing :attr:`AcquireItem.status`

    .. attribute:: stat_error

        Constant for comparing :attr:`AcquireItem.status`

    .. attribute:: stat_auth_error

        Constant for comparing :attr:`AcquireItem.status`


.. class:: AcquireFile(owner, uri[, md5, size, descr, short_descr, destdir, destfile])

    Create a new :class:`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 :class:`Acquire()` object as returned
    by :func:`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.


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 :mod:`hashlib` module.

.. class:: Hashes(object)

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

    .. attribute:: md5

        The MD5 hash of the data, as string.

    .. attribute:: sha1

        The SHA1 hash of the data, as string.

    .. attribute:: sha256

        The SHA256 hash of the data, as string.

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

    .. versionchanged:: 0.8.0
        Added support for using file descriptors.

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

    .. versionchanged:: 0.8.0
        Added support for using file descriptors.

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

    .. versionchanged:: 0.8.0
        Added support for using file descriptors.

Debian control files
--------------------
Debian control files are files containing multiple stanzas of :RFC:`822`-style
header sections. They are widely used in the Debian community, and can represent
many kinds of information. One example for such a file is the
:file:`/var/lib/dpkg/status` file which contains a list of the currently
installed packages.

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

.. class:: TagFile(file)

    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']

    .. method:: step

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

    .. method:: offset

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

    .. method:: jump(offset)

        Jump back/forward to *offset*. Use ``jump(0)`` to jump to the
        beginning of the file again.

    .. attribute:: section

        This is the current :class:`TagSection()` instance.

.. class:: TagSection(text)

    Represent a single section of a debian control file.

    .. describe:: section[key]

        Return the value of the field at *key*. If *key* is not available,
        raise :exc:`KeyError`.

    .. describe:: key in section

        Return ``True`` if *section* has a key *key*, else ``False``.

      .. versionadded:: 0.8.0

    .. method:: bytes

        The number of bytes in the section.

    .. method:: find(key, default='')

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

    .. method:: find_flag(key)

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

    .. method:: get(key, default='')

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

    .. method:: has_key(key)

        Check whether the field with named by *key* exists.

        .. deprecated:: 0.8.0

    .. method:: keys()

        Return a list of keys in the section.

.. autofunction:: rewrite_section(section, order, rewrite_list)

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

.. data:: 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
------------
.. function:: check_dep(pkgver, op, depver)

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

    Example::

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

.. function:: parse_depends(depends)

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

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

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


    .. note::

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


.. function:: parse_src_depends(depends)

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

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

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


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

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

    .. note::

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


Configuration
-------------

.. class:: Configuration()

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

    .. describe:: key in conf

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

      .. versionadded:: 0.8.0

    .. describe:: conf[key]

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

    .. describe:: conf[key] = value

        Set the option at *key* to *value*.

    .. method:: find(key[, default=''])

        Return the value for the given key *key*. This is the same as
        :meth:`Configuration.get`.

        If *key* does not exist, return *default*.

    .. method:: find_file(key[, default=''])

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

        If *key* does not exist, return *default*.

    .. method:: find_dir(key[, default='/'])

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

        If *key* does not exist, return *default*.

    .. method:: find_i(key[, default=0])

        Return the integer value stored at *key*.

        If *key* does not exist, return *default*.

    .. method:: find_b(key[, default=0])

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

        If *key* does not exist, return *default*.

    .. method:: set(key, value)

        Set the value of *key* to *value*.

    .. method:: exists(key)

        Check whether the key *key* exists in the configuration.

    .. method:: subtree(key)

        Return a sub tree starting at *key*. The resulting object can be used
        like this one.

    .. method:: list([key])

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

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

    .. method:: value_list([key])

        Same as :meth:`Configuration.list`, but this time for the values.

    .. method:: my_tag()

        Return the tag name of the current tree. Normally this is an empty
        string, but for subtrees it is the key of the subtree.

    .. method:: clear(key)

        Clear the configuration. Remove all values and keys at *key*.

    .. method:: keys([key])

        Return all the keys, recursive. If *key* is specified, ... (FIXME)

    .. method:: has_key(key)

        Return whether the configuration contains the key *key*.

        .. deprecated:: 0.8.0

    .. method:: get(key[, default=''])

        This behaves just like :meth:`dict.get` and :meth:`Configuration.find`,
        it returns the value of key or if it does not exist, *default*.

.. class:: ConfigurationPtr

    Behaves like a :class:`Configuration()` objects, but uses a pointer to the
    underlying C++ object. This is used for the default configuration in the
    :data:`Config` attribute of the module.

.. class:: ConfigurationSub

    Behaves like a :class:`Configuration()` objects, but provides access to
    a subsection of another Configuration-like object. This type of object is
    returned by the :meth:`Configuration.subtree()` method.

.. data:: config

    A :class:`ConfigurationPtr()` object with the default configuration. This
    object is initialized by calling :func:`init_config`.


Modifying
^^^^^^^^^


.. function:: read_config_file(configuration, filename)

    Read the configuration file specified by the parameter *filename* and add
    the settings therein to the :class:`Configuration()` object specified by
    the parameter *configuration*

.. function:: read_config_dir(configuration, dirname)

    Read configuration files in the directory specified by the parameter
    *dirname* and add the settings therein to the :class:`Configuration()`
    object specified by the parameter *configuration*.

.. function:: read_config_file_isc(configuration, filename)

    Read the configuration file specified by the parameter *filename* and add
    the settings therein to the :class:`Configuration()` object specified by
    the parameter *configuration*

.. function:: parse_commandline(configuration, options, argv)

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

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

Locking
--------

.. function:: get_lock(filename)

    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 :func:`os.close`.

.. function:: pkg_system_lock()

    Lock the global pkgsystem.

.. function:: pkg_system_un_lock()

    Unlock the global pkgsystem.

Other classes
--------------
.. class:: Cdrom()

    Return a Cdrom object with the following methods:

    .. method:: ident(progress)

        Identify the cdrom. The parameter *progress* refers to an
        :class:`apt.progress.CdromProgress()` object.

    .. method:: add(progress)

        Add the cdrom to the sources.list file. The parameter *progress*
        refers to an :class:`apt.progress.CdromProgress()` object.

.. class:: SourceList

    This is for :file:`/etc/apt/sources.list`.

    .. method:: find_index(pkgfile)

        Return a :class:`PackageIndexFile` object for the :class:`PackageFile`
        *pkgfile*.

    .. method:: read_main_list

        Read the main list.

    .. method:: get_indexes(acq[, all])

        Add the index files to the :class:`Acquire()` object *acq*. If *all* is
        given and ``True``, all files are fetched.

String functions
----------------
.. function:: base64_encode(string)

    Encode the given string using base64, e.g::

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


.. function:: check_domain_list(host, list)

    See if Host is in a ',' seperated list, e.g.::

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

.. function:: dequote_string(string)

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

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

.. function:: quote_string(string, repl)

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

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

.. function:: size_to_str(size)

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

    Example::

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

.. function:: string_to_bool(input)

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

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

.. function:: 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 :func:`TimeRFC1123`.

    Example::

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

.. function:: time_rfc1123(seconds)

    Format the unix time specified by the integer *seconds*, according to the
    requirements of :rfc:`1123`.

    Example::

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


.. function:: time_to_str(seconds)

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

    Example::

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

.. function:: upstream_version(version)

    Return the string *version*, eliminating everything following the last
    '-'. Thus, this should be equivalent to ``version.rsplit('-', 1)[0]``.

.. function:: uri_to_filename(uri)

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

    Example::

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


.. function:: version_compare(a, b)

    Compare two versions, *a* and *b*, and return an integer value which has
    the same characteristic as the built-in :func:`cmp` function.

    .. table:: 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
----------------
.. _CurStates:

Package States
^^^^^^^^^^^^^^^
.. data:: CURSTATE_CONFIG_FILES
.. data:: CURSTATE_HALF_CONFIGURED
.. data:: CURSTATE_HALF_INSTALLED
.. data:: CURSTATE_INSTALLED
.. data:: CURSTATE_NOT_INSTALLED
.. data:: CURSTATE_UNPACKED




Dependency types
^^^^^^^^^^^^^^^^
.. data:: DEP_CONFLICTS
.. data:: DEP_DEPENDS
.. data:: DEP_OBSOLETES
.. data:: DEP_PRE_DEPENDS
.. data:: DEP_RECOMMENDS
.. data:: DEP_REPLACES
.. data:: DEP_SUGGESTS

.. _InstStates:

Installed states
^^^^^^^^^^^^^^^^
.. data:: INSTSTATE_HOLD
.. data:: INSTSTATE_HOLD_REINSTREQ
.. data:: INSTSTATE_OK
.. data:: INSTSTATE_REINSTREQ

.. _Priorities:

Priorities
^^^^^^^^^^^
.. data:: PRI_EXTRA
.. data:: PRI_IMPORTANT
.. data:: PRI_OPTIONAL
.. data:: PRI_REQUIRED
.. data:: PRI_STANDARD


.. _SelStates:

Select states
^^^^^^^^^^^^^
.. data:: SELSTATE_DE_INSTALL
.. data:: SELSTATE_HOLD
.. data:: SELSTATE_INSTALL
.. data:: SELSTATE_PURGE
.. data:: SELSTATE_UNKNOWN


Build information
^^^^^^^^^^^^^^^^^
.. data:: DATE

    The date on which this extension has been compiled.

.. data:: LIB_VERSION

    The version of the apt_pkg library. This is **not** the version of apt,
    nor the version of python-apt.

.. data:: TIME

    The time this extension has been built.

.. data:: VERSION

    The version of apt (not of python-apt).

.. data:: _COMPAT_0_7

    A more or less internal variable defining whether this build provides an
    API which is compatible to the one of python-apt 0.7. This is used in the
    apt and aptsources packages to decide whether compatibility should be
    enabled or not.