electricore-client 0.1.0__py3-none-any.whl

electricore_client/__init__.py

@@ -0,0 +1,53 @@
+"""electricore-client — client léger vers l'API facturiste electricore.
+
+Distribué séparément du moteur, dépendances de base **httpx + pydantic
+uniquement** : ce paquet n'importe jamais polars/duckdb/fastapi au top-level
+(invariant prouvé par le test de pureté). Le client Arrow historique
+(DataFrames polars) vit dans le sous-module `electricore_client.arrow`, derrière
+l'extra `[arrow]`, et n'est *pas* importé ici.
+
+Lecture seule sur electricore (ADR-0012). Voir ADR-0043 pour la conception.
+"""
+
+from __future__ import annotations
+
+from .client import ElectricoreClient
+from .exceptions import (
+    ContractVersionError,
+    ElectricoreClientError,
+    IngestionEnCours,
+)
+from .headers import EnTetesMeta
+from .models import (
+    LigneChronologie,
+    LigneEvenement,
+    LignePeriodeEnergie,
+    LigneReleve,
+    LigneTurpeVariable,
+    ObjetReleve,
+    PeriodeMeta,
+    ResultatTurpeVariable,
+    TurpeVariableRequest,
+)
+from .streaming import JsonlStream
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ElectricoreClient",
+    "ElectricoreClientError",
+    "IngestionEnCours",
+    "ContractVersionError",
+    "EnTetesMeta",
+    "JsonlStream",
+    "PeriodeMeta",
+    "ObjetReleve",
+    "LigneChronologie",
+    "LigneEvenement",
+    "LigneReleve",
+    "LignePeriodeEnergie",
+    "LigneTurpeVariable",
+    "TurpeVariableRequest",
+    "ResultatTurpeVariable",
+    "__version__",
+]

electricore_client/arrow.py

@@ -0,0 +1,128 @@
+"""Client Arrow historique : endpoints structurés en `pl.DataFrame` (extra `[arrow]`).
+
+Ce sous-module **n'est jamais importé au top-level** de `electricore_client` :
+il porte le seul code qui dépend de polars, et l'importe **paresseusement** (à
+l'appel d'une méthode). La base du paquet reste donc polars-free — l'invariant
+prouvé par le test de pureté tient même quand `[arrow]` n'est pas installé.
+
+Endpoints Arrow IPC (`/flux/{table}.arrow`, `/releves.arrow`, `/facturation/
+detail.arrow`, `/taxes/{accise,cta}/detail.arrow`) — pour les notebooks distants
+qui n'ont pas la base DuckDB en local (ADR-0009). Lecture seule (ADR-0012).
+
+Installer avec l'extra : `pip install "electricore-client[arrow]"`.
+"""
+
+from __future__ import annotations
+
+import io
+from typing import TYPE_CHECKING, Any
+
+from .transport import _BaseClient
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only, jamais exécuté
+    import polars as pl
+
+_HINT_INSTALL = (
+    'Le client Arrow nécessite polars : installez l\'extra `arrow` (`pip install "electricore-client[arrow]"`).'
+)
+
+
+def _polars():
+    """Importe polars paresseusement, avec un message d'install clair s'il manque."""
+    try:
+        import polars as pl
+    except ModuleNotFoundError as exc:  # pragma: no cover - testé via monkeypatch
+        raise ModuleNotFoundError(_HINT_INSTALL) from exc
+    return pl
+
+
+class ElectricoreArrowClient(_BaseClient):
+    """Client Arrow synchrone : endpoints structurés rendus en `pl.DataFrame`.
+
+    Hérite du substrat de transport partagé (URL, `X-API-Key`, timeout, 503 →
+    `IngestionEnCours`). polars n'est tiré qu'au premier appel de méthode.
+    """
+
+    def _get_arrow(self, path: str, params: dict) -> pl.DataFrame:
+        pl = _polars()
+        response = self._http.get(f"{self.url}{path}", params=params, headers=self._headers)
+        self._raise_for_status(response)
+        return pl.read_ipc_stream(io.BytesIO(response.content))
+
+    def flux(
+        self,
+        table_name: str,
+        *,
+        prm: str | None = None,
+        limit: int = 1_000_000,
+    ) -> pl.DataFrame:
+        """Contenu brut d'un flux Enedis (c15, r151, f15, etc.) en Polars.
+
+        Équivalent HTTP des `c15()`/`r151()`/`f15()` du `DuckDBQuery` — pour les
+        notebooks distants sans accès local à la base (ADR-0009).
+
+        Args:
+            table_name: nom de la table flux (`c15`, `r151`, `r15`, `f15_detail`, …).
+            prm: filtre optionnel sur la colonne `pdl`.
+            limit: nombre maximum de lignes (défaut 1 000 000, max serveur 10 000 000).
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if prm:
+            params["prm"] = prm
+        return self._get_arrow(f"/flux/{table_name}.arrow", params)
+
+    def releves(
+        self,
+        *,
+        prm: str | None = None,
+        source: str | None = None,
+        debut: str | None = None,
+        fin: str | None = None,
+        limit: int = 1_000_000,
+    ) -> pl.DataFrame:
+        """Mart de relevés canonique `releves` (ADR-0029) en Polars.
+
+        Args:
+            prm: filtre optionnel sur la colonne `pdl`.
+            source: filtre optionnel (`flux_R151` / `flux_R64` / `flux_C15`).
+            debut: borne basse incluse sur `date_releve` (ex. `"2025-01-01"`).
+            fin: borne haute incluse sur `date_releve` (ex. `"2025-12-31"`).
+            limit: nombre maximum de lignes (défaut 1 000 000, max serveur 10 000 000).
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if prm:
+            params["prm"] = prm
+        if source:
+            params["source"] = source
+        if debut:
+            params["debut"] = debut
+        if fin:
+            params["fin"] = fin
+        return self._get_arrow("/releves.arrow", params)
+
+    def facturation(self, mois: str | None = None) -> pl.DataFrame:
+        """`lignes_facture_rapprochees` pour le mois donné.
+
+        Args:
+            mois: "YYYY-MM-DD" — défaut : dernier mois disponible côté serveur.
+        """
+        return self._get_arrow("/facturation/detail.arrow", {"mois": mois} if mois else {})
+
+    def accise(self, trimestre: str | None = None) -> pl.DataFrame:
+        """Détail Accise TICFE pour le trimestre donné.
+
+        Args:
+            trimestre: "YYYY-TX" (ex. "2025-T1") — défaut : tous les trimestres.
+        """
+        return self._get_arrow("/taxes/accise/detail.arrow", {"trimestre": trimestre} if trimestre else {})
+
+    def cta(self, trimestre: str | None = None) -> pl.DataFrame:
+        """Détail CTA mensuel pour le trimestre donné.
+
+        Args:
+            trimestre: "YYYY-TX" (ex. "2025-T1") — défaut : tous les trimestres.
+        """
+        return self._get_arrow("/taxes/cta/detail.arrow", {"trimestre": trimestre} if trimestre else {})
+
+
+__all__ = ["ElectricoreArrowClient"]

