Metadata-Version: 2.4
Name: githosted
Version: 0.1.0
Summary: Python SDK for githosted — git-backed file storage for AI agents
Project-URL: Homepage, https://githosted.dev
Project-URL: Documentation, https://docs.githosted.dev/sdks/python/
Project-URL: Repository, https://github.com/githosted-dev/python-sdk
Project-URL: Issues, https://github.com/githosted-dev/python-sdk/issues
Author: githosted
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# githosted

Python SDK for [githosted](https://githosted.dev) — read, write, and diff files in versioned Git repos without shelling out.

`githosted` exposes a small, typed surface for the operations you actually do against a repo: read a file, commit a change, list history, diff two refs. Real Git underneath; you're not talking to a custom blob store.

## Install

```sh
pip install githosted
```

Requires Python 3.10+.

## Quick start

```python
from githosted import Client

repo = Client(token="gw_…").repo("my-agent")

# Write a file (creates a commit).
repo.write_file("output.json", b'{"status": "ok"}', message="Run #42")

# Read it back.
result = repo.read_file("output.json")
print(result.content.decode())

# Walk recent history.
for commit in repo.log(limit=5):
    print(commit.hash[:7], commit.subject)

# Diff between two refs.
delta = repo.diff("HEAD~1", "HEAD")
print(delta.patch)
```

## Authentication

Tokens are scoped to a workspace. Mint one at [app.githosted.dev → Tokens](https://app.githosted.dev), then pass it to `Client(token=…)`.

| Token prefix | Scope |
|---|---|
| `gw_…` | Read + write |
| `gr_…` | Read-only |

For local development, set `GITHOSTED_TOKEN` and use `Client.from_env()`.

## Errors

The SDK raises typed exceptions you can match on:

```python
from githosted import (
    Client,
    NotFoundError,
    RepoBusyError,
    StaleHeadError,
)

try:
    repo.read_file("missing.txt")
except NotFoundError:
    ...
```

`RepoBusyError` and `StaleHeadError` are retryable — `with_retry()` is included for the common backoff loop.

## Documentation

- [Quickstart](https://docs.githosted.dev/welcome/quickstart/)
- [Python SDK reference](https://docs.githosted.dev/sdks/python/)
- [HTTP API](https://docs.githosted.dev/reference/http-api/)

## License

MIT.
