132 lines
4.7 KiB
Markdown
132 lines
4.7 KiB
Markdown
|
|
<!--
|
||
|
|
SPDX-FileCopyrightText: 2023 Maxwell G <gotmax@e.email>
|
||
|
|
SPDX-License-Identifier: GPL-2.0-or-later
|
||
|
|
-->
|
||
|
|
|
||
|
|
# fedrq's Python API
|
||
|
|
|
||
|
|
The `fedrq.config` module and the `fedrq.backend` package are public API.
|
||
|
|
Everything under `fedrq.cli` is internal. fedrq is a primarily a CLI tool and
|
||
|
|
its API abstracts the specific dnf/libdnf5 functionality that it uses. Its main
|
||
|
|
purpose is repoquerying, but you can use the fedrq functionality you want and
|
||
|
|
then access the underlying dnf Base object to preform other tasks if needed.
|
||
|
|
|
||
|
|
Take a look at the docstrings for more information.
|
||
|
|
|
||
|
|
## fedrq.backends
|
||
|
|
|
||
|
|
This is the heart of fedrq's API. There is a dnf backend (`fedrq.backends.dnf`)
|
||
|
|
and a libdnf5 backend (`fedrq.backends.libdnf5`). This package provides an
|
||
|
|
interface to configure a Base session, load repositories, preform queries, and
|
||
|
|
related functionality. The main primitives are:
|
||
|
|
|
||
|
|
### BaseMaker
|
||
|
|
|
||
|
|
**Base class**: `fedrq.backends.base.BaseMakerBase`
|
||
|
|
|
||
|
|
**dnf backend:** `fedrq.backends.dnf.backend.BaseMaker`
|
||
|
|
|
||
|
|
**libdnf5 backend:** `fedrq.backends.libdnf5.backend.BaseMaker`
|
||
|
|
|
||
|
|
`BaseMaker` allows configuring a dnf Base session and loading repositories.
|
||
|
|
|
||
|
|
### Repoquery
|
||
|
|
|
||
|
|
**Base class**: `fedrq.backends.base.RepoqueryBase`
|
||
|
|
|
||
|
|
**dnf backend:** `fedrq.backends.dnf.backend.Repoquery`
|
||
|
|
|
||
|
|
**libdnf5 backend:** `fedrq.backends.libdnf5.backend.Repoquery`
|
||
|
|
|
||
|
|
`BaseMaker` takes an initialized Base object (see `BaseMaker`) and allows
|
||
|
|
preforming a large range of queries. Most of its methods return
|
||
|
|
`PackageQueryCompat` or `PackageCompat` objects.
|
||
|
|
|
||
|
|
|
||
|
|
### PackageQueryCompat
|
||
|
|
|
||
|
|
**Protocol:** `fedrq.backends.base.PackageCompat`
|
||
|
|
|
||
|
|
**dnf backend:** `fedrq.backends.dnf.backend.PackageQuery` -> `hawkey.Query`
|
||
|
|
|
||
|
|
**libdnf5 backend:** `fedrq.backends.libdnf5.backend.Package`
|
||
|
|
(`libdnf5.package.Package` subclass)
|
||
|
|
|
||
|
|
PackageQueryCompat is a set like object of PackageCompat objects. It contains
|
||
|
|
methods to filter its Packages based on certain criteria. Typically, you'd
|
||
|
|
access these through the Repoquery class.
|
||
|
|
|
||
|
|
- `fedrq.backends.libdnf5.backend.PackageQuery` - subclass of
|
||
|
|
`libdnf5.rpm.PackageQuery`. adds back missing `query` and `querym` methods.
|
||
|
|
|
||
|
|
|
||
|
|
### PackageCompat
|
||
|
|
|
||
|
|
|
||
|
|
**Protocol:** `fedrq.backends.base.PackageCompat`
|
||
|
|
|
||
|
|
**dnf backend:** `fedrq.backends.dnf.backend.Package` -> `dnf.package.Package`
|
||
|
|
|
||
|
|
**libdnf5 backend:** `fedrq.backends.libdnf5.backend.Package`
|
||
|
|
(`libdnf5.package.Package` subclass)
|
||
|
|
|
||
|
|
- `fedrq.backends.libdnf5.backend.Package` - subclass of `libdnf5.rpm.Package`
|
||
|
|
that implements missing functionality and compatability with
|
||
|
|
`dnf.package.Package`. includes properties to access Package attributes.
|
||
|
|
These properties were removed from libdnf5 in favor of `get_foo()` methods.
|
||
|
|
It also includes rich comparison support (`__lt__`, `__gt__`, etc.) and
|
||
|
|
implements roughly the same sort order as the dnf backend and adds a
|
||
|
|
`__hash__()` method so it can e.g. be used in a set or as a dictionary key.
|
||
|
|
|
||
|
|
Importing `fedrq.backends.libdnf5.backend` registers the `Package` subclass
|
||
|
|
so PackageQuery contains our subclass.
|
||
|
|
|
||
|
|
## fedrq.config
|
||
|
|
|
||
|
|
Most of the code here should not be called directly. Use `get_config()` to load
|
||
|
|
the configuration from the filesystem. Create an `RQConfig` object manually if
|
||
|
|
you must.
|
||
|
|
|
||
|
|
This exaple shows how to load the configuration and preform a basic query.
|
||
|
|
|
||
|
|
``` python
|
||
|
|
# SPDX-License-Identifier: Unlicense
|
||
|
|
# SPDX-FileCopyrightText: None
|
||
|
|
|
||
|
|
# Roughly equivalent to:
|
||
|
|
# fedrq whatrequires --arch=noarch -b rawhide -r buildroot bash | grep '^a'
|
||
|
|
|
||
|
|
from fedrq.config import get_config, RQConfig
|
||
|
|
from fedrq.backends.base import RepoqueryBase
|
||
|
|
|
||
|
|
# Load config from filesystem and override some options
|
||
|
|
config: RQConfig = get_config(backend="libdnf5")
|
||
|
|
|
||
|
|
# Query the Fedora Rawhide koji buildroot repositories
|
||
|
|
# This supports any release configuration builtin to fedrq
|
||
|
|
# or configured on your local system.
|
||
|
|
rq: RepoqueryBase = config.get_rq("rawhide", "buildroot")
|
||
|
|
|
||
|
|
# Get all noarch packages that start with 'a' and depend on bash
|
||
|
|
query = rq.query(
|
||
|
|
name__glob="a*", arch="noarch", requires=rq.query(name="bash", arch="notsrc")
|
||
|
|
)
|
||
|
|
# By using sorted(), you'll get (relatively) consistent ordering between backends
|
||
|
|
for package in sorted(query):
|
||
|
|
print(package)
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
## Examples
|
||
|
|
|
||
|
|
See [api-examples] for some simple example code.
|
||
|
|
|
||
|
|
Real world examples:
|
||
|
|
|
||
|
|
- [mkblocker.py] - given a list of source packages names, use jinja2 to
|
||
|
|
template a specfile that Conflicts on every subpackage produced by the source
|
||
|
|
packages. This was used as part of the [Mass_Retire_Golang_Leaves] Fedora Change.
|
||
|
|
|
||
|
|
[api-examples]: https://git.sr.ht/~gotmax23/fedrq/tree/main/item/contrib/api_examples
|
||
|
|
[mkblocker.py]: https://git.sr.ht/~gotmax23/fedora-scripts/tree/main/item/go-sig/blocker/mkblocker.py
|
||
|
|
[Mass_Retire_Golang_Leaves]: https://fedoraproject.org/wiki/Changes/Mass_Retire_Golang_Leaves#Implementation
|