Core API Reference

Koji Smoky Dingo - Client utilities for working with the Koji build system

author

Christopher O'Brien <obriencj@gmail.com>

license

GPL v3

class AnonClientSession(profile='koji')[source]

Bases: kojismokydingo.ProfileClientSession

A koji.ClientSession which loads profile config information and which can be used via the with keyword.

Suitable for working with anonymous commands which do not require authentication. Does not authenticate, and will only connect lazily.

Since

1.0

exception BadDingo[source]

Bases: Exception

Generalized base class for exceptions raised from kojismokydingo. This class and its subclasses are used to combine a fixed complaint string with some specific information. This is a convenience primarily for the CLI, but can also be used to track more detailed situations where a requested data type wasn't present on the koji hub, rather than just working with koji.GenericError

Since

1.0

complaint = 'Something bad happened'
exception FeatureUnavailable[source]

Bases: kojismokydingo.BadDingo

A given feature isn't available due to the version on the koji hub

complaint = "The koji hub version doesn't support this feature"
class ManagedClientSession(baseurl, opts=None, sinfo=None)[source]

Bases: koji.ClientSession

A koji.ClientSession that can be used as via the with keyword to provide a managed session that will handle authenticated login and logout.

Since

1.0

exception NoSuchArchive[source]

Bases: kojismokydingo.BadDingo

An archive was not found

Since

1.0

complaint = 'No such archive'
exception NoSuchBuild[source]

Bases: kojismokydingo.BadDingo

A build was not found

Since

1.0

complaint = 'No such build'
exception NoSuchChannel[source]

Bases: kojismokydingo.BadDingo

A channel was not found

Since

1.0

complaint = 'No such builder channel'
exception NoSuchContentGenerator[source]

Bases: kojismokydingo.BadDingo

A content generator was not found

Since

1.0

complaint = 'No such content generator'
exception NoSuchPackage[source]

Bases: kojismokydingo.BadDingo

A package was not found

Since

1.1

complaint = 'No such package'
exception NoSuchPermission[source]

Bases: kojismokydingo.BadDingo

A permission was not found

Since

1.0

complaint = 'No such permission'
exception NoSuchRPM[source]

Bases: kojismokydingo.BadDingo

An RPM was not found

Since

1.0

complaint = 'No such RPM'
exception NoSuchRepo[source]

Bases: kojismokydingo.BadDingo

A repository was not found

Since

1.1

complaint = 'No such repo'
exception NoSuchTag[source]

Bases: kojismokydingo.BadDingo

A tag was not found

Since

1.0

complaint = 'No such tag'
exception NoSuchTarget[source]

Bases: kojismokydingo.BadDingo

A target was not found

Since

1.0

complaint = 'No such target'
exception NoSuchTask[source]

Bases: kojismokydingo.BadDingo

A task was not found

Since

1.0

complaint = 'No such task'
exception NoSuchUser[source]

Bases: kojismokydingo.BadDingo

A user was not found

Since

1.0

complaint = 'No such user'
exception NotPermitted[source]

Bases: kojismokydingo.BadDingo

A required permission was not associated with the currently logged in user account.

Since

1.0

complaint = 'Insufficient permissions'
class ProfileClientSession(profile='koji')[source]

Bases: kojismokydingo.ManagedClientSession

A koji.ClientSession which loads profile config information and which can be used via tha with keyword.

Since

1.0

as_archiveinfo(session, archive)[source]

Coerces an archive value into an archive info dict.

If archive is an:
  • int, will attempt to load as an archive ID

  • str, will attempt to load as an archive filename

  • dict, will presume already an archive info

Parameters
  • session -- an active koji client session

  • archive (int or str or dict) -- value to lookup

Return type

dict

Raises

NoSuchArchive -- if the archive value could not be resolved into an archive info dict

Since

1.0

as_buildinfo(session, build)[source]

Coerces a build value into a koji build info dict.

If build is an
  • int, will attempt to load as a build ID

  • str, will attempt to load as an NVR

  • dict, will presume already a build info

Parameters
  • session -- an active koji client session

  • build (int or str or dict) -- value to lookup

Return type

dict

Raises

