API

Exceptions

exception pyrpkg.errors.rpkgError

Our base error class

exception pyrpkg.errors.rpkgAuthError

Raised in case of authentication errors

exception pyrpkg.errors.UnknownTargetError

exception pyrpkg.errors.HashtypeMixingError(existing_hashtype, new_hashtype)

Raised when we try to mix hash types in a sources file

exception pyrpkg.errors.MalformedLineError

Raised when parsing a sources file with malformed lines

exception pyrpkg.errors.InvalidHashType

Raised when we don’t know the requested hash algorithm

exception pyrpkg.errors.DownloadError

Raised when something went wrong during a download

exception pyrpkg.errors.UploadError(message, http_status=None)

Raised when something went wrong during an upload

cli

class pyrpkg.cli.cliClient(config, name=None)

This is a client class for rpkg clients.

_build(sets=None)

Interface for build, scratch-build and chainbuild to start build

This is where to add general code for all the build commands.

Params bool sets

used for chainbuild to indicate if packages in the chain are separated into groups in which packages will be built in parallel. For build and scratch-build, no need to pass any value and just keep it None.

Returns

task ID returned from build system. In some cases, the overrided _build could return a list of task IDs as well.

Return type

int or list[int]

_completers = {}

_generate_srpm()

Generate an SRPM from local module content, set args.srpm to the resulting file path.

_get_bool_opt(opt, default=False)

_get_rpm_package_name(rpm_file)

Returns rpm package name by examining rpm file

Parameters

rpm_file (str) – specify path to RPM file.

Returns

the name of the package in the specified file according to the contained RPM header information, or None if file does not contain RPM data.

Return type

str

_gitcred_check_input()

Parses the git-credential-helper IO format input.

_gitcred_return(args)

Returns git-credential-helper IO format output.

_gitcred_test(args)

Test the token we are about to return for freshness.

Note that this is a best-effort, and it could be that we return scucess but the actual push fails, in which case git will call the erase method, and we tell the user to retry.

_handle_srpm_option()

Generate SRPM according to –srpm option value and upload it

Returns

a unique path of directory inside server into which the SRPM will be uploaded. If –srpm is not specified, no SRPM will be uploaded and None is returned.

Return type

str

property _oidc_scopes

Returns the configured OIDC scopes to request.

_oidc_token(**kwargs)

Returns an OpenID Connect token via the global client.

Returns: (string or bool or None): Returns a string token, None if the

client did not return a token, or False if the client was not configured.

_upload_file_for_build(file, name=None)

Upload a file (srpm or module) for building.

Parameters

• file (str) – specify which file to upload.

• name (str) – specify alternate basename for file on upload server

Returns

a unique path of directory inside server into which the file has been uploaded.

Return type

str

_watch_build_tasks(task_ids)

Watch build tasks

If –nowait is specified, it does not start to watch.

Parameters

task_ids (list) – a list of task IDs to watch.

build(sets=None)

Implement build command

chainbuild()

Implement chain-build command

check_remote_rules_gating()

clean()

clog()

clone()

property cmd

This is a property for the command attribute

commit()

compile()

container_build(flatpak=False)

container_build_koji()

container_build_setup()

copr_build()

diff()

do_imports(site=None)

Import extra stuff not needed during build

As a side effect method sets self.site with a loaded library.

Parameters

site (the module of downstream client that is built on top of rpkg.) – used to specify which library to load.

extract_greenwave_url()

flatpak_build()

static get_completer(name)

Returns one custom completer from the ‘_completers’ structure.

get_name()

gimmespec()

gitbuildhash()

gitcred_erase()

Performs the git-credential-helper erase operation.

New in version 1.55.

gitcred_get()

Performs the git-credential-helper get operation.

New in version 1.55.

gitcred_store()

Nothing to do here.

New in version 1.55.

If we returned a token, that’s already stored. If the user manually entered a password, we do not want to store it. Thus we present to you, a no-op.

giturl()

greenwave_validation_gating(greenwave_url, data)

import_srpm()

install()

lint()

list_side_tags()

load_cmd()

This sets up the cmd object

local()

mock_config()

mockbuild()

property module_api_url

A property that returns the MBS base API URL based on the maximum API version supported by both rpkg and MBS :return: a string of the MBS API URL

property module_api_version

A property that returns that maximum API version supported by both rpkg and MBS :return: an int of the API version

module_build()

Builds a module using MBS

module_build_cancel()

Cancel an MBS build

module_build_info()

Show information about an MBS build

module_build_local()

Build a module locally using mbs-manager

module_build_watch()

Watch MBS builds from the command-line

module_get_auth_config()

Get the authentication configuration for the MBS

Returns

a tuple consisting of the authentication method, the OIDC ID provider, the OIDC client ID, the OIDC client secret, and the OIDC scopes. If the authentication method is not OIDC, the OIDC values in the tuple are set to None.

Return type

tuple

module_overview()

Show the overview of the latest builds in the MBS

module_scratch_build()

module_validate_config()

Validates the configuration needed for MBS commands

Raises

pyrpkg.errors.rpkgError

module_watch_build(build_ids)

Watches the first MBS build in the list in a loop that updates every 15 seconds. The loop ends when the build state is ‘failed’, ‘done’, or ‘ready’.

Parameters

