1HAWKEY(3) Hawkey HAWKEY(3)
2
6 hawkey - Hawkey Documentation
7 Contents:
9
11 Contents
12 · API Changes
13 · Introduction
15 · Changes in 0.2.10
17 · Python bindings
19 · Changes in 0.2.11
21 · Python bindings
23 · Changes in 0.3.0
25 · Core
27 · Query: key for reponame filtering
29 · Repo initialization
31 · Query installs obsoleted
33 · Python bindings
35 · Query: filtering by repository with the reponame key
37 · Package: removed methods for direct EVR comparison
39 · Repo initialization
41 · Query installs obsoleted
43 · Changes in 0.3.1
45 · Query: hy_query_filter_package_in() takes a new parameter
47 · Removed hy_query_filter_obsoleting()
49 · Changes in 0.3.2
51 · Removed hy_packagelist_of_obsoletes.
53 · Changes in 0.3.3
55 · Renamed hy_package_get_nvra to hy_package_get_nevra
57 · Changes in 0.3.4
59 · Python bindings
61 · pkg.__repr__() is more verbose now
63 · Changes in 0.3.8
65 · Core
67 · New parameter rootdir to hy_sack_create()
69 · Python bindings
71 · Forms recognized by Subject are no longer an instance-scope
73 setting
74 · Changes in 0.3.9
76 · Core
78 · Flags for hy_sack_create
80 · hy_sack_get_cache_path is renamed to hy_sack_get_cache_dir
82 · Python bindings
84 · make_cache_dir for Sack's constructor
86 · cache_path property of Sack renamed to cache_dir
88 · Changes in 0.3.11
90 · Core
92 · hy_goal_package_obsoletes() removed, hy_goal_list_obso‐
94 leted_by_package() provided instead
95 · hy_goal_list_erasures() does not report obsoletes
97 · Python bindings
99 · Changes in 0.4.5
101 · Core
103 · Query: hy_query_filter_latest() now filter latest packages
105 ignoring architecture
106 · Python bindings
108 · Changes in 0.4.13
110 · Core
112 · Deprecated hy_package_get_update_*
114 · Changes in 0.4.15
116 · Core
118 · hy_goal_write_debugdata() takes a directory parameter
120 · Python bindings
122 · Goal.write_debugdata() takes a directory parameter
124 · Package: string attributes are represented by Unicode object
126 · Changes in 0.4.18
128 · Core
130 · Deprecated hy_advisory_get_filenames
132 · Python bindings
134 · Repo() does not accept cost keyword argument
136 · Deprecated _hawkey.Advisory.filenames
138 · Changes in 0.4.19
140 · Python bindings
142 · Advisory attributes in Unicode
144 · Changes in 0.5.2
146 · Core
148 · hy_chksum_str returns NULL
150 · Changes in 0.5.3
152 · Core
154 · New parameter logfile to hy_sack_create()
156 · Deprecated hy_create_cmdline_repo()
158 · Python bindings
160 · New optional parameter logfile to Sack constructor
162 · cache_path property of Sack renamed to cache_dir
164 · Deprecated Sack method create_cmdline_repo()
166 · Changes in 0.5.4
168 · Python bindings
170 · Goal: install() takes a new optional parameter
172 · Changes in 0.5.5
174 · Core
176 · Renamed hy_sack_load_yum_repo to hy_sack_load_repo
178 · Python bindings
180 · Sack method load_yum_repo has been renamed to Sack.load_repo()
182 · Changes in 0.5.7
184 · Python bindings
186 · Package: file attribute is represented by list of Unicode
188 objects
189 · Sack: list_arches method returns list of Unicode objects
191 · Changes in 0.5.9
193 · Core
195 · Deprecated hy_goal_req_has_distupgrade(),
197 hy_goal_req_has_erase() and hy_goal_req_has_upgrade() functions
198 · Python bindings
200 · Deprecated Goal methods Goal.req_has_distupgrade_all(),
202 Goal.req_has_erase() and Goal.req_has_upgrade_all()
203 Introduction
205 This document describes the API changes the library users should be
206 aware of before upgrading to each respective version. It is our plan to
207 have the amount of changes requiring changing the client code go to a
208 minimum after the library hits the 1.0.0 version.
209 Depracated API items (classes, methods, etc.) are designated as such in
211 this document. The first release where support for such items can be
212 dropped entirely must be issued at least five months after the issue of
213 the release that announced the deprecation and at the same time have,
214 relatively to the deprecating release, either:
215 · a higher major version number, or
217 · a higher minor version number, or
219 · a patchlevel number that is by at least five greater.
221 These criteria are likely to tighten in the future as hawkey matures.
223 Actual changes in the API are then announced in this document as well.
225 ABI changes including changes in functions' parameter counts or types
226 or removal of public symbols from libhawkey imply an increase in the
227 library's SONAME version.
228 Changes in 0.2.10
230 Python bindings
231 Query.filter() now returns a new instance of Query, the same as the
232 original with the new filtering applied. This allows for greater flexi‐
233 bility handling the Query objects and resembles the way QuerySets
234 behave in Django.
235 In practice the following code will stop working as expected:
237 q = hawkey.Query(self.sack)
239 q.filter(name__eq="flying")
240 # processing the query ...
241 It needs to be changed to:
243 q = hawkey.Query(self.sack)
245 q = q.filter(name__eq="flying")
246 # processing the query ...
247 The original semantics is now available via the Query.filterm() method,
249 so the following will also work:
250 q = hawkey.Query(self.sack)
252 q.filterm(name__eq="flying")
253 # processing the query ...
254 Changes in 0.2.11
256 Python bindings
257 In Python's Package instances accessors for string attributes now
258 return None instead of the empty string if the attribute is missing
259 (for instance a pkg.sourcerpm now returns None if pkg is a source rpm
260 package already).
261 This change is towards a more conventional Python practice. Also, this
263 leaves the empty string return value free to be used when it is actu‐
264 ally the case.
265 Changes in 0.3.0
267 Core
268 Query: key for reponame filtering
269 The Query key value used for filtering by the repo name is
270 HY_PKG_REPONAME now (was HY_PKG_REPO). The old value was misleading.
271 Repo initialization
273 hy_repo_create() for Repo object initialization now needs to be passed
274 a name of the repository.
275 Query installs obsoleted
277 All Goal methods accepting Query as the means of selecting packages,
278 such as hy_goal_install_query() have been replaced with their Selector
279 counterparts. Selector structures have been introduced for the particu‐
280 lar purpose of specifying a package that best matches the given crite‐
281 ria and at the same time is suitable for installation. For a discussion
282 of this decision see rationale_selectors.
283 Python bindings
285 Query: filtering by repository with the reponame key
286 Similar change happened in Python, the following constructs:
287 q = q.filter(repo="updates")
289 need to be changed to:
291 q = q.filter(reponame="updates")
293 The old version of this didn't allow using the same string to both con‐
295 struct the query and dynamically get the reponame attribute from the
296 returned packages (used e.g. in DNF to search by user-specified crite‐
297 ria).
298 Package: removed methods for direct EVR comparison
300 The following will no longer work:
301 if pkg.evr_eq(some_other_pkg):
303 ...
304 Instead use the result of pkg.evr_cmp, for instance:
306 if pkg.evr_cmp(some_other_pkg) == 0:
308 ...
309 This function compares only the EVR part of a package, not the name.
311 Since it rarely make sense to compare versions of packages of different
312 names, the following is suggested:
313 if pkg == some_other_pkg:
315 ...
316 Repo initialization
318 All instantiations of hawkey.Repo now must be given the name of the
319 Repo. The following will now fail:
320 r = hawkey.Repo()
322 r.name = "fedora"
323 Use this instead:
325 r = hawkey.Repo("fedora")
327 Query installs obsoleted
329 See changes_query_installs in the C section. In Python Queries will no
330 longer work as goal target specifiers, the following will fail:
331 q = hawkey.Query(sack)
333 q.filter(name="gimp")
334 goal.install(query=q)
335 Instead use:
337 sltr = hawkey.Selector(sack)
339 sltr.set(name="gimp")
340 goal.install(select=sltr)
341 Or a convenience notation:
343 goal.install(name="gimp")
345 Changes in 0.3.1
347 Query: hy_query_filter_package_in() takes a new parameter
348 keyname parameter was added to the function signature. The new parame‐
349 ter allows filtering by a specific relation to the resulting packages,
350 for instance:
351 hy_query_filter_package_in(q, HY_PKG_OBSOLETES, HY_EQ, pset)
353 only leaves the packages obsoleting a package in pset a part of the
355 result.
356 Removed hy_query_filter_obsoleting()
358 The new version of hy_query_filter_package_in() handles this now, see
359 above.
360 In Python, the following is no longer supported:
362 q = query.filter(obsoleting=1)
364 The equivalent new syntax is:
366 installed = hawkey.Query(sack).filter(reponame=SYSTEM_REPO_NAME)
368 q = query.filter(obsoletes=installed)
369 Changes in 0.3.2
371 Removed hy_packagelist_of_obsoletes.
372 The function was not systematic. Same result is achieved by obtaining
373 obsoleting reldeps from a package and then trying to find the installed
374 packages that provide it. In Python:
375 q = hawkey.Query(sack).filter(reponame=SYSTEM_REPO_NAME, provides=pkg.obsoletes)
377 Changes in 0.3.3
379 Renamed hy_package_get_nvra to hy_package_get_nevra
380 The old name was by error, the functionality has not changed: this
381 function has always returned the full NEVRA, skipping the epoch part
382 when it's 0.
383 Changes in 0.3.4
385 Python bindings
386 pkg.__repr__() is more verbose now
387 Previously, repr(pkg) would yield for instance <_hawkey.Package object,
388 id: 5>. Now more complete information is present, including the pack‐
389 age's NEVRA and repository: <hawkey.Package object id 5,
390 foo-2-9\.noarch, @System>.
391 Also notice that the representation now mentions the final hawkey.Pack‐
393 age type, not _hawkey.Package. Note that these are currently the same.
394 Changes in 0.3.8
396 Core
397 New parameter rootdir to hy_sack_create()
398 hy_sack_create() now accepts third argument, rootdir. This can be used
399 to tell Hawkey that we are intending to do transactions in a change‐
400 root, not in the current root. It effectively makes use of the RPM
401 database found under rootdir. To make your code compile in 0.3.8 with‐
402 out changing functionality, change:
403 HySack sack = hy_sack_create(cachedir, arch);
405 to:
407 HySack sack = hy_sack_create(cachedir, arch, NULL);
409 Python bindings
411 Forms recognized by Subject are no longer an instance-scope setting
412 It became necessary to differentiate between the default forms used by
413 subject.nevra_possibilities() and subject.nevra_possibilities_real().
414 Therefore there is little sense in setting the default form for an
415 entire Subject instance. The following code:
416 subj = hawkey.Subject("input", form=hawkey.FORM_NEVRA)
418 result = list(subj.nevra_possibilities())
419 is thus replaced by:
421 subj = hawkey.Subject("input")
423 result = list(subj.nevra_possibilities(form=hawkey.FORM_NEVRA))
424 Changes in 0.3.9
426 Core
427 Flags for hy_sack_create
428 hy_sack_create() now accepts fourth argument, flags, introduced to mod‐
429 ify the sack behavior with boolean flags. Currently only one flag is
430 supported, HY_MAKE_CACHE_DIR, which causes the cache directory to be
431 created if it doesn't exist yet. To preserve the previous behavior,
432 change the following:
433 HySack sack = hy_sack_create(cachedir, arch, rootdir);
435 into:
437 HySack sack = hy_sack_create(cachedir, arch, rootdir, HY_MAKE_CACHE_DIR);
439 hy_sack_get_cache_path is renamed to hy_sack_get_cache_dir
441 Update your code by mechanically replacing the name.
442 Python bindings
444 make_cache_dir for Sack's constructor
445 A new sack by default no longer automatically creates the cache direc‐
446 tory. To get the old behavior, append make_cache_dir=True to the
447 Sack.__init__() arguments, that is change the following:
448 sack = hawkey.Sack(...)
450 to:
452 sack = hawkey.Sack(..., make_cache_dir=True)
454 cache_path property of Sack renamed to cache_dir
456 Reflects the similar change in C API.
457 Changes in 0.3.11
459 Core
460 hy_goal_package_obsoletes() removed, hy_goal_list_obsoleted_by_package()
461 provided instead
462 hy_goal_package_obsoletes() was flawed in that it only returned a sin‐
463 gle obsoleted package (in general, package can obsolete arbitrary num‐
464 ber of packages and upgrade a package of the same name which is also
465 reported as an obsolete). Use hy_goal_list_obsoleted_by_package()
466 instead, to see the complete set of packages that inclusion of the
467 given package in an RPM transaction will cause to be removed.
468 hy_goal_list_erasures() does not report obsoletes
470 In other words, hy_goal_list_erasures() and hy_goal_list_obsoleted()
471 return disjoint sets.
472 Python bindings
474 Directly reflecting the core changes. In particular, instead of:
475 obsoleted_pkg = goal.package_obsoletes(pkg)
477 use:
479 obsoleted = goal.obsoleted_by_package(pkg) # list
481 obsoleted_pkg = obsoleted[0]
482 Changes in 0.4.5
484 Core
485 Query: hy_query_filter_latest() now filter latest packages ignoring archi‐
486 tecture
487 For old function behavior use new function hy_query_filter_lat‐
488 est_per_arch()
489 Python bindings
491 In Python's Query option latest in Query.filter() now filter only the
492 latest packages ignoring architecture. The original semantics for fil‐
493 tering latest packages for each arch is now available via lat‐
494 est_per_arch option.
495 For example there are these packages in sack:
497 glibc-2.17-4.fc19.x86_64
499 glibc-2.16-24.fc18.x86_64
500 glibc-2.16-24.fc18.i686
501 >>> q = hawkey.Query(self.sack).filter(name="glibc")
503 >>> map(str, q.filter(latest=True))
504 ['glibc-2.17-4.fc19.x86_64']
505 >>> map(str, q.filter(latest_per_arch=True))
507 ['glibc-2.17-4.fc19.x86_64', 'glibc-2.16-24.fc18.i686']
508 Changes in 0.4.13
510 Core
511 Deprecated hy_package_get_update_*
512 The functions were deprecated because there can be multiple advisories
513 referring to a single package. Please use the new function hy_pack‐
514 age_get_advisories() which returns all these advisories. New functions
515 hy_advisory_get_* provide the data retrieved by the deprecated func‐
516 tions.
517 The only exception is the hy_package_get_update_severity() which will
519 be dropped without any replacement. However advisory types and severity
520 levels are distinguished from now and the type is accessible via
521 hy_advisory_get_type(). Thus enum HyUpdateSeverity was also depre‐
522 cated. A new HyAdvisoryType should be used instead.
523 The old functions will be dropped after 2014-07-07.
525 Changes in 0.4.15
527 Core
528 hy_goal_write_debugdata() takes a directory parameter
529 hy_goal_write_debugdata() has a new const char *dir argument to commu‐
530 nicate the target directory for the debugging data. The old call:
531 hy_goal_write_debugdata(goal);
533 should be changed to achieve the same behavior to:
535 hy_goal_write_debugdata(goal, "./debugdata");
537 Python bindings
539 Goal.write_debugdata() takes a directory parameter
540 Analogous to core changes.
541 Package: string attributes are represented by Unicode object
543 Attributes baseurl, location, sourcerpm, version, release, name, arch,
544 description, evr, license, packager, reponame, summary and url of Pack‐
545 age object return Unicode string.
546 Changes in 0.4.18
548 Core
549 Deprecated hy_advisory_get_filenames
550 The function was deprecated because we need more information about
551 packages listed in an advisory than just file names. Please use the new
552 function hy_advisory_get_packages() in combination with hy_adviso‐
553 rypkg_get_string() to obtain the data originally provided by the depre‐
554 cated function.
555 The old function will be dropped after 2014-10-15 AND no sooner than in
557 0.4.21.
558 Python bindings
560 Repo() does not accept cost keyword argument
561 Instead of:
562 r = hawkey.Repo('name', cost=30)
564 use:
566 r = hawkey.Repo('name')
568 r.cost = 30
569 Also previously when no cost was given it defaulted to 1000. Now the
571 default is 0. Both these aspects were present by mistake and the new
572 interface is consistent with the C library.
573 Deprecated _hawkey.Advisory.filenames
575 The attribute was deprecated because the underlying C function was also
576 deprecated. Please use the new attribute packages and the attribute
577 filename of the returned objects to obtain the data originally provided
578 by the deprecated attribute.
579 The old attribute will be dropped after 2014-10-15 AND no sooner than
581 in 0.4.21.
582 Changes in 0.4.19
584 Python bindings
585 Advisory attributes in Unicode
586 All string attributes of Advisory and AdvisoryRef objects (except the
587 deprecated filenames attribute) are Unicode objects now.
588 Changes in 0.5.2
590 Core
591 hy_chksum_str returns NULL
592 Previously, the function hy_chksum_str would cause a segmentation fault
593 when it was used with incorrect type value. Now it correctly returns
594 NULL if type parameter does not correspond to any of expected values.
595 Changes in 0.5.3
597 Core
598 New parameter logfile to hy_sack_create()
599 hy_sack_create() now accepts fifth argument, logfile to customize log
600 file path. If NULL parameter as logfile is given, then all debug
601 records are written to hawkey.log in cachedir. To make your code com‐
602 pile in 0.5.3 without changing functionality, change:
603 HySack sack = hy_sack_create(cachedir, arch, rootdir, 0);
605 to:
607 HySack sack = hy_sack_create(cachedir, arch, rootdir, NULL, 0);
609 Deprecated hy_create_cmdline_repo()
611 The function will be removed since hy_add_cmdline_package creates cmd‐
612 line repository automatically.
613 The function will be dropped after 2015-06-23 AND no sooner than in
615 0.5.8.
616 Python bindings
618 New optional parameter logfile to Sack constructor
619 This addition lets user specify log file path from Sack.__init__()
620 cache_path property of Sack renamed to cache_dir
622 This change was already announced but it actually never happened.
623 Deprecated Sack method create_cmdline_repo()
625 The method will be removed since Sack.add_cmdline_package() creates
626 cmdline repository automatically.
627 The method will be dropped after 2015-06-23 AND no sooner than in
629 0.5.8.
630 Changes in 0.5.4
632 Python bindings
633 Goal: install() takes a new optional parameter
634 If the optional parameter is set to True, hawkey silently skips pack‐
635 ages that can not be installed.
636 Changes in 0.5.5
638 Core
639 Renamed hy_sack_load_yum_repo to hy_sack_load_repo
640 Hawkey is package manager agnostic and the yum phrase could be mislead‐
641 ing.
642 The function will be dropped after 2015-10-27 AND no sooner than in
644 0.5.8.
645 Python bindings
647 Sack method load_yum_repo has been renamed to Sack.load_repo()
648 Hawkey is package manager agnostic and the yum phrase could be mislead‐
649 ing.
650 The method will be dropped after 2015-10-27 AND no sooner than in
652 0.5.8.
653 Changes in 0.5.7
655 Python bindings
656 Package: file attribute is represented by list of Unicode objects
657 Sack: list_arches method returns list of Unicode objects
658 Changes in 0.5.9
659 Core
660 Deprecated hy_goal_req_has_distupgrade(), hy_goal_req_has_erase() and
661 hy_goal_req_has_upgrade() functions
662 To make your code compile in 0.5.9 without changing functionality,
663 change:
664 hy_goal_req_has_distupgrade_all(goal)
666 hy_goal_req_has_erase(goal)
667 hy_goal_req_has_upgrade_all(goal)
668 to:
670 hy_goal_has_actions(goal, HY_DISTUPGRADE_ALL)
672 hy_goal_has_actions(goal, HY_ERASE)
673 hy_goal_has_actions(goal, HY_UPGRADE_ALL)
674 respectively
676 Python bindings
678 Deprecated Goal methods Goal.req_has_distupgrade_all(),
679 Goal.req_has_erase() and Goal.req_has_upgrade_all()
680 To make your code compatible with hawkey 0.5.9 without changing func‐
681 tionality, change:
682 goal.req_has_distupgrade_all()
684 goal.req_has_erase()
685 goal.req_has_upgrade_all()
686 to:
688 goal.actions | hawkey.DISTUPGRADE_ALL
690 goal.actions | hawkey.ERASE
691 goal.actions | hawkey.UPGRADE_ALL
692 respectively
694
696 Contents
697 · FAQ
698 · Getting Started
700 · How do I build it?
702 · Are there examples using hawkey?
704 · Using Hawkey
706 · How do I obtain the repo metadata files to feed to Hawkey?
708 · Why is a tool to do the downloads not integrated into Hawkey?
710 Getting Started
712 How do I build it?
713 See the README.
714 Are there examples using hawkey?
716 Yes, look at:
717 · unit tests
719 · The Hawkey Testing Hack
721 · a more complex example is DNF, the Yum fork using hawkey for backend.
723 Using Hawkey
725 How do I obtain the repo metadata files to feed to Hawkey?
726 It is entirely up to you. Hawkey does not provide any means to do this
727 automatically, for instance from your /etc/yum.repos.d configuration.
728 Use or build tools to do that. For instance, both Yum and DNF deals
729 with the same problem and inside they employ urlgrabber to fetch the
730 files. A general solution if you work in C is for instance libcurl. If
731 you are building a nice downloading library that integrates well with
732 hawkey, let us know.
733 Why is a tool to do the downloads not integrated into Hawkey?
735 Because downloading things from remote servers is a differnt domain
736 full of its own complexities like HTTPS, parallel downloads, error han‐
737 dling and error recovery to name a few. Downloading is a concern that
738 can be naturally separated from other parts of package metadata manag‐
739 ing.
740
742 Contents
743 · python-hawkey Tutorial
744 · Setup
746 · The Sack Object
748 · Loading RPMDB
750 · Loading Repositories
752 · Case for Loading the Filelists
754 · Building and Reusing the Repo Cache
756 · Queries
758 · Resolving things with Goals
760 · Selector Installs
762 IMPORTANT:
764 Please consult every usage of the library with reference-py to be
765 sure what are you doing. The examples mentioned here are supposed to
766 be as simple as possible and may ignore some minor corner cases.
767 Setup
769 First of, make sure hawkey is installed on your system, this should
770 work from your terminal:
771 >>> import hawkey
773 The Sack Object
775 Sack is an abstraction for a collection of packages. Sacks in hawkey
776 are toplevel objects carrying much of hawkey's of functionality. You'll
777 want to create one:
778 >>> sack = hawkey.Sack()
780 >>> len(sack)
781 0
782 Initially, the sack contains no packages.
784 Loading RPMDB
786 hawkey is a lib for listing, querying and resolving dependencies of
787 packages from repositories. On most linux distributions you always have
788 at least the system repo (in Fedora it is the RPM database). To load
789 it:
790 >>> sack.load_system_repo()
792 >>> len(sack)
793 1683
794 Hawkey always knows the name of every repository. The system repository
796 is always set to hawkey.SYSTEM_REPO_NAME. and the client is responsible
797 for naming the available repository metadata.
798 Loading Repositories
800 Let's be honest here: all the fun in packaging comes from packages you
801 haven't installed yet. Information about them, their metadata, can be
802 obtained from different sources and typically they are downloaded from
803 an HTTP mirror (another possibilities are FTP server, NFS mount, DVD
804 distribution media, etc.). Hawkey does not provide any means to dis‐
805 cover and obtain the metadata locally: it is up to the client to pro‐
806 vide valid readable paths to the repository metadata XML files. Struc‐
807 tures used for passing the information to hawkey are the hawkey Repos.
808 Suppose we somehow obtained the metadata and placed it in
809 /home/akozumpl/tmp/repodata. We can then load the metadata into hawkey:
810 >>> path = "/home/akozumpl/tmp/repodata/%s"
812 >>> repo = hawkey.Repo("experimental")
813 >>> repo.repomd_fn = path % "repomd.xml"
814 >>> repo.primary_fn = path % "f7753a2636cc89d70e8aaa1f3c08413ab78462ca9f48fd55daf6dedf9ab0d5db-primary.xml.gz"
815 >>> repo.filelists_fn = path % "0261e25e8411f4f5e930a70fa249b8afd5e86bb9087d7739b55be64b76d8a7f6-filelists.xml.gz"
816 >>> sack.load_repo(repo, load_filelists=True)
817 >>> len(sack)
818 1685
819 The number of packages in the Sack will increase by the number of pack‐
821 ages found in the repository (two in this case, it is an experimental
822 repo after all).
823 Case for Loading the Filelists
825 What the load_filelists=True argument to load_repo() above does is
826 instruct hawkey to process the <hash>filelists.xml.gz file we passed in
827 and which contains structured list of absolute paths to all files of
828 all packages within the repo. This information can be used for two pur‐
829 poses:
830 · Finding a package providing given file. For instance, you need the
832 file /usr/share/man/man3/fprintf.3.gz which is not installed. Con‐
833 sulting filelists (directly or through hawkey) can reveal the file is
834 in the man-pages package.
835 · Depsolving. Some packages require concrete files as their dependen‐
837 cies. To know if these are resolvable and how, the solver needs to
838 know what package provides what files.
839 Some files provided by a package (e.g those in /usr/bin) are always
841 visible even without loading the filelists. Well-behaved packages
842 requiring only those can be thus resolved directly. Unortunately, there
843 are packages that don't behave and it is hard to tell in advance when
844 you'll deal with one.
845 The strategy for using load_filelists=True is thus:
847 · Use it if you know you'll do resolving (i.e. you'll use Goal).
849 · Use it if you know you'll be trying to match files to their packages.
851 · Use it if you are not sure.
853 Building and Reusing the Repo Cache
855 Internally to hold the package information and perform canonical
856 resolving hawkey uses Libsolv. One great benefit this library offers is
857 providing writing and reading of metadata cache files in libsolv's own
858 binary format (files with .solv extension, typically). At a cost of few
859 hundreds of milliseconds, using the solv files reduces repo load times
860 from seconds to tens of milliseconds. It is thus a good idea to write
861 and use the solv files every time you plan to use the same repo for
862 more than one Sack (which is at least every time your hawkey program is
863 run). To do that use build_cache=True with load_repo() and load_sys‐
864 tem_repo():
865 >>> sack = hawkey.Sack(make_cache_dir=True)
867 >>> sack.load_system_repo(build_cache=True)
868 By default, Hawkey creates @System.cache under the
870 /var/tmp/hawkey-<your_login>-<random_hash> directory. This is the
871 hawkey cache directory, which you can always delete later (deleting the
872 cache files in the process). The .solv files are picked up automati‐
873 cally the next time you try to create a hawkey sack. Except for a much
874 higher speed of the operation this will be completely transparent to
875 you:
876 >>> s2 = hawkey.Sack()
878 >>> s2.load_system_repo()
879 By the way, the cache directory (if not set otherwise) also contains a
881 logfile with some boring debugging information.
882 Queries
884 Query is the means in hawkey of finding a package based on one or more
885 criteria (name, version, repository of origin). Its interface is
886 loosely based on Django's QuerySets, the main concepts being:
887 · a fresh Query object matches all packages in the Sack and the selec‐
889 tion is gradually narrowed down by calls to Query.filter()
890 · applying a Query.filter() does not start to evaluate the Query, i.e.
892 the Query is lazy. Query is only evaluated when we explicitly tell it
893 to or when we start to iterate it.
894 · use Python keyword arguments to Query.filter() to specify the filter‐
896 ing criteria.
897 For instance, let's say I want to find all installed packages which
899 name ends with gtk:
900 >>> q = hawkey.Query(sack).filter(reponame=hawkey.SYSTEM_REPO_NAME, name__glob='*gtk')
902 >>> for pkg in q:
903 ... print str(pkg)
904 ...
905 NetworkManager-gtk-1:0.9.4.0-9.git20120521.fc17.x86_64
906 authconfig-gtk-6.2.1-1.fc17.x86_64
907 clutter-gtk-1.2.0-1.fc17.x86_64
908 libchamplain-gtk-0.12.2-1.fc17.x86_64
909 libreport-gtk-2.0.10-3.fc17.x86_64
910 pinentry-gtk-0.8.1-6.fc17.x86_64
911 python-slip-gtk-0.2.20-2.fc17.noarch
912 transmission-gtk-2.50-2.fc17.x86_64
913 usermode-gtk-1.109-1.fc17.x86_64
914 webkitgtk-1.8.1-2.fc17.x86_64
915 xdg-user-dirs-gtk-0.9-1.fc17.x86_64
916 Or I want to find the latest version of all python packages the Sack
918 knows of:
919 >>> q.clear()
921 >>> q = q.filter(name='python', latest_per_arch=True)
922 >>> for pkg in q:
923 ... print str(pkg)
924 ...
925 python-2.7.3-6.fc17.x86_64
926 You can also test a Query for its truth value. It will be true whenever
928 the query matched at least one package:
929 >>> q = hawkey.Query(sack).filter(file='/boot/vmlinuz-3.3.4-5.fc17.x86_64')
931 >>> if q:
932 ... print 'match'
933 ...
934 match
935 >>> q = hawkey.Query(sack).filter(file='/booty/vmlinuz-3.3.4-5.fc17.x86_64')
936 >>> if q:
937 ... print 'match'
938 ...
939 >>> if not q:
940 ... print 'no match'
941 ...
942 no match
943 NOTE:
945 If the Query hasn't been evaluated already then it is evaluated
946 whenever it's length is taken (either via len(q) or q.count()), when
947 it is tested for truth and when it is explicitly evaluated with
948 q.run().
949 Resolving things with Goals
951 Many Sack sessions culminate in a bout of dependency resolving, that is
952 answering a question along the lines of "I have a package X in a repos‐
953 itory here, what other packages do I need to install/update to have X
954 installed and all its dependencies recursively satisfied?" Suppose we
955 want to install the RTS game Spring. First let's locate the latest ver‐
956 sion of the package in repositories:
957 >>> q = hawkey.Query(sack).filter(name='spring', latest_per_arch=True)
959 >>> pkg = hawkey.Query(sack).filter(name='spring', latest_per_arch=True)[0]
960 >>> str(pkg)
961 'spring-88.0-2.fc17.x86_64'
962 >>> pkg.reponame
963 'fedora'
964 Then build the Goal object and tell it our goal is installing the pkg.
966 Then we fire off the libsolv's dependency resolver by running the goal:
967 >>> g = hawkey.Goal(sack)
969 >>> g.install(pkg)
970 >>> g.run()
971 True
972 True as a return value here indicates that libsolv could find a solu‐
974 tion to our goal. This is not always the case, there are plenty of sit‐
975 uations when there is no solution, the most common one being a package
976 should be installed but one of its dependencies is missing from the
977 sack.
978 The three methods Goal.list_installs(), Goal.list_upgrades() and
980 Goal.list_erasures() can show which packages should be
981 installed/upgraded/erased to satisfy the packaging goal we set out to
982 achieve (the mapping of str() over the results below ensures human
983 readable package names instead of numbers are presented):
984 >>> map(str, g.list_installs())
986 ['spring-88.0-2.fc17.x86_64', 'spring-installer-20090316-10.fc17.x86_64', 'springlobby-0.139-3.fc17.x86_64', 'spring-maps-default-0.1-8.fc17.noarch', 'wxBase-2.8.12-4.fc17.x86_64', 'wxGTK-2.8.12-4.fc17.x86_64', 'rb_libtorrent-0.15.9-1.fc17.x86_64', 'GeoIP-1.4.8-2.1.fc17.x86_64']
987 >>> map(str, g.list_upgrades())
988 []
989 >>> map(str, g.list_erasures())
990 []
991 So what does it tell us? That given the state of the given system and
993 the given repository we used, 8 packages need to be installed,
994 spring-88.0-2.fc17.x86_64 itself included. No packages need to be
995 upgraded or erased.
996 Selector Installs
998 For certain simple and commonly used queries we can do installs
999 directly. Instead of executing a query however we instantiate and pass
1000 the Goal.install() method a Selector:
1001 >>> g = hawkey.Goal(sack)
1003 >>> sltr = hawkey.Selector(sack).set(name='emacs-nox')
1004 >>> g.install(select=sltr)
1005 >>> g.run()
1006 True
1007 >>> map(str, g.list_installs())
1008 ['spring-88.0-2.fc17.x86_64', 'spring-installer-20090316-10.fc17.x86_64', 'springlobby-0.139-3.fc17.x86_64', 'spring-maps-default-0.1-8.fc17.noarch', 'wxBase-2.8.12-4.fc17.x86_64', 'wxGTK-2.8.12-4.fc17.x86_64', 'rb_libtorrent-0.15.9-1.fc17.x86_64', 'GeoIP-1.4.8-2.1.fc17.x86_64']
1009 >>> len(g.list_upgrades())
1010 0
1011 >>> len(g.list_erasures())
1012 0
1013 Notice we arrived at the same result as before, when a query was con‐
1015 structed and iterated first. What Selector does when passed to
1016 Goal.install() is tell hawkey to examine its settings and without eval‐
1017 uating it as a Query it instructs libsolv to find the best matching
1018 package for it and add that for installation. It saves user some deci‐
1019 sions like which version should be installed or what architecture (this
1020 gets very relevant with multiarch libraries).
1021 So Selectors usually only install a single package. If you mean to
1023 install all packages matching an arbitrarily complex query, just use
1024 the method describe above:
1025 >>> map(goal.install, q)
1027
1029 Contents
1030 · python-hawkey Reference Manual
1031 · Introduction
1033 · Contents
1035 Introduction
1037 This reference manual describes Python API to the library. For a quick
1038 start take a look at tutorial-py. To be sure that you are familiar with
1039 our deprecation policy, see changes.
1040 NOTE:
1042 The API consists of exactly those elements described in this docu‐
1043 ment, items not documented here can change from release to release.
1044 Opening a bugzilla if certain needed functionality is not exposed is
1045 the right thing to do.
1046 WARNING:
1048 The manual is not complete yet - the features are being added incre‐
1049 mentally these days.
1050 Contents
1052 API Documentation Contents
1053 Sack---The fundamental hawkey structure
1055 class hawkey.Sack
1056 Instances of hawkey.Sack represent collections of packages. An
1057 application typically needs at least one instance because it
1058 provides much of the hawkey's functionality.
1059 WARNING:
1061 Any package instance is not supposed to work interchangeably
1062 between hawkey.Query, hawkey.Selector or hawkey.Goal created
1063 from different hawkey.Sack. Usually for common tasks there is
1064 no need to initialize two or more Sacks in your program.
1065 Sacks cannot be deeply copied.
1066 cache_dir
1068 A read-only string property giving the path to the loca‐
1069 tion where a metadata cache is stored.
1070 installonly
1072 A write-only sequence of strings property setting the
1073 provide names of packages that should only ever be
1074 installed, never upgraded.
1075 installonly_limit
1077 A write-only integer property setting how many instal‐
1078 lonly packages with the same name are allowed to be
1079 installed concurrently. If 0, any number of packages can
1080 be installed.
1081 __init__(cachedir=_CACHEDIR, arch=_ARCH, rootdir=_ROOTDIR, pkg‐
1083 cls=hawkey.Package, pkginitval=None, make_cache_dir=False, log‐
1084 file=_LOGFILE)
1085 Initialize the sack with a default cache directory, log
1086 file location set to hawkey.log in the cache directory,
1087 an automatically detected architecture and the current
1088 root (/) as an installroot. The cache is disabled by
1089 default.
1090 cachedir is a string giving a path of a cache location.
1092 arch is a string specifying an architecture.
1094 rootdir is a string giving a path to an installroot.
1096 pkgcls is a class of packages retrieved from the sack.
1098 The class' __init__ method must accept two arguments. The
1099 first argument is a tuple of the sack and the ID of the
1100 package. The second argument is the pkginitval argument.
1101 pkginitval cannot be None if pkgcls is specified.
1102 make_cache_dir is a boolean that specifies whether the
1104 cache should be used to speedup loading of repositories
1105 or not (see building_and_reusing_the_repo_cache-label).
1106 logfile is a string giving a path of a log file location.
1108 __len__()
1110 Returns the number of the packages loaded into the sack.
1111 add_cmdline_package(filename)
1113 Add a package to a command line repository and return it.
1114 The package is specified as a string filename of an RPM
1115 file. The command line repository will be automatically
1116 created if doesn't exist already. It could be referenced
1117 later by hawkey.CMDLINE_REPO_NAME name.
1118 add_excludes(packages)
1120 Add a sequence of packages that cannot be fetched by
1121 Queries nor Selectors.
1122 add_includes(packages)
1124 Add a sequence of the only packages that can be fetched
1125 by Queries or Selectors.
1126 This is the inverse operation of add_excludes(). Any
1128 package that is not in the union of all the included
1129 packages is excluded. This works in conjunction with
1130 exclude and doesn't override it. So, if you both include
1131 and exclude the same package, the package is considered
1132 excluded no matter of the order.
1133 disable_repo(name)
1135 Disable the repository identified by a string name. Pack‐
1136 ages in that repository cannot be fetched by Queries nor
1137 Selectors.
1138 enable_repo(name)
1140 Enable the repository identified by a string name. Pack‐
1141 ages in that repository can be fetched by Queries or
1142 Selectors.
1143 WARNING:
1145 Execution of add_excludes(), add_includes(), disable_repo()
1146 or enable_repo() methods could cause inconsistent results in
1147 previously evaluated Query, Selector or Goal. The rule of
1148 thumb is to exclude/include packages, enable/disable reposi‐
1149 tories at first and then do actual computing using Query,
1150 Selector or Goal. For more details see developer discussion.
1151 evr_cmp(evr1, evr2)
1153 Compare two EVR strings and return a negative integer if
1154 evr1 < evr2, zero if evr1 == evr2 or a positive integer
1155 if evr1 > evr2.
1156 get_running_kernel()
1158 Detect and return the package of the currently running
1159 kernel. If the package cannot be found, None is returned.
1160 list_arches()
1162 List strings giving all the supported architectures.
1163 load_system_repo(repo=None, build_cache=False)
1165 Load the information about the packages in the system
1166 repository (in Fedora it is the RPM database) into the
1167 sack. This makes the dependency solving aware of the
1168 already installed packages. The system repository is
1169 always set to hawkey.SYSTEM_REPO_NAME. The information is
1170 not written to the cache by default.
1171 repo is an optional Repo object that represents the sys‐
1173 tem repository. The object is updated during the loading.
1174 build_cache is a boolean that specifies whether the
1176 information should be written to the cache (see build‐
1177 ing_and_reusing_the_repo_cache-label).
1178 load_repo(repo, build_cache=False, load_filelists=False,
1180 load_presto=False, load_updateinfo=False)
1181 Load the information about the packages in a Repo into
1182 the sack. This makes the dependency solving aware of
1183 these packages. The information is not written to the
1184 cache by default.
1185 repo is the Repo object to be processed. At least its
1187 Repo.repomd_fn must be set. If the cache has to be
1188 updated, Repo.primary_fn is needed too. Some information
1189 about the loading process and some results of it are
1190 written into the internal state of the repository object.
1191 build_cache is a boolean that specifies whether the
1193 information should be written to the cache (see build‐
1194 ing_and_reusing_the_repo_cache-label).
1195 load_filelists, load_presto and load_updateinfo are bool‐
1197 eans that specify whether the Repo.filelists_fn,
1198 Repo.presto_fn and Repo.updateinfo_fn files of the repos‐
1199 itory should be processed. These files may contain
1200 information needed for dependency solving, downloading or
1201 querying of some packages. Enable it if you are not sure
1202 (see case_for_loading_the_filelists-label).
1203 Error handling
1205 When an error or an unexpected event occurs during a Hawkey routine, an
1206 exception is raised:
1207 · if it is a general error that could be common to other Python pro‐
1209 grams, one of the standard Python built-in exceptions is raised. For
1210 instance, IOError and TypeError can be raised from Hawkey.
1211 · programming errors within Hawkey that cause unexpected or invalid
1213 states raise the standard AssertionError. These should be reported as
1214 bugs against Hawkey.
1215 · programming errors due to incorrect use of the library usually pro‐
1217 duce hawkey.ValueException or one of its subclasses, QueryException
1218 (poorly formed Query) or ArchException (unrecognized architecture).
1219 · sometimes there is a close call between blaming the error on an input
1221 parameter or on something else, beyond the programmer's control.
1222 hawkey.RuntimeException is generally used in this case.
1223 · hawkey.ValidationException is raised when a function call performs a
1225 preliminary check before proceeding with the main operation and this
1226 check fails.
1227 The class hierarchy for Hawkey exceptions is:
1229 +-- hawkey.Exception
1231 +-- hawkey.ValueException
1232 | +-- hawkey.QueryException
1233 | +-- hawkey.ArchException
1234 +-- hawkey.RuntimeException
1235 +-- hawkey.ValidationException
1236 Module level constants
1238 hawkey.CMDLINE_REPO_NAME
1239 The string name of the command line repository.
1240 hawkey.SYSTEM_REPO_NAME
1242 The string name of the system repository.
1243 Repositories
1245 class hawkey.Repo
1246 Instances of hawkey.Repo point to metadata of packages that are
1247 available to be installed. The metadata are expected to be in
1248 the "rpm-md" format. librepo may help you with downloading the
1249 required files.
1250 cost An integer specifying a relative cost of accessing this
1252 repository. This value is compared when the priorities of
1253 two repositories are the same. The repository with the
1254 lowest cost is picked. It is useful to make the library
1255 prefer on-disk repositories to remote ones.
1256 filelists_fn
1258 A valid string path to the readable "filelists" XML file
1259 if set.
1260 name A string name of the repository.
1262 presto_fn
1264 A valid string path to the readable "prestodelta.xml"
1265 (also called "deltainfo.xml") file if set.
1266 primary_fn
1268 A valid string path to the readable "primary" XML file if
1269 set.
1270 priority
1272 An integer priority value of this repository. If there is
1273 more than one candidate package for a particular opera‐
1274 tion, the one from the repository with the lowest prior‐
1275 ity value is picked, possibly despite being less conve‐
1276 nient otherwise (e.g. by being a lower version).
1277 repomd_fn
1279 A valid string path to the readable "repomd.xml" file if
1280 set.
1281 updateinfo_fn
1283 A valid string path to the readable "updateinfo.xml" file
1284 if set.
1285 __init__(name)
1287 Initialize the repository with empty repomd_fn, pri‐
1288 mary_fn, filelists_fn and presto_fn. The priority and the
1289 cost are set to 0.
1290 name is a string giving the name of the repository. The
1292 name should not be equal to hawkey.SYSTEM_REPO_NAME nor
1293 hawkey.CMDLINE_REPO_NAME
1294 Indices:
1296 · genindex
1298
1300 Selectors are not Queries
1301 Since both a Query and a Selector work to limit the set of all Sack's
1302 packages to a subset, it can be suggested the two concepts should be
1303 the same and e.g. Queries should be used for Goal specifications
1304 instead of Selectors:
1305 // create sack, goal, ...
1307 HyQuery q = hy_query_create(sack);
1308 hy_query_filter(q, HY_PKG_NAME, HY_EQ, "anaconda")
1309 hy_goal_install_query(q)
1310 This arrangment was in fact used in hawkey prior to version 0.3.0, just
1312 because Queries looked like a convenient structure to hold this kind of
1313 information. It was unfortunately confusing for the programmers: notice
1314 how evaluating the Query q would generally produce several packages
1315 (anaconda for different architectures and then different versions) but
1316 somehow when the same Query is passed into the goal methods it always
1317 results in up to one pacakge selected for the operation. This is a
1318 principal discrepancy. Further, Query is universal and allows one to
1319 limit the package set with all sorts of criteria, matched in different
1320 ways (substrings, globbing, set operation) while Selectors only support
1321 few. Finally, while a fresh Query with no filters applied corresponds
1322 to all packages of the Sack, a fresh Selector with no limits set is of
1323 no meaning.
1324 An alternative to introducing a completely different concept was adding
1326 a separate constructor function for Query, one that would from the
1327 start designate the Query to only accept settings compatible with its
1328 purpose of becoming the selecting element in a Goal operation (in
1329 Python this would probably be implemented as a subclass of Query). But
1330 that would break client's assumptions about Query (the unofficial C++
1331 FAQ takes up the topic).
1332 Implementation note: Selectors reflect the kind of specifications that
1334 can be directly translated into Libsolv jobs, without actually search‐
1335 ing for a concrete package to put there. In other words, Selectors are
1336 specifically designed not to iterate over the package data (with excep‐
1337 tions, like glob matching) like Queries do. While Hawkey mostly aims to
1338 hide any twists and complexities of the underlying library, in this
1339 case the combined reasons warrant a concession.
1340 Indices and tables
1342 · genindex
1344 · modindex
1346 · search
1348
1350 Aleš Kozumplík
1351
1353 2012-2015, Red Hat, Licensed under GPLv2+
13540.6.3 November 16, 2016 HAWKEY(3)