# Demeter Python SDK (`demeter-client`)

A small, **dependency-free** Python client for the Demeter REST API — built for
data-science notebooks and backend integrations (TODOS §29.21.9.4). It mirrors
the TypeScript [`@demeter/api-client`](../../libs/demeter/api-client):
Bearer-JWT and machine API-key auth, typed errors, and resource helpers. The
HTTP transport is injectable (so tests run offline); the default uses the
standard library.

## Install

```bash
pip install -e clients/demeter-python      # editable, no third-party deps
```

## Usage

```python
from demeter_client import DemeterClient

# User auth
client = DemeterClient("http://localhost:3030")
client.login("me@example.com", "secret")
gardens = client.list_gardens(limit=10)
garden = client.create_garden("Back yard", isPublic=False)

# Machine auth (API key) — e.g. an ingestion job
ingest = DemeterClient("http://localhost:3030", api_key="dk_...")
ingest.add_sensor_readings("<sensor-id>", [{"value": 27.4, "unit": "%"}])
```

Non-2xx responses raise `DemeterAPIError` (with `.status` and `.body`).

## Test

```bash
cd clients/demeter-python
PYTHONPATH=. python3 -m pytest        # offline, via an injected fake transport
```

See the [API reference](../../apps/demeter/docs/api/README.md) for endpoints and
the
[building-on-the-API guide](../../apps/demeter/docs/development/building-on-the-api.md).
