hubeau-data 0.0.1__tar.gz

hubeau_data-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  qa:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run Ruff Linter
+        run: uv run ruff check .
+
+      - name: Run Mypy Type Checking
+        run: uv run mypy .
+
+      - name: Run Mocked Tests
+        run: uv run pytest -m "not live"

hubeau_data-0.0.1/.gitignore

@@ -0,0 +1,58 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.env/
+.venv/
+
+# Poetry
+poetry.lock
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+
+# Jupyter Notebook checkpoints
+.ipynb_checkpoints
+
+# PyCharm settings
+.idea/
+*.iml
+
+# Mac OS
+.DS_Store
+
+# Windows
+Thumbs.db
+
+# Local environment variables and secrets
+.env
+.env.*
+
+# Ignore mypy daemon status file (auto-generated, local only)
+.dmypy.json
+
+# data generated during exploration
+data/
+.virtual_documents/
+.virtual_documents/

hubeau_data-0.0.1/.helix/languages.toml

@@ -0,0 +1,11 @@
+[language-server.jedi-language-server]
+command = ".venv/bin/jedi-language-server"
+args = []
+
+[language-server.jedi-language-server.config]
+workspace.environmentPath = ".venv"
+jediSettings.autoImportModules = ["httpx", "pydantic", "pandas"]
+
+[[language]]
+name = "python"
+language-servers = ["ruff", "jedi-language-server"]

hubeau_data-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: Ruff Check
+        entry: uv run ruff check .
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+
+      - id: ci-check
+        name: Run Full CI (Lint, Type, Test)
+        entry: bash -c "uv run ruff check . && uv run mypy . && uv run pytest -m 'not live'"
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

hubeau_data-0.0.1/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+### Added
+
+- Full Hub'Eau API coverage — 11 APIs implemented:
+  `hydrometrie`, `qualite_rivieres`, `piezometrie`, `qualite_nappes`,
+  `ecoulement`, `temperature`, `prelevements`, `hydrobiologie`,
+  `poisson`, `eau_potable`, `phytopharmaceutiques`
+- `check_health(n_requests)` on every API — latency stats, healthy ratio
+- `data_coverage(...)` on every API — data availability windows
+- CLI health check scripts for every API under `scripts/<api>/check_health.py`
+- Typed `Params` models for every endpoint across all APIs
+- Pydantic v2 models for all API responses
+- Pydantic mypy plugin for strict type checking
+- Mocked test suite using `pytest-httpx` — CI runs without network dependency
+- `@pytest.mark.live` marker to separate integration from unit tests
+- `xfail` markers on known unstable endpoints (qualite_rivieres, qualite_nappes,
+  temperature chronique, prelevements chroniques)
+- `models/health.py` — shared `EndpointStatus`, `HealthReport`, `DataWindow`,
+  `CoverageReport` models
+- Optional dependency groups: `[dataframe]`, `[geo]`, `[viz]`, `[all]`
+- `CHANGELOG.md` + `CONTRIBUTING.md`
+- CI badge in README
+
+### Changed
+
+- Migrated all API methods from `**kwargs` to typed `Params` models
+- Rewrote README: full API coverage table, assertive tone, accurate quickstart
+- Split runtime dependencies — core install requires only `httpx` and `pydantic`
+- Pinned `mypy<2.0` pending pydantic plugin compatibility with mypy 2.x
+- Removed `SimpleHydrometrieClient` — `HubeauClient` is the single entry point
+
+### Fixed
+
+- `get_obs_elab` was outside `HydrometrieAPI` class (indentation bug)
+- `code_entite` → `code_station` for hydrometrie observations (API mismatch)
+- `Station` and `Site` fields relaxed to `Optional` — Hub'Eau returns null on many fields
+- `phytopharmaceutiques` BASE_URL corrected to `/api/v1/vente_achat_phyto`
+
+### Skipped
+
+- **Surveillance Littoral** — API being decommissioned by Hub'Eau
+- **Indicateurs Services** — API under maintenance

