elec-tariffs 0.1.0__py3-none-any.whl

elec_tariffs/__init__.py

@@ -0,0 +1,87 @@
+"""Cost French electricity consumption hour by hour under Base, HP/HC and Tempo."""
+
+from ._version import __version__
+from .engine import (
+    TEMPO_OFF_PEAK,
+    HourCost,
+    cost_hour,
+    fixed_cost_per_hour,
+    is_off_peak,
+    period_at,
+    price_at,
+    split_hour,
+    tempo_day,
+)
+from .errors import (
+    ElecTariffsError,
+    MissingColorError,
+    MissingPriceError,
+    TempoAuthError,
+    TempoError,
+    TempoFormatError,
+    TempoRateLimitError,
+    TempoServerError,
+    TrvError,
+    TrvFormatError,
+    TrvServerError,
+)
+from .models import (
+    TRANCHES,
+    ContractKind,
+    ContractRules,
+    DayCalendar,
+    PricePeriod,
+    TempoColor,
+    TimeRange,
+    Tranche,
+)
+from .sources import (
+    FallbackTempoSource,
+    RteOfficialTempoClient,
+    RtePublicTempoClient,
+    TempoCalendarSource,
+    TrvClient,
+    parse_trv_csv,
+    season_bounds,
+    season_of,
+)
+
+__all__ = [
+    "TEMPO_OFF_PEAK",
+    "TRANCHES",
+    "ContractKind",
+    "ContractRules",
+    "DayCalendar",
+    "ElecTariffsError",
+    "FallbackTempoSource",
+    "HourCost",
+    "MissingColorError",
+    "MissingPriceError",
+    "PricePeriod",
+    "RteOfficialTempoClient",
+    "RtePublicTempoClient",
+    "TempoAuthError",
+    "TempoCalendarSource",
+    "TempoColor",
+    "TempoError",
+    "TempoFormatError",
+    "TempoRateLimitError",
+    "TempoServerError",
+    "TimeRange",
+    "Tranche",
+    "TrvClient",
+    "TrvError",
+    "TrvFormatError",
+    "TrvServerError",
+    "__version__",
+    "cost_hour",
+    "fixed_cost_per_hour",
+    "is_off_peak",
+    "parse_trv_csv",
+    "period_at",
+    "price_at",
+    "season_bounds",
+    "season_of",
+    "split_hour",
+    "tempo_day",
+]

elec_tariffs/_version.py

@@ -0,0 +1,3 @@
+"""Version of the package, read by the build backend."""
+
+__version__ = "0.1.0"

elec_tariffs/engine.py

