GhApi

Warnings

• gotcha For authenticated operations, a GitHub Personal Access Token (PAT) is required. GhApi will automatically use the `GITHUB_TOKEN` environment variable if available, otherwise, you must pass it explicitly to the `GhApi` constructor. An `authenticate=False` flag can be used to override this behavior and create an unauthenticated client even if the token is present.
  Fix: Set `GITHUB_TOKEN` environment variable or pass `token='YOUR_TOKEN'` to `GhApi()` during initialization.
• breaking When updating files via the API, GitHub now explicitly requires `branch`, `author`, and `committer` parameters. Older code that omits these for file updates will fail.
  Fix: Ensure `branch`, `author`, and `committer` are provided in file update calls (e.g., `api.repos.update_file()`).
• gotcha When working with media types that are not JSON (e.g., `application/vnd.github.v3.sha`), `GhApi` might return a raw string instead of a parsed Python object.
  Fix: Be aware of the expected return type for non-JSON media types and handle the string output accordingly.
• deprecated The `GitPython` library was removed as a dependency in `v1.0.8`. If your project implicitly relied on `GhApi` installing `GitPython` as a transitive dependency, you will now need to add `GitPython` as a direct dependency to your project.
  Fix: Explicitly install `GitPython` (`pip install GitPython`) if your project requires it.
• gotcha Previous versions (before 1.0.13) might have incorrectly decoded binary response types, potentially leading to errors or corrupted data when fetching certain content.
  Fix: Upgrade to GhApi 1.0.13 or newer to ensure correct decoding of non-binary types and proper handling of binary content.

Install

• pip install ghapi PyPI
• conda install -c fastai ghapi Conda

Imports

• GhApi

  from ghapi.all import GhApi

  The primary `GhApi` class and all its sub-APIs are conveniently exposed via `ghapi.all` for a complete interface. Direct imports from submodules (e.g., `ghapi.repos`) are also possible for specific functionality.

Quickstart

Initializes the GhApi client, demonstrating how to fetch public user information and, if authenticated with a `GITHUB_TOKEN` environment variable, list repositories for an organization. `GhApi` dynamically generates methods based on the GitHub API, providing a Pythonic interface.

import os
from ghapi.all import GhApi

# Initialize GhApi. It will automatically use GITHUB_TOKEN from environment if available.
# For unauthenticated calls, you can initialize without a token if no authenticated endpoints are used.
# Alternatively, pass a token explicitly: api = GhApi(token="YOUR_GITHUB_TOKEN")
# Set authenticate=False to explicitly create an unauthenticated client even if GITHUB_TOKEN is set.
api = GhApi(token=os.environ.get('GITHUB_TOKEN', ''))

# Example: Get user information for a public user (can be unauthenticated)
try:
    user_info = api.users.get_by_username(username='fastai')
    print(f"User: {user_info.login}, Public Repos: {user_info.public_repos}")
except Exception as e:
    print(f"Could not retrieve user info: {e}. Ensure username is correct and token (if needed) is valid.")

# Example: Get a list of repositories for an organization (requires authentication for private repos)
# Note: 'owner' and 'repo' can also be passed to GhApi constructor for auto-insertion.
if os.environ.get('GITHUB_TOKEN'):
    try:
        # For this example, let's assume we want repos for 'fastai'
        org_repos = api.repos.list_for_org(org='fastai')
        print(f"\nFirst 3 repos in 'fastai' organization:")
        for i, repo in enumerate(org_repos[:3]):
            print(f"- {repo.name}")
    except Exception as e:
        print(f"\nCould not list organization repos: {e}. Check token scopes and organization name.")
else:
    print("\nSkipping organization repo listing as GITHUB_TOKEN is not set.")