nordic-balancing 0.1.0__tar.gz

nordic_balancing-0.1.0/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.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: nordic-balancing
+Version: 0.1.0
+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 :: 3 - 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,<1
+Requires-Dist: pandas>=2.1 ; extra == 'pandas'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/Razikale365/nordic-balancing
+Project-URL: Issues, https://github.com/Razikale365/nordic-balancing/issues
+Provides-Extra: pandas
+Description-Content-Type: text/markdown
+
+# nordic-balancing
+
+Python client for Nordic electricity **balancing** and **imbalance** data, normalised to
+15-minute UTC intervals.
+
+> **Status: alpha.** Releases are on [PyPI](https://pypi.org/project/nordic-balancing/).
+> Every source is checked against its live API, but the API of this library may still
+> change between 0.x versions. See [CHANGELOG.md](CHANGELOG.md).
+
+## Install
+
+```bash
+pip install nordic-balancing            # httpx is the only dependency
+pip install "nordic-balancing[pandas]"  # adds to_frame()
+```
+
+Python 3.12 or newer.
+
+## 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)
+```
+
+With the `pandas` extra, `to_frame` turns any list of records into a DataFrame: one row
+per record, one column per field except `raw`, `start` in UTC, `None` as `NaN`, and
+directions as nullable integers.
+
+```python
+from nordic_balancing import to_frame
+
+frame = to_frame(nordic_prices).set_index(["start", "zone"])
+```
+
+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 mapping over a deep copy of the source record, private to
+that record; only its top level rejects writes, so treat nested values as read-only too.
+
+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)`.
+`series()` expands hourly records only for datasets 319, 244, 106 and 369; any other
+dataset must be 15-minute, and an hourly record raises `SourceError`.
+
+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. ENTSO-E is the exception: an interval published under
+  several price categories with one equal price collapses to that price, with
+  every category kept in `raw`; unequal prices, or equal prices at different
+  resolutions, raise.
+- **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. Sources can label the same price
+  differently: ENTSO-E kept `PT60M` for SE and NO until 2025-03-18T00:00Z, eSett
+  switched to 15 minutes on 2023-05-21T22:00Z (see
+  [docs/RELEASE_EVIDENCE.md](docs/RELEASE_EVIDENCE.md)).
+- **C8 Transport.** Network and protocol failures surface as `SourceError`, never as
+  raw `httpx` exceptions. HTTP 429/503 are retried, then raise `RateLimitError`, which
+  is raised at once when `Retry-After` exceeds 300 s. HTTP 502/504, timeouts and
+  dropped connections are retried within the same `max_retries` budget, then raise
+  `SourceError`.
+
+`reconcile_imbalance_prices` reports differences between two sources; it never merges
+series or picks a source. Zones present in only one input are listed in
+`primary_only_zones` / `reference_only_zones` rather than dropped silently.
+
+See [docs/RELEASE_EVIDENCE.md](docs/RELEASE_EVIDENCE.md) for provider verification
+status, observed API behaviour and known limitations.
+
+## Sources
+
+| Source | Client | Data | Access | Verified against the live API |
+|---|---|---|---|---|
+| Energinet — Energi Data Service | `EnergiDataServiceClient` | DK1/DK2 imbalance prices and components, from 2025-03-04 | free, no key | yes |
+| Fingrid | `FingridClient` | FI imbalance prices, mFRR up/down prices, dominating direction; any 15-minute dataset via `series()` | free API key | yes |
+| Svenska kraftnät | `SvKClient` | SE1–SE4 mFRR and aFRR capacity market prices and volumes (hourly, expanded to 15 minutes) | free (CC-BY-4.0) | yes |
+| eSett | `ESettClient` | Imbalance prices, all 12 Nordic zones, from 2021-10-31T23:00Z | free, no key | yes |
+| ENTSO-E Transparency Platform | `EntsoeClient` | Imbalance prices (A85), all 12 Nordic zones, from 2021-10-31T23:00Z | free token (`ENTSOE_API_KEY`) | yes |
+
+Not covered yet: Energi Data Service mFRR/aFRR datasets, and activated balancing energy
+volumes. 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.0/README.md

@@ -0,0 +1,144 @@
+# nordic-balancing
+
+Python client for Nordic electricity **balancing** and **imbalance** data, normalised to
+15-minute UTC intervals.
+
+> **Status: alpha.** Releases are on [PyPI](https://pypi.org/project/nordic-balancing/).
+> Every source is checked against its live API, but the API of this library may still
+> change between 0.x versions. See [CHANGELOG.md](CHANGELOG.md).
+
+## Install
+
+```bash
+pip install nordic-balancing            # httpx is the only dependency
+pip install "nordic-balancing[pandas]"  # adds to_frame()
+```
+
+Python 3.12 or newer.
+
+## 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)
+```
+
+With the `pandas` extra, `to_frame` turns any list of records into a DataFrame: one row
+per record, one column per field except `raw`, `start` in UTC, `None` as `NaN`, and
+directions as nullable integers.
+
+```python
+from nordic_balancing import to_frame
+
+frame = to_frame(nordic_prices).set_index(["start", "zone"])
+```
+
+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 mapping over a deep copy of the source record, private to
+that record; only its top level rejects writes, so treat nested values as read-only too.
+
+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)`.
+`series()` expands hourly records only for datasets 319, 244, 106 and 369; any other
+dataset must be 15-minute, and an hourly record raises `SourceError`.
+
+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. ENTSO-E is the exception: an interval published under
+  several price categories with one equal price collapses to that price, with
+  every category kept in `raw`; unequal prices, or equal prices at different
+  resolutions, raise.
+- **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. Sources can label the same price
+  differently: ENTSO-E kept `PT60M` for SE and NO until 2025-03-18T00:00Z, eSett
+  switched to 15 minutes on 2023-05-21T22:00Z (see
+  [docs/RELEASE_EVIDENCE.md](docs/RELEASE_EVIDENCE.md)).
+- **C8 Transport.** Network and protocol failures surface as `SourceError`, never as
+  raw `httpx` exceptions. HTTP 429/503 are retried, then raise `RateLimitError`, which
+  is raised at once when `Retry-After` exceeds 300 s. HTTP 502/504, timeouts and
+  dropped connections are retried within the same `max_retries` budget, then raise
+  `SourceError`.
+
+`reconcile_imbalance_prices` reports differences between two sources; it never merges
+series or picks a source. Zones present in only one input are listed in
+`primary_only_zones` / `reference_only_zones` rather than dropped silently.
+
+See [docs/RELEASE_EVIDENCE.md](docs/RELEASE_EVIDENCE.md) for provider verification
+status, observed API behaviour and known limitations.
+
+## Sources
+
+| Source | Client | Data | Access | Verified against the live API |
+|---|---|---|---|---|
+| Energinet — Energi Data Service | `EnergiDataServiceClient` | DK1/DK2 imbalance prices and components, from 2025-03-04 | free, no key | yes |
+| Fingrid | `FingridClient` | FI imbalance prices, mFRR up/down prices, dominating direction; any 15-minute dataset via `series()` | free API key | yes |
+| Svenska kraftnät | `SvKClient` | SE1–SE4 mFRR and aFRR capacity market prices and volumes (hourly, expanded to 15 minutes) | free (CC-BY-4.0) | yes |
+| eSett | `ESettClient` | Imbalance prices, all 12 Nordic zones, from 2021-10-31T23:00Z | free, no key | yes |
+| ENTSO-E Transparency Platform | `EntsoeClient` | Imbalance prices (A85), all 12 Nordic zones, from 2021-10-31T23:00Z | free token (`ENTSOE_API_KEY`) | yes |
+
+Not covered yet: Energi Data Service mFRR/aFRR datasets, and activated balancing energy
+volumes. 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.0/pyproject.toml

@@ -0,0 +1,85 @@
+[project]
+name = "nordic-balancing"
+version = "0.1.0"
+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,<1"]
+keywords = [
+    "energy",
+    "electricity",
+    "balancing",
+    "imbalance",
+    "mfrr",
+    "afrr",
+    "nordic",
+    "energinet",
+    "fingrid",
+    "esett",
+    "svenska-kraftnat",
+    "entsoe",
+]
+classifiers = [
+    "Development Status :: 3 - 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"
+
+[project.optional-dependencies]
+pandas = ["pandas>=2.1"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "mypy>=1.11",
+    "ruff>=0.6",
+    "hypothesis>=6.168.5",
+    "pandas-stubs>=3.0.5.260914",
+    "pandas>=2.1",
+]
+
+[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.0/pyproject.toml.orig

@@ -0,0 +1,76 @@
+[project]
+name = "nordic-balancing"
+version = "0.1.0"
+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,<1",
+]
+keywords = [
+    "energy",
+    "electricity",
+    "balancing",
+    "imbalance",
+    "mfrr",
+    "afrr",
+    "nordic",
+    "energinet",
+    "fingrid",
+    "esett",
+    "svenska-kraftnat",
+    "entsoe",
+]
+classifiers = [
+    "Development Status :: 3 - 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"
+
+[project.optional-dependencies]
+pandas = [
+    "pandas>=2.1",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "mypy>=1.11",
+    "ruff>=0.6",
+    "hypothesis>=6.168.5",
+    "pandas-stubs>=3.0.5.260914",
+    "pandas>=2.1",
+]
+
+[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.0/src/nordic_balancing/__init__.py

@@ -0,0 +1,56 @@
+"""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.frame import to_frame
+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",
+    "to_frame",
+]

nordic_balancing-0.1.0/src/nordic_balancing/_http.py

@@ -0,0 +1,118 @@
+"""Shared bounded retries so sources handle throttling consistently."""
+
+import math
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import httpx
+
+from nordic_balancing.errors import RateLimitError, SourceError
+
+# Throttling: exhausting the retries raises RateLimitError.
+_RATE_LIMIT_STATUSES = frozenset({429, 503})
+# Transient gateway failures: retried, then reported as an ordinary HTTP error.
+_TRANSIENT_STATUSES = frozenset({502, 504})
+_TRANSIENT_ERRORS = (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError)
+_DEFAULT_RETRY_AFTER = 10.0
+# A longer requested wait is not slept through: RateLimitError reports it instead.
+_MAX_RETRY_AFTER = 300.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):
+        last = attempt == max_retries
+        try:
+            response = http.get(f"{base_url}{path}", params=query_params)
+        except _TRANSIENT_ERRORS:
+            # Timeouts and dropped connections are retried; callers wrap the last one.
+            if last:
+                raise
+            sleep(_DEFAULT_RETRY_AFTER)
+            continue
+        if response.status_code in _RATE_LIMIT_STATUSES:
+            retry_after = _retry_after(response)
+            if last or (retry_after is not None and retry_after > _MAX_RETRY_AFTER):
+                raise RateLimitError(source, retry_after)
+            sleep(retry_after if retry_after is not None else _DEFAULT_RETRY_AFTER)
+        elif response.status_code in _TRANSIENT_STATUSES and not last:
+            sleep(_DEFAULT_RETRY_AFTER)
+        else:
+            break
+    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:
+        seconds = float(header)
+    except ValueError:
+        return None
+    # "inf" and "nan" parse as floats but are not usable delays.
+    return max(seconds, 0.0) if math.isfinite(seconds) else None