Metadata-Version: 2.5
Name: uk-energy
Version: 0.1.1
Summary: Typed Python clients for the UK's public electricity data APIs: Elexon Insights, NESO Data Portal, Carbon Intensity, DNO open data, Octopus.
Project-URL: Homepage, https://github.com/Styrle/Wind-farm-sdk
Project-URL: Repository, https://github.com/Styrle/Wind-farm-sdk
Project-URL: Issues, https://github.com/Styrle/Wind-farm-sdk/issues
Author: Josh Serpis
License-Expression: MIT
Keywords: bmrs,carbon-intensity,elexon,energy,grid,neso,uk
Classifier: Development Status :: 2 - Pre-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: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
Description-Content-Type: text/markdown

# uk-energy (Python)

Typed Python clients for the UK's public electricity data APIs. Mirrors the TypeScript packages in the same repo.

```bash
pip install uk-energy
```

Contains BMRS data © Elexon Limited copyright and database right 2026.
Contains NESO Data Portal data, used under the NESO Open Data Licence.
Carbon Intensity data © National Energy System Operator, CC BY 4.0.

See the [repo README](../README.md) for the full attribution and licence notes.

## Packages

| Module | Covers | Status |
| --- | --- | --- |
| `uk_energy.core` | `HttpClient` / `AsyncHttpClient` on httpx: retries with jittered backoff, per-host rate limiting, pagination, pluggable cache, `FixtureTransport` for tests | built, unpublished |
| `uk_energy.carbon_intensity` | Carbon Intensity API: `CarbonIntensityClient` / `AsyncCarbonIntensityClient` — national and regional intensity, forecasts, generation mix | built, unpublished |
| `uk_energy.elexon` | Elexon Insights | planned |
| `uk_energy.neso` | NESO Data Portal | planned |

```python
from uk_energy.core import HttpClient, MemoryCache, RateLimit

elexon = HttpClient(
    "https://data.elexon.co.uk/bmrs/api/v1",
    rate_limit=RateLimit(5, burst=10),
    cache=MemoryCache(),
    cache_ttl_s=60,
)
fuel = elexon.get("datasets/FUELINST", {"publishDateTimeFrom": "2026-10-20T00:00Z"})
```

```python
from uk_energy.carbon_intensity import CarbonIntensityClient

ci = CarbonIntensityClient()
ci.intensity_current()["intensity"]  # {"forecast": 125, "actual": 134, "index": "moderate"}
ci.regional_for_postcode("M1")["data"][0]  # region 3, North West England
ci.intensity_forward48h("2026-10-15T00:00Z")  # 97 half-hour periods
```

Note: `intensity_for_date()` uses a local GB day (BST in summer), and range endpoints include
the period containing `from_`; see the TypeScript package README for the full list.

## Development

```bash
cd python
uv sync
uv run pytest            # fixtures only, no network
UK_ENERGY_LIVE=1 uv run pytest -m live
uv run ruff check . && uv run mypy
```
