.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "HAWKEY" "3" "Nov 03, 2023" "0.69.0" "Hawkey"
.SH NAME
hawkey \- Hawkey Documentation
.sp
Contents:
.SH API CHANGES
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%API Changes\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Introduction\fP
.IP \(bu 2
\fI\%Changes in 0.2.10\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Python bindings\fP
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.2.11\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Python bindings\fP
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.3.0\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Query: key for reponame filtering\fP
.IP \(bu 2
\fI\%Repo initialization\fP
.IP \(bu 2
\fI\%Query installs obsoleted\fP
.UNINDENT
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Query: filtering by repository with the reponame key\fP
.IP \(bu 2
\fI\%Package: removed methods for direct EVR comparison\fP
.IP \(bu 2
\fI\%Repo initialization\fP
.IP \(bu 2
\fI\%Query installs obsoleted\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.3.1\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Query: hy_query_filter_package_in() takes a new parameter\fP
.IP \(bu 2
\fI\%Removed hy_query_filter_obsoleting()\fP
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.3.2\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Removed hy_packagelist_of_obsoletes.\fP
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.3.3\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Renamed hy_package_get_nvra to hy_package_get_nevra\fP
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.3.4\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%pkg.__repr__() is more verbose now\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.3.8\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%New parameter rootdir to hy_sack_create()\fP
.UNINDENT
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Forms recognized by Subject are no longer an instance\-scope setting\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.3.9\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Flags for hy_sack_create\fP
.IP \(bu 2
\fI\%hy_sack_get_cache_path is renamed to hy_sack_get_cache_dir\fP
.UNINDENT
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%make_cache_dir for Sack\(aqs constructor\fP
.IP \(bu 2
\fI\%cache_path property of Sack renamed to cache_dir\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.3.11\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%hy_goal_package_obsoletes() removed, hy_goal_list_obsoleted_by_package() provided instead\fP
.IP \(bu 2
\fI\%hy_goal_list_erasures() does not report obsoletes\fP
.UNINDENT
.IP \(bu 2
\fI\%Python bindings\fP
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.4.5\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Query: hy_query_filter_latest() now filter latest packages ignoring architecture\fP
.UNINDENT
.IP \(bu 2
\fI\%Python bindings\fP
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.4.13\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Deprecated hy_package_get_update_*\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.4.15\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%hy_goal_write_debugdata() takes a directory parameter\fP
.UNINDENT
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Goal.write_debugdata() takes a directory parameter\fP
.IP \(bu 2
\fI\%Package: string attributes are represented by Unicode object\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.4.18\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Deprecated hy_advisory_get_filenames\fP
.UNINDENT
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Repo() does not accept cost keyword argument\fP
.IP \(bu 2
\fI\%Deprecated _hawkey.Advisory.filenames\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.4.19\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Advisory attributes in Unicode\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.5.2\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%hy_chksum_str returns NULL\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.5.3\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%New parameter logfile to hy_sack_create()\fP
.IP \(bu 2
\fI\%Deprecated hy_create_cmdline_repo()\fP
.UNINDENT
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%New optional parameter logfile to Sack constructor\fP
.IP \(bu 2
\fI\%cache_path property of Sack renamed to cache_dir\fP
.IP \(bu 2
\fI\%Deprecated Sack method create_cmdline_repo()\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.5.4\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Goal: install() takes a new optional parameter\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.5.5\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Renamed hy_sack_load_yum_repo to hy_sack_load_repo\fP
.UNINDENT
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Sack method load_yum_repo has been renamed to Sack.load_repo()\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.5.7\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Package: file attribute is represented by list of Unicode objects\fP
.IP \(bu 2
\fI\%Sack: list_arches method returns list of Unicode objects\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.5.9\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Deprecated hy_goal_req_has_distupgrade(), hy_goal_req_has_erase() and hy_goal_req_has_upgrade() functions\fP
.UNINDENT
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Deprecated Goal methods Goal.req_has_distupgrade_all(), Goal.req_has_erase() and Goal.req_has_upgrade_all()\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Changes in 0.6.2\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Core\fP
.IP \(bu 2
\fI\%Python bindings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Advisory: The filename property is removed along with the C API\fP
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Introduction
.sp
This document describes the API changes the library users should be aware of before upgrading to each respective version. It is our plan to have the amount of changes requiring changing the client code go to a minimum after the library hits the 1.0.0 version.
.sp
Depracated API items (classes, methods, etc.) are designated as such in this document. The first release where support for such items can be dropped entirely must be issued at \fIleast five months\fP after the issue of the release that announced the deprecation and at the same time have, relatively to the deprecating release, either:
.INDENT 0.0
.IP \(bu 2
a higher major version number, or
.IP \(bu 2
a higher minor version number, or
.IP \(bu 2
a patchlevel number that is \fIby at least five\fP greater.
.UNINDENT
.sp
These criteria are likely to tighten in the future as hawkey matures.
.sp
Actual changes in the API are then announced in this document as well. ABI changes including changes in functions\(aq parameter counts or types or removal of public symbols from \fBlibhawkey\fP imply an increase in the library\(aqs SONAME version.
.SS Changes in 0.2.10
.SS Python bindings
.sp
\fBQuery.filter()\fP now returns a new instance of \fBQuery\fP, the same as
the original with the new filtering applied. This allows for greater flexibility
handling the \fBQuery\fP objects and resembles the way \fBQuerySets\fP behave in
Django.
.sp
In practice the following code will stop working as expected:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
q = hawkey.Query(self.sack)
q.filter(name__eq=\(dqflying\(dq)
# processing the query ...
.EE
.UNINDENT
.UNINDENT
.sp
It needs to be changed to:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
q = hawkey.Query(self.sack)
q = q.filter(name__eq=\(dqflying\(dq)
# processing the query ...
.EE
.UNINDENT
.UNINDENT
.sp
The original semantics is now available via the \fBQuery.filterm()\fP method, so
the following will also work:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
q = hawkey.Query(self.sack)
q.filterm(name__eq=\(dqflying\(dq)
# processing the query ...
.EE
.UNINDENT
.UNINDENT
.SS Changes in 0.2.11
.SS Python bindings
.sp
In Python\(aqs \fBPackage\fP instances accessors for string attributes now
return None instead of the empty string if the attribute is missing (for instance
a \fBpkg.sourcerpm\fP now returns None if \fBpkg\fP is a source rpm package
already).
.sp
This change is towards a more conventional Python practice. Also, this leaves the
empty string return value free to be used when it is actually the case.
.SS Changes in 0.3.0
.SS Core
.SS Query: key for reponame filtering
.sp
The Query key value used for filtering by the repo name is \fBHY_PKG_REPONAME\fP
now (was \fBHY_PKG_REPO\fP). The old value was misleading.
.SS Repo initialization
.sp
\fBhy_repo_create()\fP for Repo object initialization now needs to be passed a
name of the repository.
.SS Query installs obsoleted
.sp
All Goal methods accepting Query as the means of selecting packages, such as
\fBhy_goal_install_query()\fP have been replaced with their Selector
counterparts. Selector structures have been introduced for the particular
purpose of specifying a package that best matches the given criteria and at the
same time is suitable for installation. For a discussion of this decision see
\fI\%Selectors are not Queries\fP\&.
.SS Python bindings
.SS Query: filtering by repository with the reponame key
.sp
Similar change happened in Python, the following constructs:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
q = q.filter(repo=\(dqupdates\(dq)
.EE
.UNINDENT
.UNINDENT
.sp
need to be changed to:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
q = q.filter(reponame=\(dqupdates\(dq)
.EE
.UNINDENT
.UNINDENT
.sp
The old version of this didn\(aqt allow using the same string to both construct the
query and dynamically get the reponame attribute from the returned packages
(used e.g. in DNF to search by user\-specified criteria).
.SS Package: removed methods for direct EVR comparison
.sp
The following will no longer work:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
if pkg.evr_eq(some_other_pkg):
    ...
.EE
.UNINDENT
.UNINDENT
.sp
Instead use the result of \fBpkg.evr_cmp\fP, for instance:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
if pkg.evr_cmp(some_other_pkg) == 0:
    ...
.EE
.UNINDENT
.UNINDENT
.sp
This function compares only the EVR part of a package, not the name. Since it
rarely make sense to compare versions of packages of different names, the
following is suggested:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
if pkg == some_other_pkg:
    ...
.EE
.UNINDENT
.UNINDENT
.SS Repo initialization
.sp
All instantiations of \fI\%hawkey.Repo\fP now must be given the name of the
Repo. The following will now fail:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
r = hawkey.Repo()
r.name = \(dqfedora\(dq
.EE
.UNINDENT
.UNINDENT
.sp
Use this instead:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
r = hawkey.Repo(\(dqfedora\(dq)
.EE
.UNINDENT
.UNINDENT
.SS Query installs obsoleted
.sp
See \fI\%Query installs obsoleted\fP in the C section. In Python Queries will no
longer work as goal target specifiers, the following will fail:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
q = hawkey.Query(sack)
q.filter(name=\(dqgimp\(dq)
goal.install(query=q)
.EE
.UNINDENT
.UNINDENT
.sp
Instead use:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
sltr = hawkey.Selector(sack)
sltr.set(name=\(dqgimp\(dq)
goal.install(select=sltr)
.EE
.UNINDENT
.UNINDENT
.sp
Or a convenience notation:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
goal.install(name=\(dqgimp\(dq)
.EE
.UNINDENT
.UNINDENT
.SS Changes in 0.3.1
.SS Query: \fBhy_query_filter_package_in()\fP takes a new parameter
.sp
\fBkeyname\fP parameter was added to the function signature. The new parameter
allows filtering by a specific relation to the resulting packages, for
instance:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
hy_query_filter_package_in(q, HY_PKG_OBSOLETES, HY_EQ, pset)
.EE
.UNINDENT
.UNINDENT
.sp
only leaves the packages obsoleting a package in \fBpset\fP a part of the result.
.SS Removed \fBhy_query_filter_obsoleting()\fP
.sp
The new version of \fBhy_query_filter_package_in()\fP handles this now, see above.
.sp
In Python, the following is no longer supported:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
q = query.filter(obsoleting=1)
.EE
.UNINDENT
.UNINDENT
.sp
The equivalent new syntax is:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
installed = hawkey.Query(sack).filter(reponame=SYSTEM_REPO_NAME)
q = query.filter(obsoletes=installed)
.EE
.UNINDENT
.UNINDENT
.SS Changes in 0.3.2
.SS Removed \fBhy_packagelist_of_obsoletes\fP\&.
.sp
The function was not systematic. Same result is achieved by obtaining obsoleting
reldeps from a package and then trying to find the installed packages that
provide it. In Python:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
q = hawkey.Query(sack).filter(reponame=SYSTEM_REPO_NAME, provides=pkg.obsoletes)
.EE
.UNINDENT
.UNINDENT
.SS Changes in 0.3.3
.SS Renamed \fBhy_package_get_nvra\fP to \fBhy_package_get_nevra\fP
.sp
The old name was by error, the functionality has not changed: this function has
always returned the full NEVRA, skipping the epoch part when it\(aqs 0.
.SS Changes in 0.3.4
.SS Python bindings
.SS \fBpkg.__repr__()\fP is more verbose now
.sp
Previously, \fBrepr(pkg)\fP would yield for instance \fB<_hawkey.Package object,
id: 5>\fP\&. Now more complete information is present, including the package\(aqs
NEVRA and repository: \fB<hawkey.Package object id 5, foo\-2\-9\e.noarch,
@System>\fP\&.
.sp
Also notice that the representation now mentions the final \fBhawkey.Package\fP
type, not \fB_hawkey.Package\fP\&. Note that these are currently the same.
.SS Changes in 0.3.8
.SS Core
.SS New parameter \fBrootdir\fP to \fBhy_sack_create()\fP
.sp
\fBhy_sack_create()\fP now accepts third argument, \fBrootdir\fP\&. This can be used
to tell Hawkey that we are intending to do transactions in a changeroot, not in
the current root. It effectively makes use of the RPM database found under
\fBrootdir\fP\&. To make your code compile in 0.3.8 without changing functionality, change:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
HySack sack = hy_sack_create(cachedir, arch);
.EE
.UNINDENT
.UNINDENT
.sp
to:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
HySack sack = hy_sack_create(cachedir, arch, NULL);
.EE
.UNINDENT
.UNINDENT
.SS Python bindings
.SS Forms recognized by \fBSubject\fP are no longer an instance\-scope setting
.sp
It became necessary to differentiate between the default forms used by
\fBsubject.nevra_possibilities()\fP and
\fBsubject.nevra_possibilities_real()\fP\&. Therefore there is little sense in
setting the default form for an entire \fBSubject\fP instance. The following
code:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
subj = hawkey.Subject(\(dqinput\(dq, form=hawkey.FORM_NEVRA)
result = list(subj.nevra_possibilities())
.EE
.UNINDENT
.UNINDENT
.sp
is thus replaced by:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
subj = hawkey.Subject(\(dqinput\(dq)
result = list(subj.nevra_possibilities(form=hawkey.FORM_NEVRA))
.EE
.UNINDENT
.UNINDENT
.SS Changes in 0.3.9
.SS Core
.SS Flags for \fBhy_sack_create\fP
.sp
\fBhy_sack_create()\fP now accepts fourth argument, \fBflags\fP, introduced to
modify the sack behavior with boolean flags. Currently only one flag is
supported, \fBHY_MAKE_CACHE_DIR\fP, which causes the cache directory to be created
if it doesn\(aqt exist yet. To preserve the previous behavior, change the
following:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
HySack sack = hy_sack_create(cachedir, arch, rootdir);
.EE
.UNINDENT
.UNINDENT
.sp
into:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
HySack sack = hy_sack_create(cachedir, arch, rootdir, HY_MAKE_CACHE_DIR);
.EE
.UNINDENT
.UNINDENT
.SS \fBhy_sack_get_cache_path\fP is renamed to \fBhy_sack_get_cache_dir\fP
.sp
Update your code by mechanically replacing the name.
.SS Python bindings
.SS \fBmake_cache_dir\fP for Sack\(aqs constructor
.sp
A new sack by default no longer automatically creates the cache directory. To
get the old behavior, append \fBmake_cache_dir=True\fP to the
\fI\%Sack.__init__()\fP arguments, that is change the following:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
sack = hawkey.Sack(...)
.EE
.UNINDENT
.UNINDENT
.sp
to:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
sack = hawkey.Sack(..., make_cache_dir=True)
.EE
.UNINDENT
.UNINDENT
.SS \fBcache_path\fP property of \fBSack\fP renamed to \fBcache_dir\fP
.sp
Reflects the similar change in C API.
.SS Changes in 0.3.11
.SS Core
.SS \fBhy_goal_package_obsoletes()\fP removed, \fBhy_goal_list_obsoleted_by_package()\fP provided instead
.sp
\fBhy_goal_package_obsoletes()\fP was flawed in that it only returned a single
obsoleted package (in general, package can obsolete arbitrary number of packages
and upgrade a package of the same name which is also reported as an
obsolete). Use \fBhy_goal_list_obsoleted_by_package()\fP instead, to see the
complete set of packages that inclusion of the given package in an RPM
transaction will cause to be removed.
.SS \fBhy_goal_list_erasures()\fP does not report obsoletes
.sp
In other words, \fBhy_goal_list_erasures()\fP and \fBhy_goal_list_obsoleted()\fP
return disjoint sets.
.SS Python bindings
.sp
Directly reflecting the \fI\%core changes\fP\&. In particular,
instead of:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
obsoleted_pkg = goal.package_obsoletes(pkg)
.EE
.UNINDENT
.UNINDENT
.sp
use:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
obsoleted = goal.obsoleted_by_package(pkg) # list
obsoleted_pkg = obsoleted[0]
.EE
.UNINDENT
.UNINDENT
.SS Changes in 0.4.5
.SS Core
.SS Query: \fBhy_query_filter_latest()\fP now filter latest packages ignoring architecture
.sp
For old function behavior use new function \fBhy_query_filter_latest_per_arch()\fP
.SS Python bindings
.sp
In Python\(aqs \fBQuery\fP option \fBlatest\fP in \fBQuery.filter()\fP now filter
only the latest packages ignoring architecture. The original semantics for filtering
latest packages for each arch is now available via \fBlatest_per_arch\fP option.
.sp
For example there are these packages in sack:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
glibc\-2.17\-4.fc19.x86_64
glibc\-2.16\-24.fc18.x86_64
glibc\-2.16\-24.fc18.i686

>>> q = hawkey.Query(self.sack).filter(name=\(dqglibc\(dq)
>>> map(str, q.filter(latest=True))
[\(aqglibc\-2.17\-4.fc19.x86_64\(aq]

>>> map(str, q.filter(latest_per_arch=True))
[\(aqglibc\-2.17\-4.fc19.x86_64\(aq, \(aqglibc\-2.16\-24.fc18.i686\(aq]
.EE
.UNINDENT
.UNINDENT
.SS Changes in 0.4.13
.SS Core
.SS Deprecated \fBhy_package_get_update_*\fP
.sp
The functions were deprecated because there can be multiple advisories referring
to a single package. Please use the new function \fBhy_package_get_advisories()\fP
which returns all these advisories. New functions \fBhy_advisory_get_*\fP provide
the data retrieved by the deprecated functions.
.sp
The only exception is the \fBhy_package_get_update_severity()\fP which will be
dropped without any replacement. However advisory types and severity levels are
distinguished from now and the type is accessible via \fBhy_advisory_get_type()\fP\&.
Thus enum \fBHyUpdateSeverity\fP was also deprecated. A new \fBHyAdvisoryType\fP
should be used instead.
.sp
The old functions will be dropped after 2014\-07\-07.
.SS Changes in 0.4.15
.SS Core
.SS \fBhy_goal_write_debugdata()\fP takes a directory parameter
.sp
\fBhy_goal_write_debugdata()\fP has a new \fIconst char *dir\fP argument to communicate the target directory for the debugging data. The old call:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
hy_goal_write_debugdata(goal);
.EE
.UNINDENT
.UNINDENT
.sp
should be changed to achieve the same behavior to:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
hy_goal_write_debugdata(goal, \(dq./debugdata\(dq);
.EE
.UNINDENT
.UNINDENT
.SS Python bindings
.SS \fBGoal.write_debugdata()\fP takes a directory parameter
.sp
Analogous to \fI\%core changes\fP\&.
.SS Package: string attributes are represented by Unicode object
.sp
Attributes \fBbaseurl\fP, \fBlocation\fP, \fBsourcerpm\fP, \fBversion\fP, \fBrelease\fP, \fBname\fP, \fBarch\fP, \fBdescription\fP, \fBevr\fP, \fBlicense\fP, \fBpackager\fP, \fBreponame\fP, \fBsummary\fP and \fBurl\fP of Package object return Unicode string.
.SS Changes in 0.4.18
.SS Core
.SS Deprecated \fBhy_advisory_get_filenames\fP
.sp
The function was deprecated because we need more information about packages
listed in an advisory than just file names. Please use the new function
\fBhy_advisory_get_packages()\fP in combination with
\fBhy_advisorypkg_get_string()\fP to obtain the data originally provided by the
deprecated function.
.sp
The old function will be dropped after 2014\-10\-15 AND no sooner than in 0.4.21.
.SS Python bindings
.SS \fBRepo()\fP does not accept \fBcost\fP keyword argument
.sp
Instead of:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
r = hawkey.Repo(\(aqname\(aq, cost=30)
.EE
.UNINDENT
.UNINDENT
.sp
use:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
r = hawkey.Repo(\(aqname\(aq)
r.cost = 30
.EE
.UNINDENT
.UNINDENT
.sp
Also previously when no \fBcost\fP was given it defaulted to 1000. Now the default is 0. Both these aspects were present by mistake and the new interface is consistent with the C library.
.SS Deprecated \fB_hawkey.Advisory.filenames\fP
.sp
The attribute was deprecated because the underlying C function was also
deprecated. Please use the new attribute \fBpackages\fP and the attribute
\fBfilename\fP of the returned objects to obtain the data originally provided by
the deprecated attribute.
.sp
The old attribute will be dropped after 2014\-10\-15 AND no sooner than in 0.4.21.
.SS Changes in 0.4.19
.SS Python bindings
.SS Advisory attributes in Unicode
.sp
All string attributes of \fBAdvisory\fP and \fBAdvisoryRef\fP objects (except the
deprecated \fBfilenames\fP attribute) are Unicode objects now.
.SS Changes in 0.5.2
.SS Core
.SS \fBhy_chksum_str\fP returns NULL
.sp
Previously, the function \fBhy_chksum_str\fP would cause a segmentation fault when it was used
with incorrect type value. Now it correctly returns NULL if type parameter does not correspond
to any of expected values.
.SS Changes in 0.5.3
.SS Core
.SS New parameter \fBlogfile\fP to \fBhy_sack_create()\fP
.sp
\fBhy_sack_create()\fP now accepts fifth argument, \fBlogfile\fP to customize log file path.
If NULL parameter as \fBlogfile\fP is given, then all debug records are written to \fBhawkey.log\fP
in \fBcachedir\fP\&. To make your code compile in 0.5.3 without changing functionality, change:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
HySack sack = hy_sack_create(cachedir, arch, rootdir, 0);
.EE
.UNINDENT
.UNINDENT
.sp
to:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
HySack sack = hy_sack_create(cachedir, arch, rootdir, NULL, 0);
.EE
.UNINDENT
.UNINDENT
.SS Deprecated \fBhy_create_cmdline_repo()\fP
.sp
The function will be removed since \fIhy_add_cmdline_package\fP creates cmdline repository automatically.
.sp
The function will be dropped after 2015\-06\-23 AND no sooner than in 0.5.8.
.SS Python bindings
.SS New optional parameter \fBlogfile\fP to \fBSack\fP constructor
.sp
This addition lets user specify log file path from \fI\%Sack.__init__()\fP
.SS \fBcache_path\fP property of \fBSack\fP renamed to \fBcache_dir\fP
.sp
This change was already announced but it actually never happened.
.SS Deprecated \fBSack\fP method \fBcreate_cmdline_repo()\fP
.sp
The method will be removed since \fI\%Sack.add_cmdline_package()\fP creates cmdline repository automatically.
.sp
The method will be dropped after 2015\-06\-23 AND no sooner than in 0.5.8.
.SS Changes in 0.5.4
.SS Python bindings
.SS Goal: \fBinstall()\fP takes a new optional parameter
.sp
If the \fBoptional\fP parameter is set to \fBTrue\fP, hawkey silently skips packages that can not
be installed.
.SS Changes in 0.5.5
.SS Core
.SS Renamed \fBhy_sack_load_yum_repo\fP to \fBhy_sack_load_repo\fP
.sp
Hawkey is package manager agnostic and the \fByum\fP phrase could be misleading.
.sp
The function will be dropped after 2015\-10\-27 AND no sooner than in 0.5.8.
.SS Python bindings
.SS Sack method \fIload_yum_repo\fP has been renamed to \fI\%Sack.load_repo()\fP
.sp
Hawkey is package manager agnostic and the \fByum\fP phrase could be misleading.
.sp
The method will be dropped after 2015\-10\-27 AND no sooner than in 0.5.8.
.SS Changes in 0.5.7
.SS Python bindings
.SS Package: file attribute is represented by list of Unicode objects
.SS Sack: \fIlist_arches\fP method returns list of Unicode objects
.SS Changes in 0.5.9
.SS Core
.SS Deprecated \fBhy_goal_req_has_distupgrade()\fP, \fBhy_goal_req_has_erase()\fP and \fBhy_goal_req_has_upgrade()\fP functions
.sp
To make your code compile in 0.5.9 without changing functionality, change:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
hy_goal_req_has_distupgrade_all(goal)
hy_goal_req_has_erase(goal)
hy_goal_req_has_upgrade_all(goal)
.EE
.UNINDENT
.UNINDENT
.sp
to:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
hy_goal_has_actions(goal, HY_DISTUPGRADE_ALL)
hy_goal_has_actions(goal, HY_ERASE)
hy_goal_has_actions(goal, HY_UPGRADE_ALL)
.EE
.UNINDENT
.UNINDENT
.sp
respectively
.SS Python bindings
.SS Deprecated Goal methods \fBGoal.req_has_distupgrade_all()\fP, \fBGoal.req_has_erase()\fP and \fBGoal.req_has_upgrade_all()\fP
.sp
To make your code compatible with hawkey 0.5.9 without changing functionality,
change:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
goal.req_has_distupgrade_all()
goal.req_has_erase()
goal.req_has_upgrade_all()
.EE
.UNINDENT
.UNINDENT
.sp
to:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
goal.actions & hawkey.DISTUPGRADE_ALL
goal.actions & hawkey.ERASE
goal.actions & hawkey.UPGRADE_ALL
.EE
.UNINDENT
.UNINDENT
.sp
respectively
.SS Changes in 0.6.2
.SS Core
.sp
The \fBhy_advisory_get_filenames()\fP API call, the corresponding Python
property \fBfilenames\fP of class \fBAdvisory\fP are removed.
Instead, iterate over \fBhy_advisory_get_packages()\fP with
\fBhy_advisorypkg_get_string()\fP and \fBHY_ADVISORYPKG_FILENAME\fP\&.  No
known hawkey API consumers were using this call.
.sp
Hawkey now has a dependency on GLib.  Aside from the above
\fBhy_advisory_get_filenames()\fP call, the Python API is fully
preserved.  The C API has minor changes, but the goal is to avoid
causing a significant amount of porting work for existing consumers.
.sp
The \fBhy_package_get_files\fP API call now returns a \fBchar **\fP,
allocated via \fIg_malloc\fP\&.  Free with \fIg_strfreev\fP\&.
.sp
The \fBHyStringArray\fP type is removed, as nothing now uses it.
.sp
\fBHyPackageList\fP is now just a \fBGPtrArray\fP, though
the existing API is converted into wrappers.  Notably, this means
you can now use \fBg_ptr_array_unref()\fP\&.
.SS Python bindings
.sp
Aside from the one change below, the Python bindings should be
unaffected by the C API changes.
.SS Advisory: The \fBfilename\fP property is removed along with the C API
.SH FAQ
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%FAQ\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Getting Started\fP
.INDENT 2.0
.IP \(bu 2
\fI\%How do I build it?\fP
.IP \(bu 2
\fI\%Are there examples using hawkey?\fP
.UNINDENT
.IP \(bu 2
\fI\%Using Hawkey\fP
.INDENT 2.0
.IP \(bu 2
\fI\%How do I obtain the repo metadata files to feed to Hawkey?\fP
.IP \(bu 2
\fI\%Why is a tool to do the downloads not integrated into Hawkey?\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Getting Started
.SS How do I build it?
.sp
See the \fI\%README\fP\&.
.SS Are there examples using hawkey?
.sp
Yes, look at:
.INDENT 0.0
.IP \(bu 2
\fI\%unit tests\fP
.IP \(bu 2
\fI\%The Hawkey Testing Hack\fP
.IP \(bu 2
a more complex example is \fI\%DNF\fP, the Yum fork using hawkey for backend.
.UNINDENT
.SS Using Hawkey
.SS How do I obtain the repo metadata files to feed to Hawkey?
.sp
It is entirely up to you. Hawkey does not provide any means to do this
automatically, for instance from your \fI/etc/yum.repos.d\fP configuration. Use or
build tools to do that. For instance, both Yum and DNF deals with the same
problem and inside they employ \fI\%urlgrabber\fP to
fetch the files. A general solution if you work in C is for instance \fI\%libcurl\fP\&.  If you are building a nice downloading library that
integrates well with hawkey, let us know.
.SS Why is a tool to do the downloads not integrated into Hawkey?
.sp
Because downloading things from remote servers is a differnt domain full of its
own complexities like HTTPS, parallel downloads, error handling and error
recovery to name a few. Downloading is a concern that can be naturally separated
from other parts of package metadata managing.
.SH PYTHON-HAWKEY TUTORIAL
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%python\-hawkey Tutorial\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Setup\fP
.IP \(bu 2
\fI\%The Sack Object\fP
.IP \(bu 2
\fI\%Loading RPMDB\fP
.IP \(bu 2
\fI\%Loading Repositories\fP
.IP \(bu 2
\fI\%Case for Loading the Filelists\fP
.IP \(bu 2
\fI\%Building and Reusing the Repo Cache\fP
.IP \(bu 2
\fI\%Queries\fP
.IP \(bu 2
\fI\%Resolving things with Goals\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Selector Installs\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBIMPORTANT:\fP
.INDENT 0.0
.INDENT 3.5
Please consult every usage of the library with \fI\%python\-hawkey Reference Manual\fP to be sure
what are you doing. The examples mentioned here are supposed to be as simple
as possible and may ignore some minor corner cases.
.UNINDENT
.UNINDENT
.SS Setup
.sp
First of, make sure hawkey is installed on your system, this should work from your terminal:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> import hawkey
.EE
.UNINDENT
.UNINDENT
.SS The Sack Object
.sp
\fISack\fP is an abstraction for a collection of packages. Sacks in hawkey are
toplevel objects carrying much of hawkey\(aqs of functionality. You\(aqll want to
create one:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> sack = hawkey.Sack()
>>> len(sack)
0
.EE
.UNINDENT
.UNINDENT
.sp
Initially, the sack contains no packages.
.SS Loading RPMDB
.sp
hawkey is a lib for listing, querying and resolving dependencies of \fIpackages\fP
from \fIrepositories\fP\&. On most linux distributions you always have at least \fIthe
system repo\fP (in Fedora it is the RPM database). To load it:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> sack.load_system_repo()
>>> len(sack)
1683
.EE
.UNINDENT
.UNINDENT
.sp
Hawkey always knows the name of every repository. The system repository is always
set to \fI\%hawkey.SYSTEM_REPO_NAME\fP\&. and the client is responsible for naming
the available repository metadata.
.SS Loading Repositories
.sp
Let\(aqs be honest here: all the fun in packaging comes from packages you haven\(aqt
installed yet. Information about them, their \fImetadata\fP, can be obtained from
different sources and typically they are downloaded from an HTTP mirror (another
possibilities are FTP server, NFS mount, DVD distribution media, etc.). Hawkey
does not provide any means to discover and obtain the metadata locally: it is up
to the client to provide valid readable paths to the repository metadata XML
files. Structures used for passing the information to hawkey are the hawkey
\fI\%Repos\fP\&. Suppose we somehow obtained the metadata and placed it in
\fB/home/akozumpl/tmp/repodata\fP\&. We can then load the metadata into hawkey:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> path = \(dq/home/akozumpl/tmp/repodata/%s\(dq
>>> repo = hawkey.Repo(\(dqexperimental\(dq)
>>> repo.repomd_fn = path % \(dqrepomd.xml\(dq
>>> repo.primary_fn = path % \(dqf7753a2636cc89d70e8aaa1f3c08413ab78462ca9f48fd55daf6dedf9ab0d5db\-primary.xml.gz\(dq
>>> repo.filelists_fn = path % \(dq0261e25e8411f4f5e930a70fa249b8afd5e86bb9087d7739b55be64b76d8a7f6\-filelists.xml.gz\(dq
>>> sack.load_repo(repo, load_filelists=True)
>>> len(sack)
1685
.EE
.UNINDENT
.UNINDENT
.sp
The number of packages in the Sack will increase by the number of packages found
in the repository (two in this case, it is an experimental repo after all).
.SS Case for Loading the Filelists
.sp
What the \fBload_filelists=True\fP argument to \fI\%load_repo()\fP above does is
instruct hawkey to process the \fB<hash>filelists.xml.gz\fP file we passed in and
which contains structured list of absolute paths to all files of all packages
within the repo. This information can be used for two purposes:
.INDENT 0.0
.IP \(bu 2
Finding a package providing given file. For instance, you need the file
\fB/usr/share/man/man3/fprintf.3.gz\fP which is not installed. Consulting
filelists (directly or through hawkey) can reveal the file is in the
\fBman\-pages\fP package.
.IP \(bu 2
Depsolving. Some packages require concrete files as their dependencies. To
know if these are resolvable and how, the solver needs to know what package
provides what files.
.UNINDENT
.sp
Some files provided by a package (e.g those in \fB/usr/bin\fP) are always visible
even without loading the filelists. Well\-behaved packages requiring only those
can be thus resolved directly. Unortunately, there are packages that don\(aqt
behave and it is hard to tell in advance when you\(aqll deal with one.
.sp
The strategy for using \fBload_filelists=True\fP is thus:
.INDENT 0.0
.IP \(bu 2
Use it if you know you\(aqll do resolving (i.e. you\(aqll use \fBGoal\fP).
.IP \(bu 2
Use it if you know you\(aqll be trying to match files to their packages.
.IP \(bu 2
Use it if you are not sure.
.UNINDENT
.SS Building and Reusing the Repo Cache
.sp
Internally to hold the package information and perform canonical resolving
hawkey uses \fI\%Libsolv\fP\&. One great benefit this library offers is providing
writing and reading of metadata cache files in libsolv\(aqs own binary format
(files with \fB\&.solv\fP extension, typically). At a cost of few hundreds of
milliseconds, using the solv files reduces repo load times from seconds to tens
of milliseconds. It is thus a good idea to write and use the solv files every
time you plan to use the same repo for more than one Sack (which is at least
every time your hawkey program is run). To do that use \fBbuild_cache=True\fP with
\fI\%load_repo()\fP and \fI\%load_system_repo()\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> sack = hawkey.Sack(make_cache_dir=True)
>>> sack.load_system_repo(build_cache=True)
.EE
.UNINDENT
.UNINDENT
.sp
By default, Hawkey creates \fB@System.cache\fP under the
\fB/var/tmp/hawkey\-<your_login>\-<random_hash>\fP directory. This is the hawkey
cache directory, which you can always delete later (deleting the cache files in
the process). The \fB\&.solv\fP files are picked up automatically the next time you
try to create a hawkey sack. Except for a much higher speed of the operation
this will be completely transparent to you:
.sp
.EX
>>> s2 = hawkey.Sack()
>>> s2.load_system_repo()
.EE
.sp
By the way, the cache directory (if not set otherwise) also contains a logfile
with some boring debugging information.
.SS Queries
.sp
Query is the means in hawkey of finding a package based on one or more criteria
(name, version, repository of origin). Its interface is loosely based on
\fI\%Django\(aqs QuerySets\fP, the main concepts being:
.INDENT 0.0
.IP \(bu 2
a fresh Query object matches all packages in the Sack and the selection is
gradually narrowed down by calls to \fBQuery.filter()\fP
.IP \(bu 2
applying a \fBQuery.filter()\fP does not start to evaluate the Query, i.e. the
Query is lazy. Query is only evaluated when we explicitly tell it to or when
we start to iterate it.
.IP \(bu 2
use Python keyword arguments to \fBQuery.filter()\fP to specify the filtering
criteria.
.UNINDENT
.sp
For instance, let\(aqs say I want to find all installed packages which name ends
with \fBgtk\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> q = hawkey.Query(sack).filter(reponame=hawkey.SYSTEM_REPO_NAME, name__glob=\(aq*gtk\(aq)
>>> for pkg in q:
\&...     print str(pkg)
\&...
NetworkManager\-gtk\-1:0.9.4.0\-9.git20120521.fc17.x86_64
authconfig\-gtk\-6.2.1\-1.fc17.x86_64
clutter\-gtk\-1.2.0\-1.fc17.x86_64
libchamplain\-gtk\-0.12.2\-1.fc17.x86_64
libreport\-gtk\-2.0.10\-3.fc17.x86_64
pinentry\-gtk\-0.8.1\-6.fc17.x86_64
python\-slip\-gtk\-0.2.20\-2.fc17.noarch
transmission\-gtk\-2.50\-2.fc17.x86_64
usermode\-gtk\-1.109\-1.fc17.x86_64
webkitgtk\-1.8.1\-2.fc17.x86_64
xdg\-user\-dirs\-gtk\-0.9\-1.fc17.x86_64
.EE
.UNINDENT
.UNINDENT
.sp
Or I want to find the latest version of all \fBpython\fP packages the Sack knows of:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> q.clear()
>>> q = q.filter(name=\(aqpython\(aq, latest_per_arch=True)
>>> for pkg in q:
\&...     print str(pkg)
\&...
python\-2.7.3\-6.fc17.x86_64
.EE
.UNINDENT
.UNINDENT
.sp
You can also test a \fBQuery\fP for its truth value. It will be true whenever
the query matched at least one package:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> q = hawkey.Query(sack).filter(file=\(aq/boot/vmlinuz\-3.3.4\-5.fc17.x86_64\(aq)
>>> if q:
\&...     print \(aqmatch\(aq
\&...
match
>>> q = hawkey.Query(sack).filter(file=\(aq/booty/vmlinuz\-3.3.4\-5.fc17.x86_64\(aq)
>>> if q:
\&...     print \(aqmatch\(aq
\&...
>>> if not q:
\&...     print \(aqno match\(aq
\&...
no match
.EE
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If the Query hasn\(aqt been evaluated already then it is evaluated whenever it\(aqs
length is taken (either via \fBlen(q)\fP or \fBq.count()\fP), when it is tested for
truth and when it is explicitly evaluated with \fBq.run()\fP\&.
.UNINDENT
.UNINDENT
.SS Resolving things with Goals
.sp
Many \fI\%Sack\fP sessions culminate in a bout of dependency resolving, that
is answering a question along the lines of \(dqI have a package X in a repository
here, what other packages do I need to install/update to have X installed and
all its dependencies recursively satisfied?\(dq Suppose we want to install \fI\%the RTS
game Spring\fP\&. First let\(aqs locate the latest version of
the package in repositories:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> q = hawkey.Query(sack).filter(name=\(aqspring\(aq, latest_per_arch=True)
>>> pkg = hawkey.Query(sack).filter(name=\(aqspring\(aq, latest_per_arch=True)[0]
>>> str(pkg)
\(aqspring\-88.0\-2.fc17.x86_64\(aq
>>> pkg.reponame
\(aqfedora\(aq
.EE
.UNINDENT
.UNINDENT
.sp
Then build the \fBGoal\fP object and tell it our goal is installing the
\fBpkg\fP\&. Then we fire off the libsolv\(aqs dependency resolver by running the
goal:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> g = hawkey.Goal(sack)
>>> g.install(pkg)
>>> g.run()
True
.EE
.UNINDENT
.UNINDENT
.sp
\fBTrue\fP as a return value here indicates that libsolv could find a solution to
our goal. This is not always the case, there are plenty of situations when there
is no solution, the most common one being a package should be installed but one
of its dependencies is missing from the sack.
.sp
The three methods \fBGoal.list_installs()\fP, \fBGoal.list_upgrades()\fP and
\fBGoal.list_erasures()\fP can show which packages should be
installed/upgraded/erased to satisfy the packaging goal we set out to achieve
(the mapping of \fBstr()\fP over the results below ensures human readable
package names instead of numbers are presented):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> map(str, g.list_installs())
[\(aqspring\-88.0\-2.fc17.x86_64\(aq, \(aqspring\-installer\-20090316\-10.fc17.x86_64\(aq, \(aqspringlobby\-0.139\-3.fc17.x86_64\(aq, \(aqspring\-maps\-default\-0.1\-8.fc17.noarch\(aq, \(aqwxBase\-2.8.12\-4.fc17.x86_64\(aq, \(aqwxGTK\-2.8.12\-4.fc17.x86_64\(aq, \(aqrb_libtorrent\-0.15.9\-1.fc17.x86_64\(aq, \(aqGeoIP\-1.4.8\-2.1.fc17.x86_64\(aq]
>>> map(str, g.list_upgrades())
[]
>>> map(str, g.list_erasures())
[]
.EE
.UNINDENT
.UNINDENT
.sp
So what does it tell us? That given the state of the given system and the given
repository we used, 8 packages need to be installed,
\fBspring\-88.0\-2.fc17.x86_64\fP itself included. No packages need to be upgraded
or erased.
.SS Selector Installs
.sp
For certain simple and commonly used queries we can do installs
directly. Instead of executing a query however we instantiate and pass the
\fBGoal.install()\fP method a \fBSelector\fP:
.sp
.EX
>>> g = hawkey.Goal(sack)
>>> sltr = hawkey.Selector(sack).set(name=\(aqemacs\-nox\(aq)
>>> g.install(select=sltr)
>>> g.run()
True
>>> map(str, g.list_installs())
[\(aqspring\-88.0\-2.fc17.x86_64\(aq, \(aqspring\-installer\-20090316\-10.fc17.x86_64\(aq, \(aqspringlobby\-0.139\-3.fc17.x86_64\(aq, \(aqspring\-maps\-default\-0.1\-8.fc17.noarch\(aq, \(aqwxBase\-2.8.12\-4.fc17.x86_64\(aq, \(aqwxGTK\-2.8.12\-4.fc17.x86_64\(aq, \(aqrb_libtorrent\-0.15.9\-1.fc17.x86_64\(aq, \(aqGeoIP\-1.4.8\-2.1.fc17.x86_64\(aq]
>>> len(g.list_upgrades())
0
>>> len(g.list_erasures())
0
.EE
.sp
Notice we arrived at the same result as before, when a query was constructed and
iterated first. What \fBSelector\fP does when passed to \fBGoal.install()\fP
is tell hawkey to examine its settings and without evaluating it as a
\fBQuery\fP it instructs libsolv to find \fIthe best matching package\fP for it
and add that for installation. It saves user some decisions like which version
should be installed or what architecture (this gets very relevant with multiarch
libraries).
.sp
So Selectors usually only install a single package. If you mean to install \fIall
packages\fP matching an arbitrarily complex query, just use the method describe
above:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> map(goal.install, q)
.EE
.UNINDENT
.UNINDENT
.SH PYTHON-HAWKEY REFERENCE MANUAL
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%python\-hawkey Reference Manual\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Introduction\fP
.IP \(bu 2
\fI\%Contents\fP
.UNINDENT
.UNINDENT
.SS Introduction
.sp
This reference manual describes Python API to the library. For a quick start
take a look at \fI\%python\-hawkey Tutorial\fP\&. To be sure that you are familiar with our
deprecation policy, see \fI\%API Changes\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The API consists of exactly those elements described in this document, items
not documented here can change from release to release. Opening a \fI\%bugzilla\fP
if certain needed functionality is not exposed is the right thing to do.
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
The manual is not complete yet \- the features are being added incrementally
these days.
.UNINDENT
.UNINDENT
.SS Contents
.sp
API Documentation Contents
.SS Sack\-\-\-The fundamental hawkey structure
.INDENT 0.0
.TP
.B class  hawkey.Sack
Instances of \fI\%hawkey.Sack\fP represent collections of packages. An
application typically needs at least one instance because it provides much of
the hawkey\(aqs functionality.
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Any package instance is not supposed to work interchangeably between
\fBhawkey.Query\fP, \fBhawkey.Selector\fP or \fBhawkey.Goal\fP
created from different \fI\%hawkey.Sack\fP\&. Usually for common tasks
there is no need to initialize two or more \fISacks\fP in your program.
Sacks cannot be deeply copied.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cache_dir
A read\-only string property giving the path to the location where a
metadata cache is stored.
.UNINDENT
.INDENT 7.0
.TP
.B installonly
A write\-only sequence of strings property setting the provide names of
packages that should only ever be installed, never upgraded.
.UNINDENT
.INDENT 7.0
.TP
.B installonly_limit
A write\-only integer property setting how many installonly packages with
the same name are allowed to be installed concurrently. If \fB0\fP, any
number of packages can be installed.
.UNINDENT
.INDENT 7.0
.TP
.B __init__(cachedir=_CACHEDIR, arch=_ARCH, rootdir=_ROOTDIR, pkgcls=hawkey.Package, pkginitval=None, make_cache_dir=False, logfile=_LOGFILE)
Initialize the sack with a default cache directory, log file location set
to \fBhawkey.log\fP in the cache directory, an automatically detected
architecture and the current root (\fB/\fP) as an installroot. The cache is
disabled by default.
.sp
\fIcachedir\fP is a string giving a path of a cache location.
.sp
\fIarch\fP is a string specifying an architecture.
.sp
\fIrootdir\fP is a string giving a path to an installroot.
.sp
\fIpkgcls\fP is a class of packages retrieved from the sack. The class\(aq
\fB__init__\fP method must accept two arguments. The first argument is a tuple
of the sack and the ID of the package. The second argument is the
\fIpkginitval\fP argument. \fIpkginitval\fP cannot be \fBNone\fP if \fIpkgcls\fP is
specified.
.sp
\fImake_cache_dir\fP is a boolean that specifies whether the cache should be
used to speedup loading of repositories or not (see
\fI\%Building and Reusing the Repo Cache\fP).
.sp
\fIlogfile\fP is a string giving a path of a log file location.
.UNINDENT
.INDENT 7.0
.TP
.B __len__()
Returns the number of the packages loaded into the sack.
.UNINDENT
.INDENT 7.0
.TP
.B add_cmdline_package(filename)
Add a package to a command line repository and return it. The package is specified as a string \fIfilename\fP of an RPM file. The command line repository will be automatically created if doesn\(aqt exist already. It could be referenced later by \fI\%hawkey.CMDLINE_REPO_NAME\fP name.
.UNINDENT
.INDENT 7.0
.TP
.B add_excludes(packages)
Add a sequence of packages that cannot be fetched by Queries nor Selectors.
.UNINDENT
.INDENT 7.0
.TP
.B add_includes(packages)
Add a sequence of the only packages that can be fetched by Queries or
Selectors.
.sp
This is the inverse operation of \fI\%add_excludes()\fP\&. Any package that
is not in the union of all the included packages is excluded. This works in
conjunction with exclude and doesn\(aqt override it. So, if you both include
and exclude the same package, the package is considered excluded no matter
of the order.
.UNINDENT
.INDENT 7.0
.TP
.B disable_repo(name)
Disable the repository identified by a string \fIname\fP\&. Packages in that
repository cannot be fetched by Queries nor Selectors.
.UNINDENT
.INDENT 7.0
.TP
.B enable_repo(name)
Enable the repository identified by a string \fIname\fP\&. Packages in that
repository can be fetched by Queries or Selectors.
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Execution of \fI\%add_excludes()\fP, \fI\%add_includes()\fP,
\fI\%disable_repo()\fP or \fI\%enable_repo()\fP methods could cause
inconsistent results in previously evaluated \fBQuery\fP,
\fBSelector\fP or \fBGoal\fP\&. The rule of thumb is
to exclude/include packages, enable/disable repositories at first and
then do actual computing using \fBQuery\fP, \fBSelector\fP
or \fBGoal\fP\&. For more details see
\fI\%developer discussion\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B evr_cmp(evr1, evr2)
Compare two EVR strings and return a negative integer if \fIevr1\fP < \fIevr2\fP,
zero if \fIevr1\fP == \fIevr2\fP or a positive integer if \fIevr1\fP > \fIevr2\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B get_running_kernel()
Detect and return the package of the currently running kernel. If the
package cannot be found, \fBNone\fP is returned.
.UNINDENT
.INDENT 7.0
.TP
.B list_arches()
List strings giving all the supported architectures.
.UNINDENT
.INDENT 7.0
.TP
.B load_system_repo(repo=None, build_cache=False)
Load the information about the packages in the system repository (in Fedora
it is the RPM database) into the sack. This makes the dependency solving
aware of the already installed packages. The system repository is always
set to \fI\%hawkey.SYSTEM_REPO_NAME\fP\&. The information is not written to
the cache by default.
.sp
\fIrepo\fP is an optional \fI\%Repo\fP object that represents the system
repository. The object is updated during the loading.
.sp
\fIbuild_cache\fP is a boolean that specifies whether the information should be
written to the cache (see \fI\%Building and Reusing the Repo Cache\fP).
.UNINDENT
.INDENT 7.0
.TP
.B load_repo(repo, build_cache=False, load_filelists=False, load_presto=False, load_updateinfo=False)
Load the information about the packages in a \fI\%Repo\fP into the sack.
This makes the dependency solving aware of these packages. The information
is not written to the cache by default.
.sp
\fIrepo\fP is the \fI\%Repo\fP object to be processed. At least its
\fI\%Repo.repomd_fn\fP must be set. If the cache has to be updated,
\fI\%Repo.primary_fn\fP is needed too. Some information about the loading
process and some results of it are written into the internal state of the
repository object.
.sp
\fIbuild_cache\fP is a boolean that specifies whether the information should be
written to the cache (see \fI\%Building and Reusing the Repo Cache\fP).
.sp
\fIload_filelists\fP, \fIload_presto\fP and \fIload_updateinfo\fP are booleans that
specify whether the \fI\%Repo.filelists_fn\fP, \fI\%Repo.presto_fn\fP and
\fI\%Repo.updateinfo_fn\fP files of the repository should be processed.
These files may contain information needed for dependency solving,
downloading or querying of some packages. Enable it if you are not sure (see
\fI\%Case for Loading the Filelists\fP).
.UNINDENT
.UNINDENT
.SS Error handling
.sp
When an error or an unexpected event occurs during a Hawkey routine, an
exception is raised:
.INDENT 0.0
.IP \(bu 2
if it is a general error that could be common to other Python programs, one of
the standard Python built\-in exceptions is raised. For instance, \fBIOError\fP
and \fBTypeError\fP can be raised from Hawkey.
.IP \(bu 2
programming errors within Hawkey that cause unexpected or invalid states raise
the standard \fBAssertionError\fP\&. These should be reported as bugs against
Hawkey.
.IP \(bu 2
programming errors due to incorrect use of the library usually produce
\fBhawkey.ValueException\fP or one of its subclasses, \fBQueryException\fP (poorly
formed Query) or \fBArchException\fP (unrecognized architecture).
.IP \(bu 2
sometimes there is a close call between blaming the error on an input
parameter or on something else, beyond the programmer\(aqs
control. \fBhawkey.RuntimeException\fP is generally used in this case.
.IP \(bu 2
\fBhawkey.ValidationException\fP is raised when a function call performs a
preliminary check before proceeding with the main operation and this check
fails.
.UNINDENT
.sp
The class hierarchy for Hawkey exceptions is:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
+\-\- hawkey.Exception
     +\-\- hawkey.ValueException
     |    +\-\- hawkey.QueryException
     |    +\-\- hawkey.ArchException
     +\-\- hawkey.RuntimeException
     +\-\- hawkey.ValidationException
.EE
.UNINDENT
.UNINDENT
.SS Module level constants
.INDENT 0.0
.TP
.B hawkey.CMDLINE_REPO_NAME
The string name of the command line repository.
.UNINDENT
.INDENT 0.0
.TP
.B hawkey.SYSTEM_REPO_NAME
The string name of the system repository.
.UNINDENT
.SS Repositories
.INDENT 0.0
.TP
.B class  hawkey.Repo
Instances of \fI\%hawkey.Repo\fP point to metadata of packages that are
available to be installed. The metadata are expected to be in the \(dqrpm\-md\(dq
format. \fI\%librepo\fP may help you with
downloading the required files.
.INDENT 7.0
.TP
.B cost
An integer specifying a relative cost of accessing this repository. This
value is compared when the priorities of two repositories are the same. The
repository with \fIthe lowest cost\fP is picked. It is useful to make the
library prefer on\-disk repositories to remote ones.
.UNINDENT
.INDENT 7.0
.TP
.B filelists_fn
A valid string path to the readable \(dqfilelists\(dq XML file if set.
.UNINDENT
.INDENT 7.0
.TP
.B name
A string name of the repository.
.UNINDENT
.INDENT 7.0
.TP
.B presto_fn
A valid string path to the readable \(dqprestodelta.xml\(dq (also called
\(dqdeltainfo.xml\(dq) file if set.
.UNINDENT
.INDENT 7.0
.TP
.B primary_fn
A valid string path to the readable \(dqprimary\(dq XML file if set.
.UNINDENT
.INDENT 7.0
.TP
.B priority
An integer priority value of this repository. If there is more than one
candidate package for a particular operation, the one from the repository
with \fIthe lowest priority\fP value is picked, possibly despite being less
convenient otherwise (e.g. by being a lower version).
.UNINDENT
.INDENT 7.0
.TP
.B repomd_fn
A valid string path to the readable \(dqrepomd.xml\(dq file if set.
.UNINDENT
.INDENT 7.0
.TP
.B updateinfo_fn
A valid string path to the readable \(dqupdateinfo.xml\(dq file if set.
.UNINDENT
.INDENT 7.0
.TP
.B __init__(name)
Initialize the repository with empty \fI\%repomd_fn\fP, \fI\%primary_fn\fP,
\fI\%filelists_fn\fP and \fI\%presto_fn\fP\&. The priority and the cost are
set to \fB0\fP\&.
.sp
\fIname\fP is a string giving the name of the repository. The name should not
be equal to \fI\%hawkey.SYSTEM_REPO_NAME\fP nor
\fI\%hawkey.CMDLINE_REPO_NAME\fP
.UNINDENT
.UNINDENT
.sp
Indices:
.INDENT 0.0
.IP \(bu 2
\fI\%Index\fP
.UNINDENT
.SH DESIGN RATIONALE
.SS Selectors are not Queries
.sp
Since both a Query and a Selector work to limit the set of all Sack\(aqs packages
to a subset, it can be suggested the two concepts should be the same and
e.g. Queries should be used for Goal specifications instead of Selectors:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// create sack, goal, ...
HyQuery q = hy_query_create(sack);
hy_query_filter(q, HY_PKG_NAME, HY_EQ, \(dqanaconda\(dq)
hy_goal_install_query(q)
.EE
.UNINDENT
.UNINDENT
.sp
This arrangment was in fact used in hawkey prior to version 0.3.0, just because
Queries looked like a convenient structure to hold this kind of information. It
was unfortunately confusing for the programmers: notice how evaluating the Query
\fBq\fP would generally produce several packages (\fBanaconda\fP for different
architectures and then different versions) but somehow when the same Query is
passed into the goal methods it always results in up to one pacakge selected for
the operation. This is a principal discrepancy. Further, Query is universal and
allows one to limit the package set with all sorts of criteria, matched in
different ways (substrings, globbing, set operation) while Selectors only
support few. Finally, while a fresh Query with no filters applied corresponds to
all packages of the Sack, a fresh Selector with no limits set is of no meaning.
.sp
An alternative to introducing a completely different concept was adding a
separate constructor function for Query, one that would from the start designate
the Query to only accept settings compatible with its purpose of becoming the
selecting element in a Goal operation (in Python this would probably be
implemented as a subclass of Query). But that would break client\(aqs assumptions
about Query (\fI\%the unofficial C++ FAQ\fP takes up the topic).
.sp
\fIImplementation note\fP: Selectors reflect the kind of specifications that can be
directly translated into Libsolv jobs, without actually searching for a concrete
package to put there. In other words, Selectors are specifically designed not to
iterate over the package data (with exceptions, like glob matching) like Queries
do. While Hawkey mostly aims to hide any twists and complexities of the
underlying library, in this case the combined reasons warrant a concession.
.sp
Indices and tables
.INDENT 0.0
.IP \(bu 2
\fI\%Index\fP
.IP \(bu 2
\fI\%Module Index\fP
.IP \(bu 2
\fI\%Search Page\fP
.UNINDENT
.SH AUTHOR
Aleš Kozumplík
.SH COPYRIGHT
2012-2023, Red Hat, Licensed under GPLv2+
.\" Generated by docutils manpage writer.
.