{"id":9879,"library":"koji","title":"Koji Python Client","description":"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.","status":"active","version":"1.36.0","language":"en","source_language":"en","source_url":"https://pagure.io/koji","tags":["build system","RPM","Fedora","Red Hat","automation","client"],"install":[{"cmd":"pip install koji","lang":"bash","label":"Install Koji client library"}],"dependencies":[],"imports":[{"note":"The entire koji module is typically imported to access its client session and utility functions.","symbol":"koji","correct":"import koji"},{"note":"ClientSession is the primary class for interacting with a Koji Hub.","symbol":"ClientSession","correct":"import koji\nsession = koji.ClientSession(...)"}],"quickstart":{"code":"import koji\nimport os\n\n# Koji Hub URL. For authenticated access, Koji typically reads ~/.koji/config\n# or uses certificate paths.\n# We'll use a public read-only hub for this quickstart.\nKOJI_HUB_URL = os.environ.get('KOJI_HUB_URL', 'https://koji.fedoraproject.org/kojihub')\n\ntry:\n    session = koji.ClientSession(KOJI_HUB_URL)\n    print(f\"Connected to Koji Hub: {KOJI_HUB_URL}\")\n\n    # Get and print the Koji server version to confirm connectivity\n    server_info = session.getKojiVersion()\n    print(f\"Koji server version: {server_info['version']} ({server_info['release']})\")\n\n    # Example: Get info for a specific build (if you know an NVR)\n    # For a real scenario, you'd look up a valid NVR first.\n    # print(\"\\nTrying to find a specific build (e.g., 'kernel-5.18.11-200.fc36')\")\n    # try:\n    #     build_info = session.getBuild('kernel-5.18.11-200.fc36')\n    #     print(f\"Found build: {build_info['nvr']} (ID: {build_info['build_id']})\")\n    # except Exception as e:\n    #     print(f\"Could not find build or an error occurred: {e}\")\n\nexcept koji.AuthError as e:\n    print(f\"Authentication Error: {e}\")\n    print(\"\\nIf you intend to use authenticated access, ensure your Koji configuration (e.g., ~/.koji/config) is correct.\")\nexcept Exception as e:\n    print(f\"An error occurred during Koji interaction: {e}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Develop new Koji client scripts using Python 3. Ensure your Python environment is consistent.","message":"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.","severity":"gotcha","affected_versions":"<=1.x.x (gradual transition from Py2 to Py3)"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"koji.AuthError: authentication failed"},{"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.","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.","error":"xmlrpc.client.Fault: <Server message>"},{"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`).","cause":"The Koji Hub URL specified in `ClientSession` or your Koji configuration file is incorrect or unreachable, or there's a DNS resolution issue.","error":"socket.gaierror: [Errno -2] Name or service not known"}]}