NoSuchBuild -- if the build value could not be resolved into a build info dict

Since

1.0

as_channelinfo(session, channel)[source]

Coerces a channel value into a koji channel info dict.

If channel is an
  • int, will attempt to load as a channel ID

  • str, will attempt to load as a channel name

  • dict, will presume already a channel info

Parameters
  • session -- an active koji client session

  • channel -- value to lookup

Return type

dict

Raises

NoSuchChannel -- if the channel could not be resolved

Since

1.1

as_hostinfo(session, host)[source]

Coerces a host value into a host info dict.

If target is an:
  • int, will attempt to load as a host ID

  • str, will attempt to load as a host name

  • dict, will presume already a host info

Parameters
  • session -- an active koji client session

  • host (int or str or dict) -- value to lookup

Return type

dict

Raises

NoSuchHost -- if the host value could not be resolved into a host info dict

Since

1.0

as_packageinfo(session, pkg)[source]

Coerces a host value into a host info dict.

If pkg is an:
  • int, will attempt to load as a package ID

  • str, will attempt to load as a package name

  • dict, will presume already a package info

Parameters
  • session -- an active koji client session

  • pkg -- value to lookup

Return type

dict

Raises

NoSuchPackage -- if the pkg value could not be resolved into a package info dict

Since

1.1

as_repoinfo(session, repo)[source]

Coerces a repo value into a Repo info dict.

If repo is an:
  • dict with name, will attempt to load the current repo from a tag by that name

  • str, will attempt to load the current repo from a tag by name

  • int, will attempt to load the repo by ID

  • dict, will presume already a repo info

Parameters
  • session -- an active koji client session

  • repo -- repo to resolve

Return type

dict

Raises

NoSuchRepo -- if the repo value could not be resolved to a repo info dict

Since

1.1

as_rpminfo(session, rpm)[source]

Coerces a host value into a RPM info dict.

If rpm is an:
  • int, will attempt to load as a RPM ID

  • str, will attempt to load as a RPM NVR

  • dict, will presume already an RPM info

Parameters
  • session -- an active koji client session

  • rpm (int or str or dict) -- value to lookup

Return type

dict

Raises

NoSuchRPM -- if the rpm value could not be resolved into a RPM info dict

Since

1.0

as_taginfo(session, tag)[source]

Coerces a tag value into a koji tag info dict.

If tag is an
  • int, will attempt to load as a tag ID

  • str, will attempt to load as a tag name

  • dict, will presume already a tag info

Parameters
  • session -- an active koji client session

  • tag (int or str or dict) -- value to lookup

Return type

dict

Raises

NoSuchTag -- if the tag value could not be resolved into a tag info dict

Since

1.0

as_targetinfo(session, target)[source]

Coerces a target value into a koji target info dict.

If target is an
  • int, will attempt to load as a target ID

  • str, will attempt to load as a target name

  • dict, will presume already a target info

Parameters
  • session -- an active koji client session

  • target (int or str or dict) -- value to lookup

Return type

dict

Raises

NoSuchTarget -- if the target value could not be resolved into a target info dict

Since

1.0

as_taskinfo(session, task)[source]

Coerces a task value into a koji task info dict.

If task is an
  • int, will attempt to load as a task ID

  • dict, will presume already a task info

Parameters
  • session -- an active koji client session

  • task (int or dict) -- value to lookup

Return type

dict

Raises

NoSuchTask -- if the task value could not be resolved into a task info dict

Since

1.0

as_userinfo(session, user)[source]

Resolves user to a userinfo dict.

If user is a str or int, then getUser will be invoked. If user is already a dict, it's presumed to be a userinfo already and it's returned unaltered.

Parameters
  • session -- an active koji client session

  • user (str or int or dict) -- Name, ID, or User Info describing a koji user

Return type

dict

Raises

NoSuchUser -- when user cannot be found

Since

1.0

bulk_load(session, loadfn, keys, err=True, size=100, results=None)[source]

Generic bulk loading function. Invokes the given loadfn on each key in keys using chunking multicalls limited to the specified size.

Returns an OrderedDict associating the individual keys with the returned value of loadfn. If results is specified, it must support dict-like assignment via an update method, and will be used in place of a newly allocated OrderedDict to store and return the results.

