Metadata-Version: 2.4
Name: ghcache
Version: 0.0.4
Summary: A GitHub API client with thottling logic and file-based caching
Project-URL: Repository, https://github.com/santi-h/ghcache
Project-URL: Issues, https://github.com/santi-h/ghcache/issues
Author: Santi H
License-Expression: MIT
Keywords: api,cache,github,throttling
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.14
Requires-Dist: requests
Description-Content-Type: text/markdown

# 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:

```bash
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.

```python
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.