build_ids (list[int]) – a list of module build IDs

property name

Property used to identify prog name and key in config file

new()

new_sources()

property oidc_client

Returns a OpenID Connect client reference.

New in version 1.55.

Returns

client if configured, None if unconfigured.

Return type

openidc_client.OpenIDCClient or None

property oidc_configured

Returns a boolean indicating whether OIDC is configured.

New in version 1.55.

Returns

True if OIDC is configured. False otherwise.

Return type

bool

parse_cmdline(manpage=False)

Parse the commandline, optionally make a manpage

This also sets up self.user

patch()

pre_push_check()

prep()

pull()

push()

register_build()

Register the build target

register_build_common()

Create a common build parser to use in other commands

register_chainbuild()

Register the chain build target

register_clean()

Register the clean target

register_clog()

Register the clog target

register_clone()

Register the clone target and co alias

register_commit()

Register the commit target and ci alias

register_compile()

Register the compile target

register_container_build()

register_container_build_common()

register_container_build_setup()

register_copr_build()

Register the copr-build target

register_diff()

Register the diff target

register_flatpak_build()

register_gimmespec()

Register the gimmespec target

register_gitbuildhash()

Register the gitbuildhash target

register_gitcred()

Register the (hidden) gitcred target

These commands implement the git-credential helper API, so that we are able to provide OpenID Connect/OAuth2 tokens if requested for https based pushing.

register_giturl()

Register the giturl target

register_help()

Register the help command.

register_import_srpm()

Register the import-srpm target

register_install()

Register the install target

register_lint()

Register the lint target

register_list_side_tags()

Register the list-side-tags target

register_local()

Register the local target

register_mock_config()

Register the mock-config target

register_mockbuild()

Register the mockbuild target

register_module_build()

register_module_build_cancel()

register_module_build_common()

Create a common module build parser to use in other commands

register_module_build_info()

register_module_build_watch()

register_module_local_build()

register_module_overview()

register_module_scratch_build()

register_new()

Register the new target

register_new_sources()

Register the new-sources target

register_patch()

Register the patch target

register_pre_push_check()

Register command line parser for subcommand pre_push_check

New in version 1.44.

register_prep()

Register the prep target

register_pull()

Register the pull target

register_push()

Register the push target

register_remote()

Add command remote and options Experimental function

register_remove_side_tag()

Register remove-side-tag command.

register_request_side_tag()

Register command line parser for subcommand request-side-tag

register_retire()

Register the retire target

register_rpm_common()

Create a common parser for rpm commands

register_scratch_build()

Register the scratch-build target

register_sources()

Register the sources target

register_srpm()

Register the srpm target

register_switch_branch()

Register the switch-branch target

register_tag()

Register the tag target

register_unused_patches()

Register the unused-patches target

register_upload()

Register the upload target

register_verify_files()

Register the verify-files target

register_verrel()

remote()

Handle command remote

remove_side_tag()

request_side_tag()

retire()

scratch_build()

static set_completer(name, method, *args, **kwargs)

Initializes custom completer and stores it into the ‘_completers’ structure. ‘name’ is a search key in the ‘_completers’ structure. ‘method’ is function that defines completer’s values/choices. Additional arguments are later passed to the ‘method’

set_module_api_url()

setupLogging(log)

Setup the various logging stuff.

setup_argparser()

Setup the argument parser and register some basic commands.

setup_completers()

Prepares custom completers.

setup_subparsers()

Setup basic subparsers that all clients should use

sources()

Download files listed in sources

For command compile, prep, install, local and srpm, files are needed to be downloaded before doing what the command does. Hence, for these cases, sources is not called from command line. Instead, from rpkg inside.

srpm()

switch_branch()

tag()

unused_patches()

upload()

usage()

verify_files()

verrel()

commands

class pyrpkg.__init__.NullHandler(level=0)

Null logger to avoid spurious messages, add a handler in app code

emit(record)

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

class pyrpkg.__init__.Commands(path, lookaside, lookasidehash, lookaside_cgi, gitbaseurl, anongiturl, branchre, kojiprofile, build_client, user=None, dist=None, target=None, quiet=False, distgit_namespaced=False, realms=None, lookaside_namespaced=False, git_excludes=None, results_dir='root')

This is a class to hold all the commands that will be called by clients

_add_git_excludes(conf_dir)

Add a list of patterns from config into the config file in a git repository. This list excludes some files or dirs to be tracked by git. This list usually includes files that are automatically generated. These changes are valid just for local git repository.

_add_git_pre_push_hook(conf_dir)

Create pre-push hook script and write it in the location: <repository_directory>/.git/hooks/pre-push This hook script is run right before the ‘git push’ command. The script contains one command - ‘pre-push-check’ that checks for possible user mistakes.

_byte_offset_to_line_number(text, offset)

Convert byte offset (given by e.g. DecodeError) to human readable format (line number and char position)

Returns

a pair of line number and char offset.

Return type

list(int, int)

_cleanup_tmp_dir(tmp_dir)

Tries to remove directory and ignores EEXIST error

If occoured directory not exist error (EEXIST) it silently continue. Otherwise raise rpkgError exception.

_clone_config(conf_git, repo)

_config_dir_basic(config_dir=None, root=None)

Setup directory with essential mock config

