electricore-client 0.1.0__tar.gz

electricore_client-0.1.0/.gitignore

@@ -0,0 +1,202 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!deploy/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc
+
+# Codanna code intelligence cache
+.codanna/
+.codannaignore
+.fastembed_cache/
+
+# DLT secrets (credentials, API keys)
+electricore/ingestion/.dlt/secrets.toml
+
+# Données locales générées
+*.duckdb
+perimetre_manquants/
+surveillance_perimetre_manquants.csv
+.serena/
+
+# Artefacts de déploiement Docker générés à partir des fichiers .example
+# (les utilisateurs copient *.example vers la version sans suffixe pour les éditer)
+deploy/docker/Caddyfile
+deploy/docker/crontab
+deploy/docker/docker-compose.*.yml
+!deploy/docker/docker-compose.yml
+
+# Sortie locale du skill /sota-scan
+.sota/
+
+# Artefacts de build dbt (target par base, cf. pipeline_dbt)
+electricore/ingestion/.dbt_target_*/
+
+# repo-scoped GitHub PAT for in-sandbox automation — never commit
+.gh-token

electricore_client-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog — electricore-client
+
+Toutes les évolutions notables de ce paquet sont consignées ici.
+Le format suit [Keep a Changelog](https://keepachangelog.com/fr/1.0.0/) ;
+le versionnage suit [SemVer](https://semver.org/lang/fr/).
+
+## [0.1.0] — non publié
+
+### Ajouté
+- Squelette du paquet `electricore-client` (top-level `electricore_client`),
+  distribué séparément du moteur. Dépendances de base **httpx + pydantic**.
+- Substrat de transport partagé `_BaseClient` : URL de base, en-tête
+  `X-API-Key`, timeout, conversion d'erreur HTTP **503 → `IngestionEnCours`**,
+  garde de version de contrat asymétrique (warn si serveur en avance, raise si
+  en retard).
+- Modèle d'en-têtes de métadonnées `EnTetesMeta` (`contract_version`, `mois`,
+  `grain`).
+- Méthode `meta_periodes(...)` : flux JSONL typé de `PeriodeMeta` (contrat v3,
+  relevés imbriqués ADR-0038), context-manager, métadonnées en en-têtes,
+  sans pagination, `.collect()`.
+- Méthode `chronologie(...)` : flux JSONL d'une union discriminée
+  `LigneChronologie` (`LigneEvenement | LigneReleve | LignePeriodeEnergie`,
+  contrat v1), validation `pdl` XOR `rsc` côté client.
+- Méthode `turpe_variable(...)` : POST RPC, résultats typés indexés par l'`id`
+  opaque ré-émis. Modèles `LigneTurpeVariable` / résultat single-sourcés.
+- Extra `[arrow]` : client Arrow historique (`flux/releves/facturation/accise/
+  cta` → `pl.DataFrame`) dans `electricore_client.arrow`, polars importé
+  paresseusement (la base reste polars-free).
+- CI/CD : `release-client.yml` (tags `client-v*`, publication PyPI Trusted
+  Publishing / OIDC) + job `test-client` (install isolé, garantie polars-free).
+  Conception : ADR-0043.

electricore_client-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,44 @@
+# 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/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "electricore-client"
+version = "0.1.0"
+description = "Client Python léger (httpx + pydantic) vers l'API facturiste electricore — sans polars/duckdb/fastapi"
+authors = [
+    {name = "Virgile"}
+]
+license = {text = "AGPL-3.0"}
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = [
+    "electricore",
+    "energy",
+    "enedis",
+    "api-client",
+    "facturation",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Affero General Public License v3",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+# Deps de base STRICTEMENT légères : httpx + pydantic (aucune trace de
+# polars/duckdb/fastapi). C'est l'invariant prouvé par le test de pureté.
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+# Extra `arrow` : recolle le client Arrow historique (DataFrames polars).
+# polars n'est importé que paresseusement, dans le sous-module Arrow — jamais
+# au top-level (l'invariant de pureté tient sans cet extra).
+arrow = [
+    "polars>=1.0.0,<2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Energie-De-Nantes/electricore"
+Repository = "https://github.com/Energie-De-Nantes/electricore"
+Issues = "https://github.com/Energie-De-Nantes/electricore/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/electricore_client"]
+
+[dependency-groups]
+test = [
+    "pytest>=8.2.0",
+]

electricore_client-0.1.0/src/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-0.1.0/src/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"]