hydropeak-opendata 0.1.0__tar.gz

hydropeak_opendata-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .[dev]
+      - run: ruff check .
+      - run: mypy
+      - run: pytest -q

hydropeak_opendata-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC for PyPI Trusted Publishing — no token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

hydropeak_opendata-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

hydropeak_opendata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Beat YT
+
+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.

hydropeak_opendata-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: hydropeak-opendata
+Version: 0.1.0
+Summary: Async client for Hydro-Québec's public peak events (pointes hivernales) open data
+Project-URL: Homepage, https://github.com/Beat-YT/hydropeak-opendata
+Project-URL: Issues, https://github.com/Beat-YT/hydropeak-opendata/issues
+Author: Beat-YT
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-aiohttp>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hydropeak-opendata
+
+Async Python client for Hydro-Québec's public **peak events** (pointes hivernales) open data. No account, no login — just the open data feed.
+
+Extracted from the [HydroPeak](https://github.com/Beat-YT/hydropeak-ha) Home Assistant integration.
+
+## Data sources
+
+- **Peak events feed** — `pointeshivernales.json`: available offers (canonical, verbatim) and scheduled peak events.
+- **Offer descriptions** — the `evenements-de-pointe-offres-disponibles` Opendatasoft dataset (rate limited; intended for occasional use such as setup flows).
+
+## Usage
+
+```python
+import aiohttp
+from hydropeak_opendata import OpenDataClient
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = OpenDataClient(session)
+
+        offers = await client.get_available_offers()
+        # ('Credit hivernal Residentiel (CPC-D)', 'Flex Residentiel (TPC-DPC)', ...)
+
+        events = await client.get_events(offers[0])
+        for event in events:
+            print(event.start, event.end, event.period, event.duration)
+```
+
+Notes:
+
+- Offer identifiers are the strings published in `offresDisponibles`, used verbatim. The library applies no transformation; `get_events(offer)` filters by exact match.
+- The client sends conditional requests (`If-None-Match`) and serves its cached parse on `304 Not Modified`, so frequent polling is cheap for both sides. Concurrent refreshes are serialized on a lock.
+- All datetimes from the feed are timezone-aware. `PeakEventsFeed.last_execution` is naive (the feed publishes it without an offset).
+- Errors raise typed exceptions: `OpenDataConnectionError`, `OpenDataRateLimitError`, `OpenDataResponseError`, `OpenDataParseError` — all subclasses of `OpenDataError`. Failures never silently return empty data.
+
+## Development
+
+```
+pip install -e .[dev]
+ruff check .
+mypy
+pytest
+```
+
+## License
+
+MIT

hydropeak_opendata-0.1.0/README.md

@@ -0,0 +1,48 @@
+# hydropeak-opendata
+
+Async Python client for Hydro-Québec's public **peak events** (pointes hivernales) open data. No account, no login — just the open data feed.
+
+Extracted from the [HydroPeak](https://github.com/Beat-YT/hydropeak-ha) Home Assistant integration.
+
+## Data sources
+
+- **Peak events feed** — `pointeshivernales.json`: available offers (canonical, verbatim) and scheduled peak events.
+- **Offer descriptions** — the `evenements-de-pointe-offres-disponibles` Opendatasoft dataset (rate limited; intended for occasional use such as setup flows).
+
+## Usage
+
+```python
+import aiohttp
+from hydropeak_opendata import OpenDataClient
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = OpenDataClient(session)
+
+        offers = await client.get_available_offers()
+        # ('Credit hivernal Residentiel (CPC-D)', 'Flex Residentiel (TPC-DPC)', ...)
+
+        events = await client.get_events(offers[0])
+        for event in events:
+            print(event.start, event.end, event.period, event.duration)
+```
+
+Notes:
+
+- Offer identifiers are the strings published in `offresDisponibles`, used verbatim. The library applies no transformation; `get_events(offer)` filters by exact match.
+- The client sends conditional requests (`If-None-Match`) and serves its cached parse on `304 Not Modified`, so frequent polling is cheap for both sides. Concurrent refreshes are serialized on a lock.
+- All datetimes from the feed are timezone-aware. `PeakEventsFeed.last_execution` is naive (the feed publishes it without an offset).
+- Errors raise typed exceptions: `OpenDataConnectionError`, `OpenDataRateLimitError`, `OpenDataResponseError`, `OpenDataParseError` — all subclasses of `OpenDataError`. Failures never silently return empty data.
+
+## Development
+
+```
+pip install -e .[dev]
+ruff check .
+mypy
+pytest
+```
+
+## License
+
+MIT

hydropeak_opendata-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hydropeak-opendata"
+version = "0.1.0"
+description = "Async client for Hydro-Québec's public peak events (pointes hivernales) open data"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Beat-YT" }]
+requires-python = ">=3.11"
+dependencies = ["aiohttp>=3.9"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+]
+
+[project.urls]
+Homepage = "https://github.com/Beat-YT/hydropeak-opendata"
+Issues = "https://github.com/Beat-YT/hydropeak-opendata/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-aiohttp>=1.1",
+    "ruff>=0.6",
+    "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hydropeak_opendata"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+packages = ["hydropeak_opendata"]
+mypy_path = "src"

hydropeak_opendata-0.1.0/src/hydropeak_opendata/__init__.py

@@ -0,0 +1,31 @@
+"""Async client for Hydro-Québec's peak events (pointes hivernales) open data."""
+
+from .client import OFFER_DESCRIPTIONS_URL, PEAK_EVENTS_URL, OpenDataClient
+from .exceptions import (
+    OpenDataConnectionError,
+    OpenDataError,
+    OpenDataParseError,
+    OpenDataRateLimitError,
+    OpenDataResponseError,
+)
+from .models import (
+    OfferDescription,
+    PeakEvent,
+    PeakEventsFeed,
+    parse_feed,
+)
+
+__all__ = [
+    "OFFER_DESCRIPTIONS_URL",
+    "PEAK_EVENTS_URL",
+    "OfferDescription",
+    "OpenDataClient",
+    "OpenDataConnectionError",
+    "OpenDataError",
+    "OpenDataParseError",
+    "OpenDataRateLimitError",
+    "OpenDataResponseError",
+    "PeakEvent",
+    "PeakEventsFeed",
+    "parse_feed",
+]

hydropeak_opendata-0.1.0/src/hydropeak_opendata/client.py

@@ -0,0 +1,158 @@
+"""Async client for Hydro-Québec's peak events open data."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from datetime import date
+
+import aiohttp
+
+from .exceptions import (
+    OpenDataConnectionError,
+    OpenDataParseError,
+    OpenDataRateLimitError,
+    OpenDataResponseError,
+)
+from .models import (
+    OfferDescription,
+    PeakEvent,
+    PeakEventsFeed,
+    parse_feed,
+    parse_offer_description,
+)
+
+PEAK_EVENTS_URL = (
+    "https://donnees.solutions.hydroquebec.com/donnees-ouvertes/data/json/pointeshivernales.json"
+)
+OFFER_DESCRIPTIONS_URL = (
+    "https://donnees.hydroquebec.com/api/explore/v2.1/catalog/datasets"
+    "/evenements-de-pointe-offres-disponibles/records"
+)
+_DESCRIPTIONS_PAGE_SIZE = 100
+
+
+class OpenDataClient:
+    """Client for the peak events feed and the offer descriptions dataset.
+
+    The aiohttp session is injected and never closed by the client, so one
+    session can be shared across the application. The client sends
+    conditional requests (``If-None-Match``) and serves the last parsed feed
+    on ``304 Not Modified``; concurrent callers are serialized on a lock so
+    a burst of refreshes results in one request followed by cheap 304s.
+    """
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        *,
+        request_timeout: float = 30.0,
+        peak_events_url: str = PEAK_EVENTS_URL,
+        offer_descriptions_url: str = OFFER_DESCRIPTIONS_URL,
+    ) -> None:
+        self._session = session
+        self._peak_events_url = peak_events_url
+        self._offer_descriptions_url = offer_descriptions_url
+        self._timeout = aiohttp.ClientTimeout(total=request_timeout)
+        self._lock = asyncio.Lock()
+        self._etag: str | None = None
+        self._feed: PeakEventsFeed | None = None
+
+    async def get_feed(self) -> PeakEventsFeed:
+        """Fetch (or revalidate) the peak events feed."""
+        async with self._lock:
+            headers: dict[str, str] = {}
+            if self._etag is not None and self._feed is not None:
+                headers["If-None-Match"] = self._etag
+
+            try:
+                async with self._session.get(
+                    self._peak_events_url, headers=headers, timeout=self._timeout
+                ) as response:
+                    if response.status == 304 and self._feed is not None:
+                        return self._feed
+                    _raise_for_status(response)
+                    etag = response.headers.get("ETag")
+                    # The endpoint mislabels the JSON payload as text/plain,
+                    # so parse the body ourselves instead of response.json().
+                    text = await response.text()
+            except OSError as err:
+                raise OpenDataConnectionError(f"Error fetching peak events: {err}") from err
+            except aiohttp.ClientError as err:
+                raise OpenDataConnectionError(f"Error fetching peak events: {err}") from err
+            except TimeoutError as err:
+                raise OpenDataConnectionError("Timeout fetching peak events") from err
+
+            try:
+                data = json.loads(text)
+            except ValueError as err:
+                raise OpenDataParseError("Peak events payload is not valid JSON") from err
+
+            feed = parse_feed(data)
+            self._etag = etag
+            self._feed = feed
+            return feed
+
+    async def get_events(self, offer: str | None = None) -> tuple[PeakEvent, ...]:
+        """Fetch events, optionally filtered to one offer (exact match)."""
+        feed = await self.get_feed()
+        if offer is None:
+            return feed.events
+        return feed.events_for_offer(offer)
+
+    async def get_available_offers(self) -> tuple[str, ...]:
+        """Fetch the canonical offer list, verbatim from ``offresDisponibles``."""
+        feed = await self.get_feed()
+        return feed.offers
+
+    async def get_offer_descriptions(
+        self, active_on: date | None = None
+    ) -> tuple[OfferDescription, ...]:
+        """Fetch offer descriptions from the Opendatasoft dataset.
+
+        This endpoint is rate limited (429 raises
+        :class:`OpenDataRateLimitError`), so it is intended for occasional
+        use such as a setup flow, not for polling. Results are paginated
+        transparently. ``active_on`` filters to descriptions whose validity
+        window covers that date.
+        """
+        params: dict[str, str | int] = {"limit": _DESCRIPTIONS_PAGE_SIZE}
+        if active_on is not None:
+            day = active_on.isoformat()
+            params["where"] = f"debut<='{day}' AND fin>='{day}'"
+
+        descriptions: list[OfferDescription] = []
+        offset = 0
+        while True:
+            try:
+                async with self._session.get(
+                    self._offer_descriptions_url,
+                    params={**params, "offset": offset},
+                    timeout=self._timeout,
+                ) as response:
+                    _raise_for_status(response)
+                    data = await response.json(content_type=None)
+            except OSError as err:
+                raise OpenDataConnectionError(f"Error fetching descriptions: {err}") from err
+            except aiohttp.ClientError as err:
+                raise OpenDataConnectionError(f"Error fetching descriptions: {err}") from err
+            except TimeoutError as err:
+                raise OpenDataConnectionError("Timeout fetching descriptions") from err
+
+            if not isinstance(data, dict) or not isinstance(data.get("results"), list):
+                raise OpenDataParseError("Unexpected offer descriptions payload")
+
+            results = data["results"]
+            descriptions.extend(parse_offer_description(item) for item in results)
+
+            total = data.get("total_count", 0)
+            offset += len(results)
+            if not results or offset >= total:
+                return tuple(descriptions)
+
+
+def _raise_for_status(response: aiohttp.ClientResponse) -> None:
+    if response.status == 429:
+        raise OpenDataRateLimitError("Rate limited by the open data endpoint")
+    if response.status != 200:
+        raise OpenDataResponseError(response.status)

hydropeak_opendata-0.1.0/src/hydropeak_opendata/exceptions.py

@@ -0,0 +1,27 @@
+"""Exceptions raised by the hydropeak-opendata client."""
+
+from __future__ import annotations
+
+
+class OpenDataError(Exception):
+    """Base exception for all hydropeak-opendata errors."""
+
+
+class OpenDataConnectionError(OpenDataError):
+    """Communicating with the open data endpoint failed (network, timeout)."""
+
+
+class OpenDataRateLimitError(OpenDataError):
+    """The endpoint answered 429 Too Many Requests."""
+
+
+class OpenDataResponseError(OpenDataError):
+    """The endpoint answered with an unexpected HTTP status."""
+
+    def __init__(self, status: int, message: str | None = None) -> None:
+        super().__init__(message or f"Unexpected HTTP status {status}")
+        self.status = status
+
+
+class OpenDataParseError(OpenDataError):
+    """The endpoint answered 200 but the payload could not be parsed."""

hydropeak_opendata-0.1.0/src/hydropeak_opendata/models.py

@@ -0,0 +1,134 @@
+"""Data models for the Hydro-Québec peak events open data."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from typing import Any
+
+from .exceptions import OpenDataParseError
+
+
+@dataclass(frozen=True, slots=True)
+class PeakEvent:
+    """A single peak event from the ``evenements`` array."""
+
+    offer: str
+    start: datetime
+    end: datetime
+    period: str | None
+    sector: str | None
+
+    @property
+    def duration(self) -> timedelta:
+        """Length of the event."""
+        return self.end - self.start
+
+    def is_active(self, now: datetime) -> bool:
+        """Whether the event is in progress at ``now``."""
+        return self.start <= now <= self.end
+
+
+@dataclass(frozen=True, slots=True)
+class PeakEventsFeed:
+    """The parsed ``pointeshivernales.json`` document.
+
+    ``offers`` is the canonical list of offer identifiers exactly as
+    published in ``offresDisponibles``; no transformation is applied.
+    """
+
+    offers: tuple[str, ...]
+    events: tuple[PeakEvent, ...]
+    last_execution: datetime | None
+
+    def events_for_offer(self, offer: str) -> tuple[PeakEvent, ...]:
+        """Events whose ``offre`` value equals ``offer``, sorted by start time."""
+        return tuple(event for event in self.events if event.offer == offer)
+
+
+@dataclass(frozen=True, slots=True)
+class OfferDescription:
+    """A record from the ``evenements-de-pointe-offres-disponibles`` dataset."""
+
+    offer: str
+    client_type: str | None
+    description_fr: str | None
+    doc_url_fr: str | None
+    doc_url_en: str | None
+    start: date | None
+    end: date | None
+
+
+def _parse_event(item: dict[str, Any]) -> PeakEvent:
+    try:
+        return PeakEvent(
+            offer=item["offre"],
+            start=datetime.fromisoformat(item["dateDebut"]),
+            end=datetime.fromisoformat(item["dateFin"]),
+            period=item.get("plageHoraire"),
+            sector=item.get("secteurClient"),
+        )
+    except (KeyError, TypeError, ValueError) as err:
+        raise OpenDataParseError(f"Malformed event entry: {item!r}") from err
+
+
+def parse_feed(data: Any) -> PeakEventsFeed:
+    """Parse the raw JSON document into a :class:`PeakEventsFeed`.
+
+    Raises :class:`OpenDataParseError` if required structure is missing.
+    """
+    if not isinstance(data, dict):
+        raise OpenDataParseError(f"Expected a JSON object, got {type(data).__name__}")
+
+    try:
+        raw_offers = data["offresDisponibles"]
+        raw_events = data["evenements"]
+    except KeyError as err:
+        raise OpenDataParseError(f"Missing key in feed: {err}") from err
+
+    if not isinstance(raw_offers, list) or not isinstance(raw_events, list):
+        raise OpenDataParseError("offresDisponibles and evenements must be arrays")
+
+    # "derniereExecution" is a single-element array of a naive local
+    # timestamp ("2026-08-15 19:21:22"); its timezone is unspecified upstream.
+    last_execution: datetime | None = None
+    raw_last = data.get("derniereExecution")
+    if isinstance(raw_last, list) and raw_last:
+        try:
+            last_execution = datetime.fromisoformat(raw_last[0])
+        except (TypeError, ValueError):
+            last_execution = None
+
+    events = sorted((_parse_event(item) for item in raw_events), key=lambda e: e.start)
+    return PeakEventsFeed(
+        offers=tuple(str(raw) for raw in raw_offers),
+        events=tuple(events),
+        last_execution=last_execution,
+    )
+
+
+def _parse_date(value: Any) -> date | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        return date.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+def parse_offer_description(item: dict[str, Any]) -> OfferDescription:
+    """Parse one record from the offer descriptions dataset."""
+    try:
+        offer = item["offresdisponibles"]
+    except KeyError as err:
+        raise OpenDataParseError(f"Malformed offer description: {item!r}") from err
+
+    return OfferDescription(
+        offer=offer,
+        client_type=item.get("type_clientele"),
+        description_fr=item.get("description_fr"),
+        doc_url_fr=item.get("doc_fr"),
+        doc_url_en=item.get("doc_eng"),
+        start=_parse_date(item.get("debut")),
+        end=_parse_date(item.get("fin")),
+    )

hydropeak_opendata-0.1.0/tests/conftest.py

@@ -0,0 +1,27 @@
+"""Shared test fixtures."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def load_fixture(name: str) -> Any:
+    return json.loads((FIXTURES / name).read_text(encoding="utf-8"))
+
+
+@pytest.fixture
+def summer_feed() -> Any:
+    """The real feed as served in August 2026 (business-only events)."""
+    return load_fixture("feed_summer_2026.json")
+
+
+@pytest.fixture
+def winter_feed() -> Any:
+    """A winter-shaped feed with residential (CPC-D / TPC-DPC) events."""
+    return load_fixture("feed_winter.json")

hydropeak_opendata-0.1.0/tests/fixtures/feed_summer_2026.json

@@ -0,0 +1,103 @@
+{
+    "offresDisponibles": [
+        "Chaine de bloc",
+        "OEA",
+        "OEA Serres",
+        "ENG_100H_2F_7J",
+        "ENG_100H_2F_5J",
+        "ENG_100H_1F_7J",
+        "ENG_100H_1F_5J",
+        "ENG_80H_2F_7J",
+        "ENG_80H_2F_5J",
+        "ENG_80H_1F_7J",
+        "ENG_80H_1F_5J",
+        "ENG_60H_2F_7J",
+        "ENG_60H_2F_5J",
+        "ENG_60H_1F_7J",
+        "ENG_60H_1F_5J",
+        "ENG_40H_2F_7J",
+        "ENG_40H_2F_5J",
+        "ENG_40H_1F_7J",
+        "ENG_40H_1F_5J",
+        "ENG_20H_2F_7J",
+        "ENG_20H_2F_5J",
+        "ENG_20H_1F_7J",
+        "ENG_20H_1F_5J",
+        "LAT_100H_5J",
+        "LAT_100H_7J",
+        "LAT_Signal_FDS",
+        "LAT_20H_5J",
+        "LAT_20H_7J",
+        "LAT_40H_5J",
+        "LAT_40H_7J",
+        "LAT_60H_5J",
+        "LAT_60H_7J",
+        "LAT_80H_5J",
+        "LAT_80H_7J",
+        "Credit hivernal Residentiel (CPC-D)",
+        "Credit hivernal Affaires (CPC-G)",
+        "Flex Residentiel (TPC-DPC)",
+        "Flex Affaires (TPC-GPC)"
+    ],
+    "derniereExecution": [
+        "2026-08-15 19:21:22"
+    ],
+    "evenements": [
+        {
+            "offre": "OEA",
+            "dateDebut": "2026-06-11T16:00:00-04:00",
+            "dateFin": "2026-06-11T19:00:00-04:00",
+            "plageHoraire": "PM",
+            "duree": "PT03H00MS",
+            "secteurClient": "Affaires"
+        },
+        {
+            "offre": "Chaine de bloc",
+            "dateDebut": "2026-06-11T16:00:00-04:00",
+            "dateFin": "2026-06-11T19:00:00-04:00",
+            "plageHoraire": "PM",
+            "duree": "PT03H00MS",
+            "secteurClient": "Affaires"
+        },
+        {
+            "offre": "OEA",
+            "dateDebut": "2026-06-12T17:00:00-04:00",
+            "dateFin": "2026-06-12T19:00:00-04:00",
+            "plageHoraire": "PM",
+            "duree": "PT02H00MS",
+            "secteurClient": "Affaires"
+        },
+        {
+            "offre": "Chaine de bloc",
+            "dateDebut": "2026-06-12T17:00:00-04:00",
+            "dateFin": "2026-06-12T19:00:00-04:00",
+            "plageHoraire": "PM",
+            "duree": "PT02H00MS",
+            "secteurClient": "Affaires"
+        },
+        {
+            "offre": "Chaine de bloc",
+            "dateDebut": "2026-07-02T13:00:00-04:00",
+            "dateFin": "2026-07-02T20:00:00-04:00",
+            "plageHoraire": "PM",
+            "duree": "PT07H00MS",
+            "secteurClient": "Affaires"
+        },
+        {
+            "offre": "OEA",
+            "dateDebut": "2026-07-02T13:00:00-04:00",
+            "dateFin": "2026-07-02T20:00:00-04:00",
+            "plageHoraire": "PM",
+            "duree": "PT07H00MS",
+            "secteurClient": "Affaires"
+        },
+        {
+            "offre": "Chaine de bloc",
+            "dateDebut": "2026-08-06T13:00:00-04:00",
+            "dateFin": "2026-08-06T19:00:00-04:00",
+            "plageHoraire": "PM",
+            "duree": "PT06H00MS",
+            "secteurClient": "Affaires"
+        }
+    ]
+}

hydropeak_opendata-0.1.0/tests/fixtures/feed_winter.json

@@ -0,0 +1,47 @@
+{
+    "offresDisponibles": [
+        "Credit hivernal Residentiel (CPC-D)",
+        "Credit hivernal Affaires (CPC-G)",
+        "Flex Residentiel (TPC-DPC)",
+        "Flex Affaires (TPC-GPC)",
+        "OEA",
+        "Chaine de bloc"
+    ],
+    "derniereExecution": [
+        "2026-01-09 05:31:10"
+    ],
+    "evenements": [
+        {
+            "offre": "Credit hivernal Residentiel (CPC-D)",
+            "dateDebut": "2026-01-09T06:00:00-05:00",
+            "dateFin": "2026-01-09T09:00:00-05:00",
+            "plageHoraire": "AM",
+            "duree": "PT03H00MS",
+            "secteurClient": "Residentiel"
+        },
+        {
+            "offre": "Flex Residentiel (TPC-DPC)",
+            "dateDebut": "2026-01-09T16:00:00-05:00",
+            "dateFin": "2026-01-09T20:00:00-05:00",
+            "plageHoraire": "PM",
+            "duree": "PT04H00MS",
+            "secteurClient": "Residentiel"
+        },
+        {
+            "offre": "Credit hivernal Residentiel (CPC-D)",
+            "dateDebut": "2026-01-09T16:00:00-05:00",
+            "dateFin": "2026-01-09T20:00:00-05:00",
+            "plageHoraire": "PM",
+            "duree": "PT04H00MS",
+            "secteurClient": "Residentiel"
+        },
+        {
+            "offre": "Credit hivernal Residentiel (CPC-D)",
+            "dateDebut": "2026-01-10T06:00:00-05:00",
+            "dateFin": "2026-01-10T09:00:00-05:00",
+            "plageHoraire": "AM",
+            "duree": "PT03H00MS",
+            "secteurClient": "Residentiel"
+        }
+    ]
+}

hydropeak_opendata-0.1.0/tests/test_client.py

@@ -0,0 +1,178 @@
+"""Tests for the HTTP client, against a local aiohttp test server."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import pytest
+from aiohttp import web
+
+from hydropeak_opendata import (
+    OpenDataClient,
+    OpenDataConnectionError,
+    OpenDataParseError,
+    OpenDataRateLimitError,
+    OpenDataResponseError,
+)
+
+
+class FakeOpenData:
+    """Scriptable stand-in for the two Hydro-Québec endpoints."""
+
+    def __init__(self):
+        self.feed_responses = []  # queue of callables returning web.Response
+        self.feed_requests = []  # recorded feed request headers
+        self.desc_pages = []  # payloads keyed by offset // 100
+        self.desc_status = 200
+        self.server = None
+
+    async def handle_feed(self, request):
+        self.feed_requests.append(dict(request.headers))
+        return self.feed_responses.pop(0)(request)
+
+    async def handle_descriptions(self, request):
+        if self.desc_status != 200:
+            return web.Response(status=self.desc_status)
+        offset = int(request.query.get("offset", 0))
+        return web.json_response(self.desc_pages[offset // 100])
+
+
+def json_ok(payload, etag='"v1"'):
+    """The endpoint mislabels its JSON as text/plain; the fake does too."""
+    return lambda request: web.Response(
+        text=json.dumps(payload), content_type="text/plain", headers={"ETag": etag}
+    )
+
+
+def status(code):
+    return lambda request: web.Response(status=code)
+
+
+def body(text):
+    return lambda request: web.Response(text=text, content_type="text/plain")
+
+
+@pytest.fixture
+async def fake(aiohttp_server):
+    fake = FakeOpenData()
+    app = web.Application()
+    app.router.add_get("/feed", fake.handle_feed)
+    app.router.add_get("/descriptions", fake.handle_descriptions)
+    fake.server = await aiohttp_server(app)
+    return fake
+
+
+@pytest.fixture
+async def client(fake, aiohttp_client):
+    session = await aiohttp_client(fake.server)
+    return OpenDataClient(
+        session.session,
+        peak_events_url=str(fake.server.make_url("/feed")),
+        offer_descriptions_url=str(fake.server.make_url("/descriptions")),
+    )
+
+
+async def test_get_feed_parses_mislabeled_json(client, fake, winter_feed):
+    fake.feed_responses = [json_ok(winter_feed)]
+    feed = await client.get_feed()
+
+    assert feed.offers[0] == "Credit hivernal Residentiel (CPC-D)"
+    assert len(feed.events) == 4
+
+
+async def test_get_feed_revalidates_with_etag(client, fake, winter_feed):
+    fake.feed_responses = [json_ok(winter_feed, etag='"v1"'), status(304)]
+
+    first = await client.get_feed()
+    second = await client.get_feed()
+
+    assert fake.feed_requests[0].get("If-None-Match") is None
+    assert fake.feed_requests[1].get("If-None-Match") == '"v1"'
+    assert second is first  # cached object served on 304
+
+
+async def test_get_feed_304_without_cache_is_an_error(client, fake):
+    fake.feed_responses = [status(304)]
+    with pytest.raises(OpenDataResponseError) as excinfo:
+        await client.get_feed()
+    assert excinfo.value.status == 304
+
+
+async def test_get_feed_error_statuses(client, fake):
+    fake.feed_responses = [status(429)]
+    with pytest.raises(OpenDataRateLimitError):
+        await client.get_feed()
+
+    fake.feed_responses = [status(503)]
+    with pytest.raises(OpenDataResponseError) as excinfo:
+        await client.get_feed()
+    assert excinfo.value.status == 503
+
+
+async def test_get_feed_invalid_json(client, fake):
+    fake.feed_responses = [body("<html>maintenance</html>")]
+    with pytest.raises(OpenDataParseError):
+        await client.get_feed()
+
+
+async def test_get_feed_network_error(fake, aiohttp_client):
+    session = await aiohttp_client(fake.server)
+    unreachable = OpenDataClient(
+        session.session, peak_events_url="http://127.0.0.1:1/feed", request_timeout=2
+    )
+    with pytest.raises(OpenDataConnectionError):
+        await unreachable.get_feed()
+
+
+async def test_failed_refresh_does_not_clobber_cache(client, fake, winter_feed):
+    fake.feed_responses = [json_ok(winter_feed), status(503), status(304)]
+
+    first = await client.get_feed()
+    with pytest.raises(OpenDataResponseError):
+        await client.get_feed()
+    third = await client.get_feed()
+
+    assert third is first
+
+
+async def test_concurrent_callers_are_serialized(client, fake, winter_feed):
+    fake.feed_responses = [json_ok(winter_feed, etag='"v1"'), status(304)]
+
+    first, second = await asyncio.gather(client.get_feed(), client.get_feed())
+
+    assert first is second
+    assert fake.feed_requests[1].get("If-None-Match") == '"v1"'
+
+
+async def test_get_events_and_offers(client, fake, winter_feed):
+    fake.feed_responses = [json_ok(winter_feed), status(304), status(304)]
+
+    offers = await client.get_available_offers()
+    all_events = await client.get_events()
+    cpc_events = await client.get_events("Credit hivernal Residentiel (CPC-D)")
+
+    assert "Flex Residentiel (TPC-DPC)" in offers
+    assert len(all_events) == 4
+    assert len(cpc_events) == 3
+
+
+async def test_get_offer_descriptions_paginates(client, fake):
+    def make_record(index):
+        return {"offresdisponibles": f"OFFER_{index}", "description_fr": f"desc {index}"}
+
+    fake.desc_pages = [
+        {"total_count": 150, "results": [make_record(i) for i in range(100)]},
+        {"total_count": 150, "results": [make_record(i) for i in range(100, 150)]},
+    ]
+    descriptions = await client.get_offer_descriptions()
+
+    assert len(descriptions) == 150
+    assert descriptions[0].offer == "OFFER_0"
+    assert descriptions[-1].offer == "OFFER_149"
+
+
+async def test_get_offer_descriptions_rate_limited(client, fake):
+    fake.desc_status = 429
+    with pytest.raises(OpenDataRateLimitError):
+        await client.get_offer_descriptions()

hydropeak_opendata-0.1.0/tests/test_models.py

@@ -0,0 +1,101 @@
+"""Tests for feed parsing and models."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from hydropeak_opendata import OpenDataParseError, parse_feed
+from hydropeak_opendata.models import parse_offer_description
+
+EST = timezone(timedelta(hours=-5))
+
+
+def test_parse_summer_feed(summer_feed):
+    feed = parse_feed(summer_feed)
+
+    assert "Credit hivernal Residentiel (CPC-D)" in feed.offers
+    assert "OEA" in feed.offers
+    assert len(feed.offers) == 38
+
+    assert len(feed.events) == 7
+    # sorted by start
+    starts = [event.start for event in feed.events]
+    assert starts == sorted(starts)
+    # datetimes are timezone-aware
+    assert all(event.start.tzinfo is not None for event in feed.events)
+
+    assert feed.last_execution == datetime(2026, 8, 15, 19, 21, 22)
+
+
+def test_offers_are_verbatim(winter_feed):
+    feed = parse_feed(winter_feed)
+    assert feed.offers[0] == "Credit hivernal Residentiel (CPC-D)"
+
+
+def test_events_for_offer_exact_match(winter_feed):
+    feed = parse_feed(winter_feed)
+
+    events = feed.events_for_offer("Credit hivernal Residentiel (CPC-D)")
+    assert len(events) == 3
+    assert all(event.offer == "Credit hivernal Residentiel (CPC-D)" for event in events)
+
+    assert feed.events_for_offer("Flex Residentiel (TPC-DPC)") != ()
+    assert feed.events_for_offer("nonexistent") == ()
+
+
+def test_event_fields(winter_feed):
+    feed = parse_feed(winter_feed)
+    event = feed.events[0]
+
+    assert event.start == datetime(2026, 1, 9, 6, 0, tzinfo=EST)
+    assert event.end == datetime(2026, 1, 9, 9, 0, tzinfo=EST)
+    assert event.period == "AM"
+    assert event.sector == "Residentiel"
+    assert event.duration == timedelta(hours=3)
+
+
+def test_event_is_active(winter_feed):
+    feed = parse_feed(winter_feed)
+    event = feed.events[0]
+
+    assert event.is_active(datetime(2026, 1, 9, 7, 0, tzinfo=EST))
+    assert not event.is_active(datetime(2026, 1, 9, 5, 59, tzinfo=EST))
+    assert not event.is_active(datetime(2026, 1, 9, 9, 1, tzinfo=EST))
+
+
+def test_parse_feed_rejects_bad_payloads():
+    with pytest.raises(OpenDataParseError):
+        parse_feed([])
+    with pytest.raises(OpenDataParseError):
+        parse_feed({"evenements": []})
+    with pytest.raises(OpenDataParseError):
+        parse_feed({"offresDisponibles": [], "evenements": "nope"})
+    with pytest.raises(OpenDataParseError):
+        parse_feed({"offresDisponibles": [], "evenements": [{"offre": "X"}]})
+
+
+def test_parse_feed_tolerates_missing_last_execution(winter_feed):
+    del winter_feed["derniereExecution"]
+    assert parse_feed(winter_feed).last_execution is None
+
+
+def test_parse_offer_description():
+    record = {
+        "offresdisponibles": "CPC-D",
+        "type_clientele": "residentiel",
+        "description_fr": "Crédit hivernal",
+        "doc_fr": "https://example.test/fr",
+        "doc_eng": "https://example.test/en",
+        "debut": "2026-12-01",
+        "fin": "2027-03-31",
+    }
+    desc = parse_offer_description(record)
+    assert desc.offer == "CPC-D"
+    assert desc.client_type == "residentiel"
+    assert desc.start.isoformat() == "2026-12-01"
+    assert desc.end.isoformat() == "2027-03-31"
+
+    with pytest.raises(OpenDataParseError):
+        parse_offer_description({"description_fr": "no offer key"})