Metadata-Version: 2.4
Name: wattlayer
Version: 1.0.0
Summary: Official Python SDK for WattLayer — Korea's power-market & distributed-energy data API (The Stripe for Energy Data).
Project-URL: Homepage, https://wattlayer.io
Project-URL: Documentation, https://docs.wattlayer.io
Project-URL: Source, https://github.com/wattlayer/wattlayer-python
Author-email: WattLayer <support@wattlayer.io>
License: MIT
License-File: LICENSE
Keywords: api,data-center,distributed-energy,electricity,energy,korea,kpx,power,renewable,smp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# WattLayer Python SDK

Korea's power-market & distributed-energy data, one import away.

`wattlayer` is the official Python client for the [WattLayer API](https://wattlayer.io) —
real-time SMP (system marginal price), power supply/demand, weather, generation
facilities, distributed-energy special zones, and grid events, wrapped from Korea's
public data sources into one developer-friendly REST API.

## Install

```bash
pip install wattlayer
```

## Quickstart

```python
from wattlayer import WattLayerClient

client = WattLayerClient(api_key="wl_live_...")

# Latest SMP
smp = client.smp.latest(country="kr", region="mainland")
print(f"{smp['price']} KRW/kWh @ {smp['timestamp']}")

# Current supply / demand / reserve margin
supply = client.supply.current(country="kr")
print(f"demand {supply['current_demand_mw']} MW, reserve {supply['reserve_rate']}%")

# Distributed-energy special zone (WattLayer-exclusive metadata)
jeju = client.zones.get("kr-jeju")
print(jeju["direct_ppa_allowed"], jeju["allowed_sources"])
```

Get a free key (10,000 calls/month, no credit card) at
<https://console.wattlayer.io/register>.

## Configuration

The key and base URL are read from the environment when not passed explicitly:

```bash
export WATTLAYER_API_KEY=wl_live_...
export WATTLAYER_API_URL=https://api.wattlayer.io   # optional
```

```python
client = WattLayerClient(timeout=10.0, max_retries=3)
```

Requests retry automatically (exponential backoff: 1s, 2s, 4s) on `429` and `5xx`.
Use the client as a context manager to close its connection pool:

```python
with WattLayerClient() as client:
    print(client.meta.health())
```

## Resources

| Namespace | Methods |
|---|---|
| `client.smp` | `latest`, `history`, `stats` |
| `client.supply` | `current`, `today`, `history` |
| `client.weather` | `forecast`, `current` — pass `region="seoul"` or `nx=`/`ny=` |
| `client.facilities` | `list`, `get`, `stats` |
| `client.zones` | `list`, `get`, `facilities` |
| `client.events` | `list` |
| `client.auth` | `register`, `me`, `rotate` |
| `client.meta` | `health`, `status`, `licenses` |

Every method returns the parsed `data` payload. Attribution/license metadata is
returned by the API in each response's `meta` block — see `client.meta.licenses()`.

## Errors

```python
from wattlayer import WattLayerRateLimitError, WattLayerAuthError

try:
    client.smp.latest()
except WattLayerRateLimitError as e:
    print("quota hit, resets at", e.reset)
except WattLayerAuthError:
    print("check your API key")
```

All exceptions derive from `WattLayerError`
(`WattLayerConnectionError`, `WattLayerAPIError` → `WattLayerAuthError`,
`WattLayerNotFoundError`, `WattLayerRateLimitError`).

## License

MIT · Data sourced under KOGL Type 1 (attribution) from KPX & KMA via data.go.kr.
