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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffbb-data-client
-Version: 2.4.30
+Version: 2.4.32
 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.32}/src/ffbb_data_client/api.py

@@ -22,10 +22,13 @@ 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.openapi.utils import get_openapi
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
 
 from .clients.ffbb_data_client import FFBBDataClient
 from .helpers.normalization import parse_categorie
@@ -75,14 +78,71 @@ TAGS_METADATA = [
     },
 ]
 
+
+# ---------------------------------------------------------------------------
+# OpenAPI 3.1 Components & Models (https://www.openapis.org/)
+# ---------------------------------------------------------------------------
+class ErrorDetail(BaseModel):
+    code: str = Field(
+        description="Code d'erreur machine RFC 7807 (ex: NOT_FOUND, BAD_REQUEST)"
+    )
+    message: str = Field(
+        description="Message d'erreur descriptif lisible pour l'humain"
+    )
+    status: int = Field(description="Code statut HTTP (ex: 404, 400, 500)")
+    errors: list[dict[str, Any]] | None = Field(
+        default=None, description="Détails complémentaires de validation si applicable"
+    )
+
+
+class ErrorResponse(BaseModel):
+    detail: Any = Field(description="Détail brut rétro-compatible FastAPI")
+    error: ErrorDetail = Field(description="Enveloppe d'erreur standardisée")
+
+
+class HealthResponse(BaseModel):
+    status: str = Field(description="Statut du service ('healthy')")
+    service: str = Field(description="Nom du service")
+    timestamp: str = Field(description="Horodatage ISO-8601 UTC")
+
+
+class ReadinessResponse(BaseModel):
+    status: str = Field(description="Statut de préparation ('ready' ou 'not_ready')")
+    service: str = Field(description="Nom du service")
+    timestamp: str = Field(description="Horodatage ISO-8601 UTC")
+    checks: dict[str, str] = Field(
+        description="État individuel des dépendances amont (Directus, Meilisearch)"
+    )
+
+
+COMMON_RESPONSES = {
+    400: {
+        "model": ErrorResponse,
+        "description": "Requête invalide ou paramètre manquant",
+    },
+    404: {"model": ErrorResponse, "description": "Ressource demandée introuvable"},
+    422: {
+        "model": ErrorResponse,
+        "description": "Erreur de validation sémantique des paramètres",
+    },
+    500: {
+        "model": ErrorResponse,
+        "description": "Erreur interne du serveur ou indisponibilité amont FFBB",
+    },
+    503: {
+        "model": ErrorResponse,
+        "description": "Dépendance amont FFBB temporairement indisponible",
+    },
+}
 app = FastAPI(
     title="FFBB REST API — Données Officielles du Basket Français",
+    summary="API REST officielle & Open Data Basketball pour la Fédération Française de BasketBall",
     description="""
 # 🏀 API REST FFBB & Open Data Basketball
 
 Bienvenue sur la documentation interactive officielle de l'API **FFBB Data Client**.
 
-Cette API REST moderne et asynchrone (FastAPI + Pydantic v2) permet d'interroger directement
+Cette API REST moderne et asynchrone (FastAPI + Pydantic v2, spécification OpenAPI 3.1) permet d'interroger directement
 l'ensemble des données publiques de la **Fédération Française de BasketBall** :
 - **Clubs & Équipes** : fiches, contacts, adresses et engagements (du niveau départemental à la Betclic Élite).
 - **Compétitions & Poules** : calendriers, résultats, feuilles de match et classements officiels.
@@ -97,7 +157,18 @@ 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.32",
+    contact={
+        "name": "FFBB Data Client — Support & Open Data",
+        "url": "https://github.com/nickdesi/ffbb-data-client/issues",
+        "email": "nicolas.desimone@gmail.com",
+    },
+    license_info={
+        "name": "Apache-2.0",
+        "identifier": "Apache-2.0",
+        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
+    },
+    terms_of_service="https://github.com/nickdesi/ffbb-data-client/blob/master/LICENSE.txt",
     openapi_tags=TAGS_METADATA,
     docs_url=None,
     redoc_url=None,
@@ -112,9 +183,97 @@ l'ensemble des données publiques de la **Fédération Française de BasketBall*
             "description": "Serveur Local de Développement",
         },
     ],
+    responses=COMMON_RESPONSES,
     lifespan=lifespan,
 )
 
+
+def custom_openapi():
+    if app.openapi_schema:
+        return app.openapi_schema
+    openapi_schema = get_openapi(
+        title=app.title,
+        version=app.version,
+        openapi_version=app.openapi_version,
+        summary=app.summary,
+        description=app.description,
+        routes=app.routes,
+        tags=app.openapi_tags,
+        servers=app.servers,
+        terms_of_service=app.terms_of_service,
+        contact=app.contact,
+        license_info=app.license_info,
+    )
+    openapi_schema["externalDocs"] = {
+        "description": "Documentation Sphinx & Spécifications Officielles",
+        "url": "https://nickdesi.github.io/ffbb-data-client/",
+    }
+    app.openapi_schema = openapi_schema
+    return app.openapi_schema
+
+
+app.openapi = custom_openapi
+
+
+# ---------------------------------------------------------------------------
+# 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:
@@ -578,7 +737,11 @@ async def resolve_exact_salle_address_async(
 
 
 @app.get(
-    "/health", tags=["Monitoring & Diagnostic"], summary="Diagnostic de l'API (/health)"
+    "/health",
+    tags=["Monitoring & Diagnostic"],
+    summary="Diagnostic de l'API (/health)",
+    operation_id="getHealth",
+    response_model=HealthResponse,
 )
 async def health():
     """Vérifie l'état de fonctionnement et la disponibilité de l'API REST."""
@@ -589,6 +752,44 @@ async def health():
     }
 
 
+@app.get(
+    "/health/ready",
+    tags=["Monitoring & Diagnostic"],
+    summary="Readiness probe avec dépendances (/health/ready)",
+    operation_id="getReadiness",
+    response_model=ReadinessResponse,
+)
+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)
@@ -598,6 +799,7 @@ async def health_head():
     "/metrics",
     tags=["Monitoring & Diagnostic"],
     summary="Métriques Prometheus de l'API (/metrics)",
+    operation_id="getPrometheusMetrics",
     response_class=Response,
 )
 async def metrics():
@@ -660,6 +862,7 @@ async def metrics():
 
 @app.get(
     "/api/v1/search",
+    operation_id="searchFFBB",
     tags=["Recherche & Meilisearch"],
     summary="Recherche universelle (Clubs, Compétitions, Salles)",
     response_description="Résultats multi-index Meilisearch groupés par typologie",
@@ -717,11 +920,13 @@ async def search_ffbb(
 
 @app.get(
     "/api/v1/club/{organisme_id}/matches",
+    operation_id="getClubMatches",
     tags=["Matchs & Calendriers"],
     summary="Calendrier & Matchs d'un club",
     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 +938,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,17 +1251,33 @@ 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,
+        },
     }
 
 
 @app.get(
     "/api/v1/club/{organisme_id}/teams",
+    operation_id="getClubTeams",
     tags=["Clubs"],
     summary="Équipes engagées d'un club",
     response_description="Liste des équipes engagées par championnat",
@@ -1093,6 +1327,7 @@ async def get_club_teams(
 
 @app.get(
     "/api/v1/club/{organisme_id}",
+    operation_id="getClubDetails",
     tags=["Clubs"],
     summary="Fiche détaillée d'un club",
     response_description="Informations administratives, contacts et salle",
@@ -1120,6 +1355,7 @@ async def get_club_details(
 
 @app.get(
     "/api/v1/poule/{poule_id}",
+    operation_id="getPoule",
     tags=["Compétitions & Poules"],
     summary="Détails complets d'une poule",
     response_description="Composition, classements et rencontres",
@@ -1144,11 +1380,13 @@ async def get_poule(
 
 @app.get(
     "/api/v1/poule/{poule_id}/classement",
+    operation_id="getPouleClassement",
     tags=["Compétitions & Poules"],
     summary="Classement officiel d'une 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 +1405,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", ""),
@@ -1181,6 +1422,7 @@ async def get_poule_classement(
 
 @app.get(
     "/api/v1/lives",
+    operation_id="getLives",
     tags=["Scores en Direct"],
     summary="Scores en direct du week-end (Lives)",
     response_description="Matchs en direct avec scores temps réel",
@@ -1196,6 +1438,7 @@ async def get_lives():
 
 @app.get(
     "/api/v1/rencontre/{rencontre_id}",
+    operation_id="getRencontreDetail",
     tags=["Matchs & Calendriers"],
     summary="Détails complets d'une rencontre FFBB",
     response_description="Fiche officielle détaillée de la rencontre, scores, salle et officiels",
@@ -1230,11 +1473,13 @@ async def get_rencontre_detail(
 
 @app.get(
     "/api/v1/salle/{salle_id}",
+    operation_id="getSalleDetail",
     tags=["Clubs"],
     summary="Détails d'une salle / gymnase",
     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 +1494,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
@@ -1258,6 +1506,7 @@ async def get_salle_detail(
 
 @app.get(
     "/api/v1/competition/{competition_id}",
+    operation_id="getCompetitionDetail",
     tags=["Compétitions & Poules"],
     summary="Détails d'une compétition",
     response_description="Informations sur la compétition et composition des poules",
@@ -1288,14 +1537,18 @@ async def get_competition_detail(
 
 @app.get(
     "/api/v1/saisons",
+    operation_id="getSaisons",
     tags=["Compétitions & Poules"],
     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.32}/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.32
 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.32}/src/ffbb_data_client.egg-info/scm_version.json

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

{ffbb_data_client-2.4.30 → ffbb_data_client-2.4.32}/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