ffbb-data-client 2.4.30__tar.gz → 2.4.31__tar.gz

{ffbb_data_client-2.4.30 → ffbb_data_client-2.4.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffbb-data-client
-Version: 2.4.30
+Version: 2.4.31
 Summary: API FFBB — SDK Python moderne & asynchrone pour les donnees officielles de la Federation Francaise de BasketBall (clubs, classements, calendriers, lives, Meilisearch). Alternative moderne a ffbb-api-client.
 Home-page: https://github.com/nickdesi/ffbb-data-client
 Author: nickdesi

{ffbb_data_client-2.4.30 → ffbb_data_client-2.4.31}/src/ffbb_data_client/api.py

@@ -22,9 +22,10 @@ from typing import Any
 from fastapi import FastAPI, HTTPException
 from fastapi import Path as PathParam
 from fastapi import Query, Request, Response
+from fastapi.exceptions import RequestValidationError
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
-from fastapi.responses import FileResponse, HTMLResponse
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
 
 from .clients.ffbb_data_client import FFBBDataClient
@@ -97,7 +98,7 @@ l'ensemble des données publiques de la **Fédération Française de BasketBall*
 - ⭐ **Code Source GitHub** : [`https://github.com/nickdesi/ffbb-data-client`](https://github.com/nickdesi/ffbb-data-client)
 - 📖 **Documentation Sphinx complète** : [`https://nickdesi.github.io/ffbb-data-client/`](https://nickdesi.github.io/ffbb-data-client/)
 """,
-    version="2.4.30",
+    version="2.4.31",
     openapi_tags=TAGS_METADATA,
     docs_url=None,
     redoc_url=None,
@@ -115,6 +116,66 @@ l'ensemble des données publiques de la **Fédération Française de BasketBall*
     lifespan=lifespan,
 )
 
+
+# ---------------------------------------------------------------------------
+# Standard Error Formatting Handlers (REST Best Practices RFC 7807)
+# ---------------------------------------------------------------------------
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request: Request, exc: HTTPException):
+    code_map = {
+        400: "BAD_REQUEST",
+        401: "UNAUTHORIZED",
+        403: "FORBIDDEN",
+        404: "NOT_FOUND",
+        409: "CONFLICT",
+        422: "UNPROCESSABLE_ENTITY",
+        429: "RATE_LIMIT_EXCEEDED",
+        500: "INTERNAL_SERVER_ERROR",
+        502: "BAD_GATEWAY",
+        503: "SERVICE_UNAVAILABLE",
+    }
+    error_code = code_map.get(exc.status_code, f"HTTP_{exc.status_code}")
+    message = str(exc.detail)
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "detail": exc.detail,
+            "error": {
+                "code": error_code,
+                "message": message,
+                "status": exc.status_code,
+            },
+        },
+        headers=getattr(exc, "headers", None),
+    )
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    errors = []
+    for err in exc.errors():
+        field = ".".join(str(loc) for loc in err.get("loc", []))
+        errors.append(
+            {
+                "field": field,
+                "message": err.get("msg", ""),
+                "type": err.get("type", ""),
+            }
+        )
+    return JSONResponse(
+        status_code=422,
+        content={
+            "detail": exc.errors(),
+            "error": {
+                "code": "VALIDATION_ERROR",
+                "message": "Erreur de validation des paramètres de la requête.",
+                "status": 422,
+                "errors": errors,
+            },
+        },
+    )
+
+
 _cors_env = os.getenv("FFBB_CORS_ORIGINS", "*")
 _cors_origins = [origin.strip() for origin in _cors_env.split(",") if origin.strip()]
 if "*" in _cors_origins:
@@ -589,6 +650,42 @@ async def health():
     }
 
 
+@app.get(
+    "/health/ready",
+    tags=["Monitoring & Diagnostic"],
+    summary="Readiness probe avec dépendances (/health/ready)",
+)
+async def health_ready(response: Response):
+    """Vérifie la disponibilité réelle du serveur et de ses dépendances amont (Directus & Meilisearch)."""
+    client = get_client()
+    checks: dict[str, str] = {}
+    is_ready = True
+
+    try:
+        saisons = await client.get_saisons_async()
+        checks["directus"] = "ok" if saisons else "empty"
+    except Exception as e:
+        checks["directus"] = f"error: {e}"
+        is_ready = False
+
+    try:
+        res = client.multi_search(name="Clermont")
+        checks["meilisearch"] = "ok" if res else "empty"
+    except Exception as e:
+        checks["meilisearch"] = f"error: {e}"
+        is_ready = False
+
+    if not is_ready:
+        response.status_code = 503
+
+    return {
+        "status": "ready" if is_ready else "not_ready",
+        "service": "ffbb-data-client-api",
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "checks": checks,
+    }
+
+
 @app.head("/health", include_in_schema=False)
 async def health_head():
     return Response(status_code=200)
@@ -722,6 +819,7 @@ async def search_ffbb(
     response_description="Liste ordonnée des rencontres avec adresses et logos",
 )
 async def get_club_matches(
+    response: Response,
     organisme_id: int = PathParam(
         ...,
         ge=1,
@@ -733,6 +831,19 @@ async def get_club_matches(
         description="Filtrer par équipe (ex: 'SENIOR M1', 'U18 M1', 'ALL')",
         examples=["SENIOR M1"],
     ),
+    limit: int | None = Query(
+        None,
+        ge=1,
+        le=500,
+        description="Nombre maximal de rencontres à renvoyer (pagination)",
+        examples=[50],
+    ),
+    offset: int = Query(
+        0,
+        ge=0,
+        description="Décalage de pagination",
+        examples=[0],
+    ),
 ):
     """
     Récupère l'ensemble des rencontres officielles FFBB d'un club,
@@ -1033,12 +1144,27 @@ async def get_club_matches(
     matches_list = [m for m in built_matches if m is not None]
 
     matches_list.sort(key=lambda x: (x.get("dateISO", ""), x.get("time", "")))
+    response.headers["Cache-Control"] = "public, max-age=180, stale-while-revalidate=60"
+
+    total_count = len(matches_list)
+    paged_matches = (
+        matches_list[offset : offset + limit]
+        if limit is not None
+        else matches_list[offset:]
+    )
 
     return {
         "organisme_id": organisme_id,
         "club": club_name,
-        "matches": matches_list,
-        "count": len(matches_list),
+        "matches": paged_matches,
+        "count": len(paged_matches),
+        "total": total_count,
+        "pagination": {
+            "total": total_count,
+            "limit": limit if limit is not None else total_count,
+            "offset": offset,
+            "has_more": (offset + len(paged_matches)) < total_count,
+        },
     }
 
 
@@ -1149,6 +1275,7 @@ async def get_poule(
     response_description="Classement détaillé avec points, victoires et goal-average",
 )
 async def get_poule_classement(
+    response: Response,
     poule_id: int = PathParam(
         ..., ge=1, description="ID de la poule FFBB", examples=[129759]
     ),
@@ -1167,6 +1294,9 @@ async def get_poule_classement(
             or getattr(poule, "classements", [])
             or []
         )
+        response.headers["Cache-Control"] = (
+            "public, max-age=300, stale-while-revalidate=60"
+        )
         return {
             "poule_id": poule_id,
             "nom": getattr(poule, "nom", "") or getattr(poule, "libelle", ""),
@@ -1235,6 +1365,7 @@ async def get_rencontre_detail(
     response_description="Fiche gymnase avec adresse complète et géolocalisation",
 )
 async def get_salle_detail(
+    response: Response,
     salle_id: str = PathParam(
         ...,
         description="ID FFBB de la salle (ex: '6543')",
@@ -1249,6 +1380,9 @@ async def get_salle_detail(
             raise HTTPException(
                 status_code=404, detail=f"Salle {salle_id} introuvable."
             )
+        response.headers["Cache-Control"] = (
+            "public, max-age=86400, stale-while-revalidate=3600"
+        )
         return salle
     except HTTPException:
         raise
@@ -1292,10 +1426,13 @@ async def get_competition_detail(
     summary="Liste des saisons officielles FFBB",
     response_description="Historique et saison active",
 )
-async def get_saisons():
+async def get_saisons(response: Response):
     """Retourne la liste des saisons officielles FFBB avec indication de la saison en cours."""
     client = get_client()
     try:
+        response.headers["Cache-Control"] = (
+            "public, max-age=86400, stale-while-revalidate=3600"
+        )
         return await client.get_saisons_async()
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))

{ffbb_data_client-2.4.30 → ffbb_data_client-2.4.31}/src/ffbb_data_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffbb-data-client
-Version: 2.4.30
+Version: 2.4.31
 Summary: API FFBB — SDK Python moderne & asynchrone pour les donnees officielles de la Federation Francaise de BasketBall (clubs, classements, calendriers, lives, Meilisearch). Alternative moderne a ffbb-api-client.
 Home-page: https://github.com/nickdesi/ffbb-data-client
 Author: nickdesi

{ffbb_data_client-2.4.30 → ffbb_data_client-2.4.31}/src/ffbb_data_client.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "2.4.30",
+  "tag": "2.4.31",
   "distance": 0,
-  "node": "gfaf1a9cb9c6837dac2689031d7e582829983f79e",
+  "node": "g90a97f236b7ee1f4c1dcac417ee73a363ca4ecd8",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-23"

{ffbb_data_client-2.4.30 → ffbb_data_client-2.4.31}/tests/unit/test_314_api_endpoints.py

@@ -1,4 +1,4 @@
-"""Tests for the new REST endpoints and match card enrichment in api.py."""
+"""Tests for the REST endpoints, Best Practices, error envelopes, and caching in api.py."""
 
 from unittest.mock import AsyncMock, MagicMock, patch
 
@@ -21,14 +21,60 @@ async def test_search_acronym_expansion():
         async with AsyncClient(transport=transport, base_url="http://test") as ac:
             r = await ac.get("/api/v1/search?query=SCBA")
             assert r.status_code == 200
-            # Ensure multi_search was called with expanded name
             mock_client.multi_search.assert_called_with(
                 name="Stade Clermontois Basket Auvergne"
             )
 
 
 @pytest.mark.asyncio
-async def test_match_card_enrichment():
+async def test_health_ready_endpoint():
+    transport = ASGITransport(app=app)
+    mock_client = MagicMock()
+    mock_client.get_saisons_async = AsyncMock(return_value=[{"id": "1037"}])
+    mock_client.multi_search = MagicMock(return_value=[{"hits": []}])
+
+    with patch("ffbb_data_client.api.get_client", return_value=mock_client):
+        async with AsyncClient(transport=transport, base_url="http://test") as ac:
+            r = await ac.get("/health/ready")
+            assert r.status_code == 200
+            data = r.json()
+            assert data.get("status") == "ready"
+            assert data.get("checks", {}).get("directus") == "ok"
+            assert data.get("checks", {}).get("meilisearch") == "ok"
+
+
+@pytest.mark.asyncio
+async def test_standard_error_envelope_404():
+    transport = ASGITransport(app=app)
+    mock_client = MagicMock()
+    mock_client.get_organisme_async = AsyncMock(return_value=None)
+
+    with patch("ffbb_data_client.api.get_client", return_value=mock_client):
+        async with AsyncClient(transport=transport, base_url="http://test") as ac:
+            r = await ac.get("/api/v1/club/999999")
+            assert r.status_code == 404
+            data = r.json()
+            assert "detail" in data
+            assert "error" in data
+            assert data["error"]["code"] == "NOT_FOUND"
+            assert data["error"]["status"] == 404
+
+
+@pytest.mark.asyncio
+async def test_standard_validation_error_422():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as ac:
+        # Invalid query param length
+        r = await ac.get("/api/v1/club/not_a_number")
+        assert r.status_code == 422
+        data = r.json()
+        assert "error" in data
+        assert data["error"]["code"] == "VALIDATION_ERROR"
+        assert len(data["error"]["errors"]) > 0
+
+
+@pytest.mark.asyncio
+async def test_match_card_enrichment_and_pagination():
     transport = ASGITransport(app=app)
     mock_client = MagicMock()
     mock_org = MagicMock()
@@ -39,10 +85,14 @@ async def test_match_card_enrichment():
 
     with patch("ffbb_data_client.api.get_client", return_value=mock_client):
         async with AsyncClient(transport=transport, base_url="http://test") as ac:
-            r = await ac.get("/api/v1/club/9326/matches")
+            r = await ac.get("/api/v1/club/9326/matches?limit=10&offset=0")
             assert r.status_code == 200
+            assert "Cache-Control" in r.headers
             data = r.json()
             assert "matches" in data
+            assert "pagination" in data
+            assert data["pagination"]["limit"] == 10
+            assert data["pagination"]["offset"] == 0
 
 
 @pytest.mark.asyncio
@@ -64,7 +114,7 @@ async def test_rencontre_endpoint():
 
 
 @pytest.mark.asyncio
-async def test_salle_and_competition_endpoints():
+async def test_salle_and_competition_endpoints_caching():
     transport = ASGITransport(app=app)
     mock_client = MagicMock()
     mock_client.get_salle_async = AsyncMock(
@@ -81,7 +131,8 @@ async def test_salle_and_competition_endpoints():
         async with AsyncClient(transport=transport, base_url="http://test") as ac:
             r_salle = await ac.get("/api/v1/salle/6543")
             assert r_salle.status_code == 200
-            assert r_salle.json().get("libelle") == "Gymnase Fleury"
+            assert "Cache-Control" in r_salle.headers
+            assert "max-age=86400" in r_salle.headers["Cache-Control"]
 
             r_comp = await ac.get("/api/v1/competition/999")
             assert r_comp.status_code == 200
@@ -89,4 +140,5 @@ async def test_salle_and_competition_endpoints():
 
             r_saisons = await ac.get("/api/v1/saisons")
             assert r_saisons.status_code == 200
+            assert "Cache-Control" in r_saisons.headers
             assert len(r_saisons.json()) == 1