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')

Bases: 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

Parameters:

profile (str) -- name of the koji profile to load from local configuration locations

activate()

Ensures the anonymous session is connected, but does not attempt to login.

Since:

2.0

exception BadDingo

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: str = 'Something bad happened'

exception FeatureUnavailable

Bases: BadDingo

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

complaint: str = "The koji hub version doesn't support this feature"

class ManagedClientSession(baseurl, opts=None, sinfo=None, auth_method=None)

Bases: 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

Parameters:

• str (baseurl) -- hub url

• opts (dict) -- dictionary with content varying according to authentication method

• sinfo (dict) -- session info returned by login method

• auth_method (dict) -- method for reauthentication, shouldn't be ever set manually

activate()

Invokes koji_cli.lib.activate_session with this session's options, which will trigger the appropriate login method.

Since:

2.0

property logger

exception NoSuchArchive

Bases: BadDingo

An archive was not found

Since:

1.0

complaint: str = 'No such archive'

exception NoSuchBuild

Bases: BadDingo

A build was not found

Since:

1.0

complaint: str = 'No such build'

exception NoSuchChannel

Bases: BadDingo

A channel was not found

Since:

1.0

complaint: str = 'No such builder channel'

exception NoSuchContentGenerator

Bases: BadDingo

A content generator was not found

Since:

1.0

complaint: str = 'No such content generator'

exception NoSuchHost

Bases: BadDingo

A host was not found

Since:

1.0

complaint: str = 'No such host'

exception NoSuchPackage

Bases: BadDingo

A package was not found

Since:

1.1

complaint: str = 'No such package'

exception NoSuchPermission

Bases: BadDingo

A permission was not found

Since:

1.0

complaint: str = 'No such permission'

exception NoSuchRPM

Bases: BadDingo

An RPM was not found

complaint: str = 'No such RPM'

exception NoSuchRepo

Bases: BadDingo

A repository was not found

Since:

1.1

complaint: str = 'No such repo'

exception NoSuchTag

Bases: BadDingo

A tag was not found

Since:

1.0

complaint: str = 'No such tag'

exception NoSuchTarget

Bases: BadDingo

A target was not found

Since:

1.0

complaint: str = 'No such target'

exception NoSuchTask

Bases: BadDingo

A task was not found

Since:

1.0

complaint: str = 'No such task'

exception NoSuchUser

Bases: BadDingo

A user was not found

Since:

1.0

complaint: str = 'No such user'

exception NotPermitted

Bases: BadDingo

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

complaint: str = 'Insufficient permissions'

class ProfileClientSession(profile='koji')

Bases: ManagedClientSession

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

Since:

1.0

Parameters:

profile (str) -- name of the koji profile to load from local configuration locations

as_archiveinfo(session, archive)

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 the first-found archive matching the given filename

• dict, will presume already an archive info

Parameters:

• session (ClientSession) -- active koji session

• archive (int | str | ArchiveInfo) -- value to lookup

Raises:

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

Since:

1.0

Return type:

ArchiveInfo

as_buildinfo(session, build)

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 (ClientSession) -- active koji session

• build (int | str | BuildInfo) -- value to lookup

Raises:

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

Since:

1.0

Return type:

BuildInfo

as_channelinfo(session, channel)

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 (ClientSession) -- an active koji client session

• channel (int | str | ChannelInfo) -- value to lookup

Raises:

NoSuchChannel -- if the channel value could not be resolved into a channel info dict

Since:

1.1

Return type:

ChannelInfo

as_hostinfo(session, host)

Coerces a host value into a host info dict.

If host 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 (ClientSession) -- active koji session

• host (int | str | HostInfo) -- value to lookup

Raises:

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

Since:

1.0

Return type:

HostInfo

as_packageinfo(session, pkg)

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 (ClientSession) -- an active koji client session

• pkg (int | str | PackageInfo) -- value to lookup

Raises:

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

Since:

1.1

Return type:

PackageInfo

as_repoinfo(session, repo)

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 (ClientSession) -- active koji session

• repo (int | RepoInfo | str | TagInfo) -- value to lookup

Raises:

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

Since:

1.1

Return type:

RepoInfo

as_rpminfo(session, rpm)

Coerces a host value into a RPM info dict.

If rpm is specified as an:

• int, will attempt to load as a RPM ID

• str, will attempt to load as a RPM NVRA

• dict, will presume already an RPM info

Parameters:

• session (ClientSession) -- active koji session

• rpm (int | str | RPMInfo) -- value to lookup

Raises:

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

Since:

1.0

Return type:

RPMInfo

as_taginfo(session, tag)

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 (ClientSession) -- active koji session

• tag (int | str | TagInfo) -- value to lookup

Raises:

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

Since:

1.0

Return type:

TagInfo

as_targetinfo(session, target)

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 (ClientSession) -- active koji session

• target (int | str | TargetInfo) -- value to lookup

Raises:

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

Since:

1.0

Return type:

TargetInfo

as_taskinfo(session, task)

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

Note that if this function does attempt to load a task, it will request it with the task's request data as well.

Parameters:

• session (ClientSession) -- active koji session

• task (int | TaskInfo) -- value to lookup

Raises:

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

Since:

1.0

Return type:

TaskInfo