electricore_client/client.py

@@ -0,0 +1,180 @@
+"""Client de la facturiste electricore (httpx + pydantic, sans polars).
+
+`ElectricoreClient` assemble le substrat de transport (`_BaseClient`) et les
+méthodes d'endpoint. Ce module reste **polars-free** : le client Arrow
+historique vit dans le sous-module `arrow` (extra `[arrow]`), jamais importé
+ici au top-level.
+"""
+
+from __future__ import annotations
+
+from .models.chronologie import (
+    CONTRAT_VERSION_CHRONOLOGIE,
+    LigneEvenement,
+    LignePeriodeEnergie,
+    LigneReleve,
+    valider_ligne_chronologie,
+)
+from .models.meta_periodes import (
+    CONTRAT_VERSION_META_PERIODES,
+    PeriodeMeta,
+)
+from .models.turpe_variable import (
+    CONTRAT_VERSION_TURPE_VARIABLE,
+    LigneTurpeVariable,
+    ResultatTurpeVariable,
+    TurpeVariableRequest,
+)
+from .streaming import JsonlStream
+from .transport import _BaseClient
+
+# Type de ligne résolu par l'union discriminée de la chronologie.
+LigneFrise = LigneEvenement | LigneReleve | LignePeriodeEnergie
+
+
+class ElectricoreClient(_BaseClient):
+    """Client synchrone vers une instance de l'API facturiste electricore.
+
+    Construit avec une `url` de base et une `api_key` (en-tête `X-API-Key`).
+    Les méthodes de lecture (méta-périodes, chronologie) streament du JSONL ;
+    `turpe_variable` est un POST RPC. Le client Arrow (DataFrames polars) est
+    fourni séparément via l'extra `[arrow]` (`electricore_client.arrow`).
+    """
+
+    def meta_periodes(
+        self,
+        *,
+        mois: str | None = None,
+        rsc: list[str] | None = None,
+        page_size: int | None = None,
+    ) -> JsonlStream[PeriodeMeta]:
+        """Flux JSONL typé des méta-périodes mensuelles (contrat v3, ADR-0027/0038).
+
+        Le serveur **streame toutes les lignes** (pas de pagination) ; les
+        métadonnées (`contract_version`, `mois` résolu) sont dans les en-têtes
+        de réponse, lisibles via le flux retourné. La garde de version est
+        appliquée à l'ouverture (`__enter__`).
+
+        Args:
+            mois: mois cible `YYYY-MM-DD` (premier du mois) ; `None` → dernier
+                mois disponible côté serveur.
+            rsc: filtre optionnel sur une liste de `ref_situation_contractuelle`.
+            page_size: indication optionnelle de taille de lot serveur (hint).
+
+        Returns:
+            Un `JsonlStream[PeriodeMeta]`, à consommer en context-manager :
+
+            ```python
+            with client.meta_periodes(mois="2026-05-01") as stream:
+                stream.contract_version
+                for periode in stream:
+                    ...
+            ```
+        """
+        params: dict[str, object] = {}
+        if mois is not None:
+            params["mois"] = mois
+        if rsc:
+            params["rsc"] = rsc
+        if page_size is not None:
+            params["page_size"] = page_size
+
+        return JsonlStream(
+            client=self._http,
+            method="GET",
+            url=f"{self.url}/facturation/meta-periodes",
+            params=params or None,
+            headers=self._headers,
+            validateur=PeriodeMeta.model_validate,
+            version_attendue=CONTRAT_VERSION_META_PERIODES,
+            verifier_version=lambda attendue, servie: self._verifier_version(attendue=attendue, servie=servie),
+            raise_for_status=self._raise_for_status,
+        )
+
+    def chronologie(
+        self,
+        *,
+        pdl: str | None = None,
+        rsc: str | None = None,
+        page_size: int | None = None,
+    ) -> JsonlStream[LigneFrise]:
+        """Flux JSONL de la frise d'un point (`pdl`) **ou** d'un contrat (`rsc`) — contrat v1.
+
+        Chaque ligne se résout en son sous-type via l'union discriminée
+        `LigneChronologie` (`LigneEvenement | LigneReleve | LignePeriodeEnergie`).
+        Faits + verdicts, **sans montant tarifaire** (différenciateur vs
+        méta-périodes). Pas de pagination ; `contract_version`/`grain` en en-têtes.
+
+        Le grain est validé **côté client** (`pdl` XOR `rsc`) — un `ValueError`
+        est levé *avant* toute requête (miroir du 422 serveur).
+
+        Args:
+            pdl: grain point — toute l'histoire du PDL (RSC successives + charnières).
+            rsc: grain contrat — une tenure bornée entrée→sortie.
+            page_size: indication optionnelle de taille de lot serveur (hint).
+
+        Raises:
+            ValueError: si ni `pdl` ni `rsc`, ou si les deux sont fournis (XOR).
+        """
+        if (pdl is None) == (rsc is None):
+            raise ValueError("Fournir exactement un grain : `pdl` (point) XOR `rsc` (contrat).")
+
+        params: dict[str, object] = {}
+        if pdl is not None:
+            params["pdl"] = pdl
+        if rsc is not None:
+            params["rsc"] = rsc
+        if page_size is not None:
+            params["page_size"] = page_size
+
+        return JsonlStream(
+            client=self._http,
+            method="GET",
+            url=f"{self.url}/facturation/chronologie",
+            params=params or None,
+            headers=self._headers,
+            validateur=valider_ligne_chronologie,
+            version_attendue=CONTRAT_VERSION_CHRONOLOGIE,
+            verifier_version=lambda attendue, servie: self._verifier_version(attendue=attendue, servie=servie),
+            raise_for_status=self._raise_for_status,
+        )
+
+    def turpe_variable(
+        self,
+        lignes: list[LigneTurpeVariable | dict],
+    ) -> list[ResultatTurpeVariable]:
+        """Valorise un lot d'assiettes TURPE variable — **POST RPC** (pas un stream).
+
+        Petit calcul stateless, batch POST : un round-trip pour tout le lot. Chaque
+        résultat porte `turpe_variable_eur` **ou** un `error`, **apparié à l'entrée
+        par l'`id` opaque** ré-émis (jamais positionnel — un serveur libre de
+        réordonner reste correct). La garde de version s'applique (en-tête).
+
+        Args:
+            lignes: lot de `LigneTurpeVariable` (ou de dicts validés en
+                `LigneTurpeVariable`) — `{id, formule_tarifaire_acheminement, debut,
+                energie_*_kwh}` (7 cadrans nullables).
+
+        Returns:
+            Liste de `ResultatTurpeVariable` (autant que d'entrées). Pour un
+            appariement explicite : `{r.id: r for r in resultats}`.
+        """
+        requete = TurpeVariableRequest(
+            lignes=[
+                ligne if isinstance(ligne, LigneTurpeVariable) else LigneTurpeVariable.model_validate(ligne)
+                for ligne in lignes
+            ]
+        )
+        response = self._http.post(
+            f"{self.url}/facturation/turpe-variable",
+            content=requete.model_dump_json(),
+            headers={**self._headers, "Content-Type": "application/json"},
+        )
+        self._raise_for_status(response)
+
+        version_servie = response.headers.get("X-Contract-Version")
+        if version_servie is not None:
+            self._verifier_version(attendue=CONTRAT_VERSION_TURPE_VARIABLE, servie=int(version_servie))
+
+        corps = response.json()
+        return [ResultatTurpeVariable.model_validate(r) for r in corps["results"]]