If config directory doesn’t exist it will be created. If temporary directory was created by this method and error occours during processing, temporary directory is removed. Otherwise it caller’s responsibility to remove this directory.

Returns used config directory

_config_dir_other(config_dir, filenames=('site-defaults.cfg', 'logging.ini'))

Populates mock config directory with other necessary files

If files are found in system config directory for mock they are copied to mock config directory defined as method’s argument. Otherwise empty files are created.

_fetch_remotes()

_find_platform_stream(name, stream, version=None)

Recursively search for the platform module in dependencies to find its stream.

The stream of the ‘platform’ pseudo-module determines what base package set we need for the runtime - and thus what build target we need.

_get_build_arches_from_spec()

Given the path to an spec, retrieve the build arches

_get_build_arches_from_srpm(srpm, arches)

Given the path to an srpm, determine the possible build arches

Use supplied arches as a filter, only return compatible arches

_get_namespace_anongiturl(repo_name)

Get the namespaced git url, if DistGit namespace enabled

Parameters

repo_name (str) – a repository name with or without namespace.

Returns

anonymous giturl with a proper namespace. If repository name does not have namespace and dist-git namespace is enabled, default namespace rpms will be set.

Return type

str

_get_namespace_giturl(repo_name)

Get the namespaced git url, if DistGit namespace enabled

Parameters

repo_name (str) – a repository name with or without namespace.

Returns

giturl with proper namespace. If namespace is not in the repository name and dist-git namespace is enabled, default namespace rpms will set.

Return type

str

_guess_hashtype()

Attempt to figure out the hash type based on branch data

_has_krb_creds()

Kerberos authentication is disabled if neither gssapi nor krbV is available

_list_branches(fetch=True)

Returns a tuple of local and remote branch names

Returns

a pair of local branch names and remote branch names.

Return type

tuple(list, list)

_load_krb_user()

This attempts to get the username from active tickets

_newer(file1, file2)

Compare the last modification time of the given files

Returns

True if file1 is newer than file2

Return type

bool

_parse_output_for_nameverrel(output)

Parses an output of the ‘rpm’ command - extracts fields from the string and set the Command object’s properties.

_process_koji_task_result(task_id)

Parse and modify output from brew/koji containing information about task (and eventually builds).

Parameters

task_id (int) – id of the current task

Returns

record containing information about repositories, builds and nvrs

Return type

dict(str, str)

_run_command(cmd, shell=False, env=None, pipe=[], cwd=None, return_stdout=False, return_stderr=False, return_text=False)

Run the given command.

_run_command is able to run single command or two commands via pipe. Whatever the way to run the command, output to both stdout and stderr will not be captured and output to terminal directly, that is useful for caller to redirect.

Parameters

• cmd (str or list) – executable and arguments to run. Depending on argument shell, cmd could be a list if shell is False, and a string if False is passed to shell.

• shell (bool) – whether to run in a shell or not, defaults to False.

• env (dict(str, str)) – environment variables to use (if any)

• pipe (str or list) – command to pipe the output of cmd into. Same as argument cmd, pipe could be a string or list depending on value of shell.

• cwd (str) – optional directory to run the command from

• return_stdout (bool) – whether to capture output to stdout and return it. Default is False.

• return_stderr (bool) – whether to capture output to stderr and return it. Default is False.

• return_text (bool) – whether to return the stdout and stder output as text instead of byte string. Default is False.

Returns

a tuple containing three values of exit code from process, output to stdout, output to stderr. Either output to stdout or stderr could be None if return_stdout or return_stderr is not set.

Return type

tuple(int, str, str)

Raises

rpkgError – any error raised from underlying subprocess while executing command in local system will be mapped to rpkgError. In addition, if process returns non-zero and error message output to stderr does not intent to be returned, the error is raised as well.

Changed in version 1.56: Added argument return_stdout, return_stderr and return_text. Return process exit code, output to stdout and stderr if process executes successfully.

_srpmdetails(srpm)

Return a tuple of package name, package files, and upload files.

add_tag(tagname, force=False, message=None, file=None)

Add a git tag to the repository

Parameters

• tagname (str) – tag name.

• force (bool) – Optionally can force the tag, include a message, or reference a message file.

• file (str) – Optional. File containing tag message.

property anon_kojisession

This property ensures the anon kojisession attribute

property branch_merge

This property ensures the branch attribute

property branch_remote

This property ensures the branch_remote attribute

build(skip_tag=False, scratch=False, background=False, url=None, chain=None, arches=None, sets=False, nvr_check=True, fail_fast=False, custom_user_metadata=None)

Initiate a build in build system

Parameters

• skip_tag (bool) – Skip the tag action after the build.

• scratch (bool) – Perform a scratch build. Default is False.

• background (bool) – Perform the build with a low priority. Default is False.

• url (str) – A url to an uploaded srpm to build from.

• arches (list) – A set of arches to limit the scratch build for.

• chain (list) – A chain build set. Only used for chain build.

• sets (bool) – whether or not the chain has sets .

• nvr_check (bool) – locally construct NVR and submit a build only if NVR doesn’t exist in a build system

• fail_fast (bool) – Perform the build in fast failure mode, which will cause the entire build to fail if any subtask/architecture build fails.

• custom_user_metadata (str) – JSON string of custom metadata

Returns

task ID returned from Koji API build and chainBuild.

