Koji Python Client

1.36.0 · active · verified Fri Apr 17

Koji is a powerful, distributed system for building and tracking RPM packages, primarily used within the Fedora and Red Hat ecosystems. The `koji` Python package provides the official client library, allowing programmatic interaction with a Koji Hub, including querying build information, submitting tasks, and managing users. It is actively maintained and currently at version 1.36.0, with releases typically tied to major Koji system updates.

Common errors

```
koji.AuthError: authentication failed
```
cause The Koji client failed to authenticate with the Koji Hub, usually due to missing or incorrect certificates, an invalid Koji configuration file, or incorrect permissions.

fix Verify the Koji configuration file (e.g., `~/.koji/config` or `/etc/koji.conf`) specifies the correct `server`, `cert`, `serverca`, and `topdir` paths. Ensure certificate files exist and are readable by the user running the script.
```
xmlrpc.client.Fault: <Server message>
```
cause This is a server-side error returned by the Koji Hub, indicating an issue with the parameters of your API call (e.g., a non-existent build ID, an invalid tag name) or a server-side problem.

fix Examine the specific 'Server message' for clues. Check the parameters passed to the Koji API function (e.g., `getBuild`, `listBuilds`) to ensure they are valid and refer to existing entities on the Koji Hub.
```
socket.gaierror: [Errno -2] Name or service not known
```
cause The Koji Hub URL specified in `ClientSession` or your Koji configuration file is incorrect or unreachable, or there's a DNS resolution issue.

fix Double-check the `KOJI_HUB_URL` (or `server` setting in your config). Ensure the hostname is correct and that your machine can resolve and connect to it (e.g., using `ping` or `curl`).

Warnings

gotcha Authenticated Koji client operations (e.g., submitting tasks, managing tags) typically require specific configuration files (`~/.koji/config` or `/etc/koji.conf`) with server URL, certificates, and SSL verification settings. Anonymous read-only access is often possible without this.
Fix: Ensure your Koji configuration file is correctly set up for the target Koji Hub, including appropriate certificate paths and permissions, if you encounter `koji.AuthError`.
gotcha While Koji supports Python 2.7, it is primarily developed and deployed with Python 3. Mixing Python 2 scripts with modern Python 3 environments or relying on Python 2 features can lead to encoding issues or compatibility problems. New development should target Python 3.
Fix: Develop new Koji client scripts using Python 3. Ensure your Python environment is consistent.
gotcha Koji's client methods often return dictionary structures. The exact keys and their types can vary slightly between Koji server versions or for different types of objects. Always validate dictionary keys before accessing them.
Fix: Use `.get()` with a default value (e.g., `obj.get('key', None)`) or check for key existence (e.g., `if 'key' in obj:`) when accessing dictionary values returned by Koji API calls to prevent `KeyError`.

Install

pip install koji Install Koji client library

Imports

koji
```
import koji
```
The entire koji module is typically imported to access its client session and utility functions.
ClientSession
```
import koji
session = koji.ClientSession(...)
```
ClientSession is the primary class for interacting with a Koji Hub.

Quickstart

This quickstart demonstrates connecting to a public Koji Hub and querying its version. For anonymous access, no special configuration is needed. For tasks requiring authentication (e.g., submitting builds, modifying tags), Koji typically uses configuration files like `~/.koji/config` or environment variables for certificates.

import koji
import os

# Koji Hub URL. For authenticated access, Koji typically reads ~/.koji/config
# or uses certificate paths.
# We'll use a public read-only hub for this quickstart.
KOJI_HUB_URL = os.environ.get('KOJI_HUB_URL', 'https://koji.fedoraproject.org/kojihub')

try:
    session = koji.ClientSession(KOJI_HUB_URL)
    print(f"Connected to Koji Hub: {KOJI_HUB_URL}")

    # Get and print the Koji server version to confirm connectivity
    server_info = session.getKojiVersion()
    print(f"Koji server version: {server_info['version']} ({server_info['release']})")

    # Example: Get info for a specific build (if you know an NVR)
    # For a real scenario, you'd look up a valid NVR first.
    # print("\nTrying to find a specific build (e.g., 'kernel-5.18.11-200.fc36')")
    # try:
    #     build_info = session.getBuild('kernel-5.18.11-200.fc36')
    #     print(f"Found build: {build_info['nvr']} (ID: {build_info['build_id']})")
    # except Exception as e:
    #     print(f"Could not find build or an error occurred: {e}")

except koji.AuthError as e:
    print(f"Authentication Error: {e}")
    print("\nIf you intend to use authenticated access, ensure your Koji configuration (e.g., ~/.koji/config) is correct.")
except Exception as e:
    print(f"An error occurred during Koji interaction: {e}")

view raw JSON →