Contents
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.
Query.filter() now returns a new instance of Query, the same as the original with the new filtering applied. This allows for greater flexibility handling the Query objects and resembles the way QuerySets behave in Django.
In practice the following code will stop working as expected:
q = hawkey.Query(self.sack)
q.filter(name__eq="flying")
# processing the query ...
It needs to be changed to:
q = hawkey.Query(self.sack)
q = q.filter(name__eq="flying")
# processing the query ...
The original semantics is now available via the Query.filterm() method, so the following will also work:
q = hawkey.Query(self.sack)
q.filterm(name__eq="flying")
# processing the query ...
In Python’s Package instances accessors for string attributes now return None instead of the empty string if the attribute is missing (for instance a pkg.sourcerpm now returns None if pkg is a source rpm package already).
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.
The Query key value used for filtering by the repo name is HY_PKG_REPONAME now (was HY_PKG_REPO). The old value was misleading.
hy_repo_create() for Repo object initialization now needs to be passed a name of the repository.
All Goal methods accepting Query as the means of selecting packages, such as hy_goal_install_query() 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 Selectors are not Queries.
Similar change happened in Python, the following constructs:
q = q.filter(repo="updates")
need to be changed to:
q = q.filter(reponame="updates")
The old version of this didn’t 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).
The following will no longer work:
if pkg.evr_eq(some_other_pkg):
...
Instead use the result of pkg.evr_cmp, for instance:
if pkg.evr_cmp(some_other_pkg) == 0:
...
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:
if pkg == some_other_pkg:
...
All instantiations of hawkey.Repo now must be given the name of the Repo. The following will now fail:
r = hawkey.Repo()
r.name = "fedora"
Use this instead:
r = hawkey.Repo("fedora")
See Query installs obsoleted in the C section. In Python Queries will no longer work as goal target specifiers, the following will fail:
q = hawkey.Query(sack)
q.filter(name="gimp")
goal.install(query=q)
Instead use:
sltr = hawkey.Selector(sack)
sltr.set(name="gimp")
goal.install(select=sltr)
Or a convenience notation:
goal.install(name="gimp")
keyname parameter was added to the function signature. The new parameter allows filtering by a specific relation to the resulting packages, for instance:
hy_query_filter_package_in(q, HY_PKG_OBSOLETES, HY_EQ, pset)
only leaves the pacakges obsoleting a package in pset a part of the result.
The new version of hy_query_filter_package_in() handles this now, see above.
In Python, the following is no longer supported:
q = query.filter(obsoleting=1)
The equivalent new syntax is:
installed = hawkey.Query(sack).filter(reponame=SYSTEM_REPO_NAME)
q = query.filter(obsoletes=installed)
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:
q = hawkey.Query(sack).filter(reponame=SYSTEM_REPO_NAME, provides=pkg.obsoletes)
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’s 0.
Previously, repr(pkg) would yield for instance <_hawkey.Package object, id: 5>. Now more complete information is present, including the package’s NEVRA and repository: <hawkey.Package object id 5, foo-2-9\.noarch, @System>.
Also notice that the representation now mentions the final hawkey.Package type, not _hawkey.Package. Note that these are currently the same.
hy_sack_create() now accepts third argument, rootdir. 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 rootdir. To make your code compile in 0.3.8 without changing functionality, change:
HySack sack = hy_sack_create(cachedir, arch);
to:
HySack sack = hy_sack_create(cachedir, arch, NULL);
It became necessary to differentiate between the default forms used by subject.nevra_possibilities() and subject.nevra_possibilities_real(). Therefore there is little sense in setting the default form for an entire Subejct instance. The following code:
subj = hawkey.Subject("input", form=hawkey.FORM_NEVRA)
result = list(subj.nevra_possibilities())
is thus replaced by:
subj = hawkey.Subject("input")
result = list(subj.nevra_possibilities(form=hawkey.FORM_NEVRA))
hy_sack_create() now accepts fourth argument, flags, introduced to modify the sack behavior with boolean flags. Currently only one flag is supported, HY_MAKE_CACHE_DIR, which causes the cache directory to be created if it doesn’t exist yet. To preserve the previous behavior, change the following:
HySack sack = hy_sack_create(cachedir, arch, rootdir);
into:
HySack sack = hy_sack_create(cachedir, arch, rootdir, HY_MAKE_CACHE_DIR);
Update your code by mechanically replacing the name.
A new sack by default no longer automatically creates the cache directory. To get the old behavior, append make_cache_dir=True to the Sack’s constructor arguments, that is change the following:
sack = hawkey.Sack(...)
to:
sack = hawkey.Sack(..., make_cache_dir=True)
Reflects the similar change in C API.
hy_goal_package_obsoletes() 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 hy_goal_list_obsoleted_by_package() instead, to see the complete set of packages that inclusion of the given package in an RPM transaction will cause to be removed.
In other words, hy_goal_list_erasures() and hy_goal_list_obsoleted() return disjoint sets.
Directly reflecting the core changes. In particular, instead of:
obsoleted_pkg = goal.package_obsoletes(pkg)
use:
obsoleted = goal.obsoleted_by_package(pkg) # list
obsoleted_pkg = obsoleted[0]
For old function behaviour use new function hy_query_filter_latest_per_arch()
In Python’s Query option latest in Query.filter() now filter only the latest packages ignoring architecture. The original semantics for filtering latest packages for each arch is now available via latest_per_arch option.
For example there are these packages in sack:
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="glibc")
>>> map(str, q.filter(latest=True))
['glibc-2.17-4.fc19.x86_64']
>>> map(str, q.filter(latest_per_arch=True))
['glibc-2.17-4.fc19.x86_64', 'glibc-2.16-24.fc18.i686']