nordic-balancing 0.1.0a1__tar.gz

nordic_balancing-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Razikale365
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nordic_balancing-0.1.0a1/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: nordic-balancing
+Version: 0.1.0a1
+Summary: Python client for Nordic electricity balancing and imbalance data (Energinet, Fingrid, Svenska kraftnät, eSett, ENTSO-E), normalised to 15-minute UTC intervals.
+Keywords: energy,electricity,balancing,imbalance,mfrr,afrr,nordic,energinet,fingrid,esett,svenska-kraftnat,entsoe
+Author: Razikale365
+Author-email: Razikale365 <66191390+Razikale365@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.27
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/Razikale365/nordic-balancing
+Project-URL: Issues, https://github.com/Razikale365/nordic-balancing/issues
+Description-Content-Type: text/markdown
+
+# nordic-balancing
+
+Python client for Nordic electricity **balancing** and **imbalance** data, normalised to
+15-minute UTC intervals.
+
+> **Status: pre-alpha.** Nothing is published yet; the API will change.
+
+## Why
+
+Nordic balancing data is spread across several transmission system operators and eSett,
+each with its own API, authentication, time zone handling and resolution history. The
+Nordic markets moved to 15-minute resolution in stages (imbalance settlement in 2023,
+mFRR energy activation and intraday in 2025, day-ahead in October 2025), so the same
+series can change resolution mid-history.
+
+`nordic-balancing` aims to give one typed interface over these sources, with every series
+in UTC on 15-minute intervals and a dated record of resolution and price-formula changes.
+
+## Usage
+
+```python
+from datetime import UTC, datetime, timedelta
+
+from nordic_balancing import BiddingZone, ESettClient, EnergiDataServiceClient
+
+start = datetime(2026, 1, 15, tzinfo=UTC)
+with EnergiDataServiceClient() as eds:
+    prices = eds.imbalance_prices(start, start + timedelta(hours=1), [BiddingZone.DK1])
+
+with ESettClient() as esett:
+    nordic_prices = esett.imbalance_prices(start, start + timedelta(hours=1))  # all 12 zones
+
+for p in prices:
+    print(p.start, p.zone, p.imbalance_price_eur, p.dominating_direction)
+```
+
+Every query takes timezone-aware datetimes and returns intervals starting in
+`[start, end)`, keyed by their UTC start. A price of `None` means the source has
+not published it yet or does not provide it. `resolution` retains the source's
+publication interval; historical hourly values are expanded into four quarters.
+`raw` is a read-only copy of the source record.
+
+Set `FINGRID_API_KEY` to a free key from https://developer-data.fingrid.fi.
+Use `with FingridClient() as fingrid:` after importing it from `nordic_balancing`.
+Call `fingrid.imbalance_prices(start, end)` for FI prices, or `series(dataset_id, start, end)`.
+
+Svenska kraftnät needs no key.
+Call `SvKClient().capacity_market(ReserveProduct.MFRR, start, end)` for SE1–SE4 capacity prices and volumes.
+
+## Data contracts
+
+Every client enforces the same contracts; a violation raises `SourceError`.
+
+- **C1 Window.** Queries take aware datetimes and return exactly the intervals
+  whose start is in `[start, end)`, at any sub-second precision of `start`/`end`.
+- **C2 Pagination.** Rows fetched must equal the total the source reported; a
+  missing or invalid total, a short or empty page before the total is reached,
+  or a mismatch is an error.
+- **C3 Duplicates.** Two source records for the same series key (zone and
+  interval start, plus product and direction for SvK) are an error, even when
+  the values are equal.
+- **C4 Missing vs unpublished.** An interval the source did not return is absent
+  from the result; a record returned with a null value has that field set to
+  `None`. Clients never fill gaps.
+- **C5 Numbers.** Values must be JSON numbers (`bool` rejected), finite and
+  convertible to `float`.
+- **C6 Outside window.** Records outside the requested query window are an error.
+- **C7 Resolution.** `resolution` is the source's publication interval; hourly
+  records are repeated across four quarters.
+- **C8 Transport.** Network and protocol failures surface as `SourceError`, never as
+  raw `httpx` exceptions (after the bounded retries for HTTP 429/503).
+
+`reconcile_imbalance_prices` reports differences between two sources; it never merges
+series or picks a source.
+
+See [docs/RELEASE_EVIDENCE.md](docs/RELEASE_EVIDENCE.md) for provider verification
+status, observed API behaviour and known limitations.
+
+## Planned sources
+
+| Source | Data | Access |
+|---|---|---|
+| Energinet — Energi Data Service | DK1/DK2 imbalance prices and components (**available**); mFRR/aFRR datasets | free, no key |
+| Fingrid | FI imbalance prices, mFRR price components and 15-minute series (**available**) | free API key |
+| Svenska kraftnät | SE1–SE4 mFRR and aFRR capacity market prices and volumes (hourly, expanded to 15 minutes) (**available**) | free (CC-BY-4.0) |
+| eSett | Imbalance prices, all 12 Nordic zones, from 2021-11-01 (**available**) | free, no key |
+| ENTSO-E Transparency Platform | Imbalance prices (A85), all 12 Nordic zones (**available, not yet live-verified**) | free token (`ENTSOE_API_KEY`) |
+
+Out of scope: generic day-ahead price clients and mFRR bid submission — other projects
+already cover those.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest -m live      # calls the real APIs; not run by default
+```
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). Data retrieved through this library remains subject to each
+source's own terms of use.
+
+This is an independent project. It is not affiliated with, endorsed by or supported by
+Energinet, Fingrid, Svenska kraftnät, eSett, ENTSO-E or any other data provider.

nordic_balancing-0.1.0a1/README.md

@@ -0,0 +1,109 @@
+# nordic-balancing
+
+Python client for Nordic electricity **balancing** and **imbalance** data, normalised to
+15-minute UTC intervals.
+
+> **Status: pre-alpha.** Nothing is published yet; the API will change.
+
+## Why
+
+Nordic balancing data is spread across several transmission system operators and eSett,
+each with its own API, authentication, time zone handling and resolution history. The
+Nordic markets moved to 15-minute resolution in stages (imbalance settlement in 2023,
+mFRR energy activation and intraday in 2025, day-ahead in October 2025), so the same
+series can change resolution mid-history.
+
+`nordic-balancing` aims to give one typed interface over these sources, with every series
+in UTC on 15-minute intervals and a dated record of resolution and price-formula changes.
+
+## Usage
+
+```python
+from datetime import UTC, datetime, timedelta
+
+from nordic_balancing import BiddingZone, ESettClient, EnergiDataServiceClient
+
+start = datetime(2026, 1, 15, tzinfo=UTC)
+with EnergiDataServiceClient() as eds:
+    prices = eds.imbalance_prices(start, start + timedelta(hours=1), [BiddingZone.DK1])
+
+with ESettClient() as esett:
+    nordic_prices = esett.imbalance_prices(start, start + timedelta(hours=1))  # all 12 zones
+
+for p in prices:
+    print(p.start, p.zone, p.imbalance_price_eur, p.dominating_direction)
+```
+
+Every query takes timezone-aware datetimes and returns intervals starting in
+`[start, end)`, keyed by their UTC start. A price of `None` means the source has
+not published it yet or does not provide it. `resolution` retains the source's
+publication interval; historical hourly values are expanded into four quarters.
+`raw` is a read-only copy of the source record.
+
+Set `FINGRID_API_KEY` to a free key from https://developer-data.fingrid.fi.
+Use `with FingridClient() as fingrid:` after importing it from `nordic_balancing`.
+Call `fingrid.imbalance_prices(start, end)` for FI prices, or `series(dataset_id, start, end)`.
+
+Svenska kraftnät needs no key.
+Call `SvKClient().capacity_market(ReserveProduct.MFRR, start, end)` for SE1–SE4 capacity prices and volumes.
+
+## Data contracts
+
+Every client enforces the same contracts; a violation raises `SourceError`.
+
+- **C1 Window.** Queries take aware datetimes and return exactly the intervals
+  whose start is in `[start, end)`, at any sub-second precision of `start`/`end`.
+- **C2 Pagination.** Rows fetched must equal the total the source reported; a
+  missing or invalid total, a short or empty page before the total is reached,
+  or a mismatch is an error.
+- **C3 Duplicates.** Two source records for the same series key (zone and
+  interval start, plus product and direction for SvK) are an error, even when
+  the values are equal.
+- **C4 Missing vs unpublished.** An interval the source did not return is absent
+  from the result; a record returned with a null value has that field set to
+  `None`. Clients never fill gaps.
+- **C5 Numbers.** Values must be JSON numbers (`bool` rejected), finite and
+  convertible to `float`.
+- **C6 Outside window.** Records outside the requested query window are an error.
+- **C7 Resolution.** `resolution` is the source's publication interval; hourly
+  records are repeated across four quarters.
+- **C8 Transport.** Network and protocol failures surface as `SourceError`, never as
+  raw `httpx` exceptions (after the bounded retries for HTTP 429/503).
+
+`reconcile_imbalance_prices` reports differences between two sources; it never merges
+series or picks a source.
+
+See [docs/RELEASE_EVIDENCE.md](docs/RELEASE_EVIDENCE.md) for provider verification
+status, observed API behaviour and known limitations.
+
+## Planned sources
+
+| Source | Data | Access |
+|---|---|---|
+| Energinet — Energi Data Service | DK1/DK2 imbalance prices and components (**available**); mFRR/aFRR datasets | free, no key |
+| Fingrid | FI imbalance prices, mFRR price components and 15-minute series (**available**) | free API key |
+| Svenska kraftnät | SE1–SE4 mFRR and aFRR capacity market prices and volumes (hourly, expanded to 15 minutes) (**available**) | free (CC-BY-4.0) |
+| eSett | Imbalance prices, all 12 Nordic zones, from 2021-11-01 (**available**) | free, no key |
+| ENTSO-E Transparency Platform | Imbalance prices (A85), all 12 Nordic zones (**available, not yet live-verified**) | free token (`ENTSOE_API_KEY`) |
+
+Out of scope: generic day-ahead price clients and mFRR bid submission — other projects
+already cover those.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest -m live      # calls the real APIs; not run by default
+```
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). Data retrieved through this library remains subject to each
+source's own terms of use.
+
+This is an independent project. It is not affiliated with, endorsed by or supported by
+Energinet, Fingrid, Svenska kraftnät, eSett, ENTSO-E or any other data provider.

