Python bindings

This module provides Python bindings to the Bodhi REST API.

class bodhi.client.bindings.BodhiClient(base_url: str = 'https://bodhi.fedoraproject.org/', client_id: str = 'bodhi-client', id_provider: str = 'https://id.fedoraproject.org/openidc', staging: bool = False, oidc_storage_path: str | None = None)[source]

Bases: object

Python bindings to the Bodhi server REST API.

__dict__ = mappingproxy({'__module__': 'bodhi.client.bindings', '__doc__': 'Python bindings to the Bodhi server REST API.', '__init__': <function BodhiClient.__init__>, '_build_oidc_client': <function BodhiClient._build_oidc_client>, 'send_request': <function BodhiClient.send_request>, 'ensure_auth': <function BodhiClient.ensure_auth>, 'clear_auth': <function BodhiClient.clear_auth>, 'username': <property object>, 'save': <function BodhiClient.save>, 'request': <function BodhiClient.request>, 'waive': <function BodhiClient.waive>, 'trigger_tests': <function BodhiClient.trigger_tests>, 'query': <function BodhiClient.query>, 'get_test_status': <function BodhiClient.get_test_status>, 'comment': <function BodhiClient.comment>, 'save_override': <function BodhiClient.save_override>, 'get_compose': <function BodhiClient.get_compose>, 'list_composes': <function BodhiClient.list_composes>, 'list_overrides': <function BodhiClient.list_overrides>, 'csrf': <function BodhiClient.csrf>, 'parse_file': <function BodhiClient.parse_file>, 'latest_builds': <function BodhiClient.latest_builds>, 'testable': <function BodhiClient.testable>, 'compose_str': <staticmethod(<function BodhiClient.compose_str>)>, 'override_str': <staticmethod(<function BodhiClient.override_str>)>, 'update_str': <function BodhiClient.update_str>, 'get_releases': <function BodhiClient.get_releases>, 'get_koji_session': <function BodhiClient.get_koji_session>, 'koji_session': <property object>, 'candidates': <function BodhiClient.candidates>, '__dict__': <attribute '__dict__' of 'BodhiClient' objects>, '__weakref__': <attribute '__weakref__' of 'BodhiClient' objects>, '__annotations__': {}})
__init__(base_url: str = 'https://bodhi.fedoraproject.org/', client_id: str = 'bodhi-client', id_provider: str = 'https://id.fedoraproject.org/openidc', staging: bool = False, oidc_storage_path: str | None = None)[source]

Initialize the Bodhi client.

Parameters:

  • base_url – The URL of the Bodhi server to connect to. Ignored if `staging` is True.

  • client_id – The OpenID Connect Client ID.

  • staging – If True, use the staging server. If False, use base_url.

  • oidc_storage_path – Path to a file were OIDC credentials are stored

__module__ = 'bodhi.client.bindings'
__weakref__

list of weak references to the object (if defined)

candidates() → Iterable[dict][source]

Get a list list of update candidates.

Returns:

A list of koji builds (dictionaries returned by koji.listTagged()) that are tagged as candidate builds and are owned by the current user.

clear_auth()[source]

Clear the authentication information.

comment(update: str, comment: str, karma: int = 0) → munch.Munch[source]

Add a comment to an update.

Parameters:

  • update – The alias of the update comment on.

  • comment – The text of the comment to add to the update.

  • karma – The amount of karma to leave. May be -1, 0, or 1. Defaults to 0.

Returns:

The response from the post to comments/.

static compose_str(compose: dict, minimal: bool = True) → str[source]

Return a string representation of a compose.

Parameters:

  • compose – A dictionary representation of a Compose.

  • minimal – If True, return a minimal one-line representation of the compose. Otherwise, return a more verbose string. Defaults to True.

Returns:

A human readable string describing the compose.

csrf() → str[source]

Return CSRF token if already acquired, otherwise login, get a CSRF, cache it, and return.

If there is already a CSRF token, this method returns it.

If there is not, this method ensures that we know the username, logs in if we aren’t already logged in acquires and caches a CSRF token, and returns it.

Returns:

The CSRF token.

ensure_auth()[source]

Make sure we are authenticated.

get_compose(release: str, request: str) → munch.Munch[source]

Get information about compose.

Parameters:

  • release – The name of the release.

  • request – The request (testing, stable).

Returns:

The response from Bodhi to the request.

Raises:

ComposeNotFound – If the server returns a 404 error code.

get_koji_session() → ClientSession[source]

Return an authenticated koji session.

Returns:

An initialized authenticated koji client.

get_releases(**kwargs) → munch.Munch[source]

Return a list of bodhi releases.

This method returns a dictionary in the following format:

{"releases": [
    {"dist_tag": "dist-f12", "id_prefix": "FEDORA",
     "locked": false, "name": "F12", "long_name": "Fedora 12"}]}
Parameters:

kwargs – A dictionary of extra parameters to pass along with the request.

Returns:

A dictionary describing Bodhi’s release objects.

get_test_status(update: str) → munch.Munch[source]