Return type

int

build_target(release)

Construct build target

A build target is generally constructed by release and suffix -candidate.

Parameters

release (str) – the release name which is part of the target name.

property ca_cert

A CA certificate to authenticate the server in SSL connections

Downstream users of the pyrpkg API should override this property if they actually need to use a CA certificate, usually because their lookaside cache is using HTTPS with a self-signed certificate.

This defaults to None, which means the system CA bundle is used.

property cert_file

A client-side certificate for SSL authentication

Downstream users of the pyrpkg API should override this property if they actually need to use a client-side certificate.

This defaults to None, which means no client-side certificate is used.

check_inheritance(build_target, dest_tag)

Check if build tag inherits from dest tag

check_repo(is_dirty=True, has_namespace=True, all_pushed=True)

Check various status of current repository

Parameters

• is_dirty (bool) – Default to True. To check whether there is uncommitted changes.

• has_namespace (bool) – Default to True. To check whether this repo is checked out with namespace, e.g. rpms/, docker/. If the repo is an old checkout, warn user with message how to fix it.

• all_pushed (bool) – Default to True. To check whether all changes are pushed.

Raises

rpkgError – if any unexpected status is detected. For example, if changes are not committed yet.

clean(dry=False, useignore=True)

Clean a repository checkout of untracked files.

Parameters

• dry (bool) – Can optionally perform a dry-run. Defaults to False.

• useignore (bool) – Can optionally not use the ignore rules. Defaults to True.

clog(raw=False, subject=None)

Write the latest spec changelog entry to a clog file

clone(repo, path=None, branch=None, bare_dir=None, anon=False, target=None, depth=None, extra_args=None)

Clone a repo, optionally check out a specific branch.

Parameters

• repo (str) – the name of the repository to clone.

• path (str) – an optional basedir to perform the clone in.

• branch (str) – an optional name of a branch to checkout instead of <remote>/master.

• bare_dir (str) – an optional name of a directory to make a bare clone to if this is a bare clone. None otherwise.

• anon (bool) – whether or not to clone anonymously. Defaults to False.

• target (str) – an optional name of the folder in which to clone the repo.

• depth (int) – create a shallow clone with a history truncated to the specified number of commits.

• extra_args (list) – additional arguments that are passed to the clone command.

clone_with_dirs(repo, anon=False, target=None, depth=None, extra_args=None)

Clone a repo old style with subdirs for each branch.

Parameters

• repo (str) – name of the repository to clone.

• anon (bool) – whether or not to clone anonymously. Defaults to False.

• target (str) – an optional name of the folder in which to clone the repo.

• depth (int) – create a shallow clone with a history truncated to the specified number of commits.

• extra_args (list) – additional arguments that are passed to the clone command.

commit(message=None, file=None, files=[], signoff=False)

Commit changes to a repository (optionally found at path)

Requires the caller be a real tty or a message passed.

Parameters

• message (str) – an optional message to use as the commit message

• file (str) – an optional file to find the commit message within

• files (list) – an optional list to list files to commit.

• signoff (bool) – signoff commit optionally. Defaults to False.

property commithash

This property ensures the commit attribute

compile(arch=None, short=False, builddir=None, nocheck=False, define=None, extra_args=None)

Run rpmbuild -bc

optionally for a specific arch, or short-circuit it, define an alternate builddir, or define some macro

Logs the output and returns nothing

construct_build_url(repo_name=None, commit_hash=None)

Construct build URL with namespaced anongiturl and commit hash

Parameters

• repo_name (str) – name of the repository part of the build URL. If omitted, namespaced name will be guessed from current repository. The given repository name will be used in URL directly without guessing namespace.

• commit_hash (str) – the commit hash appended to build URL. It omitted, the latest commit hash got from current repository will be used.

Returns

URL built from anongiturl.

Return type

str

container_build_koji(target_override=False, opts={}, kojiprofile=None, build_client=None, koji_task_watcher=None, nowait=False, background=False, flatpak=False)

container_build_setup(get_autorebuild=None, set_autorebuild=None)

property container_build_target

This property ensures the target for container builds.

copr_build(project, srpm_name, nowait, config_file)

default_branch_merge()

Get the default branch used when Git repository is not found.

delete_tag(tagname)

Delete a git tag from the repository found at optional path

diff(cached=False, files=[])

Execute a git diff

Parameters

• cached (bool) – optionally diff the cached or staged changes. Defaults to not.

• files (list) – optional list of files to diff relative to the module base directory.

property disttag

This property ensures the disttag attribute

property distval

This property ensures the distval attribute

property distvar

This property ensures the distvar attribute

property epoch

This property ensures the epoch attribute

find_untracked_patches()

Find patches that are not tracked by git and sources both

property flatpak_build_target

This property ensures the target for flatpak builds.

get_base_repo(repo)

get_latest_commit(repo, branch)

Discover the latest commit has for a given repository and return it

get_mock_config_dir(root=None, force_local_mock_config=None)

get_watched_module_builds(build_ids)

gitbuildhash(build)

Determine the git hash used to produce a particular N-V-R

giturl()

Return the git url that would be used for building

import_srpm(srpm)

Import the contents of an srpm into a repo.

This function will add/remove content to match the srpm, upload new files to the lookaside, and stage the changes.

Parameters