electricore_client/exceptions.py

@@ -0,0 +1,31 @@
+"""Exceptions du client electricore.
+
+Toutes dérivent d'`ElectricoreClientError` pour qu'un appelant puisse attraper
+*toute* erreur du client en une seule clause. `IngestionEnCours` est le cas
+métier distingué : la base DuckDB est verrouillée par un cycle d'ingestion
+(l'API répond **503**), et l'appelant peut simplement réessayer plus tard.
+"""
+
+from __future__ import annotations
+
+
+class ElectricoreClientError(Exception):
+    """Racine de toutes les erreurs levées par le client."""
+
+
+class IngestionEnCours(ElectricoreClientError):
+    """L'API a répondu 503 : la base est verrouillée par un cycle d'ingestion.
+
+    Transitoire — l'API se rétablit d'elle-même après le checkpoint. L'appelant
+    peut réessayer après un délai court (cf. `main.verrou_duckdb_en_503`, #171).
+    """
+
+
+class ContractVersionError(ElectricoreClientError):
+    """Le contrat servi par le serveur est plus **ancien** que celui attendu.
+
+    Garde asymétrique : un serveur *en avance* (version > attendue) ne fait que
+    `warn` (le client tolère l'additif via `extra="ignore"`) ; un serveur *en
+    retard* (version < attendue) lève cette erreur — le client réclamerait des
+    champs absents.
+    """