hubeau_data-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/pfei/hubeau-data.git
+cd hubeau-data
+uv sync --all-extras
+```
+
+## Quality checks
+
+Run these before every commit (pre-commit handles this automatically after `uv run pre-commit install`):
+
+```bash
+uv run ruff check .          # lint
+uv run mypy .                # type check (strict)
+uv run pytest -m "not live"  # fast mocked tests
+```
+
+To run the full suite including real API calls:
+
+```bash
+uv run pytest -m "live" -s
+```
+
+## Test markers
+
+- Tests without a marker: mocked, deterministic, run in CI
+- `@pytest.mark.live`: real network calls — may be slow or flaky depending on upstream API health
+
+## Commit conventions
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/):
+
+Examples:
+
+- `feat(hydrometrie): add pagination support for obs_elab`
+- `fix(qualite_rivieres): handle empty data response`
+- `refactor(models): migrate SiteParams to typed fields`
+- `docs: update README quickstart`
+- `test: add mocked tests for hydrometrie endpoints`
+- `build: add optional dependency groups`
+
+## Adding a new Hub'Eau API
+
+- 1. Add Pydantic response models in `src/hubeau_data/models/<api_name>.py`
+- 2. Add typed `Params` models in the same file
+- 3. Add the API client in `src/hubeau_data/api/<api_name>.py`
+- 4. Register it on `HubeauClient` in `src/hubeau_data/client.py`
+- 5. Add mocked + live tests in `tests/test_<api_name>.py`
+- 6. Update `README.md` API coverage table

hubeau_data-0.0.1/LICENCE.md

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

hubeau_data-0.0.1/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: hubeau-data
+Version: 0.0.1
+Summary: Pythonic, typed, modern client for the Hubeau water data APIs.
+Project-URL: Homepage, https://github.com/pfei/hubeau-data
+Project-URL: Repository, https://github.com/pfei/hubeau-data
+Project-URL: Changelog, https://github.com/pfei/hubeau-data/blob/main/CHANGELOG.md
+Author-email: Pierre Feilles <pierre.feilles@gmail.com>
+License-Expression: MIT
+License-File: LICENCE.md
+Keywords: api-client,france,hubeau,hydrology,open-data,water
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: tenacity>=9.1.4
+Provides-Extra: all
+Requires-Dist: geopandas>=1.0.1; extra == 'all'
+Requires-Dist: matplotlib>=3.10.3; extra == 'all'
+Requires-Dist: pandas>=2.2.0; extra == 'all'
+Requires-Dist: shapely>=2.1.1; extra == 'all'
+Provides-Extra: dataframe
+Requires-Dist: pandas>=2.2.0; extra == 'dataframe'
+Provides-Extra: geo
+Requires-Dist: geopandas>=1.0.1; extra == 'geo'
+Requires-Dist: shapely>=2.1.1; extra == 'geo'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.10.3; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# hubeau-data
+
+[![CI](https://github.com/pfei/hubeau-data/actions/workflows/ci.yml/badge.svg)](https://github.com/pfei/hubeau-data/actions/workflows/ci.yml)
+[![Python Version](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/)
+[![Checked with mypy](https://img.shields.io/badge/mypy-strict-green.svg)](https://mypy.readthedocs.io/en/stable/config_file.html#using-a-pyproject-toml-file)
+[![Linting: ruff](https://img.shields.io/badge/linting-ruff-orange.svg)](https://github.com/astral-sh/ruff)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Package Manager: uv](https://img.shields.io/badge/managed%20by-uv-purple.svg)](https://github.com/astral-sh/uv)
+
+Typed, modern Python client for the [Hub'Eau](https://hubeau.eaufrance.fr/) water data APIs.
+
+Hub'Eau exposes 15+ REST APIs for French national water data — but no official typed Python client exists.
+This library fills that gap: Pydantic v2 models, strict typing, and a clean interface ready for data science workflows.
+
+## Quickstart
+
+```python
+from hubeau_data.client import HubeauClient
+from hubeau_data.models.hydrometrie import ObservationTrParams
+from hubeau_data.models.qualite_rivieres import StationPcParams
+
+client = HubeauClient()
+
+# Hydrométrie — real-time observations
+params = ObservationTrParams(code_station=["Y120201001"], size=3)
+observations = client.hydrometrie.get_observations_tr(params=params)
+print(observations[0].date_obs, observations[0].resultat_obs)
+
+# Qualité Rivières — water quality stations
+stations = client.qualite_rivieres.get_stations(
+    params=StationPcParams(code_departement=["75"], size=3)
+)
+print(stations[0].code_station, stations[0].libelle_station)
+
+# Eau potable — drinking water analyses for a commune
+from hubeau_data.models.eau_potable import ResultatEauPotableParams
+resultats = client.eau_potable.get_resultats_dis(
+    params=ResultatEauPotableParams(code_commune=["75056"], size=5)
+)
+print(resultats[0].libelle_parametre, resultats[0].resultat_numerique)
+
+# Phytopharmaceutiques — national pesticide sales
+from hubeau_data.models.phytopharmaceutiques import VenteSubstanceParams
+ventes = client.phytopharmaceutiques.get_ventes_substances(
+    params=VenteSubstanceParams(type_territoire="National", size=5)
+)
+print(ventes[0].libelle_substance, ventes[0].quantite, ventes[0].annee)
+
+# API health check — works on every API
+report = client.hydrometrie.check_health(n_requests=3)
+print(report.summary())
+
+# Data coverage — spot-check stations
+cov = client.hydrometrie.data_coverage(code_station="Y120201001")
+print(cov.summary())
+```
+
+## Async client
+
+For bulk data collection — e.g. fetching many stations before inserting into a database —
+`AsyncHubeauClient` mirrors the sync client and supports `asyncio.gather()` for parallel requests:
+
+```python
+import asyncio
+from hubeau_data.async_client import AsyncHubeauClient
+from hubeau_data.models.hydrometrie import ObservationTrParams
+
+async def main():
+    async with AsyncHubeauClient() as client:
+        codes = ["Y120201001", "K418001001", "A1234567"]
+        tasks = [
+            client.hydrometrie.get_observations_tr(
+                params=ObservationTrParams(code_station=[c], size=10)
+            )
+            for c in codes
+        ]
+        results = await asyncio.gather(*tasks)
+        for code, obs in zip(codes, results):
+            print(code, len(obs), "observations")
+
+asyncio.run(main())
+```
+
+All 11 APIs are available on `AsyncHubeauClient` with the same method names as the sync client
+(`get_sites`, `get_stations`, etc.) — just `await` them. Retry logic (tenacity) applies to async
+requests too. `check_health` and `data_coverage` are sync-only (diagnostic tools, not bulk operations).
+
+## API Coverage
+
+| API | Status | Notes |
+|-----|--------|-------|
+| **Hydrométrie** | ✅ Supported | Sites, stations, real-time and elaborated observations |
+| **Qualité des cours d'eau** | ⚠️ Partial | Stations and analyses. Upstream API has known stability issues |
+| **Piézométrie** | ✅ Supported | Stations, chroniques, chroniques temps réel |
+| **Qualité des nappes** | ⚠️ Partial | Stations and analyses. Known 503/timeout issues |
+| **Écoulement** | ✅ Supported | Stations, observations, campaigns |
+| **Température** | ✅ Supported | Stations and chroniques |
+| **Prélèvements en eau** | ✅ Supported | Ouvrages, points de prélèvement, chroniques |
+| **Hydrobiologie** | ✅ Supported | Stations, indices (IBGN/IBMR/IBD/IPR), taxons |
+| **Poisson** | ✅ Supported | Stations, indicateurs IPR/IPR+, observations, operations |
+| **Qualité eau potable** | ✅ Supported | Communes/UDI links, analysis results |
+| **Phytopharmaceutiques** | ✅ Supported | Purchases and sales by substance and product |
+| **Surveillance Littoral** | 🚫 Skipped | API being decommissioned by Hub'Eau |
+| **Indicateurs Services** | 🚧 Maintenance | API under maintenance — see services.eaufrance.fr |
+
+All supported APIs expose `check_health(n_requests)` and `data_coverage(...)`, and are available
+on both `HubeauClient` (sync) and `AsyncHubeauClient` (async, except health/coverage).
+
+## Features
+
+- Pydantic v2 models for all responses — strict runtime validation, IDE autocomplete
+- Typed query `Params` models for every endpoint — no more `**kwargs`
+- Sync (`HubeauClient`) and async (`AsyncHubeauClient`) clients, same method names
+- Automatic retry with exponential backoff (tenacity) on transient errors — Hub'Eau APIs have known stability issues
+- `check_health(n_requests)` — latency stats per endpoint, healthy ratio
+- `data_coverage(...)` — data availability windows per station or territory
+- Optional extras: `[dataframe]`, `[geo]`, `[viz]` — install only what you need
+
+## Stack
+
+- Python 3.13+, `mypy --strict`, `ruff`, `uv`, `hatchling`, src-layout
+- `httpx` + `tenacity` for resilient sync/async HTTP
+- `pytest-httpx` mocked test suite — CI runs without network dependency
+
+## Installation & Development
+
+```zsh
+git clone https://github.com/pfei/hubeau-data.git
+cd hubeau-data
+uv sync                   # core only
+uv sync --all-extras      # with pandas, geopandas, matplotlib
+```
+
+```zsh
+uv run ruff check .           # lint
+uv run mypy .                 # type check
+uv run pytest -m "not live"   # fast mocked tests (CI)
+uv run pytest -m "live" -s    # real network integration tests
+```
+
+## Examples & Scripts
+
+```zsh
+uv run python examples/demo.py
+uv run jupyter lab            # open examples/demo.ipynb
+```
+
+Health check scripts for every API under `scripts/<api>/check_health.py`:
+
+```zsh
+uv run python scripts/hydrometrie/check_health.py --n-requests 3 --random
+uv run python scripts/qualite_rivieres/check_health.py --n-requests 2
+uv run python scripts/eau_potable/check_health.py --commune 75056
+uv run python scripts/phytopharmaceutiques/check_health.py
+```
+
+Exploration scripts under `scripts/qualite_rivieres/` and `scripts/hydrometrie/`.
+
+## Roadmap
+
+- [x] Full Hub'Eau API coverage (11 APIs implemented)
+- [x] `check_health` and `data_coverage` on all APIs
+- [x] Typed `Params` models for every endpoint
+- [x] Automatic retry with exponential backoff (tenacity)
+- [x] Async client (`AsyncHubeauClient`, all 11 APIs)
+- [x] Optional dependency groups — `pandas`, `geopandas`, `matplotlib` as extras
+- [x] `CHANGELOG.md` + `CONTRIBUTING.md`
+- [ ] PyPI release
+
+## License
+
+MIT © Pierre Feilles

hubeau_data-0.0.1/README.md

@@ -0,0 +1,172 @@
+# hubeau-data
+
+[![CI](https://github.com/pfei/hubeau-data/actions/workflows/ci.yml/badge.svg)](https://github.com/pfei/hubeau-data/actions/workflows/ci.yml)
+[![Python Version](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/)
+[![Checked with mypy](https://img.shields.io/badge/mypy-strict-green.svg)](https://mypy.readthedocs.io/en/stable/config_file.html#using-a-pyproject-toml-file)
+[![Linting: ruff](https://img.shields.io/badge/linting-ruff-orange.svg)](https://github.com/astral-sh/ruff)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Package Manager: uv](https://img.shields.io/badge/managed%20by-uv-purple.svg)](https://github.com/astral-sh/uv)
+
+Typed, modern Python client for the [Hub'Eau](https://hubeau.eaufrance.fr/) water data APIs.
+
+Hub'Eau exposes 15+ REST APIs for French national water data — but no official typed Python client exists.
+This library fills that gap: Pydantic v2 models, strict typing, and a clean interface ready for data science workflows.
+
+## Quickstart
+
+```python
+from hubeau_data.client import HubeauClient
+from hubeau_data.models.hydrometrie import ObservationTrParams
+from hubeau_data.models.qualite_rivieres import StationPcParams
+
+client = HubeauClient()
+
+# Hydrométrie — real-time observations
+params = ObservationTrParams(code_station=["Y120201001"], size=3)
+observations = client.hydrometrie.get_observations_tr(params=params)
+print(observations[0].date_obs, observations[0].resultat_obs)
+
+# Qualité Rivières — water quality stations
+stations = client.qualite_rivieres.get_stations(
+    params=StationPcParams(code_departement=["75"], size=3)
+)
+print(stations[0].code_station, stations[0].libelle_station)
+
+# Eau potable — drinking water analyses for a commune
+from hubeau_data.models.eau_potable import ResultatEauPotableParams
+resultats = client.eau_potable.get_resultats_dis(
+    params=ResultatEauPotableParams(code_commune=["75056"], size=5)
+)
+print(resultats[0].libelle_parametre, resultats[0].resultat_numerique)
+
+# Phytopharmaceutiques — national pesticide sales
+from hubeau_data.models.phytopharmaceutiques import VenteSubstanceParams
+ventes = client.phytopharmaceutiques.get_ventes_substances(
+    params=VenteSubstanceParams(type_territoire="National", size=5)
+)
+print(ventes[0].libelle_substance, ventes[0].quantite, ventes[0].annee)
+
+# API health check — works on every API
+report = client.hydrometrie.check_health(n_requests=3)
+print(report.summary())
+
+# Data coverage — spot-check stations
+cov = client.hydrometrie.data_coverage(code_station="Y120201001")
+print(cov.summary())
+```
+
+## Async client
+
+For bulk data collection — e.g. fetching many stations before inserting into a database —
+`AsyncHubeauClient` mirrors the sync client and supports `asyncio.gather()` for parallel requests:
+
+```python
+import asyncio
+from hubeau_data.async_client import AsyncHubeauClient
+from hubeau_data.models.hydrometrie import ObservationTrParams
+
+async def main():
+    async with AsyncHubeauClient() as client:
+        codes = ["Y120201001", "K418001001", "A1234567"]
+        tasks = [
+            client.hydrometrie.get_observations_tr(
+                params=ObservationTrParams(code_station=[c], size=10)
+            )
+            for c in codes
+        ]
+        results = await asyncio.gather(*tasks)
+        for code, obs in zip(codes, results):
+            print(code, len(obs), "observations")
+
+asyncio.run(main())
+```
+
+All 11 APIs are available on `AsyncHubeauClient` with the same method names as the sync client
+(`get_sites`, `get_stations`, etc.) — just `await` them. Retry logic (tenacity) applies to async
+requests too. `check_health` and `data_coverage` are sync-only (diagnostic tools, not bulk operations).
+
+## API Coverage
+
+| API | Status | Notes |
+|-----|--------|-------|
+| **Hydrométrie** | ✅ Supported | Sites, stations, real-time and elaborated observations |
+| **Qualité des cours d'eau** | ⚠️ Partial | Stations and analyses. Upstream API has known stability issues |
+| **Piézométrie** | ✅ Supported | Stations, chroniques, chroniques temps réel |
+| **Qualité des nappes** | ⚠️ Partial | Stations and analyses. Known 503/timeout issues |
+| **Écoulement** | ✅ Supported | Stations, observations, campaigns |
+| **Température** | ✅ Supported | Stations and chroniques |
+| **Prélèvements en eau** | ✅ Supported | Ouvrages, points de prélèvement, chroniques |
+| **Hydrobiologie** | ✅ Supported | Stations, indices (IBGN/IBMR/IBD/IPR), taxons |
+| **Poisson** | ✅ Supported | Stations, indicateurs IPR/IPR+, observations, operations |
+| **Qualité eau potable** | ✅ Supported | Communes/UDI links, analysis results |
+| **Phytopharmaceutiques** | ✅ Supported | Purchases and sales by substance and product |
+| **Surveillance Littoral** | 🚫 Skipped | API being decommissioned by Hub'Eau |
+| **Indicateurs Services** | 🚧 Maintenance | API under maintenance — see services.eaufrance.fr |
+
+All supported APIs expose `check_health(n_requests)` and `data_coverage(...)`, and are available
+on both `HubeauClient` (sync) and `AsyncHubeauClient` (async, except health/coverage).
+
+## Features
+
+- Pydantic v2 models for all responses — strict runtime validation, IDE autocomplete
+- Typed query `Params` models for every endpoint — no more `**kwargs`
+- Sync (`HubeauClient`) and async (`AsyncHubeauClient`) clients, same method names
+- Automatic retry with exponential backoff (tenacity) on transient errors — Hub'Eau APIs have known stability issues
+- `check_health(n_requests)` — latency stats per endpoint, healthy ratio
+- `data_coverage(...)` — data availability windows per station or territory
+- Optional extras: `[dataframe]`, `[geo]`, `[viz]` — install only what you need
+
+## Stack
+
+- Python 3.13+, `mypy --strict`, `ruff`, `uv`, `hatchling`, src-layout
+- `httpx` + `tenacity` for resilient sync/async HTTP
+- `pytest-httpx` mocked test suite — CI runs without network dependency
+
+## Installation & Development
+
+```zsh
+git clone https://github.com/pfei/hubeau-data.git
+cd hubeau-data
+uv sync                   # core only
+uv sync --all-extras      # with pandas, geopandas, matplotlib
+```
+
+```zsh
+uv run ruff check .           # lint
+uv run mypy .                 # type check
+uv run pytest -m "not live"   # fast mocked tests (CI)
+uv run pytest -m "live" -s    # real network integration tests
+```
+
+## Examples & Scripts
+
+```zsh
+uv run python examples/demo.py
+uv run jupyter lab            # open examples/demo.ipynb
+```
+
+Health check scripts for every API under `scripts/<api>/check_health.py`:
+
+```zsh
+uv run python scripts/hydrometrie/check_health.py --n-requests 3 --random
+uv run python scripts/qualite_rivieres/check_health.py --n-requests 2
+uv run python scripts/eau_potable/check_health.py --commune 75056
+uv run python scripts/phytopharmaceutiques/check_health.py
+```
+
+Exploration scripts under `scripts/qualite_rivieres/` and `scripts/hydrometrie/`.
+
+## Roadmap
+
+- [x] Full Hub'Eau API coverage (11 APIs implemented)
+- [x] `check_health` and `data_coverage` on all APIs
+- [x] Typed `Params` models for every endpoint
+- [x] Automatic retry with exponential backoff (tenacity)
+- [x] Async client (`AsyncHubeauClient`, all 11 APIs)
+- [x] Optional dependency groups — `pandas`, `geopandas`, `matplotlib` as extras
+- [x] `CHANGELOG.md` + `CONTRIBUTING.md`
+- [ ] PyPI release
+
+## License
+
+MIT © Pierre Feilles