srpm (str) – file to import contents from.

Returns

a list of files to upload.

Return type

list

install(arch=None, short=False, builddir=None, nocheck=False, buildrootdir=None, define=None, extra_args=None)

Run rpmbuild -bi

optionally for a specific arch, short-circuit it, define an alternative builddir, or define rpmbuild macros

Logs the output and returns nothing

Parameters

• arch (str) – specify a specific arch.

• define (list) – specify a list of rpmbuild macros.

• short (bool) – short-circuit it.

• builddir (str) – alternate builddir.

• nocheck (bool) – do not check.

• buildrootdir (str) – alternate buildrootdir.

• extra_args (list) – additional arguments that are passed to the rpmbuild command.

is_retired()

Checks whether package or module is already retired. The state is indicated by present of files ‘dead.package’ or ‘dead.module’.

koji_upload(file, path, callback=None, name=None)

Upload a file to koji

file is the file you wish to upload

path is the relative path on the server to upload to

callback is the progress callback to use, if any

name is an alternate upload file name to use on the server if specified,

otherwise basename of local file will be used

Returns nothing or raises

property kojisession

This property ensures the kojisession attribute

property kojiweburl

This property ensures the kojiweburl attribute

lint(info=False, rpmlintconf=None)

Run rpmlint over a built srpm

Log the output and returns nothing rpmlintconf is the name of the config file passed to rpmlint if specified by the command line argument.

list_side_tags(base_tag=None, user=None)

list_tag(tagname='*')

List all tags in the repository which match a given tagname.

Parameters

tagname (str) – an optional shell glob to match part of tags (it is matched with fnmatch). Defaults to ‘*’ to list all tags.

load_branch_merge()

Find the remote tracking branch from the branch we’re on.

The goal of this function is to catch if we are on a branch we can make some assumptions about. If there is no merge point then we raise and ask the user to specify.

load_branch_remote()

Find the name of remote from branch we’re on.

load_commit()

Discover the latest commit to the package

load_container_build_target()

This creates a target based on git branch and namespace.

load_flatpak_build_target()

This locates a target appropriate for the runtime that the Flatpak targets.

load_kojisession(anon=False)

Initiate a koji session.

The koji session can be logged in or anonymous

load_localarch()

Get the local arch as defined by rpm

load_mockconfig()

This sets the mockconfig attribute

load_nameverrel()

Set the release and version of a package.

load_nameverrel_dockerfile()

load_nameverrel_mock(mockargs=[], root=None, force_local_mock_config=None)

Set the release and version of a package with mock.

Log the output and returns nothing

Parameters

• mockargs (list) – list of command line arguments which are passed mock.

• root (str) – chroot config name which is passed to mock -r option.

• force_local_mock_config (bool) – enforce download of the Mock configuration from Kojihub (True), or enforce local Mock config (False). If None local configuration is used if present.

New in version 1.64.

load_ns()

Loads the namespace

load_nvr()

This sets the nvr attribute

load_push_url()

Find the pushurl or url of remote of branch we’re on.

load_repo()

Create a repo object from our path

load_repo_name()

Loads repository name

New in version 1.55.

load_rpmautospec()

Set which features and macros are active in the current specfile

load_rpmdefines()

Populate rpmdefines based on current active branch

load_spec()

This sets the spec attribute

load_target()

This creates the target attribute based on branch merge

load_user()

This sets the user attribute

local(localargs, arch=None, hashtype=None, builddir=None, buildrootdir=None, define=None, extra_args=None)

rpmbuild locally for given arch.

Takes localargs (passed to rpmbuild), arch to build for, and hashtype to build with.

Writes output to a log file and logs it to the logger. Log file is written into current working directory and in format .build-{version}-{release}.log.

Parameters

• arch (str) – to optionally build for a specific arch.

• define (list) – optional list of rpmbuild macros.

• hashtype (str) – an alternative algorithm used for payload file digests.

• builddir (str) – an alternative builddir.

• buildrootdir (str) – an alternative buildrootdir.

• extra_args (list) – additional arguments that are passed to the rpmbuild command.

Raises

rpkgError – if underlying rpmbuild fails.

property localarch

This property ensures the localarch attribute

login_koji_session(koji_config, session)

Login Koji session

property lookasidecache

A helper to interact with the lookaside cache

Downstream users of the pyrpkg API may override this property with their own, returning their own implementation of a lookaside cache helper object.

Returns

lookaside cache instance providing all the needed stuff to communicate with a Fedora-style lookaside cache.

Return type

pyrpkg.lookaside.CGILookasideCache

mock_config(target=None, arch=None)

Generate a mock config based on branch data.

Parameters

• target (str) – an alternative build target, otherwise default build target will be used.

• arch (str) – an alternative arch, otherwise local system arch will be used.

Returns

the mock config content got from Koji.

Return type

str

property mock_results_dir

mockbuild(mockargs=[], root=None, hashtype=None, shell=None, force_local_mock_config=None, srpm_mock=False)

Build the package in mock, using mockargs

Log the output and returns nothing

Parameters

• mockargs (list) – list of command line arguments which are passed mock.

• root (str) – chroot config name which is passed to mock -r option.

• hashtype (str) – used to generate SRPM only if there is no SRPM generated before.

• shell (bool) – indicate whether to go into chroot.