electricore_client/headers.py

@@ -0,0 +1,44 @@
+"""Métadonnées portées par les en-têtes de réponse.
+
+Les endpoints de lecture streament leurs lignes en JSONL : ils n'ont plus
+d'enveloppe pour loger la version de contrat et le contexte résolu (mois,
+grain). Ces métadonnées remontent donc dans des en-têtes HTTP, parsés ici en
+un petit modèle typé.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from pydantic import BaseModel, ConfigDict
+
+# En-têtes de métadonnées (conventionnés serveur + client).
+HEADER_CONTRACT_VERSION = "X-Contract-Version"
+HEADER_MOIS = "X-Mois"
+HEADER_GRAIN = "X-Grain"
+
+
+class EnTetesMeta(BaseModel):
+    """Métadonnées d'un flux JSONL, extraites des en-têtes de réponse.
+
+    `contract_version` est toujours présent ; `mois` (méta-périodes) et `grain`
+    (chronologie) le sont selon l'endpoint.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    contract_version: int
+    mois: str | None = None
+    grain: str | None = None
+
+    @classmethod
+    def from_headers(cls, headers: Mapping[str, str]) -> EnTetesMeta:
+        """Parse les en-têtes de réponse (insensibles à la casse via httpx)."""
+        version = headers.get(HEADER_CONTRACT_VERSION)
+        if version is None:
+            raise ValueError(f"En-tête manquant : {HEADER_CONTRACT_VERSION}")
+        return cls(
+            contract_version=int(version),
+            mois=headers.get(HEADER_MOIS),
+            grain=headers.get(HEADER_GRAIN),
+        )

electricore_client/models/__init__.py

@@ -0,0 +1,40 @@
+"""Modèles de contrat des endpoints facturiste (source unique, ADR-0043).
+
+Ces modèles pydantic décrivent les lignes émises par l'API en JSONL. Ils sont
+**single-sourcés** : le moteur (routers FastAPI) les importe d'ici plutôt que
+de redéfinir des modèles inline.
+"""
+
+from __future__ import annotations
+
+from .chronologie import (
+    CONTRAT_VERSION_CHRONOLOGIE,
+    LigneChronologie,
+    LigneEvenement,
+    LignePeriodeEnergie,
+    LigneReleve,
+    valider_ligne_chronologie,
+)
+from .meta_periodes import CONTRAT_VERSION_META_PERIODES, ObjetReleve, PeriodeMeta
+from .turpe_variable import (
+    CONTRAT_VERSION_TURPE_VARIABLE,
+    LigneTurpeVariable,
+    ResultatTurpeVariable,
+    TurpeVariableRequest,
+)
+
+__all__ = [
+    "PeriodeMeta",
+    "ObjetReleve",
+    "CONTRAT_VERSION_META_PERIODES",
+    "LigneChronologie",
+    "LigneEvenement",
+    "LigneReleve",
+    "LignePeriodeEnergie",
+    "CONTRAT_VERSION_CHRONOLOGIE",
+    "valider_ligne_chronologie",
+    "LigneTurpeVariable",
+    "TurpeVariableRequest",
+    "ResultatTurpeVariable",
+    "CONTRAT_VERSION_TURPE_VARIABLE",
+]

electricore_client/models/chronologie.py

