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