permisapi-client 0.1.0__tar.gz

permisapi_client-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.local
+.env.*.backup
+.env.backup-*
+.env.*.local
+
+# Secrets inventory (file listant les valeurs sensibles a copier dans
+# 1Password/Bitwarden avant de changer de machine). Ne doit JAMAIS
+# remonter sur git.
+SECRETS_INVENTORY.md
+
+# Claude Code workspace (launch.json personnel)
+.claude/
+
+# Data (too big, ignored)
+data/raw/*.csv
+data/raw/*.zip
+data/processed/*.parquet
+
+# Database
+*.sqlite
+*.db
+
+# Logs
+*.log
+logs/
+
+# Tests
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Node (landing page)
+landing/node_modules/
+landing/.next/
+landing/out/
+
+# Post-piratage rotation (contient les nouvelles cles API en clair)
+secrets_NEW_KEYS.json
+scrape-downloads/

permisapi_client-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: permisapi-client
+Version: 0.1.0
+Summary: Client Python officiel pour PermisAPI : permis de construire France en API REST.
+Project-URL: Homepage, https://permisapi.fr
+Project-URL: Documentation, https://permisapi.fr/docs
+Project-URL: Changelog, https://permisapi.fr/changelog
+Author-email: Evan Caroux <evan@permisapi.fr>
+License: MIT
+Keywords: api,construire,france,geocoding,permis,proptech,real-estate,sitadel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: French
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# permisapi-client
+
+Client Python officiel pour [PermisAPI](https://permisapi.fr) : accede aux 311k+ permis de construire France via une API REST moderne.
+
+## Installation
+
+```bash
+pip install permisapi-client
+```
+
+## Quickstart
+
+```python
+from permisapi_client import PermisAPI
+
+client = PermisAPI(api_key="pk_live_...")  # obtenue sur https://permisapi.fr/#pricing
+
+# Liste
+data = client.permits.list(dep_code="75", limit=10)
+for permit in data["items"]:
+    print(permit["num_pa"], permit["adr_localite_ter"])
+
+# Recherche geographique (PostGIS)
+nearby = client.permits.near(lat=48.85, lng=2.35, radius_m=500)
+
+# Detail
+permit = client.permits.get("PC 075 115 24 B0001")
+
+# Stats par commune
+stats = client.stats.commune("75115")
+print(stats["total"], stats["granted"])
+
+# Itere sur toutes les pages
+for p in client.permits.iter_all(dep_code="75"):
+    print(p["num_pa"])
+```
+
+## Async
+
+```python
+import asyncio
+from permisapi_client import AsyncPermisAPI
+
+async def main():
+    async with AsyncPermisAPI(api_key="pk_live_...") as client:
+        data = await client.permits.list(dep_code="75")
+        async for p in client.permits.iter_all(dep_code="75"):
+            print(p["num_pa"])
+
+asyncio.run(main())
+```
+
+## Alertes webhook
+
+```python
+alert = client.alerts.create(
+    name="Paris 18e renovations",
+    center_lat=48.88,
+    center_lng=2.35,
+    radius_km=3,
+    permit_types=["PC_LOGEMENT"],
+    webhook_url="https://tonapp.fr/permisapi-hook",
+)
+# Le webhook_secret n'est renvoye QU'ICI. Stocke-le pour verifier les HMAC.
+print(alert["webhook_secret"])
+```
+
+## Gestion des erreurs
+
+```python
+from permisapi_client import (
+    PermisAPI,
+    PermisAPIRateLimited,
+    PermisAPIQuotaExceeded,
+    PermisAPIUnauthorized,
+)
+
+try:
+    client.permits.list()
+except PermisAPIUnauthorized:
+    print("Cle API invalide")
+except PermisAPIQuotaExceeded as e:
+    print(f"Quota mensuel atteint, retry dans {e.retry_after}s")
+except PermisAPIRateLimited as e:
+    print(f"Burst limit, retry dans {e.retry_after}s")
+```
+
+## Licence
+
+MIT. Source : SDES, base Sitadel, data.gouv.fr (Licence Ouverte Etalab).
+
+## Liens
+
+- Documentation : https://permisapi.fr/docs
+- Reference API complete : https://api.permisapi.fr/docs
+- Changelog : https://permisapi.fr/changelog

permisapi_client-0.1.0/README.md

@@ -0,0 +1,96 @@
+# permisapi-client
+
+Client Python officiel pour [PermisAPI](https://permisapi.fr) : accede aux 311k+ permis de construire France via une API REST moderne.
+
+## Installation
+
+```bash
+pip install permisapi-client
+```
+
+## Quickstart
+
+```python
+from permisapi_client import PermisAPI
+
+client = PermisAPI(api_key="pk_live_...")  # obtenue sur https://permisapi.fr/#pricing
+
+# Liste
+data = client.permits.list(dep_code="75", limit=10)
+for permit in data["items"]:
+    print(permit["num_pa"], permit["adr_localite_ter"])
+
+# Recherche geographique (PostGIS)
+nearby = client.permits.near(lat=48.85, lng=2.35, radius_m=500)
+
+# Detail
+permit = client.permits.get("PC 075 115 24 B0001")
+
+# Stats par commune
+stats = client.stats.commune("75115")
+print(stats["total"], stats["granted"])
+
+# Itere sur toutes les pages
+for p in client.permits.iter_all(dep_code="75"):
+    print(p["num_pa"])
+```
+
+## Async
+
+```python
+import asyncio
+from permisapi_client import AsyncPermisAPI
+
+async def main():
+    async with AsyncPermisAPI(api_key="pk_live_...") as client:
+        data = await client.permits.list(dep_code="75")
+        async for p in client.permits.iter_all(dep_code="75"):
+            print(p["num_pa"])
+
+asyncio.run(main())
+```
+
+## Alertes webhook
+
+```python
+alert = client.alerts.create(
+    name="Paris 18e renovations",
+    center_lat=48.88,
+    center_lng=2.35,
+    radius_km=3,
+    permit_types=["PC_LOGEMENT"],
+    webhook_url="https://tonapp.fr/permisapi-hook",
+)
+# Le webhook_secret n'est renvoye QU'ICI. Stocke-le pour verifier les HMAC.
+print(alert["webhook_secret"])
+```
+
+## Gestion des erreurs
+
+```python
+from permisapi_client import (
+    PermisAPI,
+    PermisAPIRateLimited,
+    PermisAPIQuotaExceeded,
+    PermisAPIUnauthorized,
+)
+
+try:
+    client.permits.list()
+except PermisAPIUnauthorized:
+    print("Cle API invalide")
+except PermisAPIQuotaExceeded as e:
+    print(f"Quota mensuel atteint, retry dans {e.retry_after}s")
+except PermisAPIRateLimited as e:
+    print(f"Burst limit, retry dans {e.retry_after}s")
+```
+
+## Licence
+
+MIT. Source : SDES, base Sitadel, data.gouv.fr (Licence Ouverte Etalab).
+
+## Liens
+
+- Documentation : https://permisapi.fr/docs
+- Reference API complete : https://api.permisapi.fr/docs
+- Changelog : https://permisapi.fr/changelog

permisapi_client-0.1.0/permisapi_client/__init__.py

@@ -0,0 +1,33 @@
+"""Client Python officiel pour PermisAPI.
+
+Usage sync :
+    from permisapi_client import PermisAPI
+    client = PermisAPI(api_key="pk_live_...")
+    for permit in client.permits.list(dep_code="75", limit=10):
+        print(permit["num_pa"], permit["adr_localite_ter"])
+
+Usage async :
+    from permisapi_client import AsyncPermisAPI
+    async with AsyncPermisAPI(api_key="pk_live_...") as client:
+        permits = await client.permits.near(lat=48.85, lng=2.35, radius_m=500)
+"""
+from permisapi_client.client import AsyncPermisAPI, PermisAPI
+from permisapi_client.exceptions import (
+    PermisAPIError,
+    PermisAPIQuotaExceeded,
+    PermisAPIRateLimited,
+    PermisAPIUnauthorized,
+    PermisAPIValidationError,
+)
+
+__all__ = [
+    "PermisAPI",
+    "AsyncPermisAPI",
+    "PermisAPIError",
+    "PermisAPIUnauthorized",
+    "PermisAPIRateLimited",
+    "PermisAPIQuotaExceeded",
+    "PermisAPIValidationError",
+]
+
+__version__ = "0.1.0"

permisapi_client-0.1.0/permisapi_client/client.py

@@ -0,0 +1,384 @@
+"""PermisAPI sync + async client.
+
+Minimal, no ORM. Returns dict / list[dict] pour rester flexible aux
+futurs changements de schema cote API.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterator, AsyncIterator
+
+import httpx
+
+from permisapi_client.exceptions import error_from_response
+
+DEFAULT_BASE_URL = "https://api.permisapi.fr"
+DEFAULT_TIMEOUT = 15.0
+USER_AGENT = "permisapi-client-python/0.1.0"
+
+
+def _raise_for_status(resp: httpx.Response) -> None:
+    if 200 <= resp.status_code < 300:
+        return
+    try:
+        payload = resp.json()
+    except ValueError:
+        payload = {"message": resp.text[:200] or "Erreur inconnue"}
+    if "retry_after" not in payload and "Retry-After" in resp.headers:
+        try:
+            payload["retry_after"] = int(resp.headers["Retry-After"])
+        except ValueError:
+            pass
+    raise error_from_response(resp.status_code, payload)
+
+
+def _build_headers(api_key: str, extra: dict[str, str] | None = None) -> dict[str, str]:
+    h = {
+        "X-API-Key": api_key,
+        "Accept": "application/json",
+        "User-Agent": USER_AGENT,
+    }
+    if extra:
+        h.update(extra)
+    return h
+
+
+# ---------------------------------------------------------------------------
+# Sync client
+# ---------------------------------------------------------------------------
+
+
+class _PermitsResource:
+    def __init__(self, client: PermisAPI) -> None:
+        self._c = client
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        """GET /v1/permits avec filtres. Retourne {items, pagination}."""
+        return self._c._get("/v1/permits", params=params)
+
+    def iter_all(self, **params: Any) -> Iterator[dict[str, Any]]:
+        """Itere sur toutes les pages (limite fixee par le plan)."""
+        page = 1
+        per_page = params.get("limit", 100)
+        while True:
+            p = {**params, "page": page, "limit": per_page}
+            data = self.list(**p)
+            items = data.get("items", [])
+            if not items:
+                return
+            yield from items
+            pages = (data.get("pagination") or {}).get("pages", 1)
+            if page >= pages:
+                return
+            page += 1
+
+    def get(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}."""
+        return self._c._get(f"/v1/permits/{num_pa}")
+
+    def near(
+        self, *, lat: float, lng: float, radius_m: int, **filters: Any
+    ) -> dict[str, Any]:
+        """GET /v1/permits/near?lat&lng&radius_m (PostGIS)."""
+        return self._c._get(
+            "/v1/permits/near",
+            params={"lat": lat, "lng": lng, "radius_m": radius_m, **filters},
+        )
+
+    def by_cadastre(self, *, section: str, numero: str) -> dict[str, Any]:
+        return self._c._get(
+            "/v1/permits/by-cadastre",
+            params={"section": section, "numero": numero},
+        )
+
+
+class _StatsResource:
+    def __init__(self, client: PermisAPI) -> None:
+        self._c = client
+
+    def commune(self, code: str) -> dict[str, Any]:
+        return self._c._get(f"/v1/stats/commune/{code}")
+
+    def departement(self, code: str) -> dict[str, Any]:
+        return self._c._get(f"/v1/stats/departement/{code}")
+
+    def region(self, code: str) -> dict[str, Any]:
+        return self._c._get(f"/v1/stats/region/{code}")
+
+    def trends(
+        self,
+        *,
+        dep_code: str | None = None,
+        comm_code: str | None = None,
+        group_by: str = "month",
+    ) -> dict[str, Any]:
+        params = {"group_by": group_by}
+        if dep_code:
+            params["dep_code"] = dep_code
+        if comm_code:
+            params["comm_code"] = comm_code
+        return self._c._get("/v1/stats/trends", params=params)
+
+    def latest_day(self) -> dict[str, Any]:
+        return self._c._get("/v1/stats/latest-day")
+
+
+class _AlertsResource:
+    def __init__(self, client: PermisAPI) -> None:
+        self._c = client
+
+    def list(self) -> list[dict[str, Any]]:
+        return self._c._get("/v1/alerts")
+
+    def create(
+        self,
+        *,
+        name: str,
+        center_lat: float,
+        center_lng: float,
+        radius_km: float,
+        webhook_url: str,
+        permit_types: list[str] | None = None,
+        min_superficie: int | None = None,
+        etat_pa: int | None = None,
+    ) -> dict[str, Any]:
+        """Cree une alerte. Le `webhook_secret` renvoye n'est visible QU'ICI."""
+        body: dict[str, Any] = {
+            "name": name,
+            "center_lat": center_lat,
+            "center_lng": center_lng,
+            "radius_km": radius_km,
+            "webhook_url": webhook_url,
+        }
+        if permit_types:
+            body["permit_types"] = permit_types
+        if min_superficie is not None:
+            body["min_superficie"] = min_superficie
+        if etat_pa is not None:
+            body["etat_pa"] = etat_pa
+        return self._c._post("/v1/alerts", json=body)
+
+    def get(self, alert_id: int) -> dict[str, Any]:
+        return self._c._get(f"/v1/alerts/{alert_id}")
+
+    def update(self, alert_id: int, **patch: Any) -> dict[str, Any]:
+        return self._c._patch(f"/v1/alerts/{alert_id}", json=patch)
+
+    def delete(self, alert_id: int) -> None:
+        self._c._delete(f"/v1/alerts/{alert_id}")
+
+    def replay(self, alert_id: int) -> dict[str, Any]:
+        return self._c._post(f"/v1/alerts/{alert_id}/replay")
+
+
+class _MeResource:
+    def __init__(self, client: PermisAPI) -> None:
+        self._c = client
+
+    def get(self) -> dict[str, Any]:
+        return self._c._get("/v1/me")
+
+    def usage(self, days: int = 30) -> dict[str, Any]:
+        return self._c._get("/v1/me/usage", params={"days": days})
+
+    def regenerate_key(self) -> dict[str, Any]:
+        """Rotate la cle. La nouvelle cle n'est visible QU'UNE FOIS."""
+        return self._c._post("/v1/me/regenerate-key")
+
+
+class PermisAPI:
+    """Client sync. Thread-safe pour des lectures concurrentes.
+
+    Args:
+        api_key: ta cle `pk_live_...` (obtenue sur https://permisapi.fr/#pricing)
+        base_url: override si tu self-host (defaut Railway prod)
+        timeout: timeout HTTP par requete (defaut 15s)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key est requise (pk_live_... ou pk_test_...)")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._http = client or httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=_build_headers(api_key),
+        )
+        self.permits = _PermitsResource(self)
+        self.stats = _StatsResource(self)
+        self.alerts = _AlertsResource(self)
+        self.me = _MeResource(self)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> PermisAPI:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # -- internal HTTP helpers --
+
+    def _get(self, path: str, *, params: dict | None = None) -> Any:
+        resp = self._http.get(path, params=params)
+        _raise_for_status(resp)
+        return resp.json()
+
+    def _post(self, path: str, *, json: dict | None = None) -> Any:
+        resp = self._http.post(path, json=json)
+        _raise_for_status(resp)
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    def _patch(self, path: str, *, json: dict | None = None) -> Any:
+        resp = self._http.patch(path, json=json)
+        _raise_for_status(resp)
+        return resp.json()
+
+    def _delete(self, path: str) -> None:
+        resp = self._http.delete(path)
+        _raise_for_status(resp)
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+
+class _AsyncPermitsResource:
+    def __init__(self, client: AsyncPermisAPI) -> None:
+        self._c = client
+
+    async def list(self, **params: Any) -> dict[str, Any]:
+        return await self._c._get("/v1/permits", params=params)
+
+    async def iter_all(self, **params: Any) -> AsyncIterator[dict[str, Any]]:
+        page = 1
+        per_page = params.get("limit", 100)
+        while True:
+            p = {**params, "page": page, "limit": per_page}
+            data = await self.list(**p)
+            items = data.get("items", [])
+            if not items:
+                return
+            for item in items:
+                yield item
+            pages = (data.get("pagination") or {}).get("pages", 1)
+            if page >= pages:
+                return
+            page += 1
+
+    async def get(self, num_pa: str) -> dict[str, Any]:
+        return await self._c._get(f"/v1/permits/{num_pa}")
+
+    async def near(
+        self, *, lat: float, lng: float, radius_m: int, **filters: Any
+    ) -> dict[str, Any]:
+        return await self._c._get(
+            "/v1/permits/near",
+            params={"lat": lat, "lng": lng, "radius_m": radius_m, **filters},
+        )
+
+
+class _AsyncStatsResource:
+    def __init__(self, client: AsyncPermisAPI) -> None:
+        self._c = client
+
+    async def commune(self, code: str) -> dict[str, Any]:
+        return await self._c._get(f"/v1/stats/commune/{code}")
+
+    async def departement(self, code: str) -> dict[str, Any]:
+        return await self._c._get(f"/v1/stats/departement/{code}")
+
+    async def region(self, code: str) -> dict[str, Any]:
+        return await self._c._get(f"/v1/stats/region/{code}")
+
+    async def trends(self, **params: Any) -> dict[str, Any]:
+        return await self._c._get("/v1/stats/trends", params=params)
+
+
+class _AsyncAlertsResource:
+    def __init__(self, client: AsyncPermisAPI) -> None:
+        self._c = client
+
+    async def list(self) -> list[dict[str, Any]]:
+        return await self._c._get("/v1/alerts")
+
+    async def create(self, **body: Any) -> dict[str, Any]:
+        return await self._c._post("/v1/alerts", json=body)
+
+    async def delete(self, alert_id: int) -> None:
+        await self._c._delete(f"/v1/alerts/{alert_id}")
+
+
+class _AsyncMeResource:
+    def __init__(self, client: AsyncPermisAPI) -> None:
+        self._c = client
+
+    async def get(self) -> dict[str, Any]:
+        return await self._c._get("/v1/me")
+
+    async def usage(self, days: int = 30) -> dict[str, Any]:
+        return await self._c._get("/v1/me/usage", params={"days": days})
+
+
+class AsyncPermisAPI:
+    """Version async : `async with` et `await`."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key est requise (pk_live_... ou pk_test_...)")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._http = client or httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=_build_headers(api_key),
+        )
+        self.permits = _AsyncPermitsResource(self)
+        self.stats = _AsyncStatsResource(self)
+        self.alerts = _AsyncAlertsResource(self)
+        self.me = _AsyncMeResource(self)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncPermisAPI:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    async def _get(self, path: str, *, params: dict | None = None) -> Any:
+        resp = await self._http.get(path, params=params)
+        _raise_for_status(resp)
+        return resp.json()
+
+    async def _post(self, path: str, *, json: dict | None = None) -> Any:
+        resp = await self._http.post(path, json=json)
+        _raise_for_status(resp)
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    async def _delete(self, path: str) -> None:
+        resp = await self._http.delete(path)
+        _raise_for_status(resp)

permisapi_client-0.1.0/permisapi_client/exceptions.py

@@ -0,0 +1,106 @@
+"""Exceptions hierarchy mirror des codes d'erreur de l'API."""
+from __future__ import annotations
+
+from typing import Any
+
+
+class PermisAPIError(Exception):
+    """Base : toute erreur renvoyee par l'API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        error_code: str | None = None,
+        detail: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.detail = detail
+
+
+class PermisAPIUnauthorized(PermisAPIError):
+    """401 : cle manquante ou invalide."""
+
+
+class PermisAPIForbidden(PermisAPIError):
+    """403 : compte desactive."""
+
+
+class PermisAPIRateLimited(PermisAPIError):
+    """429 : quota minute atteint (retry apres X secondes)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after: int | None = None,
+        status_code: int | None = None,
+        error_code: str | None = None,
+        detail: Any = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            error_code=error_code,
+            detail=detail,
+        )
+        self.retry_after = retry_after
+
+
+class PermisAPIQuotaExceeded(PermisAPIRateLimited):
+    """Quota mensuel depasse : il faut upgrade ou attendre le prochain mois."""
+
+
+class PermisAPIValidationError(PermisAPIError):
+    """400 : un parametre n'est pas au bon format."""
+
+
+class PermisAPINotFound(PermisAPIError):
+    """404 : permit ou ressource inexistante."""
+
+
+def error_from_response(status_code: int, payload: dict[str, Any]) -> PermisAPIError:
+    """Construit la bonne sous-classe selon le status + payload de l'API."""
+    error_code = payload.get("error")
+    message = payload.get("message") or payload.get("detail") or "Erreur API"
+    detail = payload.get("detail")
+
+    if status_code == 401:
+        return PermisAPIUnauthorized(
+            message, status_code=status_code, error_code=error_code, detail=detail
+        )
+    if status_code == 403:
+        return PermisAPIForbidden(
+            message, status_code=status_code, error_code=error_code, detail=detail
+        )
+    if status_code == 404:
+        return PermisAPINotFound(
+            message, status_code=status_code, error_code=error_code, detail=detail
+        )
+    if status_code == 429:
+        retry_after = payload.get("retry_after")
+        if error_code == "quota_exceeded":
+            return PermisAPIQuotaExceeded(
+                message,
+                retry_after=retry_after,
+                status_code=status_code,
+                error_code=error_code,
+                detail=detail,
+            )
+        return PermisAPIRateLimited(
+            message,
+            retry_after=retry_after,
+            status_code=status_code,
+            error_code=error_code,
+            detail=detail,
+        )
+    if status_code == 400:
+        return PermisAPIValidationError(
+            message, status_code=status_code, error_code=error_code, detail=detail
+        )
+    return PermisAPIError(
+        message, status_code=status_code, error_code=error_code, detail=detail
+    )

permisapi_client-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "permisapi-client"
+version = "0.1.0"
+description = "Client Python officiel pour PermisAPI : permis de construire France en API REST."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Evan Caroux", email = "evan@permisapi.fr" },
+]
+keywords = ["permis", "construire", "france", "api", "real-estate", "sitadel", "geocoding", "proptech"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Natural Language :: French",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-asyncio>=0.23",
+    "respx>=0.20",
+]
+
+[project.urls]
+Homepage = "https://permisapi.fr"
+Documentation = "https://permisapi.fr/docs"
+Changelog = "https://permisapi.fr/changelog"
+
+[tool.hatch.build.targets.wheel]
+packages = ["permisapi_client"]

permisapi_client-0.1.0/tests/test_client.py

@@ -0,0 +1,195 @@
+"""Tests du SDK via respx (mock httpx transport)."""
+from __future__ import annotations
+
+import httpx
+import pytest
+import respx
+
+from permisapi_client import (
+    AsyncPermisAPI,
+    PermisAPI,
+    PermisAPIQuotaExceeded,
+    PermisAPIRateLimited,
+    PermisAPIUnauthorized,
+    PermisAPIValidationError,
+)
+from permisapi_client.exceptions import PermisAPINotFound
+
+
+BASE = "https://api.permisapi.fr"
+
+
+def test_requires_api_key() -> None:
+    with pytest.raises(ValueError, match="api_key"):
+        PermisAPI(api_key="")
+
+
+@respx.mock
+def test_permits_list() -> None:
+    route = respx.get(f"{BASE}/v1/permits").respond(
+        json={
+            "items": [{"num_pa": "PC 075 115 24 B0001", "dep_code": "75"}],
+            "pagination": {"page": 1, "total": 1, "pages": 1},
+        }
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        data = client.permits.list(dep_code="75", limit=5)
+    assert route.called
+    assert data["items"][0]["num_pa"] == "PC 075 115 24 B0001"
+    # Header propage
+    assert route.calls.last.request.headers["x-api-key"] == "pk_test_abc"
+
+
+@respx.mock
+def test_permits_get() -> None:
+    respx.get(f"{BASE}/v1/permits/PC-123").respond(
+        json={"num_pa": "PC-123", "dep_code": "75"}
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        permit = client.permits.get("PC-123")
+    assert permit["num_pa"] == "PC-123"
+
+
+@respx.mock
+def test_unauthorized_raises() -> None:
+    respx.get(f"{BASE}/v1/me").respond(
+        status_code=401,
+        json={"error": "unauthorized", "message": "API key manquante"},
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        with pytest.raises(PermisAPIUnauthorized):
+            client.me.get()
+
+
+@respx.mock
+def test_rate_limit_raises_with_retry_after() -> None:
+    respx.get(f"{BASE}/v1/permits").respond(
+        status_code=429,
+        json={"error": "rate_limit_exceeded", "message": "burst"},
+        headers={"Retry-After": "3"},
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        with pytest.raises(PermisAPIRateLimited) as exc:
+            client.permits.list()
+    assert exc.value.retry_after == 3
+
+
+@respx.mock
+def test_quota_exceeded_subclass() -> None:
+    respx.get(f"{BASE}/v1/permits").respond(
+        status_code=429,
+        json={"error": "quota_exceeded", "message": "mensuel"},
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        with pytest.raises(PermisAPIQuotaExceeded):
+            client.permits.list()
+
+
+@respx.mock
+def test_not_found() -> None:
+    respx.get(f"{BASE}/v1/permits/UNKNOWN").respond(
+        status_code=404,
+        json={"error": "not_found", "message": "permit introuvable"},
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        with pytest.raises(PermisAPINotFound):
+            client.permits.get("UNKNOWN")
+
+
+@respx.mock
+def test_validation_error() -> None:
+    respx.get(f"{BASE}/v1/permits").respond(
+        status_code=400,
+        json={"error": "validation_error", "message": "dep_code invalide"},
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        with pytest.raises(PermisAPIValidationError):
+            client.permits.list(dep_code="999999")
+
+
+@respx.mock
+def test_iter_all_paginates() -> None:
+    respx.get(f"{BASE}/v1/permits", params={"page": "1", "limit": "2"}).respond(
+        json={
+            "items": [{"num_pa": "a"}, {"num_pa": "b"}],
+            "pagination": {"page": 1, "total": 3, "pages": 2},
+        }
+    )
+    respx.get(f"{BASE}/v1/permits", params={"page": "2", "limit": "2"}).respond(
+        json={
+            "items": [{"num_pa": "c"}],
+            "pagination": {"page": 2, "total": 3, "pages": 2},
+        }
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        results = list(client.permits.iter_all(limit=2))
+    assert [p["num_pa"] for p in results] == ["a", "b", "c"]
+
+
+@respx.mock
+def test_alerts_create() -> None:
+    respx.post(f"{BASE}/v1/alerts").respond(
+        json={
+            "id": 42,
+            "name": "Paris 18",
+            "webhook_secret": "super-secret-abc",
+        }
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        alert = client.alerts.create(
+            name="Paris 18",
+            center_lat=48.88,
+            center_lng=2.35,
+            radius_km=3,
+            webhook_url="https://x/hook",
+        )
+    assert alert["webhook_secret"] == "super-secret-abc"
+
+
+@respx.mock
+def test_alerts_delete_204() -> None:
+    respx.delete(f"{BASE}/v1/alerts/42").respond(status_code=204)
+    with PermisAPI(api_key="pk_test_abc") as client:
+        client.alerts.delete(42)
+
+
+# ---------------------------------------------------------------------------
+# Async
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_permits_list() -> None:
+    respx.get(f"{BASE}/v1/permits").respond(
+        json={"items": [{"num_pa": "x"}], "pagination": {"pages": 1}}
+    )
+    async with AsyncPermisAPI(api_key="pk_test_abc") as client:
+        data = await client.permits.list()
+    assert data["items"][0]["num_pa"] == "x"
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_rate_limit() -> None:
+    respx.get(f"{BASE}/v1/me").respond(
+        status_code=429,
+        json={"error": "rate_limit_exceeded", "message": "burst"},
+    )
+    async with AsyncPermisAPI(api_key="pk_test_abc") as client:
+        with pytest.raises(PermisAPIRateLimited):
+            await client.me.get()
+
+
+def test_custom_base_url() -> None:
+    client = PermisAPI(api_key="pk_test_abc", base_url="http://localhost:8000/")
+    assert client.base_url == "http://localhost:8000"
+    client.close()
+
+
+def test_custom_http_client() -> None:
+    """On peut injecter un httpx.Client pre-configure (proxy, retry, etc)."""
+    h = httpx.Client(base_url=BASE, headers={"X-API-Key": "pk_test_xyz"})
+    client = PermisAPI(api_key="pk_test_xyz", client=h)
+    assert client._http is h
+    client.close()