@@ -0,0 +1,110 @@
+"""Modèles de contrat de la chronologie facturiste (contrat v1, ADR-0039/0041).
+
+Miroir de `chronologie_service` : la frise d'un point/contrat est une suite de
+lignes hétérogènes — **faits** (événements C15, relevés) tissés avec les
+**verdicts** des périodes d'énergie. Une ligne est donc une **union discriminée**
+(pydantic v2) sur `type_ligne` : `evenement | releve | periode_energie`.
+
+Tout est optionnel (sauf le discriminant + `date`) : registres et énergies ne
+sont émis que non-nuls (jamais de cadran synthétisé). Typage (ADR-0034) :
+`index_*_kwh` entiers, `energie_*_kwh` flottants. **Pas de montant tarifaire**
+(différenciateur vs méta-périodes).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+
+# Version du contrat (cf. chronologie_service.CONTRAT_VERSION). Source unique.
+CONTRAT_VERSION_CHRONOLOGIE = 1
+
+
+class _LigneBase(BaseModel):
+    """Champs partagés par toute ligne de frise (additive-tolérante)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    date: str
+    pdl: str | None = None
+    ref_situation_contractuelle: str | None = None
+
+
+class LigneEvenement(_LigneBase):
+    """Un fait événementiel : événement C15 (y compris hors-comptage) ou borne FACTURATION.
+
+    Porte la situation au moment du fait (puissance, FTA, niveau d'ouverture) et
+    les annotations de rupture d'abonnement.
+    """
+
+    type_ligne: Literal["evenement"]
+    source: str | None = None
+    type_fait: str | None = None
+    evenement_declencheur: str | None = None
+    puissance_souscrite_kva: float | None = None
+    formule_tarifaire_acheminement: str | None = None
+    niveau_ouverture_services: str | None = None
+    impacte_abonnement: bool | None = None
+    resume_modification: str | None = None
+
+
+class LigneReleve(_LigneBase):
+    """Un fait de relevé : index utilisé, avec origine (périodique/événementiel) et nature.
+
+    Seuls les registres réels (non nuls) ressortent. `evenement_declencheur` n'est
+    présent que pour un relevé d'origine événementielle (C15).
+    """
+
+    type_ligne: Literal["releve"]
+    source: str | None = None
+    releve_id: str | None = None
+    nature_index: str | None = None
+    origine_releve: str | None = None
+    ordre_index: int | None = None
+    evenement_declencheur: str | None = None
+
+    # Registres réels (index_*_kwh) — entiers (ADR-0034), non-nuls uniquement.
+    index_base_kwh: int | None = None
+    index_hp_kwh: int | None = None
+    index_hc_kwh: int | None = None
+    index_hph_kwh: int | None = None
+    index_hch_kwh: int | None = None
+    index_hpb_kwh: int | None = None
+    index_hcb_kwh: int | None = None
+
+
+class LignePeriodeEnergie(_LigneBase):
+    """Une période d'énergie dérivée : bornes + **verdicts** (qualité/communication) + énergie
+    physique (kWh). **Aucun** montant tarifaire (ADR-0027)."""
+
+    type_ligne: Literal["periode_energie"]
+    debut: str | None = None
+    fin: str | None = None
+    nb_jours: int | None = None
+    qualite: str | None = None
+    statut_communication: str | None = None
+
+    # Énergies (energie_*_kwh) — flottants (ADR-0034), non-nulles uniquement.
+    energie_base_kwh: float | None = None
+    energie_hp_kwh: float | None = None
+    energie_hc_kwh: float | None = None
+    energie_hph_kwh: float | None = None
+    energie_hch_kwh: float | None = None
+    energie_hpb_kwh: float | None = None
+    energie_hcb_kwh: float | None = None
+
+
+# Union discriminée sur `type_ligne` : pydantic résout chaque ligne au bon sous-type.
+LigneChronologie = Annotated[
+    LigneEvenement | LigneReleve | LignePeriodeEnergie,
+    Field(discriminator="type_ligne"),
+]
+
+# Adaptateur réutilisable pour valider une ligne brute (dict) → sous-type concret.
+_ADAPTER: TypeAdapter = TypeAdapter(LigneChronologie)
+
+
+def valider_ligne_chronologie(ligne: dict) -> LigneEvenement | LigneReleve | LignePeriodeEnergie:
+    """Valide une ligne brute en son sous-type concret via l'union discriminée."""
+    return _ADAPTER.validate_python(ligne)

electricore_client/models/meta_periodes.py

