ghcache

A GitHub API client with thottling logic and file-based caching.

ghcache provides access to the GitHub API while caching the results to the local filesystem. It is aware of API rate limits and has throttling logic to avoid hitting them.

The caching in the filesystem is also helpful for debugging. Only use on endpoints where data wouldn't change (or you might get stale data). Otherwise, disable reading from the cache with cache_r=False.

At the moment, this is better fit for long running scripts that make many requests to GitHub and preventing rate limits is more important than minimizing running time. It might be too slow for anything short of that due to the throttling, which is admittedly naively aggressive.

Features

• File-based Caching: Caches GitHub API responses in a local directory.
• Rate Limit Aware: Includes delays between requests to avoid hitting GitHub's rate limits.
• Automatic Pagination: The iterate method handles paginated API responses automatically.
• Simple Interface: Provides get and iterate methods for interaction with the GitHub API.

Installation

You can install ghcache from PyPI:

pip install ghcache

Usage

First, make sure you have a GitHub personal access token. You can either pass it to the GithubCache constructor or set it as the GITHUB_TOKEN environment variable.

from ghcache import GithubCache

# It's recommended to set the GITHUB_TOKEN environment variable
gh = GithubCache()

# Get a user's information
user = gh.get("/users/santi-h")
print(user["name"])

# Iterate through a user's repositories
for repo, total, page, last_page in gh.iterate("/users/santi-h/repos"):
  print(f"Repo: {repo['name']}, Page: {page}/{last_page}")

Configuration

The GithubCache class can be configured with the following parameters:

• github_token (str): Your GitHub personal access token. If not provided, it will be read from the GITHUB_TOKEN environment variable.
• cache_directory (str): The directory where cache files will be stored. Defaults to a cache directory in the current working directory.
• cache_r (bool): Whether to read from the cache. Defaults to True.
• cache_w (bool): Whether to write to the cache. Defaults to True.

License

This project is licensed under the MIT License.