@@ -0,0 +1,140 @@
+"""Split an hour of consumption into tranches and cost it.
+
+An hourly statistic row starts at the top of an hour. Every hour is costed as two
+half hours with half the energy each: that is the finest boundary of an off-peak
+range, and it assumes the consumption is even within the hour.
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import date, datetime, time, timedelta
+from typing import Final
+
+from .errors import MissingColorError, MissingPriceError
+from .models import (
+    ContractKind,
+    ContractRules,
+    DayCalendar,
+    PricePeriod,
+    TempoColor,
+    TimeRange,
+    Tranche,
+)
+
+TEMPO_DAY_START: Final = time(6)
+TEMPO_OFF_PEAK: Final = (TimeRange(start=time(22), end=time(6)),)
+
+_TEMPO_TRANCHES: Final = {
+    (TempoColor.BLUE, True): Tranche.BLUE_HC,
+    (TempoColor.BLUE, False): Tranche.BLUE_HP,
+    (TempoColor.WHITE, True): Tranche.WHITE_HC,
+    (TempoColor.WHITE, False): Tranche.WHITE_HP,
+    (TempoColor.RED, True): Tranche.RED_HC,
+    (TempoColor.RED, False): Tranche.RED_HP,
+}
+_SATURDAY: Final = 5
+
+
+def tempo_day(local: datetime) -> date:
+    """Return the Tempo day that `local` belongs to: they run from 6:00 to 6:00."""
+    wall = local.replace(tzinfo=None) - timedelta(hours=TEMPO_DAY_START.hour)
+    return wall.date()
+
+
+def is_off_peak(value: time, ranges: Sequence[TimeRange]) -> bool:
+    """Tell whether a time of day falls in one of the off-peak ranges."""
+    return any(time_range.contains(value) for time_range in ranges)
+
+
+def _tranche(local: datetime, rules: ContractRules, calendar: DayCalendar) -> Tranche:
+    """Return the tranche of the half hour starting at `local`."""
+    if rules.kind is ContractKind.BASE:
+        return Tranche.BASE
+    if rules.kind is ContractKind.HPHC:
+        weekend = rules.weekend_off_peak and local.weekday() >= _SATURDAY
+        if weekend or is_off_peak(local.time(), rules.off_peak):
+            return Tranche.HC
+        return Tranche.HP
+    day = tempo_day(local)
+    color = calendar.get(day)
+    if color is None:
+        raise MissingColorError(day)
+    return _TEMPO_TRANCHES[color, is_off_peak(local.time(), TEMPO_OFF_PEAK)]
+
+
+def split_hour(
+    start: datetime, kwh: float, rules: ContractRules, calendar: DayCalendar
+) -> dict[Tranche, float]:
+    """Split the energy of the hour starting at `start` (local, aware) into tranches.
+
+    Raise MissingColorError when a Tempo contract needs a color that is not known.
+    """
+    if start.minute or start.second or start.microsecond:
+        msg = f"{start.isoformat()} is not the start of an hour"
+        raise ValueError(msg)
+    split: dict[Tranche, float] = {}
+    for half in (start, start.replace(minute=30)):
+        tranche = _tranche(half, rules, calendar)
+        split[tranche] = split.get(tranche, 0.0) + kwh / 2
+    return split
+
+
+def period_at(periods: Sequence[PricePeriod], day: date) -> PricePeriod:
+    """Return the price period in force on `day`, or raise MissingPriceError."""
+    for period in periods:
+        if period.covers(day):
+            return period
+    raise MissingPriceError(day)
+
+
+def price_at(periods: Sequence[PricePeriod], day: date, tranche: Tranche) -> float:
+    """Return the price of a tranche on `day`, or raise MissingPriceError."""
+    period = period_at(periods, day)
+    if tranche not in period.prices:
+        raise MissingPriceError(day)
+    return period.prices[tranche]
+
+
+def fixed_cost_per_hour(period: PricePeriod, start: datetime) -> float:
+    """Spread the yearly fixed part evenly over the hours of the year of `start`."""
+    year = start.year
+    days = (date(year + 1, 1, 1) - date(year, 1, 1)).days
+    return period.fixed_per_year / days / 24
+
+
+@dataclass(frozen=True, kw_only=True)
+class HourCost:
+    """Energy (kWh) and variable cost per tranche of one hour, and its fixed cost."""
+
+    energy: dict[Tranche, float]
+    variable: dict[Tranche, float]
+    fixed: float
+
+    @property
+    def total(self) -> float:
+        """Variable and fixed cost together."""
+        return sum(self.variable.values()) + self.fixed
+
+
+def cost_hour(
+    start: datetime,
+    kwh: float,
+    rules: ContractRules,
+    periods: Sequence[PricePeriod],
+    calendar: DayCalendar,
+) -> HourCost:
+    """Cost the hour starting at `start` (local, aware).
+
+    Prices change at midnight local time, so the whole hour uses the prices of its
+    day. Raise MissingColorError or MissingPriceError when data is missing.
+    """
+    energy = split_hour(start, kwh, rules, calendar)
+    period = period_at(periods, start.date())
+    variable: dict[Tranche, float] = {}
+    for tranche, tranche_kwh in energy.items():
+        if tranche not in period.prices:
+            raise MissingPriceError(start.date())
+        variable[tranche] = tranche_kwh * period.prices[tranche]
+    return HourCost(
+        energy=energy, variable=variable, fixed=fixed_cost_per_hour(period, start)
+    )

elec_tariffs/errors.py

@@ -0,0 +1,57 @@
+"""Exceptions raised by elec-tariffs."""
+
+from datetime import date
+
+
+class ElecTariffsError(Exception):
+    """Base class of every error raised by this library."""
+
+
+class MissingColorError(ElecTariffsError):
+    """The Tempo color of a day is not known yet."""
+
+    def __init__(self, day: date) -> None:
+        """Keep the day whose color is missing."""
+        super().__init__(f"No Tempo color for {day.isoformat()}")
+        self.day = day
+
+
+class MissingPriceError(ElecTariffsError):
+    """No price period covers a day."""
+
+    def __init__(self, day: date) -> None:
+        """Keep the day that no price period covers."""
+        super().__init__(f"No price period covers {day.isoformat()}")
+        self.day = day
+
+
+class TrvError(ElecTariffsError):
+    """The regulated prices could not be read."""
+
+
+class TrvServerError(TrvError):
+    """data.gouv.fr could not be reached or answered with an error."""
+
+
+class TrvFormatError(TrvError):
+    """A regulated price file does not have the expected columns or values."""
+
+
+class TempoError(ElecTariffsError):
+    """The Tempo calendar could not be read."""
+
+
+class TempoServerError(TempoError):
+    """The calendar source could not be reached or answered with a server error."""
+
+
+class TempoRateLimitError(TempoError):
+    """The calendar source asks to slow down (HTTP 429)."""
+
+
+class TempoAuthError(TempoError):
+    """The RTE API refused the client credentials."""
+
+
+class TempoFormatError(TempoError):
+    """The calendar source answered with data in an unexpected format."""

elec_tariffs/models.py

@@ -0,0 +1,104 @@
+"""Contracts, tranches and prices."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import date, time
+from enum import StrEnum
+
+
+class ContractKind(StrEnum):
+    """How a contract splits consumption into tranches."""
+
+    BASE = "base"
+    HPHC = "hphc"
+    TEMPO = "tempo"
+
+
+class TempoColor(StrEnum):
+    """Color of a Tempo day."""
+
+    BLUE = "blue"
+    WHITE = "white"
+    RED = "red"
+
+
+class Tranche(StrEnum):
+    """A part of the consumption billed at one price."""
+
+    BASE = "base"
+    HC = "hc"
+    HP = "hp"
+    BLUE_HC = "blue_hc"
+    BLUE_HP = "blue_hp"
+    WHITE_HC = "white_hc"
+    WHITE_HP = "white_hp"
+    RED_HC = "red_hc"
+    RED_HP = "red_hp"
+
+
+TRANCHES: Mapping[ContractKind, tuple[Tranche, ...]] = {
+    ContractKind.BASE: (Tranche.BASE,),
+    ContractKind.HPHC: (Tranche.HC, Tranche.HP),
+    ContractKind.TEMPO: (
+        Tranche.BLUE_HC,
+        Tranche.BLUE_HP,
+        Tranche.WHITE_HC,
+        Tranche.WHITE_HP,
+        Tranche.RED_HC,
+        Tranche.RED_HP,
+    ),
+}
+
+DayCalendar = Mapping[date, TempoColor]
+
+
+@dataclass(frozen=True, kw_only=True)
+class TimeRange:
+    """Off-peak hours from `start` to `end`, crossing midnight when end <= start."""
+
+    start: time
+    end: time
+
+    def __post_init__(self) -> None:
+        """Only accept whole and half hours, the finest split an hourly row allows."""
+        for value in (self.start, self.end):
+            if value.minute not in (0, 30) or value.second or value.microsecond:
+                msg = f"{value.isoformat()} is not on a whole or half hour"
+                raise ValueError(msg)
+
+    def contains(self, value: time) -> bool:
+        """Tell whether `value` falls in the range (start included, end excluded)."""
+        if self.start < self.end:
+            return self.start <= value < self.end
+        return value >= self.start or value < self.end
+
+
+@dataclass(frozen=True, kw_only=True)
+class ContractRules:
+    """What decides the tranche of each half hour."""
+
+    kind: ContractKind
+    off_peak: tuple[TimeRange, ...] = ()
+    weekend_off_peak: bool = False
+
+    def __post_init__(self) -> None:
+        """Refuse options that only make sense for an HP/HC contract."""
+        if self.kind is not ContractKind.HPHC and (
+            self.off_peak or self.weekend_off_peak
+        ):
+            msg = "Off-peak ranges only apply to HP/HC contracts"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, kw_only=True)
+class PricePeriod:
+    """Prices in force from `start` to `end` (both included, `end` None if open)."""
+
+    start: date
+    end: date | None
+    fixed_per_year: float
+    prices: Mapping[Tranche, float] = field(default_factory=dict)
+
+    def covers(self, day: date) -> bool:
+        """Tell whether the period applies on `day`."""
+        return self.start <= day and (self.end is None or day <= self.end)