@@ -0,0 +1,88 @@
+"""Modèles de contrat des méta-périodes mensuelles (contrat v3, ADR-0027/0038).
+
+Miroir de `meta_periodes_service.COLONNES_CONTRAT` + `source_hash` + le tableau
+imbriqué `releves_utilises` (ADR-0038). Conventions de typage (ADR-0034) : les
+index de compteur (`index_*_kwh`) sont des **entiers** (kWh entier au boundary
+dbt) ; les énergies (`energie_*_kwh`) et montants (`*_eur`) sont des **flottants**.
+
+`model_config = extra="ignore"` : le contrat est additif-tolérant — un serveur
+plus récent qui ajoute une colonne ne casse pas un client plus ancien.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+# Version du contrat (cf. meta_periodes_service.CONTRAT_VERSION). Source unique.
+CONTRAT_VERSION_META_PERIODES = 3
+
+
+class ObjetReleve(BaseModel):
+    """Un relevé d'index utilisé pour borner une méta-période (ADR-0038).
+
+    Seuls les registres réellement affichés par le compteur ressortent (les
+    autres sont absents, pas null). `evenement` n'est présent que pour un relevé
+    d'origine événementielle (C15).
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    releve_id: str
+    date_releve: str
+    nature_index: str | None = None
+    origine_releve: str | None = None
+    evenement: str | None = None
+
+    # Registres réels (index_*_kwh) — entiers (ADR-0034), seuls les non-nuls émis.
+    index_base_kwh: int | None = None
+    index_hp_kwh: int | None = None
+    index_hc_kwh: int | None = None
+    index_hph_kwh: int | None = None
+    index_hch_kwh: int | None = None
+    index_hpb_kwh: int | None = None
+    index_hcb_kwh: int | None = None
+
+
+class PeriodeMeta(BaseModel):
+    """Méta-période mensuelle d'un contrat — agrégat valorisé (contrat v3).
+
+    Quantités physiques + montants réseau (pas de prix fournisseur). Porte la
+    trace d'index imbriquée `releves_utilises` (ADR-0038) et `source_hash`
+    (intégrité de contenu, ADR-0027/0038).
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    ref_situation_contractuelle: str
+    pdl: str
+    mois_annee: str
+    debut: str
+    fin: str
+    nb_jours: int
+    puissance_moyenne_kva: float | None = None
+    formule_tarifaire_acheminement: str | None = None
+
+    # Énergies (kWh) — flottants (ADR-0034).
+    energie_base_kwh: float | None = None
+    energie_hp_kwh: float | None = None
+    energie_hc_kwh: float | None = None
+
+    # Montants réseau (€) — flottants.
+    turpe_fixe_eur: float | None = None
+    turpe_variable_eur: float | None = None
+    cta_eur: float | None = None
+
+    # Taux accise (€/MWh) — flottant (taux, pas montant : assiette possédée par l'ERP).
+    taux_accise_eur_mwh: float | None = None
+
+    has_changement: bool | None = None
+
+    # Verdicts méta jumeaux (qualité ADR-0033 / communication ADR-0036).
+    qualite: str | None = None
+    statut_communication: str | None = None
+
+    # Trace d'index légale (ADR-0038) — imbriquée, requise (peut être vide).
+    releves_utilises: list[ObjetReleve] = []
+
+    # Intégrité de contenu (ADR-0027/0038) — requise.
+    source_hash: str

electricore_client/models/turpe_variable.py

@@ -0,0 +1,57 @@
+"""Modèles de contrat du calculateur TURPE variable (POST RPC, ADR-0030, #247/#409).
+
+Calculateur **sans état** : l'appelant prête l'assiette (énergies par cadran +
+FTA + `debut`), electricore renvoie le **montant** € — ou un motif d'erreur, par
+`id`, jamais de silent-drop. L'`id` est **opaque** : ré-émis tel quel, jamais
+interprété. Les 7 cadrans sont nullables (null → 0).
+
+Single-sourcés ici (ADR-0043) : le router FastAPI les importe, ne les redéfinit pas.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Version du contrat (cf. turpe_variable_service.CONTRAT_VERSION). Source unique.
+CONTRAT_VERSION_TURPE_VARIABLE = 1
+
+
+class LigneTurpeVariable(BaseModel):
+    """Une ligne d'assiette à valoriser. Les 7 cadrans sont nullables (null → 0)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str = Field(..., description="Identifiant opaque ré-émis tel quel (electricore ne l'interprète jamais)")
+    formule_tarifaire_acheminement: str = Field(..., description="FTA, ex. BTINFCUST")
+    debut: datetime = Field(..., description="Début de période (tz Europe/Paris) — sélection temporelle de la règle")
+    energie_base_kwh: float | None = None
+    energie_hp_kwh: float | None = None
+    energie_hc_kwh: float | None = None
+    energie_hph_kwh: float | None = None
+    energie_hpb_kwh: float | None = None
+    energie_hch_kwh: float | None = None
+    energie_hcb_kwh: float | None = None
+
+
+class TurpeVariableRequest(BaseModel):
+    """Lot de lignes à valoriser en une passe."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    lignes: list[LigneTurpeVariable] = Field(..., description="Lot de lignes (le cas mono-période est n=1)")
+
+
+class ResultatTurpeVariable(BaseModel):
+    """Résultat pour un `id` : **soit** `turpe_variable_eur`, **soit** `error` (xor).
+
+    Jamais de silent-drop (ADR-0030) : chaque `id` envoyé revient. `error` porte le
+    motif (FTA inconnue, aucune règle pour la date) ; `turpe_variable_eur` le montant.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str
+    turpe_variable_eur: float | None = None
+    error: str | None = None

electricore_client/streaming.py

@@ -0,0 +1,113 @@
+"""Flux JSONL typé : un context-manager qui valide chaque ligne en un modèle.
+
+Les endpoints de lecture (méta-périodes, chronologie) streament leur résultat
+en JSONL — une ligne = un objet JSON, validé à la volée par un modèle pydantic.
+Les métadonnées (version de contrat, mois/grain) arrivent en en-têtes ; la garde
+de version est appliquée à l'ouverture (`__enter__`). Le flux est lazy (rien
+n'est matérialisé tant qu'on n'itère pas) et libère la connexion à la sortie du
+`with`, **même mi-consommé**.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Iterator
+from typing import Generic, TypeVar
+
+import httpx
+
+from .headers import EnTetesMeta
+
+T = TypeVar("T")
+
+# Type-construit une ligne (dict JSON décodé) → modèle typé. En pratique
+# `Model.model_validate`, mais on garde la signature ouverte (unions discriminées).
+Validateur = Callable[[dict], T]
+
+
+class JsonlStream(Generic[T]):
+    """Itérateur paresseux sur un flux JSONL, validé ligne à ligne.
+
+    Construit autour d'un `httpx.Client.stream(...)` (context-manager de requête).
+    `__enter__` ouvre la réponse, parse les en-têtes de métadonnées et applique la
+    garde de version ; l'itération décode et valide chaque ligne non vide. À la
+    sortie du `with`, la réponse est fermée (connexion rendue au pool) qu'elle ait
+    été entièrement consommée ou non.
+    """
+
+    def __init__(
+        self,
+        *,
+        client: httpx.Client,
+        method: str,
+        url: str,
+        params: dict | None,
+        headers: dict[str, str],
+        validateur: Validateur[T],
+        version_attendue: int,
+        verifier_version: Callable[[int, int], None],
+        raise_for_status: Callable[[httpx.Response], None],
+    ) -> None:
+        self._request_cm = client.stream(method, url, params=params, headers=headers)
+        self._response: httpx.Response | None = None
+        self._validateur = validateur
+        self._version_attendue = version_attendue
+        self._verifier_version = verifier_version
+        self._raise_for_status = raise_for_status
+        self._meta: EnTetesMeta | None = None
+        self._closed = False
+
+    # -- context manager ------------------------------------------------------
+
+    def __enter__(self) -> JsonlStream[T]:
+        response = self._request_cm.__enter__()
+        self._response = response
+        self._raise_for_status(response)
+        self._meta = EnTetesMeta.from_headers(response.headers)
+        # Garde de version appliquée à l'ouverture (avant toute consommation).
+        self._verifier_version(self._version_attendue, self._meta.contract_version)
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Libère le flux (connexion rendue au pool), idempotent et mi-consommé-safe."""
+        if self._closed:
+            return
+        self._closed = True
+        self._request_cm.__exit__(None, None, None)
+
+    # -- métadonnées (en-têtes) ----------------------------------------------
+
+    @property
+    def meta(self) -> EnTetesMeta:
+        if self._meta is None:
+            raise RuntimeError("Flux non ouvert : utiliser `with client.<endpoint>(...) as stream:`")
+        return self._meta
+
+    @property
+    def contract_version(self) -> int:
+        return self.meta.contract_version
+
+    @property
+    def mois(self) -> str | None:
+        return self.meta.mois
+
+    @property
+    def grain(self) -> str | None:
+        return self.meta.grain
+
+    # -- itération ------------------------------------------------------------
+
+    def __iter__(self) -> Iterator[T]:
+        if self._response is None:
+            raise RuntimeError("Flux non ouvert : utiliser `with client.<endpoint>(...) as stream:`")
+        for ligne in self._response.iter_lines():
+            if not ligne.strip():
+                continue
+            yield self._validateur(json.loads(ligne))
+
+    def collect(self) -> list[T]:
+        """Matérialise tout le flux en liste (convenance)."""
+        return list(self)

electricore_client/transport.py

@@ -0,0 +1,90 @@
+"""Substrat de transport partagé par toutes les méthodes du client.
+
+`_BaseClient` factorise tout ce qui est commun aux endpoints : URL de base,
+en-tête `X-API-Key`, construction du `httpx.Client` (timeout), conversion
+d'erreur HTTP (503 → `IngestionEnCours`) et la garde de version de contrat.
+Les méthodes d'endpoint (méta-périodes, chronologie, turpe variable, Arrow)
+sont montées par-dessus dans `client.py`.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import httpx
+
+from .exceptions import ContractVersionError, IngestionEnCours
+
+# Timeout généreux en lecture : les flux JSONL peuvent durer (gros parc).
+DEFAULT_TIMEOUT = httpx.Timeout(30.0, read=300.0)
+
+# Code HTTP « ingestion en cours » (base DuckDB verrouillée par un writer, #171).
+STATUS_INGESTION_EN_COURS = 503
+
+
+class _BaseClient:
+    """Transport partagé : URL de base, auth, timeout, gestion d'erreur, garde de version."""
+
+    def __init__(
+        self,
+        url: str,
+        api_key: str,
+        *,
+        http_client: httpx.Client | None = None,
+        timeout: httpx.Timeout | None = None,
+    ) -> None:
+        self.url = url.rstrip("/")
+        self.api_key = api_key
+        self._http = http_client or httpx.Client(timeout=timeout or DEFAULT_TIMEOUT)
+
+    # -- cycle de vie ---------------------------------------------------------
+
+    def close(self) -> None:
+        """Ferme le client HTTP sous-jacent."""
+        self._http.close()
+
+    def __enter__(self) -> _BaseClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- helpers transport ----------------------------------------------------
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {"X-API-Key": self.api_key}
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        """Convertit les erreurs HTTP en exceptions du client.
+
+        503 (base verrouillée par l'ingestion) → `IngestionEnCours` ; tout autre
+        statut d'erreur → `httpx.HTTPStatusError` via `raise_for_status`.
+        """
+        if response.status_code == STATUS_INGESTION_EN_COURS:
+            raise IngestionEnCours(
+                "L'API electricore est momentanément indisponible : un cycle d'ingestion "
+                "verrouille la base. Réessayer après le checkpoint."
+            )
+        response.raise_for_status()
+
+    @staticmethod
+    def _verifier_version(*, attendue: int, servie: int) -> None:
+        """Garde asymétrique sur la version de contrat (en-tête `X-Contract-Version`).
+
+        - serveur **en avance** (servie > attendue) → `warn` : le client tolère
+          l'additif (`model_config = extra="ignore"`), pas besoin d'échouer ;
+        - serveur **en retard** (servie < attendue) → `ContractVersionError` : le
+          client réclamerait des champs que le serveur n'émet plus.
+        """
+        if servie > attendue:
+            warnings.warn(
+                f"Le serveur sert le contrat v{servie}, le client attend v{attendue} : "
+                f"des champs additifs peuvent être ignorés. Mettez le client à jour.",
+                stacklevel=3,
+            )
+        elif servie < attendue:
+            raise ContractVersionError(
+                f"Le serveur sert le contrat v{servie}, le client attend v{attendue} : "
+                f"trop ancien, des champs attendus sont absents. Mettez le serveur à jour."
+            )

electricore_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: electricore-client
+Version: 0.1.0
+Summary: Client Python léger (httpx + pydantic) vers l'API facturiste electricore — sans polars/duckdb/fastapi
+Project-URL: Homepage, https://github.com/Energie-De-Nantes/electricore
+Project-URL: Repository, https://github.com/Energie-De-Nantes/electricore
+Project-URL: Issues, https://github.com/Energie-De-Nantes/electricore/issues
+Author: Virgile
+License: AGPL-3.0
+Keywords: api-client,electricore,enedis,energy,facturation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: arrow
+Requires-Dist: polars<2.0.0,>=1.0.0; extra == 'arrow'
+Description-Content-Type: text/markdown
+
+# electricore-client
+
+Client Python **léger** vers l'API facturiste [electricore](https://github.com/Energie-De-Nantes/electricore).
+
+Dépendances de base : **httpx + pydantic uniquement** — pas de polars, duckdb ni
+fastapi. Pensé pour être consommé par `souscriptions_odoo` (Odoo 19) et tout
+intégrateur qui n'a pas besoin de tirer le moteur entier.
+
+Lecture seule sur electricore (« Odoo tire d'electricore », ADR-0027/0012).
+
+## Installation
+
+```bash
+pip install electricore-client            # base : httpx + pydantic
+pip install "electricore-client[arrow]"   # + client Arrow (DataFrames polars)
+```
+
+## Usage
+
+```python
+from electricore_client import ElectricoreClient
+
+client = ElectricoreClient(url="https://electricore.example", api_key="…")
+
+# Méta-périodes mensuelles (flux JSONL typé, sans pagination)
+with client.meta_periodes(mois="2026-05-01") as stream:
+    print(stream.contract_version)        # version de contrat (en-tête)
+    for periode in stream:                # itère des PeriodeMeta typés
+        ...
+
+# Chronologie d'un point ou d'un contrat (union discriminée)
+with client.chronologie(pdl="12345678901234") as stream:
+    lignes = stream.collect()
+
+# Calculateur TURPE variable (POST RPC, pas un stream)
+resultats = client.turpe_variable([...])  # résultats indexés par id opaque
+```
+
+Le client Arrow historique (`flux/releves/facturation/accise/cta` → `pl.DataFrame`)
+vit dans `electricore_client.arrow`, derrière l'extra `[arrow]`.
+
+## Conception
+
+Voir [ADR-0043](https://github.com/Energie-De-Nantes/electricore/blob/main/docs/adr/0043-electricore-client-paquet-separe.md).

electricore_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+electricore_client/__init__.py,sha256=RtqPn5wVcT94EvlxkzHWggUllsHKMW7g1B4vb9s0QvY,1391
+electricore_client/arrow.py,sha256=IrUecusae-MgJ6lk-Ar0JO_CCz6rZggfyiH05ZHOiug,4841
+electricore_client/client.py,sha256=4MbDPKkAVOtFb-2zdhonxnoPLLM2ofwaQSbZLFCO7ZE,7082
+electricore_client/exceptions.py,sha256=qEgChZKqsbrfKewR5ZWOPQAHzccQhrEfqnHK_NSIT1g,1207
+electricore_client/headers.py,sha256=WphP2TLqh1UMxCWL0bbihvuvXUsOh_6xILiQgEFSbc8,1461
+electricore_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+electricore_client/streaming.py,sha256=Lu9HLphVLFM9Qez7ixtY5Ej1xhVv5RRjjWvte20UIAk,4098
+electricore_client/transport.py,sha256=Uy3bUvLHs6ePKNefztJD3AuXBHysmq2JaTpBRd58syw,3425
+electricore_client/models/__init__.py,sha256=RpQWIZZoGkqamq8kG0BibTjt7P-_5HkpIlVuIQESulY,1089
+electricore_client/models/chronologie.py,sha256=yoiBzZTYFRWVYTcHFPSfhvoK8YfRsNJqNiouSz58ts8,4076
+electricore_client/models/meta_periodes.py,sha256=KfFGaTWfDcRd060-Xt7iJh976Kctt02app8j8UidYBs,3083
+electricore_client/models/turpe_variable.py,sha256=o9jCICtmyIwzI4ntqnzR7lXIAnC0MDT09cwumn2hnWk,2201
+electricore_client-0.1.0.dist-info/METADATA,sha256=Z33_XxaHOj5nIW__LHIbJFCB-3hVrpOi2hHGYIW6Xyc,2811
+electricore_client-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+electricore_client-0.1.0.dist-info/RECORD,,

electricore_client-0.1.0.dist-info/WHEEL

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