Parameters
  • session (koji.ClientSession) -- The koji session

  • loadfn (Callable[[object], object]) -- The loading function, to be invoked in a multicall arrangement. Will be called once with each given key from keys

  • keys (list[object]) -- The sequence of keys to be used to invoke loadfn. These keys need to be individually hashable, or the results value needs to be specified with an instance that accepts assignmnet using these values as the key.

  • err (bool, optional) -- Whether to raise any underlying fault returns as exceptions. Default, True

  • size (int, optional) -- How many calls to loadfn to chunk up for each multicall. Default, 100

  • results (dict, optional) -- storage for loadfn results. If specified, must support item assignment (like a dict) via an update method, and it will be populated and then used as the return value for this function. Default, a new OrderedDict will be allocated.

Raises

koji.GenericError -- if err is True and an issue occurrs while invoking the loadfn

Return type

dict[object, object]

bulk_load_build_archives(session, build_ids, btype=None, size=100, results=None)[source]

Set up a chunking multicall to fetch the archives of builds via session.listArchives for each build ID in build_ids.

Returns an OrderedDict associating the individual build IDs with their resulting archive lists.

If results is non-None, it must support dict-like update method, and will be used in place of a newly allocated OrderedDict to store and return the results.

bulk_load_build_rpms(session, build_ids, size=100, results=None)[source]

Set up a chunking multicall to fetch the RPMs of builds via session.listRPMS for each build ID in build_ids.

Returns an OrderedDict associating the individual build IDs with their resulting RPM lists.

If results is non-None, it must support a dict-like update method, and will be used in place of a newly allocated OrderedDict to store and return the results.

bulk_load_buildroot_archives(session, buildroot_ids, btype=None, size=100, results=None)[source]

Set up a chunking multicall to fetch the archives of buildroots via session.listArchives for each buildroot ID in buildrood_ids.

Returns an OrderedDict associating the individual buildroot IDs with their resulting archive lists.

If results is non-None, it must support dict-like update method, and will be used in place of a newly allocated OrderedDict to store and return the results.

bulk_load_buildroot_rpms(session, buildroot_ids, size=100, results=None)[source]

Set up a chunking multicall to fetch the RPMs of buildroots via session.listRPMs for each buildroot ID in buildrood_ids.

Returns an OrderedDict associating the individual buildroot IDs with their resulting RPM lists.

If results is non-None, it must support dict-like update method, and will be used in place of a newly allocated OrderedDict to store and return the results.

bulk_load_buildroots(session, broot_ids, size=100, results=None)[source]

Set up a chunking multicall to fetch the buildroot data via session.getBuildroot for each ID in broot_ids.

Returns an OrderedDict associating the individual buildroot IDs with their resulting buildroot info dicts.

If results is non-None, it must support a dict-like update method, and will be used in place of a newly allocated OrderedDict to store and return the results.

bulk_load_builds(session, nvrs, err=True, size=100, results=None)[source]

Load many buildinfo dicts from a koji client session and a sequence of NVRs.

Returns an OrderedDict associating the individual NVRs with their resulting buildinfo.

If err is True (default) then any missing build info will raise a NoSuchBuild exception. If err is False, then a None will be substituted into the ordered dict for the result.

If results is non-None, it must support dict assignment, and will be used in place of a newly allocated OrderedDict to store and return the results.

Parameters
  • nvrs (Iterator[str] or Iterator[int]) -- Sequence of build NVRs or build IDs to load

  • err (bool, optional) -- Raise an exception if an NVR fails to load. Default, True.

  • size (int, optional) -- Count of NVRs to load in a single multicall. Default, 100

  • results (Mapping, optional) -- mapping to store the results in. Default, produce a new OrderedDict

Return type

Mapping

bulk_load_rpm_sigs(session, rpm_ids, size=100, results=None)[source]

Set up a chunking multicall to fetch the signatures for a list of RPM via session.queryRPMSigs for each ID in rpm_ids.

Returns an OrderedDict associating the individual RPM IDs with their resulting RPM signature lists.