• force_local_mock_config (bool) – enforce download of the Mock configuration from Kojihub (True), or enforce local Mock config (False). If None local configuration is used if present.

• srpm_mock (bool) – genereate source rpm

New in version 1.56: Parameter shell.

New in version 1.64: Parameter srpm_mock.

property mockconfig

This property ensures the mockconfig attribute

module_build_cancel(build_id, auth_method, oidc_id_provider=None, oidc_client_id=None, oidc_client_secret=None, oidc_scopes=None)

Cancel an MBS build

Parameters

• build_id (int) – build ID to cancel

• auth_method (str) – authentication method used by the MBS

• oidc_id_provider (str) – the OIDC provider when MBS is using OIDC for authentication

• oidc_client_id (str) – the OIDC client ID when MBS is using OIDC for authentication

• oidc_client_secret (str) – the OIDC client secret when MBS is using OIDC for authentication. Based on the OIDC setup, this could be None.

• oidc_scopes (list) – a list of OIDC scopes when MBS is using OIDC for authentication

module_build_info(build_id)

Show information about an MBS build

Parameters

build_id (int) – build ID to query MBS about

module_get_api_version(api_url)

Queries the /about/ API to determine what the latest API version that MBS supports is and returns the latest API that both rpkg and MBS support. :param api_url: a string of the URL of the MBS API :return: an int of the API version

module_get_build(build_id)

Get an MBS build :param build_id: an integer of the build ID to query MBS about :return: None or a dictionary representing the module build

static module_get_koji_state_dict()

Get a dictionary of Koji build states with the keys being strings and the values being their associated integer.

Returns

a dictionary of Koji build states

Return type

dict

module_get_latest_build(nsvc)

Get the latest MBS build for a particular module. If the module is built with multiple contexts, a random one will be returned.

Parameters

nsvc – a NAME:STREAM:VERSION:CONTEXT to filter the query (may be partial - e.g. only NAME or only NAME:STREAM)

Returns

the latest build

module_get_scm_info(scm_url=None, branch=None, check_repo=True)

Determines the proper SCM URL and branch based on the arguments. If the user doesn’t specify an SCM URL and branch, then the git repo the user is currently in is used instead.

Parameters

• scm_url (str) – a string of the module’s SCM URL

• branch (str) – a string of the module’s branch

• check_repo (bool) – a boolean that determines if check_repo should be run when an scm_url is not provided.

Returns

a tuple containing a string of the SCM URL and a string of the branch

Return type

tuple

module_get_url(build_id, action='GET', verbose=True)

Get the proper MBS API URL for the desired action

Parameters

• build_id (int) – an integer of the module build desired. If this is set to None, then the base URL for all module builds is returned.

• action (str) – a string determining the HTTP action. If this is set to GET, then the URL will contain ?verbose=true. Any other value will not have verbose set.

Returns

a string of the desired MBS API URL.

Return type

str

module_local_build(file_path, stream, local_builds_nsvs=None, verbose=False, debug=False, skip_tests=False, mbs_config=None, mbs_config_section=None, default_streams=None, offline=False, base_module_repositories=None, srpms=None)

A wrapper for mbs-manager build_module_locally.

Parameters

• file_path (str) – a string, path of the module’s modulemd yaml file.

• stream (str) – a string, stream of the module.

• local_builds_nsvs (list) – a list of localbuild ids to import into MBS before running this local build.

• verbose (bool) – a boolean specifying if mbs-manager should be verbose. This is overridden by self.quiet.

• debug (bool) – a boolean specifying if mbs-manager should be debug. This is overridden by self.quiet and verbose.

• skip_tests (bool) – a boolean determining if the check sections should be skipped.

• mbs_config (str) – a string, path to alternative MBS config file to use.

• mbs_config_section (str) – a string, name of alternative config section to use.

• default_streams (list[str]) – a list, contains strings with default name:stream pairs which are passed to mbs-manager using the ‘-s’ command line argument.

• offline (bool) – when True, the module is built offline without accessing any external infrastructure.

• base_module_repositories (list) – a list of full paths to local .repo files defining the repositories for base module when building with offline set to True.

• srpms (list[str]) – a list, contains strings with paths to SRPMs to override components from distgit when building module.

Returns

None

module_overview(limit=10, finished=True, owner=None)

Show the overview of the latest builds in MBS

Parameters

• limit (int) – an integer of the number of most recent module builds to display. This defaults to 10.

• finished (bool) – a boolean that determines if only finished or unfinished module builds should be displayed. This defaults to True.

• owner (str) – list only builds of that user.

module_send_authorized_request(verb, url, body, auth_method, oidc_id_provider=None, oidc_client_id=None, oidc_client_secret=None, oidc_scopes=None, **kwargs)

Sends authorized request to MBS

Parameters

• verb (str) – a string of the HTTP verb of the request (e.g. POST)

• url (str) – a string of the URL to make the request on.

• body (dict) – a dictionary of the data to send in the authorized request.

• auth_method (str) – a string of the authentication method used by the MBS. Valid methods are oidc and kerberos.

• oidc_id_provider (str) – a string of the OIDC provider when MBS is using OIDC for authentication

• oidc_client_id (str) – a string of the OIDC client ID when MBS is using OIDC for authentication