Query bodhi for the test status of the specified update..

Parameters:

update – The alias of the update to retrieve the test status of.

Returns:

The response from Bodhi describing the query results.

property koji_session: ClientSession

Return an authenticated koji session.

Returns:

An initialized authenticated koji client.

latest_builds(package: str) → munch.Munch[source]

Get the latest builds for a package.

Parameters:

package – The package name, for example “kernel”.

Returns:

A dict-like object of the release dist tag to the latest build.

list_composes() → munch.Munch[source]

List composes.

Returns:

A dictionary-like representation of the Composes.

list_overrides(user: str | None = None, packages: str | None = None, expired: bool | None = None, releases: str | None = None, builds: str | None = None, rows_per_page: int | None = None, page: int | None = None) → munch.Munch[source]

List buildroot overrides.

Parameters:

  • user – A username whose buildroot overrides you want returned.

  • packages – Comma separated package names to filter buildroot overrides by.

  • expired – If True, only return expired overrides. If False, only return active overrides.

  • releases – Comma separated Release shortnames to filter buildroot overrides by.

  • builds – Comma separated build NVRs to filter overrides by.

  • rows_per_page – Limit the results to a certain number of rows per page.

  • page – Return a specific page of results.

Returns:

A dictionary-like representation of the Overrides.

static override_str(override: dict, minimal: bool = True) → str[source]

Return a string representation of a given override dictionary.

Parameters:

  • override – An override dictionary.

  • minimal – If True, return a minimal one-line representation of the override. Otherwise, return a more verbose string. Defaults to True.

Returns:

A human readable string describing the given override.

parse_file(input_file: str) → List[Dict[str, Any]][source]

Parse an update template file.

Parameters:

input_file – The filename of the update template.

Returns:

A list of dictionaries of parsed update values which

can be directly passed to the save method.

Raises:

ValueError – If the input_file does not exist, or if it cannot be parsed.

query(**kwargs) → munch.Munch[source]

Query bodhi for a list of updates.

Parameters:

  • alias (str) – The update alias.

  • updateid (str) – The update ID (eg: FEDORA-2015-0001).

  • content_type (str) – A content type (rpm, module) to limit the query to.

  • releases (str) – A comma separated list of releases that you wish to query updates for.

  • status (str) – The update status (pending, testing, stable, obsolete, unpushed)

  • type (str) – The type of the update: security, bugfix, enhancement, and newpackage.

  • bugs (str) – A comma separated list of Red Hat Bugzilla IDs.

  • request (str) – An update request to query for testing, stable, unpush, obsolete or None.

  • mine (bool) – If True, only query the users updates. Default: False.

  • packages (str) – A space or comma delimited list of package names.

  • limit (int) – A deprecated argument, sets rows_per_page. See its docstring for more info.

  • approved_before (str) – A datetime string.

  • approved_since (str) – A datetime string.

  • builds (str) – A space or comma delimited string of build nvrs.

  • critpath (bool) – A boolean to query only critical path updates.

  • locked (bool) – A boolean to filter only locked updates.

  • modified_before (str) – A datetime string to query updates that have been modified before a certain time.

  • modified_since (str) – A datetime string to query updates that have been modified since a certain time.

  • pushed (bool) – A boolean to filter only pushed updates.

  • pushed_before (str) – A datetime string to filter updates pushed before a certain time.

  • pushed_since (str) – A datetime string to filter updates pushed since a certain time.

  • severity (str) – A severity type to filter by (unspecified, urgent, high, medium, low).

  • submitted_before (str) – A datetime string to filter updates submitted before a certain time.

  • submitted_since (str) – A datetime string to filter updates submitted after a certain time.

  • suggest (str) – Query for updates that suggest a user restart (logout, reboot).

  • gating (str) – filter by TestGatingStatus description.

  • from_side_tag (bool) – A boolean to filter updates created from side tag or from normal workflow.

  • user (str) – Query for updates submitted by a specific user.

  • rows_per_page (int) – Limit the results to a certain number of rows per page (min:1 max: 100 default: 20).

  • page (int) – Return a specific page of results.

Returns:

The response from Bodhi describing the query results.

request(update: str, request: str) → munch.Munch[source]

Request an update state change.

Parameters:

  • update – The alias of the update.

  • request – The request (testing, stable, obsolete, unpush, revoke).

Returns:

The response from Bodhi to the request.

Raises:

UpdateNotFound – If the server returns a 404 error code.

save(**kwargs) → munch.Munch[source]

Save an update.

This entails either creating a new update, or editing an existing one. To edit an existing update, you must specify the update alias in the edited keyword argument.

