1.. 2 Copyright (C) 2014-2018 Red Hat, Inc. 3 4 This copyrighted material is made available to anyone wishing to use, 5 modify, copy, or redistribute it subject to the terms and conditions of 6 the GNU General Public License v.2, or (at your option) any later version. 7 This program is distributed in the hope that it will be useful, but WITHOUT 8 ANY WARRANTY expressed or implied, including the implied warranties of 9 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General 10 Public License for more details. You should have received a copy of the 11 GNU General Public License along with this program; if not, write to the 12 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 13 02110-1301, USA. Any Red Hat trademarks that are incorporated in the 14 source code or documentation are not subject to the GNU General Public 15 License and may only be used or replicated with the express permission of 16 Red Hat, Inc. 17 18====================== 19 Queries and Subjects 20====================== 21 22.. module:: dnf.query 23 24.. class:: Query 25 26 Facilitates lookup of packages in a :class:`~dnf.sack.Sack` based on given criteria. Query actually does not consult the information in the :class:`~!dnf.sack.Sack` until it is evaluated. The evaluation happens either explicitly using :meth:`~dnf.query.Query.run` or by iterating the query, for example:: 27 28 #!/usr/bin/python3 29 import dnf 30 31 base = dnf.Base() 32 base.fill_sack() 33 34 q = base.sack.query() 35 i = q.installed() 36 i = i.filter(name='dnf') 37 38 packages = list(i) # i only gets evaluated here 39 print("Installed dnf package:") 40 for pkg in packages: 41 print(pkg, pkg.reponame) 42 43 or:: 44 45 #!/usr/bin/python3 46 import dnf 47 48 base = dnf.Base() 49 base.read_all_repos() 50 base.fill_sack() 51 52 q = base.sack.query() 53 a = q.available() 54 a = a.filter(name='dnf') 55 56 print("Available dnf packages:") 57 for pkg in a: # a only gets evaluated here 58 print('{} in repo {}'.format(pkg, pkg.reponame)) 59 60 61 Notice that none of the filtering methods mutates the state of the :class:`~dnf.query.Query` but produces a new object instead. 62 63 .. method:: available() 64 65 Returns a new query limiting the original query to the packages available from the repositories. 66 67 .. method:: difference(other) 68 69 Returns a new query that contains only those results of original query that are not in the results of the ``other`` query. 70 71 .. method:: downgrades() 72 73 Returns a new query that limits the result only to packages that can be downgrade candidates to other packages in the current set. Downgrade candidate has the same name, lower EVR and the architecture of the original and the downgrade candidate are suitable for a downgrade. Specifically, the filtering does not take any steps to establish that the downgrade candidate can actually be installed. 74 75 .. method:: duplicated() 76 77 Returns a new query that limits the result only to installed packages of same name and different version. Optional argument exclude accepts a list of package names that will be excluded from result. 78 79 .. method:: extras() 80 81 Returns a new query that limits the result to installed packages that are not present in any repo 82 83 .. method:: filter(\*\*kwargs) 84 85 Returns a new query limiting the original query to the key/value pairs from `kwargs`. Multiple `kwargs` can be passed, the filter then works by applying all of them together (logical AND). Values inside of list or query are cumulative (logical OR). 86 87 Allowed keys are: 88 89 =============== ============== ====================================================== 90 key value type value meaning 91 =============== ============== ====================================================== 92 arch string match against packages' architecture 93 downgrades boolean see :meth:`downgrades`. Defaults to ``False``. 94 empty boolean ``True`` limits to empty result set. 95 Defaults to ``False``. 96 epoch integer match against packages' epoch. 97 file string match against packages' files 98 latest integer limit to all packages of number of versions 99 latest_per_arch integer see :meth:`latest`. 100 name string match against packages' names 101 release string match against packages' releases 102 reponame string match against packages repositories' names 103 version string match against packages' versions 104 pkg Query match against packages in query 105 pkg* list match against hawkey.Packages in list 106 provides string match against packages' provides 107 provides* Hawkey.Reldep match against packages' provides 108 <DEP> string match against packages' <DEP> 109 <DEP>* Hawkey.Reldep match a reldep against packages' <DEP> 110 <DEP>* Query match the result of a query against packages' <DEP> 111 <DEP>* list(Package) match the list of hawkey.Packages against packages' <DEP> 112 sourcerpm string match against packages' source rpm 113 upgrades boolean see :meth:`upgrades`. Defaults to ``False``. 114 =============== ============== ====================================================== 115 116 ``<DEP>`` can be any of: requires, conflicts, obsoletes, enhances, recomments, suggests, supplements 117 118 \* The key can also accept a list of values with specified type. 119 120 The key name can be supplemented with a relation-specifying suffix, separated by ``__``: 121 122 ========== =========== =========================================================== 123 key suffix value type semantics 124 ========== =========== =========================================================== 125 eq any exact match; This is the default if no suffix is specified. 126 glob string shell-style wildcard match 127 gt integer the actual value is greater than specified 128 gte integer the actual value is greater than or equal to specified 129 lt integer the actual value is less than specified 130 lte integer the actual value is less than or equal to specified 131 neq any does not equal 132 substr string the specified value is contained in the actual value 133 eqg string exact match or the first higher, used with advisory filters 134 upgrade string skips advisory resolved by installed packages 135 ========== =========== =========================================================== 136 137 For example, the following creates a query that matches all packages containing the string "club" in its name:: 138 139 q = base.sack.query().filter(name__substr="club") 140 141 Note that using packages or queries for dependency filtering performs a more advanced resolution than using a string or a reldep. When a package list or a query is used, rich dependencies are resolved in a more precise way than what is possible when a string or a reldep is used. 142 143 .. method:: filterm(\*\*kwargs) 144 145 Similar to :meth:`dnf.query.Query.filter` but it modifies the query in place. 146 147 .. method:: installed() 148 149 Returns a new query that limits the result to the installed packages only. 150 151 .. method:: intersection(other) 152 153 Returns a new query where the result contains only packages that are found in both original and ``other`` queries. 154 155 .. method:: latest(limit=1) 156 157 Returns a new query that limits the result to ``limit`` highest version of packages per package 158 name and per architecture. In case the limit is negative number, it excludes the number of 159 latest versions according to limit. 160 161 .. method:: run() 162 163 Evaluate the query. Returns a list of matching :class:`dnf.package.Package` instances. 164 165 .. method:: union(other) 166 167 Returns a new query where the results of the ``other`` query are added to the results of the original query. 168 169 .. method:: upgrades() 170 171 Returns a new query that limits the result only to packages that can be upgrade candidates to at least one package in the current set. Upgrade candidate has the same name, higher EVR and the architectures of the original and the upgrade candidate package are suitable for an upgrade. Specifically, the filtering does not take any steps to establish that the upgrade candidate can actually be installed. 172 173.. module:: dnf.subject 174 175.. class:: Subject 176 177 As :ref:`explained on the DNF man page <specifying_packages-label>`, users of the CLI are able to select packages for an operation in different formats, leaving seemingly arbitrary parts out of the spec and even using globbing characters. This class implements a common approach to parsing such input and produce a :class:`~dnf.query.Query` listing all packages matching the input or a :class:`~dnf.selector.Selector` selecting a single package that best matches the input given a transaction operation. 178 179 .. method:: __init__(pkg_spec, ignore_case=False) 180 181 Initialize the :class:`Subject` with `pkg_spec` input string with following :ref:`semantic <specifying_packages-label>`. If `ignore_case` is ``True`` ignore the case of characters in `pkg_spec`. 182 183 .. method:: get_best_query(sack, with_nevra=True, with_provides=True, with_filenames=True, forms=None) 184 185 Returns a :class:`~Query` yielding packages matching the given input. The result of the returned 186 query can be an empty set if no package matches. `sack` is the :class:`~dnf.sack.Sack` that the 187 returned query will search. `with_nevra` enable search by nevra, `with_provides` indicates 188 whether besides package names also packages' provides are searched for a match, and 189 `with_filenames` indicates whether besides package provides also packages' file provides are 190 searched for a match. `forms` is a list of pattern forms from `hawkey`_. Leaving the parameter 191 to ``None`` results in using a reasonable default list of forms. 192 193 .. method:: get_best_selector(sack, forms=None, obsoletes=True, reponame=None) 194 195 Returns a :class:`~dnf.selector.Selector` that will select a single best-matching package when 196 used in a transaction operation. `sack` and `forms` have the same meaning as in 197 :meth:`get_best_query`. If ``obsoletes``, selector will also contain packages that obsoletes 198 requested packages (default is True). If ``reponame``, the selection of available packages is 199 limited to packages from that repo (default is None). 200 201 .. method:: get_nevra_possibilities(self, forms=None) 202 203 Returns generator for every possible nevra. Each possible nevra is represented by NEVRA class 204 (libdnf) that has attributes name, epoch, version, release, arch. `forms` have the same 205 meaning as in :meth:`get_best_query`. 206 207 Example how to use it when it is known that string could be full NEVRA or NEVR:: 208 209 #!/usr/bin/python3 210 import dnf 211 import hawkey 212 213 nevra_string = "dnf-0:4.2.2-2.fc30.noarch" 214 subject = dnf.subject.Subject(nevra_string) 215 possible_nevra = subject.get_nevra_possibilities( 216 forms=[hawkey.FORM_NEVRA, hawkey.FORM_NEVR]) 217 218 for i,nevra in enumerate(possible_nevra): 219 print("Possibility {} for \"{}\":".format(i+1, nevra_string)) 220 print("name: {}".format(nevra.name)) 221 print("epoch: {}".format(nevra.epoch)) 222 print("version: {}".format(nevra.version)) 223 print("release: {}".format(nevra.release)) 224 print("architecture: {}".format(nevra.arch)) 225 print() 226