as_userinfo(session, user)

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 (ClientSession) -- active koji session

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

Raises:

NoSuchUser -- when user cannot be found

Since:

1.0

Return type:

UserInfo

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

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

Returns a dict 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 dict to store and return the results.

Parameters:

• session (ClientSession) -- an active koji client session

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

• keys (Iterable[Any]) -- 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) -- Whether to raise any underlying fault returns as exceptions. Default, True

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

• results (dict | None) -- 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 dict will be allocated.

Raises:

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

Since:

1.0

Return type:

Dict[Any, Any]

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

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

Returns a dict 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 dict to store and return the results.

Since:

1.0

Parameters:

• session (ClientSession)

• build_ids (Iterable[int])

• btype (str | None)

• size (int)

• results (dict | None)

Return type:

Dict[int, List[ArchiveInfo]]

bulk_load_build_rpms(session, build_ids, size=100, results=None)

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

Returns a dict 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 dict to store and return the results.

Since:

1.0

Parameters:

• session (ClientSession)

• build_ids (Iterable[int])

• size (int)

• results (dict | None)

Return type:

Dict[int, List[RPMInfo]]

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

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

Returns a dict 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 dict to store and return the results.

Since:

1.0

Parameters:

• session (ClientSession)

• buildroot_ids (Iterable[int])

• btype (str | None)

• size (int)

• results (dict | None)

Return type:

Dict[int, List[ArchiveInfo]]

bulk_load_buildroot_rpms(session, buildroot_ids, size=100, results=None)

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

Returns a dict 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 dict to store and return the results.

Since:

1.0

Parameters:

• session (ClientSession)

• buildroot_ids (Iterable[int])

• size (int)

• results (dict | None)

Return type:

Dict[int, List[RPMInfo]]

bulk_load_buildroots(session, broot_ids, size=100, results=None)

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

Returns a dict 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 dict to store and return the results.

Since:

1.0

Parameters:

• session (ClientSession)

• broot_ids (Iterable[int])

• size (int)

• results (dict | None)

Return type:

Dict[int, dict]

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

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

Returns a dict 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 dict to store and return the results.

Parameters:

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

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

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

• results (dict | None) -- mapping to store the results in. Default, produce a new dict

• session (ClientSession)

Raises:

NoSuchBuild -- if err is True and any of the given builds could not be loaded

Since:

1.0

Return type:

Dict[int | str, BuildInfo]

bulk_load_rpm_sigs(session, rpm_ids, size=100, results=None)

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

Returns a dict 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 dict to store and return the results.

Since:

1.0

Parameters:

• session (ClientSession)

• rpm_ids (Iterable[int])

• size (int)

• results (dict | None)

Return type:

Dict[int, List[RPMSignature]]

bulk_load_tags(session, tags, err=True, size=100, results=None)

Load many taginfo dicts from tag names or IDs.

Parameters:

• session (ClientSession) -- an active koji client session

• tags (Iterable[str | int]) -- tag IDs or names to load

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

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

• results (dict | None) -- mapping to store the results in. Default, produce a new dict

Raises:

NoSuchTag -- if err is True and a tag couldn't be loaded

Since:

1.0

Return type:

Dict[int | str, TagInfo]

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

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

Returns a dict associating the individual IDs with their resulting taskinfo.

Parameters:

• session (ClientSession) -- an active koji client session

• task_ids (Iterable[int]) -- IDs of tasks to be loaded

• request (bool) -- if True then load the task's request data as well. Default, False

• err (bool) -- raise an exception if a task fails to load. Default, True

• size (int) -- count of tasks to load in a single multicall. Default, 100

• results (dict | None) -- mapping to store the results in. Default, produce a new dict

Raises:

NoSuchTask -- if err is True and a task couldn't be loaded

Since:

1.0

Return type:

Dict[int, TaskInfo]

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

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

Returns a dict 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 dict to store and return the results.

Parameters:

• session (ClientSession) -- active koji session

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

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

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

• results (dict | None) -- dict to store results in. Default, allocate a new dict

Raises:

NoSuchUser -- if err is True and a user could not be loaded

Since:

1.0

Return type:

Dict[int | str, UserInfo]

hub_version(session)

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 the getKojiVersion API was added.

If used with koji hub and client >= 1.35 then this value is farmed from the Koji-Version header of XMLRPC responses, rather than directly calling getKojiVersion.

Parameters:

session (ClientSession) -- active koji session

Since:

1.0

Return type:

Tuple[int, ...]

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

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 (ClientSession) -- The koji session

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

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

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

• size (int) -- 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

Since:

1.0

Return type:

Iterator[Tuple[KT, Any]]

version_check(session, minimum=(1, 23))

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 (ClientSession) -- active koji session

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

Since:

1.0

Return type:

bool

version_require(session, minimum=(1, 23), message=None)

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 (ClientSession) -- active koji session

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

• message (str | None) -- 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

Since:

1.0

Return type:

bool

Core Modules

• kojismokydingo.archives
• kojismokydingo.builds
• kojismokydingo.clients
• kojismokydingo.common
• kojismokydingo.dnf
• kojismokydingo.hosts
• kojismokydingo.rpm
• kojismokydingo.tags
• kojismokydingo.types
• kojismokydingo.users