Parameters:

  • display_name (str) – The name of the update.

  • builds (str) – A list of koji builds for this update.

  • type (str) – The type of this update: security, bugfix, enhancement, and newpackage.

  • bugs (str) – A list of Red Hat Bugzilla ID’s associated with this update.

  • notes (str) – Details as to why this update exists.

  • request (str) – Request for this update to change state, either to testing, stable, unpush, obsolete or None.

  • close_bugs (bool) – Close bugs when update is stable.

  • suggest (str) – Suggest that the user reboot or logout after update. (reboot, logout).

  • autotime (bool) – Allow bodhi to automatically change the state of this update based on the time spent in testing by this update. It will push your update to stable once it reaches the stable_days.

  • stable_days (int) – The minimun amount of time an update has to spend in testing before being automatically pushed to stable.

  • autokarma (bool) – Allow bodhi to automatically change the state of this update based on the karma from user feedback. It will push your update to stable once it reaches the stable_karma and unpush your update when reaching unstable_karma.

  • stable_karma (int) – The upper threshold for marking an update as stable.

  • unstable_karma (int) – The lower threshold for unpushing an update.

  • edited (str) – The update alias of the existing update that we are editing.

  • severity (str) – The severity of this update (urgent, high, medium, low).

  • requirements (str) – A list of required Taskotron tests that must pass for this update to reach stable. (e.g. dist.rpmdeplint, dist.upgradepath, dist.rpmlint, etc).

  • require_bugs (bool) – A boolean to require that all of the bugs in your update have been confirmed by testers.

  • require_testcases (bool) – A boolean to require that this update passes all test cases before reaching stable.

  • from_tag (str) – The name of a Koji tag from which to pull builds instead of providing them manually in builds.

Returns:

The Bodhi server’s response to the request.

save_override(nvr: str, notes: str, duration: int | None = None, expiration_date: datetime | None = None, edit: bool = False, expired: bool = False) → munch.Munch[source]

Save a buildroot override.

This entails either creating a new buildroot override, or editing an existing one.

Parameters:

  • nvr – The nvr of a koji build.

  • notes – Notes about why this override is in place.

  • duration – Number of days from now that this override should expire.

  • expiration_date – Date when this override should expire. This argument or the duration argument must be provided.

  • edit – True if we are editing an existing override, False otherwise. Defaults to False.

  • expired – Set to True to expire an override. Defaults to False.

Returns:

A dictionary-like representation of the saved override.

send_request(url, verb='GET', **kwargs)[source]

Send the request to the Bodhi server.

Parameters:

  • url (str) – The relative URL on the Bodhi server

  • verb (str, optional) – The HTTP method. Defaults to “GET”.

Returns:

The response as returned by python-requests.

Return type:

requests.Response

testable() → Iterator[dict][source]

Return a generator that iterates installed testing updates.

This method is a generator that yields packages that you currently have installed that you have yet to test and provide feedback for.

Only works on systems with dnf.

Returns:

An iterable of dictionaries describing updates that match builds installed on

the local system.

Return type:

generator

Raises:

RuntimeError – If the dnf Python bindings are not installed.

trigger_tests(update: str) → munch.Munch[source]

Trigger tests for update.

Parameters:

update – The alias of the update to run tests for.

Returns:

The response from the post to trigger_tests/.

update_str(update: dict, minimal: bool = False) → str[source]

Return a string representation of a given update dictionary.

Parameters:

  • update – An update dictionary, acquired by the list method.

  • minimal – If True, return a minimal one-line representation of the update. Otherwise, return a more verbose representation. Defaults to False.

Returns:

A human readable string describing the given update.

property username

Return the authenticated username.

waive(update: str, comment: str, tests: Iterable[str] | None = None) → munch.Munch[source]

Waive unsatisfied requirements on an update.

Parameters:

  • update – The alias of the update.

  • comment – A comment explaining the waiver.

  • tests – The list of unsatisfied requirements to waive. If not specified, all unsatisfied requirements of this update will be waived.

Returns:

The response from Bodhi to the request.

Raises:

UpdateNotFound – If the server returns a 404 error code.

exception bodhi.client.bindings.BodhiClientException(*args, **kwargs)[source]

Bases: RequestException

Used to indicate there was an error in the client.

__module__ = 'bodhi.client.bindings'
exception bodhi.client.bindings.ComposeNotFound(release: str, request: str, **kwargs)[source]

Bases: BodhiClientException

Used to indicate that a referenced Compose is not found on the server.

__annotations__ = {}
__init__(release: str, request: str, **kwargs)[source]

Initialize the Exception.

Parameters:

  • release – The release component of the compose that was not found.

  • request – The request component of the compose that was not found.

__module__ = 'bodhi.client.bindings'
__str__() → str[source]

Return a human readable error message.

Returns:

An error message.

exception bodhi.client.bindings.UpdateNotFound(update: str, **kwargs)[source]

Bases: BodhiClientException

Used to indicate that a referenced Update is not found on the server.

__annotations__ = {}
__init__(update: str, **kwargs)[source]

Initialize the Exception.

Parameters:

update – The alias of the update that was not found.

__module__ = 'bodhi.client.bindings'
__str__() → str[source]

Return a human readable error message.

Returns:

An error message.

bodhi.client.bindings.errorhandled(method: Callable) → Callable[source]

Raise exceptions on failure. Used as a decorator for BodhiClient methods.