• oidc_client_secret (str) – a string of the OIDC client secret when MBS is using OIDC for authentication. Based on the OIDC setup, this could be None.

• oidc_scopes (list) – a list of OIDC scopes when MBS is using OIDC for authentication

• kwargs – any additional python-requests keyword arguments.

Returns

a python-requests response object

module_submit_build(scm_url, branch, auth_method, buildrequires=None, requires=None, optional=None, oidc_id_provider=None, oidc_client_id=None, oidc_client_secret=None, oidc_scopes=None, scratch=False, modulemd=None, srpms=[])

Submit a module build to the MBS

Parameters

• scm_url – a string of the module’s SCM URL

• branch – a string of the module’s branch

• auth_method (str) – a string of the authentication method used by the MBS.

• buildrequires (list) – a list of buildrequires in the format of ‘name:stream’ to override.

• requires (list) – a list of requires in the format of ‘name:stream’ to override.

• optional (list[str]) – an optional list of tuples (key, value) to be passed in with the MBS build submission.

• oidc_id_provider (str) – a string of the OIDC provider when MBS is using OIDC for authentication.

• oidc_client_id (str) – a string of the OIDC client ID when MBS is using OIDC for authentication

• oidc_client_secret (str) – a string of the OIDC client secret when MBS is using OIDC for authentication. Based on the OIDC setup, this could be None. :kwarg oidc_scopes: a list of OIDC scopes when MBS is using OIDC for authentication.

• scratch (bool) – optionally perform a scratch module build, default is False.

• modulemd (str) – a string, path of the module’s modulemd yaml file to use for a scratch build.

• srpms (list[str]) – a list of koji upload links for SRPMs to use for a scratch build.

Returns

a list of module build IDs that are being built from this request.

Return type

list[int]

module_watch_build(build_ids)

Watches the first MBS build in the list in a loop that updates every 15 seconds. The loop ends when the build state is ‘failed’, ‘done’, or ‘ready’.

Parameters

build_ids (list[int]) – a list of module build IDs

new()

Return changes in a repo since the last tag

property ns

This property provides the namespace of the repository

property ns_repo_name

Return repository name with namespace

New in version 1.55.

property nvr

This property ensures the nvr attribute

property osbs_config_filename

property password

This property ensures the password attribute

patch(suffix, rediff=False)

Generate a patch from the expanded source and add it to index

suffix: Look for files named with this suffix to diff rediff: optionally retain any comments in the patch file and rediff

Will create a patch file named name-version-suffix.patch

property path

pre_push_check(ref)

prep(arch=None, builddir=None, buildrootdir=None, define=None, extra_args=None)

Run rpmbuild -bp

Parameters

• arch (str) – optional to run prep section for a specific arch. By default, local system arch will be used.

• define (list) – an optional list of rpmbuild macros.

• builddir (str) – an alternative builddir.

• buildrootdir (str) – an alternative buildrootdir.

• extra_args (list) – additional arguments that are passed to the rpmbuild command.

pull(rebase=False, norebase=False)

Pull changes from the remote repository

Optionally rebase current branch on top of remote branch

Optionally override .git setting to always rebase

push(force=False, no_verify=False, extra_config=None)

Push changes to the remote repository

property push_url

This property ensures the push_url attribute

property rel

This property ensures the rel attribute

remote(remote_name, repo_name)

Add remote pointing repository from remote dist-git service

Simply a wrapper on ‘git remote …’ interface that uses internal values to get package-specific target URL.

Parameters

• remote_name (str) – chosen name for remote

• repo_name (str) – remote repository name. If remote repository has same name as current repository, repo_name can be None

remove_side_tag(tag)

property repo

This property ensures the repo attribute

property repo_name

Property to get repository name

New in version 1.55.

request_side_tag(base_tag=None, suffix=None)

retire(message)

Delete all tracked files and commit a new dead.package file for rpms or dead.module file for modules.

Use optional message in commit.

Runs the commands and returns nothing

property rpmdefines

This property ensures the rpm defines

property runas

This property ensures the runas attribute

sources(outdir=None, force=False)

Download source files

property sources_filename

property spec

This property ensures the spec attribute

srpm(hashtype=None, define=None, builddir=None, buildrootdir=None, arch=None, extra_args=None)

Create an srpm using hashtype from content

Requires sources already downloaded. The generated SRPM file will be put into package repository directory.

Parameters

• hashtype (str) – an alternative algorithm used for payload file digests.

• define (list) – an optional list of rpmbuild macros.

• builddir (str) – optionally define an alternate builddir.

• buildrootdir (str) – optionally define an alternate buildrootdir.

• arch (str) – optional to run prep section for a specific arch. By default, local system arch will be used.

• extra_args (list) – additional arguments that are passed to the rpmbuild command.

static stats_module_build_components(build_info)

switch_branch(branch, fetch=True)

Switch the working branch

Will create a local branch if one doesn’t already exist, based on <remote>/<branch>

Logs output and returns nothing.

property target

This property ensures the target attribute

property topurl

This property ensures the topurl attribute

unused_patches()

Discover patches checked into source control that are not used

Returns

a list of unused patches, which may be empty.

Return type

list

upload(files, replace=False, offline=False)

Upload source file(s) in the lookaside cache

Both file sources and .gitignore will be updated with uploaded files, and added to index tree eventually.

Parameters