elec_tariffs/sources/__init__.py

@@ -0,0 +1,22 @@
+"""Where prices and Tempo colors come from."""
+
+from .tempo import (
+    FallbackTempoSource,
+    RteOfficialTempoClient,
+    RtePublicTempoClient,
+    TempoCalendarSource,
+    season_bounds,
+    season_of,
+)
+from .trv import TrvClient, parse_trv_csv
+
+__all__ = [
+    "FallbackTempoSource",
+    "RteOfficialTempoClient",
+    "RtePublicTempoClient",
+    "TempoCalendarSource",
+    "TrvClient",
+    "parse_trv_csv",
+    "season_bounds",
+    "season_of",
+]

elec_tariffs/sources/tempo.py

@@ -0,0 +1,394 @@
+"""Tempo calendar: the color of each day, from RTE.
+
+Two sources give the same data:
+
+- RTE's public Tempo page backend (`services-rte.com/cms/open_data`), without an
+  account. It is not documented and may change without notice, so its answers are
+  checked strictly.
+- RTE's official "Tempo Like Supply Contract" API, which needs the client ID and
+  secret of an application created on data.rte-france.com.
+"""
+
+import base64
+import time as monotonic_time
+from collections.abc import Callable, Sequence
+from datetime import date, datetime, time, timedelta
+from typing import Any, Final, Protocol
+from zoneinfo import ZoneInfo
+
+import aiohttp
+
+from elec_tariffs._version import __version__
+from elec_tariffs.errors import (
+    TempoAuthError,
+    TempoError,
+    TempoFormatError,
+    TempoRateLimitError,
+    TempoServerError,
+)
+from elec_tariffs.models import TempoColor
+
+PUBLIC_BASE_URL: Final = "https://www.services-rte.com/cms/open_data/v1"
+OFFICIAL_BASE_URL: Final = "https://digital.iservices.rte-france.com"
+TOKEN_PATH: Final = "/token/oauth/"  # noqa: S105 - a path, not a password
+CALENDAR_PATH: Final = "/open_api/tempo_like_supply_contract/v1/tempo_like_calendars"
+
+MAX_RED_DAYS: Final = 22
+MAX_WHITE_DAYS: Final = 43
+FIRST_SEASON: Final = "2014-2015"
+OFFICIAL_MAX_DAYS: Final = 366
+
+PARIS: Final = ZoneInfo("Europe/Paris")
+USER_AGENT: Final = (
+    f"elec-tariffs/{__version__} (+https://github.com/damou8/elec-tariffs)"
+)
+
+_SEASON_START_MONTH: Final = 9
+_TIMEOUT: Final = aiohttp.ClientTimeout(total=30)
+_TOKEN_MARGIN: Final = 60
+_DEFAULT_TOKEN_LIFETIME: Final = 3600
+_COLORS: Final = {
+    "BLUE": TempoColor.BLUE,
+    "WHITE": TempoColor.WHITE,
+    "RED": TempoColor.RED,
+}
+_HTTP_OK: Final = 200
+_HTTP_UNAUTHORIZED: Final = 401
+_HTTP_FORBIDDEN: Final = 403
+_HTTP_TOO_MANY_REQUESTS: Final = 429
+_HTTP_SERVER_ERROR: Final = 500
+
+type Calendar = dict[date, TempoColor]
+
+
+def season_of(day: date) -> str:
+    """Return the Tempo season of a day, like "2025-2026" (September to August)."""
+    first = day.year if day.month >= _SEASON_START_MONTH else day.year - 1
+    return f"{first}-{first + 1}"
+
+
+def season_bounds(season: str) -> tuple[date, date]:
+    """Return the first and last day of a season named like "2025-2026"."""
+    first = int(season.split("-", 1)[0])
+    return date(first, _SEASON_START_MONTH, 1), date(first + 1, 8, 31)
+
+
+def _seasons(start: date, end: date) -> list[str]:
+    first = int(season_of(start).split("-", 1)[0])
+    last = int(season_of(end).split("-", 1)[0])
+    return [f"{year}-{year + 1}" for year in range(first, last + 1)]
+
+
+def _color(value: Any) -> TempoColor:
+    color = _COLORS.get(value) if isinstance(value, str) else None
+    if color is None:
+        msg = f"Unknown Tempo color {value!r}"
+        raise TempoFormatError(msg)
+    return color
+
+
+def parse_public_values(payload: Any) -> Calendar:
+    """Read a `{"values": {"YYYY-MM-DD": "BLUE", ...}}` answer of the public source."""
+    values = payload.get("values") if isinstance(payload, dict) else None
+    if not isinstance(values, dict):
+        msg = "The answer has no 'values' object"
+        raise TempoFormatError(msg)
+    calendar: Calendar = {}
+    for key, value in values.items():
+        if key.endswith("-fallback"):
+            continue
+        try:
+            day = date.fromisoformat(key)
+        except ValueError as err:
+            msg = f"Unexpected key {key!r}"
+            raise TempoFormatError(msg) from err
+        calendar[day] = _color(value)
+    return calendar
+
+
+def check_season(calendar: Calendar, season: str) -> None:
+    """Refuse a season with days outside it or more red or white days than allowed."""
+    first, last = season_bounds(season)
+    if any(not first <= day <= last for day in calendar):
+        msg = f"Days outside the {season} season"
+        raise TempoFormatError(msg)
+    colors = list(calendar.values())
+    if (
+        colors.count(TempoColor.RED) > MAX_RED_DAYS
+        or colors.count(TempoColor.WHITE) > MAX_WHITE_DAYS
+    ):
+        msg = f"Too many red or white days in the {season} season"
+        raise TempoFormatError(msg)
+
+
+def _raise_for_status(status: int) -> None:
+    if status == _HTTP_OK:
+        return
+    if status in (_HTTP_UNAUTHORIZED, _HTTP_FORBIDDEN):
+        msg = f"Access refused (HTTP {status})"
+        raise TempoAuthError(msg)
+    if status == _HTTP_TOO_MANY_REQUESTS:
+        msg = "Too many requests (HTTP 429)"
+        raise TempoRateLimitError(msg)
+    if status >= _HTTP_SERVER_ERROR:
+        msg = f"Server error (HTTP {status})"
+        raise TempoServerError(msg)
+    msg = f"Unexpected answer (HTTP {status})"
+    raise TempoFormatError(msg)
+
+
+class TempoCalendarSource(Protocol):
+    """Something that gives the Tempo color of days."""
+
+    @property
+    def name(self) -> str:
+        """Short, stable name of the source, used in logs and diagnostics."""
+        ...
+
+    async def async_calendar(self, start: date, end: date) -> Calendar:
+        """Return the known colors from `start` to `end`, both included.
+
+        Days not published yet are missing from the result.
+        """
+        ...
+
+
+class RtePublicTempoClient:
+    """RTE's public Tempo page backend, no account needed."""
+
+    def __init__(
+        self, session: aiohttp.ClientSession, *, base_url: str = PUBLIC_BASE_URL
+    ) -> None:
+        """Use the caller's HTTP session; `base_url` replaces RTE's address."""
+        self._session = session
+        self._base_url = base_url.rstrip("/")
+
+    @property
+    def name(self) -> str:
+        """Name of the source."""
+        return "rte_public"
+
+    async def _get(self, path: str, params: dict[str, str] | None = None) -> Any:
+        headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+        try:
+            async with self._session.get(
+                f"{self._base_url}/{path}",
+                params=params,
+                headers=headers,
+                timeout=_TIMEOUT,
+            ) as response:
+                _raise_for_status(response.status)
+                return await response.json(content_type=None)
+        except TempoAuthError as err:
+            msg = f"The public Tempo source refused the request: {err}"
+            raise TempoFormatError(msg) from err
+        except ValueError as err:
+            msg = "The public Tempo source did not answer with JSON"
+            raise TempoFormatError(msg) from err
+        except (aiohttp.ClientError, TimeoutError) as err:
+            msg = f"Could not reach the public Tempo source: {err}"
+            raise TempoServerError(msg) from err
+
+    async def async_season(self, season: str) -> Calendar:
+        """Return the colors of a season published so far."""
+        calendar = parse_public_values(await self._get("tempo", {"season": season}))
+        check_season(calendar, season)
+        return calendar
+
+    async def async_today_tomorrow(self) -> Calendar:
+        """Return today's color and tomorrow's once published."""
+        return parse_public_values(await self._get("tempoLight"))
+
+    async def async_calendar(self, start: date, end: date) -> Calendar:
+        """Return the known colors from `start` to `end`, both included."""
+        if (end - start).days <= 1:
+            light = await self.async_today_tomorrow()
+            if start in light and end in light:
+                return {
+                    day: color for day, color in light.items() if start <= day <= end
+                }
+        calendar: Calendar = {}
+        for season in _seasons(start, end):
+            calendar.update(await self.async_season(season))
+        return {day: color for day, color in calendar.items() if start <= day <= end}
+
+
+class RteOfficialTempoClient:
+    """RTE's official Tempo Like Supply Contract API (OAuth2 client credentials)."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        client_id: str,
+        client_secret: str,
+        *,
+        base_url: str = OFFICIAL_BASE_URL,
+        clock: Callable[[], float] = monotonic_time.monotonic,
+    ) -> None:
+        """Use the caller's HTTP session and the application's credentials.
+
+        `base_url` replaces RTE's address and `clock` the monotonic clock that
+        tells when the token expires.
+        """
+        self._session = session
+        self._base_url = base_url.rstrip("/")
+        credentials = f"{client_id}:{client_secret}".encode()
+        self._basic_auth = f"Basic {base64.b64encode(credentials).decode('ascii')}"
+        self._clock = clock
+        self._token: str | None = None
+        self._expires_at = 0.0
+
+    @property
+    def name(self) -> str:
+        """Name of the source."""
+        return "rte_official"
+
+    async def _async_token(self, *, refresh: bool = False) -> str:
+        if self._token and not refresh and self._clock() < self._expires_at:
+            return self._token
+        try:
+            async with self._session.post(
+                f"{self._base_url}{TOKEN_PATH}",
+                data={"grant_type": "client_credentials"},
+                headers={"Authorization": self._basic_auth, "User-Agent": USER_AGENT},
+                timeout=_TIMEOUT,
+            ) as response:
+                if response.status == 400:  # noqa: PLR2004 - OAuth answers 400 for a bad client
+                    msg = "RTE refused the client credentials (HTTP 400)"
+                    raise TempoAuthError(msg)
+                _raise_for_status(response.status)
+                payload = await response.json(content_type=None)
+        except ValueError as err:
+            msg = "The RTE token endpoint did not answer with JSON"
+            raise TempoFormatError(msg) from err
+        except (aiohttp.ClientError, TimeoutError) as err:
+            msg = f"Could not reach RTE: {err}"
+            raise TempoServerError(msg) from err
+        token = payload.get("access_token") if isinstance(payload, dict) else None
+        if not isinstance(token, str) or not token:
+            msg = "The RTE token answer has no access_token"
+            raise TempoFormatError(msg)
+        lifetime = payload.get("expires_in", _DEFAULT_TOKEN_LIFETIME)
+        if not isinstance(lifetime, int):
+            lifetime = _DEFAULT_TOKEN_LIFETIME
+        self._token = token
+        self._expires_at = self._clock() + max(lifetime - _TOKEN_MARGIN, 0)
+        return token
+
+    async def async_check_credentials(self) -> None:
+        """Get a token, raising TempoAuthError if RTE refuses the credentials."""
+        await self._async_token(refresh=True)
+
+    async def _async_get_calendar(
+        self, params: dict[str, str], *, refresh: bool
+    ) -> tuple[int, Any]:
+        """Return the status and, when it is 200, the JSON answer."""
+        token = await self._async_token(refresh=refresh)
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        try:
+            async with self._session.get(
+                f"{self._base_url}{CALENDAR_PATH}",
+                params=params,
+                headers=headers,
+                timeout=_TIMEOUT,
+            ) as response:
+                if response.status != _HTTP_OK:
+                    return response.status, None
+                return response.status, await response.json(content_type=None)
+        except ValueError as err:
+            msg = "The RTE calendar did not answer with JSON"
+            raise TempoFormatError(msg) from err
+        except (aiohttp.ClientError, TimeoutError) as err:
+            msg = f"Could not reach RTE: {err}"
+            raise TempoServerError(msg) from err
+
+    async def _async_chunk(self, start: date, end: date) -> Calendar:
+        params = {
+            "start_date": datetime.combine(start, time(), PARIS).isoformat(),
+            "end_date": datetime.combine(
+                end + timedelta(days=1), time(), PARIS
+            ).isoformat(),
+        }
+        status, payload = await self._async_get_calendar(params, refresh=False)
+        if status == _HTTP_UNAUTHORIZED:
+            # The token may have been revoked before it expired: get a new one once.
+            status, payload = await self._async_get_calendar(params, refresh=True)
+        _raise_for_status(status)
+        return parse_official_values(payload)
+
+    async def async_calendar(self, start: date, end: date) -> Calendar:
+        """Return the known colors from `start` to `end`, both included."""
+        calendar: Calendar = {}
+        chunk_start = start
+        while chunk_start <= end:
+            chunk_end = min(end, chunk_start + timedelta(days=OFFICIAL_MAX_DAYS - 1))
+            calendar.update(await self._async_chunk(chunk_start, chunk_end))
+            chunk_start = chunk_end + timedelta(days=1)
+        return {day: color for day, color in calendar.items() if start <= day <= end}
+
+
+def parse_official_values(payload: Any) -> Calendar:
+    """Read a `tempo_like_calendars.values[]` answer of the official API."""
+    container = (
+        payload.get("tempo_like_calendars") if isinstance(payload, dict) else None
+    )
+    values = container.get("values") if isinstance(container, dict) else None
+    if not isinstance(values, list):
+        msg = "The answer has no 'tempo_like_calendars.values' list"
+        raise TempoFormatError(msg)
+    calendar: Calendar = {}
+    for item in values:
+        start = item.get("start_date") if isinstance(item, dict) else None
+        if not isinstance(start, str):
+            msg = f"Unexpected calendar item {item!r}"
+            raise TempoFormatError(msg)
+        try:
+            day = datetime.fromisoformat(start).date()
+        except ValueError as err:
+            msg = f"Unexpected start_date {start!r}"
+            raise TempoFormatError(msg) from err
+        calendar[day] = _color(item.get("value"))
+    return calendar
+
+
+class FallbackTempoSource:
+    """Ask each source in turn and return the first answer."""
+
+    def __init__(self, sources: Sequence[TempoCalendarSource]) -> None:
+        """Try `sources` in this order."""
+        if not sources:
+            msg = "At least one source is needed"
+            raise ValueError(msg)
+        self._sources = tuple(sources)
+        self.last_source: str | None = None
+        self.last_errors: dict[str, TempoError] = {}
+
+    @property
+    def name(self) -> str:
+        """Names of the sources, in order."""
+        return "+".join(source.name for source in self._sources)
+
+    async def async_calendar(self, start: date, end: date) -> Calendar:
+        """Return the first source's answer; raise the last error if all fail.
+
+        `last_source` names the source that answered, `last_errors` the errors of
+        the sources tried before it (or of all of them).
+        """
+        self.last_errors = {}
+        self.last_source = None
+        error: TempoError | None = None
+        for source in self._sources:
+            try:
+                calendar = await source.async_calendar(start, end)
+            except TempoError as err:
+                self.last_errors[source.name] = err
+                error = err
+                continue
+            self.last_source = source.name
+            return calendar
+        assert error is not None  # noqa: S101 - at least one source was tried
+        raise error

elec_tariffs/sources/trv.py

@@ -0,0 +1,121 @@
+"""Regulated prices (Tarif Bleu) published on data.gouv.fr.
+
+Each CSV has one row per price period and subscribed power: start and end dates
+(DD/MM/YYYY, an empty end for the prices in force), the yearly fixed part and the
+price of each tranche, with and without taxes. Rows of powers not offered at the
+time are empty.
+"""
+
+import csv
+from collections.abc import Mapping
+from datetime import date, datetime
+from typing import Final
+
+import aiohttp
+
+from elec_tariffs.errors import TrvFormatError, TrvServerError
+from elec_tariffs.models import ContractKind, PricePeriod, Tranche
+
+TRV_URLS: Final[Mapping[ContractKind, str]] = {
+    ContractKind.BASE: "https://www.data.gouv.fr/fr/datasets/r/c13d05e5-9e55-4d03-bf7e-042a2ade7e49",
+    ContractKind.HPHC: "https://www.data.gouv.fr/fr/datasets/r/f7303b3a-93c7-4242-813d-84919034c416",
+    ContractKind.TEMPO: "https://www.data.gouv.fr/fr/datasets/r/0c3d1d36-c412-4620-8566-e5cbb4fa2b5a",
+}
+
+_PRICE_COLUMNS: Final[Mapping[ContractKind, Mapping[Tranche, str]]] = {
+    ContractKind.BASE: {Tranche.BASE: "PART_VARIABLE_TTC"},
+    ContractKind.HPHC: {
+        Tranche.HC: "PART_VARIABLE_HC_TTC",
+        Tranche.HP: "PART_VARIABLE_HP_TTC",
+    },
+    ContractKind.TEMPO: {
+        Tranche.BLUE_HC: "PART_VARIABLE_HCBleu_TTC",
+        Tranche.BLUE_HP: "PART_VARIABLE_HPBleu_TTC",
+        Tranche.WHITE_HC: "PART_VARIABLE_HCBlanc_TTC",
+        Tranche.WHITE_HP: "PART_VARIABLE_HPBlanc_TTC",
+        Tranche.RED_HC: "PART_VARIABLE_HCRouge_TTC",
+        Tranche.RED_HP: "PART_VARIABLE_HPRouge_TTC",
+    },
+}
+_START: Final = "DATE_DEBUT"
+_END: Final = "DATE_FIN"
+_POWER: Final = "P_SOUSCRITE"
+_FIXED: Final = "PART_FIXE_TTC"
+_TIMEOUT: Final = aiohttp.ClientTimeout(total=30)
+
+
+def _date(value: str) -> date:
+    return datetime.strptime(value, "%d/%m/%Y").date()  # noqa: DTZ007
+
+
+def _number(value: str) -> float:
+    return float(value.replace(",", "."))
+
+
+def parse_trv_csv(text: str, kind: ContractKind, kva: int) -> list[PricePeriod]:
+    """Return the price periods of one contract kind and power, oldest first.
+
+    Raise TrvFormatError when a column is missing or a value can't be read.
+    """
+    reader = csv.DictReader(text.lstrip("").splitlines(), delimiter=";")
+    price_columns = _PRICE_COLUMNS[kind]
+    required = {_START, _END, _POWER, _FIXED, *price_columns.values()}
+    missing = required - set(reader.fieldnames or ())
+    if missing:
+        msg = f"Missing columns in the {kind} prices: {', '.join(sorted(missing))}"
+        raise TrvFormatError(msg)
+
+    periods: list[PricePeriod] = []
+    for raw in reader:
+        # A short row leaves None in its last columns; extra fields have no name.
+        row = {name: (value or "").strip() for name, value in raw.items() if name}
+        if row[_POWER] != str(kva) or not row[_FIXED]:
+            continue
+        try:
+            periods.append(
+                PricePeriod(
+                    start=_date(row[_START]),
+                    end=_date(row[_END]) if row[_END] else None,
+                    fixed_per_year=_number(row[_FIXED]),
+                    prices={
+                        tranche: _number(row[column])
+                        for tranche, column in price_columns.items()
+                    },
+                )
+            )
+        except ValueError as err:
+            msg = f"Unreadable {kind} price row starting {row[_START]}: {err}"
+            raise TrvFormatError(msg) from err
+    return sorted(periods, key=lambda period: period.start)
+
+
+class TrvClient:
+    """Download the regulated prices from data.gouv.fr."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        *,
+        urls: Mapping[ContractKind, str] = TRV_URLS,
+    ) -> None:
+        """Use the caller's HTTP session; `urls` replaces the data.gouv.fr files."""
+        self._session = session
+        self._urls = urls
+
+    async def async_price_periods(
+        self, kind: ContractKind, kva: int
+    ) -> list[PricePeriod]:
+        """Return the price periods of one contract kind and power, oldest first."""
+        try:
+            async with self._session.get(
+                self._urls[kind], timeout=_TIMEOUT
+            ) as response:
+                response.raise_for_status()
+                text = await response.text(encoding="utf-8")
+        except UnicodeDecodeError as err:
+            msg = f"The {kind} prices are not UTF-8 text"
+            raise TrvFormatError(msg) from err
+        except (aiohttp.ClientError, TimeoutError) as err:
+            msg = f"Could not download the {kind} prices: {err}"
+            raise TrvServerError(msg) from err
+        return parse_trv_csv(text, kind, kva)