If results is non-None, it must support a dict-like update method, and will be used in place of a newly allocated OrderedDict to store and return the results.

bulk_load_tags(session, tags, err=True, size=100, results=None)[source]
Parameters
  • err (bool, optional) -- Raise an exception if a tag fails to load. Default, True.

  • size (int, optional) -- Count of tags to load in a single multicall. Default, 100

bulk_load_tasks(session, task_ids, request=False, err=True, size=100, results=None)[source]

Load many taskinfo dicts from a koji client session and a sequence of task IDs.

Returns an OrderedDict associating the individual IDs with their resulting taskinfo.

bulk_load_users(session, users, err=True, size=100, results=None)[source]

Load many userinfo dicts from a koji client session and a sequence of user identifiers.

Returns an OrderedDict associating the individual identifiers with their resulting userinfo.

If err is True (default) then any missing user info will raise a NoSuchUser exception. If err is False, then a None will be substituted into the ordered dict for the result.

If results is non-None, it must support dict assignment, and will be used in place of a newly allocated OrderedDict to store and return the results.

Parameters
  • session (koji.ClientSession) -- active koji session

  • users (Iterator[str] or Iterator[int]) -- user names or IDs to load

  • err (bool, optional) -- halt on problems and raise an exception. Default, True

  • size (int, optional) -- number of users to load in a single multicall. Default, 100

  • results (dict, optional) -- dict to store results in. Default, allocate a new OrderedDict

Return type

dict

Since

1.0

hub_version(session)[source]

Wrapper for session.getKojiVersion which caches the results on the session and splits the value into a tuple of ints for easy comparison.

If the getKojiVersion method isn't implemented on the hub, we presume that we're version 1.22 (1, 22) which is the last version before getKojiVersion was added.

Parameters

session -- an active koji client session

Return type

tuple[int]

Since

1.0

iter_bulk_load(session, loadfn, keys, err=True, size=100)[source]

Generic bulk loading generator. Invokes the given loadfn on each key in keys using chunking multicalls limited to the specified size.

Yields (key, result) pairs in order.

If err is True (default) then any faults will raise an exception. If err is False, then a None will be substituted as the result for the failing key.

Parameters
  • session (koji.ClientSession) -- The koji session

  • loadfn (Callable[[object], object]) -- The loading function, to be invoked in a multicall arrangement. Will be called once with each given key from keys

  • keys (list[object]) -- The sequence of keys to be used to invoke loadfn.

  • err (bool, optional) -- Whether to raise any underlying fault returns as exceptions. Default, True

  • size (int, optional) -- How many calls to loadfn to chunk up for each multicall. Default, 100

Raises

koji.GenericError -- if err is True and an issue occurrs while invoking the loadfn

Return type

Generator[tuple[object, object]]

version_check(session, minimum=(1, 23))[source]

Verifies that the requested minimum version is met compared against session.getKojiVersion.

If the getKojiVersion method isn't implemented on the hub, we presume that we're version 1.22 (the last version before getKojiVersion was added). Because of this, checking for minimum versions lower than 1.23 will always return True.

Version is specified as a tuple of integers, eg. 1.23 is (1, 23)

Parameters
  • session -- an active koji client session

  • minimum (tuple[int]) -- Minimum version required. Default, (1, 23)

Return type

bool

Since

1.0

version_require(session, minimum=(1, 23), message=None)[source]

Verifies that the requested minimum version is met compared against session.getKojiVersion()

If the getKojiVersion method isn't implemented on the hub, we presume that we're version 1.22 (the last version before getKojiVersion was added). Because of this, checking for minimum versions lower than 1.23 will always return True.

Version is specified as a tuple of integers, eg. 1.23 is (1, 23)

If the version requirement is not met, a FeatureUnavailable exception is raised, with the given message. If message is not provided, a simple one is constructed based on the minimum value.

Parameters
  • session -- an active koji client session

  • minimum (tuple[int]) -- Minimum version required. Default, (1, 23)

  • message (str, optional) -- Message to use in exception if version check fails. Default, with a minimum of (1, 23), "requires >= 1.23"

Raises

FeatureUnavailable -- If the minimum version is not met

Return type

bool

Since

1.0