Python Gerrit API Client

Warnings

• breaking Python 2.x support has been dropped. Versions of python-gerrit-api 3.x and above require Python 3.8 or newer.
  Fix: Ensure your project is running on Python 3.8+ and update your dependencies. Older versions of the library (2.x) might support Python 2.7, but are not actively maintained.
• gotcha Gerrit REST API authentication requires an HTTP password, which is distinct from an SSH password. Authenticated calls also typically require prefixing the endpoint URL with '/a/' (e.g., /a/projects/). The library handles the '/a/' prefix automatically when `username` and `password` are provided to `GerritClient`.
  Fix: Ensure you are using the correct HTTP password for your Gerrit user, which can often be generated or found in your Gerrit user settings. The library typically adds the '/a/' prefix for authenticated requests automatically.
• gotcha The API structure and available methods within `GerritClient` may have evolved between major versions (e.g., from 2.x to 3.x). While not explicitly documented as breaking changes for the client library, internal Gerrit server API changes (like those in Gerrit 3.0.x) can necessitate updates to the client library and its usage patterns.
  Fix: Refer to the specific release notes or the latest documentation on GitHub/ReadTheDocs when upgrading major versions. Test your code thoroughly after major version upgrades to catch any API changes.

Install

• pip install python-gerrit-api Install latest version

Imports

• GerritClient
  wrong:

  from gerrit import Gerrit

  correct:

  from gerrit import GerritClient

  While older examples or the GitHub README might show 'from gerrit import Gerrit', 'GerritClient' is the consistently used class in current documentation and examples for initializing the client.

Quickstart

This quickstart demonstrates how to initialize the `GerritClient` and perform a basic operation, such as listing projects. It uses environment variables for authentication credentials, which is recommended for security. Ensure your Gerrit instance uses HTTP Basic Authentication and you have an HTTP password configured (not an SSH password).

import os
from gerrit import GerritClient

GERRIT_HOST = os.environ.get('GERRIT_HOST', 'http://review.example.com')
GERRIT_USERNAME = os.environ.get('GERRIT_USERNAME', 'your_username')
GERRIT_PASSWORD = os.environ.get('GERRIT_PASSWORD', 'your_http_password')

try:
    # Initialize the Gerrit client with HTTP Basic Authentication
    client = GerritClient(
        base_url=GERRIT_HOST,
        username=GERRIT_USERNAME,
        password=GERRIT_PASSWORD
    )

    # Example: List projects
    projects = client.projects.list(limit=5)
    print(f"Successfully connected to Gerrit. Found {len(projects)} projects:")
    for project in projects:
        print(f"- {project['name']}")

    # Example: Get a specific change (replace with a real change ID/number)
    # Note: Gerrit REST API often expects the 'id' of a change, not just the change number.
    # You might need to fetch a list of changes first to get an ID.
    # change = client.changes.get('12345') # Example change number
    # print(f"Change {change['id']}: {change['subject']}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure GERRIT_HOST, GERRIT_USERNAME, and GERRIT_PASSWORD are set correctly.")