permisapi-client 0.1.0__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+permisapi_client/__init__.py,sha256=9pbg6c9oAVlE9foYvhjil_vt5379nASvUdb58fLVkvg,967
+permisapi_client/client.py,sha256=oK09zY_pFdWbRheIFPhtF0pLuaCwjVWj2UpvTmgNA7U,12632
+permisapi_client/exceptions.py,sha256=5nqRA28mwoB3gDFoWyDuaxS8R4fXCdI9j90F_QNN84s,3284
+permisapi_client-0.1.0.dist-info/METADATA,sha256=eJ80i8aKQUnFe6ngDDzLtgUpulPhW_oI4t5QG5IwHe0,3457
+permisapi_client-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+permisapi_client-0.1.0.dist-info/RECORD,,

permisapi_client-0.1.0.dist-info/WHEEL

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