elec_tariffs-0.1.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: elec-tariffs
+Version: 0.1.0
+Summary: Cost French electricity consumption hour by hour under Base, HP/HC and Tempo contracts
+Project-URL: Homepage, https://github.com/damou8/elec-tariffs
+Project-URL: Issues, https://github.com/damou8/elec-tariffs/issues
+Author: damou8
+License-Expression: MIT
+License-File: LICENSE
+Keywords: edf,electricity,home-assistant,linky,rte,tariff,tempo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: aiohttp>=3.10
+Description-Content-Type: text/markdown
+
+# elec-tariffs
+
+Cost French electricity consumption hour by hour under Base, HP/HC and Tempo contracts.
+
+`elec-tariffs` takes hourly consumption (as a Linky meter reports it) and works out what it cost under one or more contracts: which tranche each hour falls into, its price on that day, and its share of the yearly subscription. It also downloads the data that needs:
+
+- the regulated prices (Tarif Bleu) of every period since 2012, from [data.gouv.fr](https://www.data.gouv.fr/fr/datasets/historique-des-tarifs-reglementes-de-vente-delectricite-pour-les-consommateurs-residentiels/);
+- the color of each Tempo day, from RTE.
+
+It is async (aiohttp), fully typed and has no dependency on Home Assistant. It was written for the [Electricity Contracts](https://github.com/damou8/electricity_contracts) Home Assistant integration.
+
+It is not affiliated with EDF, RTE or Enedis.
+
+## Install
+
+```bash
+pip install elec-tariffs
+```
+
+Python 3.14 or later.
+
+## Use
+
+```python
+import asyncio
+from datetime import date, datetime
+from zoneinfo import ZoneInfo
+
+import aiohttp
+
+from elec_tariffs import (
+    ContractKind,
+    ContractRules,
+    RtePublicTempoClient,
+    TrvClient,
+    cost_hour,
+)
+
+PARIS = ZoneInfo("Europe/Paris")
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        prices = await TrvClient(session).async_price_periods(ContractKind.TEMPO, 6)
+        colors = await RtePublicTempoClient(session).async_calendar(
+            date(2026, 1, 4), date(2026, 1, 5)
+        )
+
+    # 1.8 kWh used from 19:00 to 20:00 on 5 January 2026.
+    cost = cost_hour(
+        datetime(2026, 1, 5, 19, tzinfo=PARIS),
+        1.8,
+        ContractRules(kind=ContractKind.TEMPO),
+        prices,
+        colors,
+    )
+    print(cost.energy, cost.variable, cost.fixed, cost.total)
+
+
+asyncio.run(main())
+```
+
+An HP/HC contract takes its own off-peak ranges, to the half hour, and can make weekends off-peak:
+
+```python
+from datetime import time
+
+from elec_tariffs import ContractKind, ContractRules, TimeRange
+
+rules = ContractRules(
+    kind=ContractKind.HPHC,
+    off_peak=(
+        TimeRange(start=time(12, 30), end=time(14)),
+        TimeRange(start=time(22), end=time(6, 30)),
+    ),
+    weekend_off_peak=True,
+)
+```
+
+Prices you set yourself are `PricePeriod` objects: a first and last day (`None` while in force), the yearly fixed part and a price per tranche, all with taxes.
+
+## How an hour is costed
+
+- **Tranches.** Each hour is split into two half hours with half the energy each, so an off-peak range that starts or ends on a half hour is followed. This assumes the consumption is even within the hour.
+- **Tempo.** A Tempo day runs from 6:00 to 6:00, so a night takes the color of the day that started the evening before. Off-peak hours are 22:00 to 6:00.
+- **Prices** change at midnight on the first day of a price period (1 February and 1 August for the regulated prices). An hour uses the prices of its calendar day.
+- **Subscription.** The yearly fixed part is spread evenly over the hours of the year (8,760, or 8,784 in a leap year).
+- **Missing data.** An hour whose Tempo color or price isn't known raises `MissingColorError` or `MissingPriceError` instead of guessing.
+
+## Tempo calendar sources
+
+| Source | Account | Notes |
+| --- | --- | --- |
+| `RtePublicTempoClient` | none | The backend of RTE's public [Tempo calendar page](https://www.services-rte.com/fr/visualisez-les-donnees-publiees-par-rte/calendrier-des-offres-de-fourniture-de-type-tempo.html). It isn't documented and RTE can change it without notice, so its answers are checked strictly: an unexpected format raises `TempoFormatError` instead of giving wrong colors. |
+| `RteOfficialTempoClient` | free [data.rte-france.com](https://data.rte-france.com/catalog/-/api/consumption/Tempo-Like-Supply-Contract/v1.1) application | RTE's documented "Tempo Like Supply Contract" API, with OAuth2 client credentials. The token is kept until it expires and renewed once if refused. Long ranges are split into requests of 366 days at most. **Not yet tested against the live API**: its tests follow the format used by other clients. |
+
+`FallbackTempoSource` asks each source in turn, for example the public one first and the official one when it fails. It records which source answered and the errors of the others.
+
+Past colors never change, so callers should cache them and only ask for the current season and the next day.
+
+To create the official API application: sign up on data.rte-france.com, open the "Tempo Like Supply Contract" API, choose "S'abonner à l'API" (this creates an application), then copy its client ID and secret.
+
+## Errors
+
+Every error derives from `ElecTariffsError`:
+
+- `MissingColorError`, `MissingPriceError` (with the `day` concerned);
+- `TrvServerError`, `TrvFormatError` for data.gouv.fr;
+- `TempoServerError` (network or 5xx), `TempoRateLimitError` (429), `TempoAuthError` (credentials refused) and `TempoFormatError` for the Tempo sources.
+
+## Development
+
+```bash
+python3.14 -m venv .venv
+.venv/bin/pip install -r requirements-dev.txt -e .
+.venv/bin/ruff check && .venv/bin/ruff format --check && .venv/bin/mypy
+.venv/bin/pytest --cov
+```
+
+The tests use recorded answers in `tests/fixtures/` and a local HTTP server; they make no network requests.
+
+Releases are published to PyPI by GitHub Actions when a GitHub release is published; the tag (`vX.Y.Z`) must match `src/elec_tariffs/_version.py`.
+
+## License
+
+[MIT](LICENSE)

elec_tariffs-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+elec_tariffs/__init__.py,sha256=B_6bxtr5iG9oGkjpPmaDK0x9JV20zFsncN1ryJ6wYtM,1680
+elec_tariffs/_version.py,sha256=SMtRk4qxf0OYKoTBdCtPkBUDYVklfxDXkbrQZ69TsZo,80
+elec_tariffs/engine.py,sha256=ie2dKaImyTNN0ATN_OSB_2tTDBwmGtsZFhm-OxW01pI,4903
+elec_tariffs/errors.py,sha256=iEGZLg0sKiIq7mHTaPDOGhKiiOGaKhdUHmbM4eyXF8U,1540
+elec_tariffs/models.py,sha256=eXa_oyegUc3DjoyxIiDS5Oyv_8E00k4dh5n1czuSMtg,2880
+elec_tariffs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+elec_tariffs/sources/__init__.py,sha256=UwPJLU6cZ5mM9KML5DNRwU2JXAZs5Z-K38MNXrT8Woc,454
+elec_tariffs/sources/tempo.py,sha256=KJgXILZUNKYNti9QPn2VHFm5-P402F5GgmzhxYXXxVY,15270
+elec_tariffs/sources/trv.py,sha256=YKmyApGN64Wsn9gPflPVTMxa-vyCbyNBranv8PT3ehs,4651
+elec_tariffs-0.1.0.dist-info/METADATA,sha256=sYDLgyzVKbw2lwhLnKgDt_L0SKoi1Scpr55A7xUs864,6329
+elec_tariffs-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+elec_tariffs-0.1.0.dist-info/licenses/LICENSE,sha256=0ETqjySAVmmSopcwiOYZ2G05CrpF11Uotvki5FeXvyo,1063
+elec_tariffs-0.1.0.dist-info/RECORD,,

elec_tariffs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

elec_tariffs-0.1.0.dist-info/licenses/LICENSE

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