Metadata-Version: 2.4
Name: bio-pype-carbon-intensity
Version: 0.1.0
Summary: Grid carbon intensity (gCO2eq/kWh), current + forecast, from free public APIs: ENTSO-E (EU, flow-traced), carbonintensity.org.uk (GB), OpenElectricity + AEMO pre-dispatch (AU)
Author: Francesco Favero
License: MIT
Project-URL: Repository, https://codeberg.org/bio-pype/bio-pype-carbon-intensity
Keywords: carbon-intensity,co2,electricity,entso-e,green-computing,bio-pype
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: backend
Requires-Dist: entsoe-py>=0.6; extra == "backend"
Requires-Dist: pandas>=2.0; extra == "backend"
Dynamic: license-file

# bio-pype-carbon-intensity

Grid carbon intensity (gCO2eq/kWh); current values and forecasts  from
free public APIs. Built for [compute.bio](https://compute.bio) /
[bio-pype](https://codeberg.org/bio-pype) but usable standalone; the Python
import name is `carbon_intensity`. Not affiliated with carbonintensity.org.uk
or any of the upstream data providers. This package just organises their
great public data. MIT licensed.

| Zones | Source | Forecast | Notes |
|---|---|---|---|
| EU bidding zones (`FR`, `DE_LU`, …) | ENTSO-E Transparency (key required) | ✓ | consumption-based via iterative flow tracing |
| `GB` + 17 DNO regions (`GB-LONDON`, …) | carbonintensity.org.uk (no key) | ✓ 48h | precomputed by NG ESO; also pinned into the EU solve |
| `AU-NSW1` … `AU-VIC1`, `AU-WEM` | OpenElectricity (free key) + AEMO NEMWEB (no key) | ✓ ~40h (NEM), climatology (WEM) | production-based |
| anything else | Electricity Maps (personal key) / compute.bio backend | ✓ / – | escape hatch |

The core package has **no dependencies** (stdlib only). The multi-zone
backend bulk path needs the `backend` extra:

```
pip install bio-pype-carbon-intensity            # worker / single-zone use
pip install bio-pype-carbon-intensity[backend]   # bulk window fetch + EU flow tracing
```

## Usage

```python
from carbon_intensity import get_current, get_forecast, run_window

rec = get_current("GB-LONDON")           # one or two HTTP calls
print(rec.intensity_g_per_kwh, rec.kind)

for slot in get_forecast("AU-NSW1"):     # AEMO pre-dispatch, ~40h ahead
    print(slot.start, slot.intensity_g_per_kwh, slot.extra["method"])

# backend bulk (needs [backend] extra for EU zones):
import datetime as dt
now = dt.datetime.now(dt.timezone.utc)
results = run_window(["FR", "BE", "GB", "AU-NSW1"], now - dt.timedelta(hours=4),
                     now + dt.timedelta(hours=24))
```

API keys via env vars: `ENTSOE_API_KEY`, `OPENELECTRICITY_API_KEY`,
`ELECTRICITY_MAPS_API_KEY`, `COMPUTE_BIO_API_URL`/`COMPUTE_BIO_TOKEN` — or
pass a `ProviderConfig` explicitly.

**Method caveat for EU zones**: `get_current()` / `get_forecast()` on an
ENTSO-E zone return *production* intensity (single-zone fast path, labeled
`extra["method"] = "production_only"`) — they do **not** account for
imports/exports. Consumption intensity for EU zones requires the flow-traced
`run_window()` (or the `compute_bio` provider, which serves a backend's
flow-traced value). Don't compare fast-path numbers against consumption-based
sources such as Electricity Maps.

Forecast caveats: WEM (Western Australia) uses a 7-day hour-of-day
climatology, not a physical forecast; NEM forecasts assume the current
thermal mix holds. The method is labeled in each record's `extra["method"]`.

Run the test suite: `python tests/smoke.py` (live UK checks need network;
ENTSO-E/AU live checks run when keys are set).
