|
Packit |
6f3914 |
..
|
|
Packit |
6f3914 |
Copyright (C) 2014-2018 Red Hat, Inc.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
This copyrighted material is made available to anyone wishing to use,
|
|
Packit |
6f3914 |
modify, copy, or redistribute it subject to the terms and conditions of
|
|
Packit |
6f3914 |
the GNU General Public License v.2, or (at your option) any later version.
|
|
Packit |
6f3914 |
This program is distributed in the hope that it will be useful, but WITHOUT
|
|
Packit |
6f3914 |
ANY WARRANTY expressed or implied, including the implied warranties of
|
|
Packit |
6f3914 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
|
|
Packit |
6f3914 |
Public License for more details. You should have received a copy of the
|
|
Packit |
6f3914 |
GNU General Public License along with this program; if not, write to the
|
|
Packit |
6f3914 |
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
|
|
Packit |
6f3914 |
02110-1301, USA. Any Red Hat trademarks that are incorporated in the
|
|
Packit |
6f3914 |
source code or documentation are not subject to the GNU General Public
|
|
Packit |
6f3914 |
License and may only be used or replicated with the express permission of
|
|
Packit |
6f3914 |
Red Hat, Inc.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
======================
|
|
Packit |
6f3914 |
Queries and Subjects
|
|
Packit |
6f3914 |
======================
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. module:: dnf.query
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. class:: Query
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
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::
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
#!/usr/bin/python3
|
|
Packit |
6f3914 |
import dnf
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
base = dnf.Base()
|
|
Packit |
6f3914 |
base.fill_sack()
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
q = base.sack.query()
|
|
Packit |
6f3914 |
i = q.installed()
|
|
Packit |
6f3914 |
i = i.filter(name='dnf')
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
packages = list(i) # i only gets evaluated here
|
|
Packit |
6f3914 |
print("Installed dnf package:")
|
|
Packit |
6f3914 |
for pkg in packages:
|
|
Packit |
6f3914 |
print(pkg, pkg.reponame)
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
or::
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
#!/usr/bin/python3
|
|
Packit |
6f3914 |
import dnf
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
base = dnf.Base()
|
|
Packit |
6f3914 |
base.read_all_repos()
|
|
Packit |
6f3914 |
base.fill_sack()
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
q = base.sack.query()
|
|
Packit |
6f3914 |
a = q.available()
|
|
Packit |
6f3914 |
a = a.filter(name='dnf')
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
print("Available dnf packages:")
|
|
Packit |
6f3914 |
for pkg in a: # a only gets evaluated here
|
|
Packit |
6f3914 |
print('{} in repo {}'.format(pkg, pkg.reponame))
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Notice that none of the filtering methods mutates the state of the :class:`~dnf.query.Query` but produces a new object instead.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: available()
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Returns a new query limiting the original query to the packages available from the repositories.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: difference(other)
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Returns a new query that contains only those results of original query that are not in the results of the ``other`` query.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: downgrades()
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
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.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: duplicated()
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
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.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: extras()
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Returns a new query that limits the result to installed packages that are not present in any repo
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: filter(\*\*kwargs)
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
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).
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Allowed keys are:
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
=============== ============== ======================================================
|
|
Packit |
6f3914 |
key value type value meaning
|
|
Packit |
6f3914 |
=============== ============== ======================================================
|
|
Packit |
6f3914 |
arch string match against packages' architecture
|
|
Packit |
6f3914 |
downgrades boolean see :meth:`downgrades`. Defaults to ``False``.
|
|
Packit |
6f3914 |
empty boolean ``True`` limits to empty result set.
|
|
Packit |
6f3914 |
Defaults to ``False``.
|
|
Packit |
6f3914 |
epoch integer match against packages' epoch.
|
|
Packit |
6f3914 |
file string match against packages' files
|
|
Packit |
6f3914 |
latest integer limit to all packages of number of versions
|
|
Packit |
6f3914 |
latest_per_arch integer see :meth:`latest`.
|
|
Packit |
6f3914 |
name string match against packages' names
|
|
Packit |
6f3914 |
release string match against packages' releases
|
|
Packit |
6f3914 |
reponame string match against packages repositories' names
|
|
Packit |
6f3914 |
version string match against packages' versions
|
|
Packit |
6f3914 |
obsoletes Query match packages that obsolete any package from query
|
|
Packit |
6f3914 |
pkg Query match against packages in query
|
|
Packit |
6f3914 |
pkg* list match against hawkey.Packages in list
|
|
Packit |
6f3914 |
provides string match against packages' provides
|
|
Packit |
6f3914 |
provides* Hawkey.Reldep match against packages' provides
|
|
Packit |
6f3914 |
requires string match against packages' requirements
|
|
Packit |
6f3914 |
requires* Hawkey.Reldep match against packages' requirements
|
|
Packit |
6f3914 |
sourcerpm string match against packages' source rpm
|
|
Packit |
6f3914 |
upgrades boolean see :meth:`upgrades`. Defaults to ``False``.
|
|
Packit |
6f3914 |
=============== ============== ======================================================
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
\* The key can also accept a list of values with specified type.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
The key name can be supplemented with a relation-specifying suffix, separated by ``__``:
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
========== =========== ==========================================================
|
|
Packit |
6f3914 |
key suffix value type semantics
|
|
Packit |
6f3914 |
========== =========== ==========================================================
|
|
Packit |
6f3914 |
eq any exact match; This is the default if no suffix is specified.
|
|
Packit |
6f3914 |
glob string shell-style wildcard match
|
|
Packit |
6f3914 |
gt integer the actual value is greater than specified
|
|
Packit |
6f3914 |
gte integer the actual value is greater than or equal to specified
|
|
Packit |
6f3914 |
lt integer the actual value is less than specified
|
|
Packit |
6f3914 |
lte integer the actual value is less than or equal to specified
|
|
Packit |
6f3914 |
neq any does not equal
|
|
Packit |
6f3914 |
substr string the specified value is contained in the actual value
|
|
Packit |
6f3914 |
========== =========== ==========================================================
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
For example, the following creates a query that matches all packages containing the string "club" in its name::
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
q = base.sack.query().filter(name__substr="club")
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: filterm(\*\*kwargs)
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Similar to :meth:`dnf.query.Query.filter` but it modifies the query in place.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: installed()
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Returns a new query that limits the result to the installed packages only.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: intersection(other)
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Returns a new query where the result contains only packages that are found in both original and ``other`` queries.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: latest(limit=1)
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Returns a new query that limits the result to ``limit`` highest version of packages per package
|
|
Packit |
6f3914 |
name and per architecture. In case the limit is negative number, it excludes the number of
|
|
Packit |
6f3914 |
latest versions according to limit.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: run()
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Evaluate the query. Returns a list of matching :class:`dnf.package.Package` instances.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: union(other)
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Returns a new query where the results of the ``other`` query are added to the results of the original query.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: upgrades()
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
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.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. module:: dnf.subject
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. class:: Subject
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
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.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: __init__(pkg_spec, ignore_case=False)
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
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`.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: get_best_query(sack, with_nevra=True, with_provides=True, with_filenames=True, forms=None)
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Returns a :class:`~Query` yielding packages matching the given input. The result of the returned
|
|
Packit |
6f3914 |
query can be an empty set if no package matches. `sack` is the :class:`~dnf.sack.Sack` that the
|
|
Packit |
6f3914 |
returned query will search. `with_nevra` enable search by nevra, `with_provides` indicates
|
|
Packit |
6f3914 |
whether besides package names also packages' provides are searched for a match, and
|
|
Packit |
6f3914 |
`with_filenames` indicates whether besides package provides also packages' file provides are
|
|
Packit |
6f3914 |
searched for a match. `forms` is a list of pattern forms from `hawkey`_. Leaving the parameter
|
|
Packit |
6f3914 |
to ``None`` results in using a reasonable default list of forms.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: get_best_selector(sack, forms=None, obsoletes=True, reponame=None, reports=False)
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Returns a :class:`~dnf.selector.Selector` that will select a single best-matching package when
|
|
Packit |
6f3914 |
used in a transaction operation. `sack` and `forms` have the same meaning as in
|
|
Packit |
6f3914 |
:meth:`get_best_query`. If ``obsoletes``, selector will also contain packages that obsoletes
|
|
Packit |
6f3914 |
requested packages (default is True). If ``reponame``, the selection of available packages is
|
|
Packit |
6f3914 |
limited to packages from that repo (default is None). Attribute ``reports`` is deprecated and
|
|
Packit |
6f3914 |
not used any more. Will be removed on 2018-01-01.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
.. method:: get_nevra_possibilities(self, forms=None)
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Returns generator for every possible nevra. Each possible nevra is represented by NEVRA class
|
|
Packit |
6f3914 |
(libdnf) that has attributes name, epoch, version, release, arch. `forms` have the same
|
|
Packit |
6f3914 |
meaning as in :meth:`get_best_query`.
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
Example how to use it when it is known that string could be full NEVRA or NEVR::
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
#!/usr/bin/python3
|
|
Packit |
6f3914 |
import dnf
|
|
Packit |
6f3914 |
import hawkey
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
nevra_string = "dnf-0:4.2.2-2.fc30.noarch"
|
|
Packit |
6f3914 |
subject = dnf.subject.Subject(nevra_string)
|
|
Packit |
6f3914 |
possible_nevra = subject.get_nevra_possibilities(
|
|
Packit |
6f3914 |
forms=[hawkey.FORM_NEVRA, hawkey.FORM_NEVR])
|
|
Packit |
6f3914 |
|
|
Packit |
6f3914 |
for i,nevra in enumerate(possible_nevra):
|
|
Packit |
6f3914 |
print("Possibility {} for \"{}\":".format(i+1, nevra_string))
|
|
Packit |
6f3914 |
print("name: {}".format(nevra.name))
|
|
Packit |
6f3914 |
print("epoch: {}".format(nevra.epoch))
|
|
Packit |
6f3914 |
print("version: {}".format(nevra.version))
|
|
Packit |
6f3914 |
print("release: {}".format(nevra.release))
|
|
Packit |
6f3914 |
print("architecture: {}".format(nevra.arch))
|
|
Packit |
6f3914 |
print()
|