permisapi-client 0.6.0__tar.gz → 0.7.1__tar.gz

{permisapi_client-0.6.0 → permisapi_client-0.7.1}/.gitignore

@@ -63,3 +63,6 @@ landing/out/
 # Post-piratage rotation (contient les nouvelles cles API en clair)
 secrets_NEW_KEYS.json
 scrape-downloads/
+
+# Local handoff bundle (assembled then zipped, not committed)
+handoff-bundle/

{permisapi_client-0.6.0 → permisapi_client-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: permisapi-client
-Version: 0.6.0
+Version: 0.7.1
 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

{permisapi_client-0.6.0 → permisapi_client-0.7.1}/permisapi_client/__init__.py

@@ -30,4 +30,4 @@ __all__ = [
     "PermisAPIValidationError",
 ]
 
-__version__ = "0.6.0"
+__version__ = "0.7.1"

{permisapi_client-0.6.0 → permisapi_client-0.7.1}/permisapi_client/client.py

@@ -13,7 +13,7 @@ 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.6.0"
+USER_AGENT = "permisapi-client-python/0.7.1"
 
 
 def _raise_for_status(resp: httpx.Response) -> None:
@@ -52,7 +52,18 @@ class _PermitsResource:
         self._c = client
 
     def list(self, **params: Any) -> dict[str, Any]:
-        """GET /v1/permits avec filtres. Retourne {items, pagination}."""
+        """GET /v1/permits avec filtres. Retourne {data, pagination}.
+
+        Filtres acceptes : dep_code, comm_code, localite, codpost,
+        permit_type, etat_pa, an_depot, date_from, date_to,
+        min_superficie, siren, geocoded_only, page, limit.
+
+        Tri : passer `sort="-date_reelle_autorisation"` (defaut),
+        `sort="date_depot"`, `sort="-superficie_terrain"`, etc.
+        Champs autorises : date_reelle_autorisation, date_depot,
+        an_depot, superficie_terrain. Prefixe `-` pour descendant.
+        Tout autre champ retourne 422 (et non ignore silencieusement).
+        """
         return self._c._get("/v1/permits", params=params)
 
     def iter_all(self, **params: Any) -> Iterator[dict[str, Any]]:
@@ -177,6 +188,33 @@ class _PermitsResource:
         """
         return self._c._get(f"/v1/permits/{num_pa}/plu")
 
+    def full_view(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}/360 : vue agregee 6-en-1 en 1 appel HTTP.
+
+        Combine en 1 reponse : detail + sirene + dvf + score + plu + risks.
+        Equivalent fonctionnel de 6 calls separes mais en 1 round-trip,
+        avec parallelisation cote serveur des sub-fetches lents (PLU
+        apicarto + Risks BRGM).
+
+        Cout quota : 6 unites du quota mensuel pour Pro+, 1 unite pour
+        Free / Explorer (qui recoivent juste `detail`, autres champs `null`
+        avec `plan_required_for_full="pro"`). Le header de reponse
+        `X-RateLimit-Cost` confirme le cout decompte.
+
+        Best-effort : si une sous-feature echoue (timeout, 5xx tiers),
+        son champ vaut `null` et l'erreur est listee dans `fetch_errors`.
+        Les autres sous-features ne sont pas affectees.
+
+        Latence typique 5-7s (dominee par PLU + Risks live, paralleles).
+
+        Returns:
+            dict avec cles : num_pa, detail, sirene, dvf, score, plu,
+            risks, fetch_errors (list), subfetches_billed (int).
+            Si plan Free/Explorer : `plan_required_for_full="pro"` est
+            present et toutes les sous-features sauf detail sont null.
+        """
+        return self._c._get(f"/v1/permits/{num_pa}/360")
+
     def score_feedback(
         self,
         *,
@@ -435,6 +473,8 @@ class _AsyncPermitsResource:
         self._c = client
 
     async def list(self, **params: Any) -> dict[str, Any]:
+        """GET /v1/permits avec filtres. Voir _PermitsResource.list pour
+        la doc complete (filtres + tri sort=)."""
         return await self._c._get("/v1/permits", params=params)
 
     async def iter_all(self, **params: Any) -> AsyncIterator[dict[str, Any]]:
@@ -506,6 +546,15 @@ class _AsyncPermitsResource:
         Voir _PermitsResource.risks pour la doc complete."""
         return await self._c._get(f"/v1/permits/{num_pa}/risks")
 
+    async def full_view(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}/360 : version async. Vue agregee 6-en-1.
+
+        Cout quota : 6 unites pour Pro+, 1 unite pour Free / Explorer.
+        Le header `X-RateLimit-Cost` confirme le cout. Voir
+        _PermitsResource.full_view pour la doc complete.
+        """
+        return await self._c._get(f"/v1/permits/{num_pa}/360")
+
     async def score_feedback(
         self,
         *,

{permisapi_client-0.6.0 → permisapi_client-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "permisapi-client"
-version = "0.6.0"
+version = "0.7.1"
 description = "Client Python officiel pour PermisAPI : permis de construire France en API REST."
 readme = "README.md"
 requires-python = ">=3.9"

{permisapi_client-0.6.0 → permisapi_client-0.7.1}/tests/test_client.py

@@ -337,6 +337,74 @@ async def test_async_permits_export() -> None:
     assert b"PC-A,75" in result
 
 
+@respx.mock
+def test_permits_list_with_sort() -> None:
+    """SDK propagates `sort=` query param transparently to the API."""
+    route = respx.get(f"{BASE}/v1/permits").respond(
+        json={
+            "data": [{"num_pa": "PC-1", "superficie_terrain": 1500}],
+            "pagination": {"page": 1, "total": 1, "pages": 1},
+        }
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        client.permits.list(dep_code="33", sort="-superficie_terrain", limit=10)
+    assert route.called
+    # The sort param must appear in the request URL query string
+    url = str(route.calls.last.request.url)
+    assert "sort=-superficie_terrain" in url
+    assert "dep_code=33" in url
+
+
+@respx.mock
+def test_permits_full_view_sync() -> None:
+    """Sync : full_view appelle GET /v1/permits/{num_pa}/360 et retourne
+    le payload agrege complet."""
+    respx.get(f"{BASE}/v1/permits/PC-360-001/360").respond(
+        json={
+            "num_pa": "PC-360-001",
+            "detail": {"num_pa": "PC-360-001", "dep_code": "75"},
+            "sirene": {"match": {"siren": "111222333"}},
+            "dvf": {"matches": []},
+            "score": {"score": 72, "tier": "high"},
+            "plu": {"zonage": {"code": "UA", "constructible": True}},
+            "risks": {"risk_tier": "low"},
+            "fetch_errors": [],
+            "subfetches_billed": 6,
+        }
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        view = client.permits.full_view("PC-360-001")
+    assert view["num_pa"] == "PC-360-001"
+    assert view["subfetches_billed"] == 6
+    assert view["score"]["tier"] == "high"
+    assert view["plu"]["zonage"]["constructible"] is True
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_permits_full_view() -> None:
+    """Async : full_view appelle GET /v1/permits/{num_pa}/360."""
+    respx.get(f"{BASE}/v1/permits/PC-FREE/360").respond(
+        json={
+            "num_pa": "PC-FREE",
+            "detail": {"num_pa": "PC-FREE"},
+            "sirene": None,
+            "dvf": None,
+            "score": None,
+            "plu": None,
+            "risks": None,
+            "fetch_errors": [],
+            "plan_required_for_full": "pro",
+            "subfetches_billed": 1,
+        }
+    )
+    async with AsyncPermisAPI(api_key="pk_test_abc") as client:
+        view = await client.permits.full_view("PC-FREE")
+    assert view["plan_required_for_full"] == "pro"
+    assert view["subfetches_billed"] == 1
+    assert view["sirene"] is None
+
+
 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"