nordic_balancing-0.1.0a1/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "nordic-balancing"
+version = "0.1.0a1"
+description = "Python client for Nordic electricity balancing and imbalance data (Energinet, Fingrid, Svenska kraftnät, eSett, ENTSO-E), normalised to 15-minute UTC intervals."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["httpx>=0.27"]
+keywords = [
+    "energy",
+    "electricity",
+    "balancing",
+    "imbalance",
+    "mfrr",
+    "afrr",
+    "nordic",
+    "energinet",
+    "fingrid",
+    "esett",
+    "svenska-kraftnat",
+    "entsoe",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Razikale365"
+email = "66191390+Razikale365@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/Razikale365/nordic-balancing"
+Issues = "https://github.com/Razikale365/nordic-balancing/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "mypy>=1.11",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.15,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "B",
+    "UP",
+    "SIM",
+    "RUF",
+]
+
+[tool.mypy]
+strict = true
+files = [
+    "src",
+    "tests",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -m 'not live'"
+markers = ["live: calls real data source APIs (run with: pytest -m live)"]

nordic_balancing-0.1.0a1/pyproject.toml.orig

@@ -0,0 +1,68 @@
+[project]
+name = "nordic-balancing"
+version = "0.1.0a1"
+description = "Python client for Nordic electricity balancing and imbalance data (Energinet, Fingrid, Svenska kraftnät, eSett, ENTSO-E), normalised to 15-minute UTC intervals."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Razikale365", email = "66191390+Razikale365@users.noreply.github.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.27",
+]
+keywords = [
+    "energy",
+    "electricity",
+    "balancing",
+    "imbalance",
+    "mfrr",
+    "afrr",
+    "nordic",
+    "energinet",
+    "fingrid",
+    "esett",
+    "svenska-kraftnat",
+    "entsoe",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/Razikale365/nordic-balancing"
+Issues = "https://github.com/Razikale365/nordic-balancing/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "mypy>=1.11",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.15,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -m 'not live'"
+markers = ["live: calls real data source APIs (run with: pytest -m live)"]

nordic_balancing-0.1.0a1/src/nordic_balancing/__init__.py

@@ -0,0 +1,54 @@
+"""Nordic electricity balancing and imbalance data, normalised to 15-minute UTC intervals."""
+
+from importlib.metadata import version
+
+from nordic_balancing.changes import CHANGES, MarketChange, changes_between
+from nordic_balancing.errors import NordicBalancingError, RateLimitError, SourceError
+from nordic_balancing.models import (
+    INTERVAL,
+    BiddingZone,
+    Direction,
+    ImbalancePrice,
+    ReserveCapacity,
+    ReserveProduct,
+)
+from nordic_balancing.reconcile import (
+    Divergence,
+    DivergenceKind,
+    ReconciliationReport,
+    reconcile_imbalance_prices,
+)
+from nordic_balancing.sources import (
+    EnergiDataServiceClient,
+    EntsoeClient,
+    ESettClient,
+    FingridClient,
+    SvKClient,
+)
+
+__version__ = version("nordic-balancing")
+
+__all__ = [
+    "CHANGES",
+    "INTERVAL",
+    "BiddingZone",
+    "Direction",
+    "Divergence",
+    "DivergenceKind",
+    "ESettClient",
+    "EnergiDataServiceClient",
+    "EntsoeClient",
+    "FingridClient",
+    "ImbalancePrice",
+    "MarketChange",
+    "NordicBalancingError",
+    "RateLimitError",
+    "ReconciliationReport",
+    "ReserveCapacity",
+    "ReserveProduct",
+    "SourceError",
+    "SvKClient",
+    "__version__",
+    "changes_between",
+    "reconcile_imbalance_prices",
+]

nordic_balancing-0.1.0a1/src/nordic_balancing/_http.py

@@ -0,0 +1,98 @@
+"""Shared bounded retries so sources handle throttling consistently."""
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import httpx
+
+from nordic_balancing.errors import RateLimitError, SourceError
+
+_RETRY_STATUSES = frozenset({429, 503})
+_DEFAULT_RETRY_AFTER = 10.0
+
+
+def get_json(
+    http: httpx.Client,
+    base_url: str,
+    path: str,
+    params: Mapping[str, str] | list[tuple[str, str]],
+    *,
+    source: str,
+    max_retries: int,
+    sleep: Callable[[float], None],
+) -> Any:
+    response = _request(
+        http,
+        base_url,
+        path,
+        params,
+        source=source,
+        max_retries=max_retries,
+        sleep=sleep,
+        passthrough_statuses=frozenset(),
+    )
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise SourceError(f"{source}: response for {path} is not JSON") from exc
+
+
+def get_bytes(
+    http: httpx.Client,
+    base_url: str,
+    path: str,
+    params: Mapping[str, str] | list[tuple[str, str]],
+    *,
+    source: str,
+    max_retries: int,
+    sleep: Callable[[float], None],
+    passthrough_statuses: frozenset[int] = frozenset(),
+) -> tuple[bytes, str]:
+    response = _request(
+        http,
+        base_url,
+        path,
+        params,
+        source=source,
+        max_retries=max_retries,
+        sleep=sleep,
+        passthrough_statuses=passthrough_statuses,
+    )
+    return response.content, response.headers.get("content-type", "")
+
+
+def _request(
+    http: httpx.Client,
+    base_url: str,
+    path: str,
+    params: Mapping[str, str] | list[tuple[str, str]],
+    *,
+    source: str,
+    max_retries: int,
+    sleep: Callable[[float], None],
+    passthrough_statuses: frozenset[int],
+) -> httpx.Response:
+    query_params = params if isinstance(params, Mapping) else tuple(params)
+    for attempt in range(max_retries + 1):
+        response = http.get(f"{base_url}{path}", params=query_params)
+        if response.status_code not in _RETRY_STATUSES:
+            break
+        retry_after = _retry_after(response)
+        if attempt == max_retries:
+            raise RateLimitError(source, retry_after)
+        sleep(retry_after if retry_after is not None else _DEFAULT_RETRY_AFTER)
+    if response.is_error and response.status_code not in passthrough_statuses:
+        raise SourceError(
+            f"{source}: HTTP {response.status_code} for {path}: {response.text[:200]}"
+        )
+    return response
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    header = response.headers.get("Retry-After")
+    if header is None:
+        return None
+    try:
+        return max(float(header), 0.0)
+    except ValueError:
+        return None

nordic_balancing-0.1.0a1/src/nordic_balancing/_validate.py

@@ -0,0 +1,33 @@
+"""Shared record validators enforcing the data contracts in README.md."""
+
+import math
+from collections.abc import Hashable
+
+from nordic_balancing.errors import SourceError
+
+
+def finite_number(value: object, *, source: str, column: str) -> float | None:
+    """Return ``value`` as a float, ``None`` for null; reject the rest (C5).
+
+    A JSON bool, a non-number, a NaN/Infinity token and an overflowing value
+    are all rejected. The offending value is never echoed: Fingrid fields can
+    contain the API key.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise SourceError(f"{source}: {column} is not a number")
+    try:
+        number = float(value)
+    except OverflowError as exc:
+        raise SourceError(f"{source}: {column} is not finite") from exc
+    if not math.isfinite(number):
+        raise SourceError(f"{source}: {column} is not finite")
+    return number
+
+
+def reject_duplicate[K: Hashable](seen: set[K], key: K, *, source: str, detail: str) -> None:
+    """Reject a second record for the same series key (C3)."""
+    if key in seen:
+        raise SourceError(f"{source}: duplicate {detail}")
+    seen.add(key)