Metadata-Version: 2.4
Name: aioukcarbon
Version: 0.1.0
Summary: Async Python client for the UK Carbon Intensity API
Author-email: Darryl Cauldwell <darryl.cauldwell@outlook.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/darrylcauldwell/aioukcarbon
Project-URL: Repository, https://github.com/darrylcauldwell/aioukcarbon
Project-URL: Issues, https://github.com/darrylcauldwell/aioukcarbon/issues
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: aioresponses>=0.7; extra == "dev"
Dynamic: license-file

# aioukcarbon

Async Python client for the [UK Carbon Intensity API](https://carbon-intensity.github.io/api-definitions/).

Data provided by National Energy System Operator (NESO) via the Carbon Intensity API.

## Installation

```bash
pip install aioukcarbon
```

## Usage

```python
import asyncio
from aioukcarbon import CarbonIntensityClient

async def main():
    async with CarbonIntensityClient() as client:
        # Regional intensity by postcode
        regional = await client.get_regional_intensity("DE45")
        print(f"Region: {regional.shortname}")
        print(f"Forecast: {regional.periods[0].intensity.forecast} gCO2eq/kWh")
        print(f"Index: {regional.periods[0].intensity.index}")

        # National intensity
        national = await client.get_national_intensity()
        print(f"National: {national.intensity.forecast} gCO2eq/kWh")

        # Generation mix
        mix = await client.get_generation_mix()
        for fuel in mix.generationmix:
            print(f"  {fuel.fuel}: {fuel.perc}%")

        # 24h regional forecast
        forecast = await client.get_regional_forecast("DE45")
        for period in forecast.periods:
            print(f"  {period.from_time}: {period.intensity.forecast} gCO2eq/kWh")

asyncio.run(main())
```

## API Reference

### `CarbonIntensityClient`

- `get_regional_intensity(postcode)` - Current regional carbon intensity
- `get_regional_forecast(postcode, hours=24)` - Regional forecast (24h or 48h)
- `get_national_intensity()` - Current national carbon intensity
- `get_generation_mix()` - Current national generation mix

### Exceptions

- `CarbonIntensityError` - Base exception
- `CarbonIntensityConnectionError` - Connection failures
- `CarbonIntensityTimeoutError` - Request timeouts
- `CarbonIntensityNoDataError` - No data available for postcode

## License

MIT
