Metadata-Version: 2.4
Name: fetchurl-sdk
Version: 0.2.2
Summary: Protocol-level client SDK for fetchurl content-addressable cache servers
Project-URL: Homepage, https://pypi.org/project/fetchurl-sdk/
Project-URL: Repository, https://github.com/fetchurl/sdk-python
Project-URL: Bug Tracker, https://github.com/fetchurl/sdk-python/issues
Author: lucasew
License: MIT
License-File: LICENSE
Keywords: cache,content-addressable,fetchurl,hash,sha256
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Provides-Extra: test
Requires-Dist: httpx>=0.27.0; extra == 'test'
Requires-Dist: testcontainers>=3.7.0; extra == 'test'
Description-Content-Type: text/markdown

# fetchurl Python SDK

Protocol-level client for [fetchurl](https://github.com/fetchurl/spec) content-addressable cache servers.

Zero runtime dependencies — uses only the Python standard library. Works with any HTTP library via `Fetcher` / `AsyncFetcher` protocols.

## Install

```bash
pip install fetchurl-sdk
# or
uv add fetchurl-sdk
```

## Protocol

Normative behavior: **[fetchurl/spec](https://github.com/fetchurl/spec)** (`SPEC.md`).

Reference server: **[fetchurl/fetchurl](https://github.com/fetchurl/fetchurl)**.

## Usage

```python
from fetchurl import fetch, UrllibFetcher, parse_fetchurl_server
import os

servers = parse_fetchurl_server(os.environ.get("FETCHURL_SERVER", ""))
# Or drive FetchSession yourself with your HTTP client — see package docstring.
```

Clients **must** treat the server as untrusted and verify the hash (this SDK does that for you).

## Environment

| Variable | Meaning |
|----------|---------|
| `FETCHURL_SERVER` | Server base URL(s) per the [spec](https://github.com/fetchurl/spec/blob/main/SPEC.md). Empty/absent disables server use. |

## Development

```bash
uv sync --dev
uv run python -m unittest test_fetchurl.py
# Integration (Docker + image):
# FETCHURL_TEST_IMAGE=fetchurl:local uv run --extra test python -m unittest test_fetchurl_integration.py
```

## Related

| Repo | Role |
|------|------|
| [fetchurl/spec](https://github.com/fetchurl/spec) | Protocol |
| [fetchurl/fetchurl](https://github.com/fetchurl/fetchurl) | Go server |
| [fetchurl/sdk-js](https://github.com/fetchurl/sdk-js) | JavaScript SDK |
| [fetchurl/sdk-rust](https://github.com/fetchurl/sdk-rust) | Rust SDK |