• files (iterable) – an iterable of files to upload.

• replace (bool) – optionally replace the existing tracked sources. Defaults to False.

• offline (bool) – do all the steps except uploading into lookaside cache

Raises

rpkgError – if failed to add a file to file sources.

static use_local_mock_config(root, force_local)

Decide if local mock configuration should be used, based on Mock root name and command-line arguments.

Parameters

• root (str) – mock chroot, the -r <chroot> argument

• force_local (bool) – enforce download of the Mock configuration from Kojihub (when False), or enforce local Mock config (when True). If None, local configuration is used if the config file exists.

Returns

bool, True for local config, False for downloaded config.

property user

This property ensures the user attribute

property uses_autochangelog

property uses_autorelease

property uses_rpmautospec

property ver

This property ensures the ver attribute

verify_files(builddir=None, buildrootdir=None, define=None, extra_args=None)

Run rpmbuild -bl to verify the %files section

Parameters

• define (list) – an optional list of rpmbuild macros.

• builddir (str) – optionally define an alternate builddir.

• buildrootdir (str) – optionally define an alternate buildrootdir.

• extra_args (list) – additional arguments that are passed to the rpmbuild command.

New in version 1.56: Parameter buildrootdir.

Lookaside

class pyrpkg.lookaside.CGILookasideCache(hashtype, download_url, upload_url, client_cert=None, ca_cert=None)

A class to interact with a CGI-based lookaside cache

download(name, filename, hash, outfile, hashtype=None, **kwargs)

Download a source file

Parameters

• name (str) – The name of the module. (usually the name of the SRPM). This can include the namespace as well (depending on what the server side expects).

• filename (str) – The name of the file to download.

• hash (str) – The known good hash of the file.

• outfile (str) – The full path where to save the downloaded file.

• hashtype (str) – Optional. The hash algorithm. (e.g ‘md5’) This defaults to the hashtype passed to the constructor.

• kwargs – Additional keyword arguments. They will be used when constructing the full URL to the file to download.

file_is_valid(filename, hash, hashtype=None)

Ensure the file is correct

Parameters

• filename (str) – The full path to the file. It is assumed to exist.

• hash (str) – The known good hash of the file.

• hashtype (str) – Optional. The hash algorithm to use. (e.g ‘md5’) This defaults to the hashtype passed to the constructor.

Returns

True if the file is valid, False otherwise.

Return type

bool

get_download_url(name, filename, hash, hashtype=None, **kwargs)

hash_file(filename, hashtype=None)

Compute the hash of a file

Parameters

• filename (str) – The full path to the file. It is assumed to exist.

• hashtype (str) – Optional. The hash algorithm to use. (e.g ‘md5’) This defaults to the hashtype passed to the constructor.

Returns

The hash digest.

print_progress(to_download, downloaded, to_upload, uploaded)

raise_upload_error(http_status)

remote_file_exists(name, filename, hash)

Verify whether a file exists on the lookaside cache

Parameters

• name (str) – The name of the module. (usually the name of the SRPM). This can include the namespace as well (depending on what the server side expects).

• filename (str) – The name of the file to check for.

• hash (str) – The known good hash of the file.

upload(name, filepath, hash, offline=False)

Upload a source file

Parameters

• name (str) – The name of the module. (usually the name of the SRPM) This can include the namespace as well (depending on what the server side expects).

• filepath (str) – The full path to the file to upload.

• hash (str) – The known good hash of the file.

• offline (bool) – Method prints a message about disabled upload and does return.

Sources

class pyrpkg.sources.SourcesFile(sourcesfile, entry_type, replace=False)

add_entry(hashtype, file, hash)

parse_line(line)

write()

class pyrpkg.sources.SourceFileEntry(hashtype, file, hash)

class pyrpkg.sources.BSDSourceFileEntry(hashtype, file, hash)

gitignore

class pyrpkg.gitignore.GitIgnore(path)

A class to manage a .gitignore file

add(line)

Add a line

Parameters

line (str) – The line to add to the file. It will not be added if it already matches an existing line.

match(line)

Check whether the line matches an existing one

This uses fnmatch to match against wildcards.

Parameters

line (str) – The new line to match against existing ones.

Returns

True if the new line matches, False otherwise.

Return type

bool

write()

Write the file to the disk

This will only actually write if necessary, that is if lines have been added since the last time the file was written.

Utilities

class pyrpkg.utils.cached_property(fget=None, fset=None, fdel=None, doc=None)

A property caching its return value

This is pretty much the same as a normal Python property, except that the decorated function is called only once. Its return value is then saved, subsequent calls will return it without executing the function any more.

Example:

>>> class Foo(object):
...     @cached_property
...     def bar(self):
...         print("Executing Foo.bar...")
...         return 42
...
>>> f = Foo()
>>> f.bar
Executing Foo.bar...
42
>>> f.bar
42

pyrpkg.utils.warn_deprecated(clsname, oldname, newname)

Emit a deprecation warning

Parameters

• clsname (str) – The name of the class which has its attribute deprecated.

• oldname (str) – The name of the deprecated attribute.

• newname (str) – The name of the new attribute, which should be used instead.

pyrpkg.utils._log_value(log_func, value, level, indent, suffix='')

pyrpkg.utils.log_result(log_func, result, level=0, indent=2)