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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffbb-data-client
-Version: 2.4.29
+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.29 → 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.25",
+    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)
@@ -693,9 +790,23 @@ async def search_ffbb(
             status_code=400,
             detail="Le terme de recherche doit comporter au moins 2 caractères.",
         )
+    # Résolution des acronymes fréquents (ex: SCBA -> Stade Clermontois Basket Auvergne)
+    _SEARCH_ACRONYMS = {
+        "SCBA": "Stade Clermontois Basket Auvergne",
+        "SCBF": "Stade Clermontois Basket Féminin",
+        "ASVEL": "LDLC ASVEL",
+        "SIG": "Strasbourg IG",
+        "JDA": "JDA Dijon",
+        "MSB": "Le Mans Sarthe Basket",
+        "EBPLO": "Elan Béarnais",
+        "CSP": "Limoges CSP",
+        "BCM": "Gravelines Dunkerque",
+        "ESSM": "Le Portel",
+    }
+    effective_query = _SEARCH_ACRONYMS.get(search_term.upper(), search_term)
     client = get_client()
     try:
-        results = client.multi_search(name=search_term)
+        results = client.multi_search(name=effective_query)
         return results
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Erreur de recherche: {e}")
@@ -708,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,
@@ -719,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,
@@ -975,6 +1100,14 @@ async def get_club_matches(
             else (parsed_cat.numero_equipe if parsed_cat.numero_equipe else 1)
         )
 
+        res1 = getattr(m, "resultatEquipe1", None)
+        res2 = getattr(m, "resultatEquipe2", None)
+        is_played = bool(
+            getattr(m, "joue", False) or res1 is not None or res2 is not None
+        )
+        score_local = res1 if is_home else res2
+        score_opp = res2 if is_home else res1
+
         match_data: dict[str, Any] = {
             "ffbbMatchId": m_id,
             "team": scba_team,
@@ -990,6 +1123,14 @@ async def get_club_matches(
             "competition": comp_nom,
             "poule": poule_nom,
             "pouleId": poule_id,
+            "round": getattr(m, "numeroJournee", None)
+            or getattr(m, "numero_journee", None),
+            "isPlayed": is_played,
+            "scoreLocal": score_local,
+            "scoreOpponent": score_opp,
+            "scoreEquipe1": res1,
+            "scoreEquipe2": res2,
+            "competitionUrl": getattr(m, "url_competition", "") or "",
             "teamLogo": club_logo_url,
         }
         if opponent_logo:
@@ -1003,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,
+        },
     }
 
 
@@ -1119,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]
     ),
@@ -1137,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", ""),
@@ -1164,6 +1324,120 @@ async def get_lives():
         raise HTTPException(status_code=500, detail=str(e))
 
 
+@app.get(
+    "/api/v1/rencontre/{rencontre_id}",
+    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",
+)
+@app.get(
+    "/api/v1/match/{rencontre_id}",
+    tags=["Matchs & Calendriers"],
+    summary="Détails complets d'une rencontre FFBB (alias /match)",
+    include_in_schema=False,
+)
+async def get_rencontre_detail(
+    rencontre_id: str = PathParam(
+        ...,
+        description="ID FFBB de la rencontre (ex: '200000014753740')",
+        examples=["200000014753740"],
+    ),
+):
+    """Retourne la fiche détaillée d'un match officiel FFBB avec scores, salle résolue et détails des équipes."""
+    client = get_client()
+    try:
+        match_data = await client.get_rencontre_async(rencontre_id)
+        if not match_data:
+            raise HTTPException(
+                status_code=404, detail=f"Rencontre {rencontre_id} introuvable."
+            )
+        return match_data
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get(
+    "/api/v1/salle/{salle_id}",
+    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')",
+        examples=["6543"],
+    ),
+):
+    """Retourne les informations complètes d'un gymnase (nom, rue, code postal, ville, cartographie)."""
+    client = get_client()
+    try:
+        salle = await client.get_salle_async(salle_id)
+        if not salle:
+            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
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get(
+    "/api/v1/competition/{competition_id}",
+    tags=["Compétitions & Poules"],
+    summary="Détails d'une compétition",
+    response_description="Informations sur la compétition et composition des poules",
+)
+async def get_competition_detail(
+    competition_id: int = PathParam(
+        ...,
+        ge=1,
+        description="ID FFBB de la compétition (ex: 200000002898785)",
+        examples=[200000002898785],
+    ),
+):
+    """Retourne les métadonnées et la liste des poules associées à une compétition officielle FFBB."""
+    client = get_client()
+    try:
+        comp = await client.get_competition_async(competition_id)
+        if not comp:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Compétition {competition_id} introuvable.",
+            )
+        return comp
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get(
+    "/api/v1/saisons",
+    tags=["Compétitions & Poules"],
+    summary="Liste des saisons officielles FFBB",
+    response_description="Historique et saison active",
+)
+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))
+
+
 # --------------------------------------------------------------------------
 # Modern API Documentation Interfaces (Scalar, Swagger UI, ReDoc)
 # --------------------------------------------------------------------------

{ffbb_data_client-2.4.29 → ffbb_data_client-2.4.31}/src/ffbb_data_client/helpers/meilisearch_client_extension.py

@@ -79,10 +79,11 @@ def _build_pagination_jobs(
     return jobs
 
 
-def _single_result(multi: MultiSearchResults, index: int) -> MultiSearchResults:
+def _single_result(multi: MultiSearchResults, index: int) -> MultiSearchResults | None:
     """Isole le i-ème sous-résultat d'un multi_search dans un MultiSearchResults
     à un élément, pour une fusion cohérente avec ``_merge_page``."""
-    assert multi.results is not None
+    if not multi.results or index >= len(multi.results):
+        return None
     return MultiSearchResults(results=[multi.results[index]])
 
 
@@ -148,7 +149,10 @@ class MeilisearchClientExtension(MeilisearchClient):
         out: list[tuple[int, int, MultiSearchResults | None]] = []
         if new_result and new_result.results:
             for k, (orig_idx, offset, _q) in enumerate(batch):
-                out.append((orig_idx, offset, _single_result(new_result, k)))
+                if k < len(new_result.results):
+                    res = _single_result(new_result, k)
+                    if res is not None:
+                        out.append((orig_idx, offset, res))
         return out
 
     async def _fetch_batch_async(
@@ -162,7 +166,10 @@ class MeilisearchClientExtension(MeilisearchClient):
         out: list[tuple[int, int, MultiSearchResults | None]] = []
         if new_result and new_result.results:
             for k, (orig_idx, offset, _q) in enumerate(batch):
-                out.append((orig_idx, offset, _single_result(new_result, k)))
+                if k < len(new_result.results):
+                    res = _single_result(new_result, k)
+                    if res is not None:
+                        out.append((orig_idx, offset, res))
         return out
 
     def recursive_smart_multi_search(

{ffbb_data_client-2.4.29 → 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.29
+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.29 → ffbb_data_client-2.4.31}/src/ffbb_data_client.egg-info/SOURCES.txt

@@ -320,6 +320,7 @@ tests/unit/test_310_discover_endpoints.py
 tests/unit/test_311_normalize_team_name.py
 tests/unit/test_312_api_cors.py
 tests/unit/test_313_api_metrics.py
+tests/unit/test_314_api_endpoints.py
 tests/unit/test_314_discover_permissions.py
 tests/unit/clients/__init__.py
 tests/unit/clients/test_200_api_ffbb_app_client.py

{ffbb_data_client-2.4.29 → ffbb_data_client-2.4.31}/src/ffbb_data_client.egg-info/scm_file_list.json

@@ -366,6 +366,7 @@
     "tests/unit/test_311_normalize_team_name.py",
     "tests/unit/test_312_api_cors.py",
     "tests/unit/test_313_api_metrics.py",
+    "tests/unit/test_314_api_endpoints.py",
     "tests/unit/test_314_discover_permissions.py",
     "tests/unit/utils/__init__.py",
     "tests/unit/utils/test_300_secure_logging.py",

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

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

{ffbb_data_client-2.4.29 → ffbb_data_client-2.4.31}/tests/unit/helpers/test_meilisearch_client_extension_recursive_pagination.py

@@ -91,3 +91,12 @@ def test_merge_page_with_empty_or_missing_results():
 
     # 3. orig_idx out of bounds
     _merge_page(res, 999, empty_page)
+
+
+def test_single_result_out_of_bounds_safety():
+    from ffbb_data_client.helpers.meilisearch_client_extension import _single_result
+
+    res = MultiSearchResults(results=[CompetitionsMultiSearchResult()])
+    assert _single_result(res, 0) is not None
+    assert _single_result(res, 1) is None
+    assert _single_result(MultiSearchResults(results=[]), 0) is None

ffbb_data_client-2.4.31/tests/unit/test_314_api_endpoints.py

@@ -0,0 +1,144 @@
+"""Tests for the REST endpoints, Best Practices, error envelopes, and caching in api.py."""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+
+from ffbb_data_client.api import app
+
+
+@pytest.mark.asyncio
+async def test_search_acronym_expansion():
+    transport = ASGITransport(app=app)
+    mock_client = MagicMock()
+    mock_client.multi_search = MagicMock(
+        return_value=[
+            {"index_uid": "organismes", "hits": [{"nom": "STADE CLERMONTOIS"}]}
+        ]
+    )
+    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/search?query=SCBA")
+            assert r.status_code == 200
+            mock_client.multi_search.assert_called_with(
+                name="Stade Clermontois Basket Auvergne"
+            )
+
+
+@pytest.mark.asyncio
+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()
+    mock_org.nom = "STADE CLERMONTOIS BASKET AUVERGNE"
+    mock_org.logo = None
+    mock_org.engagements = []
+    mock_client.get_organisme_async = AsyncMock(return_value=mock_org)
+
+    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?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
+async def test_rencontre_endpoint():
+    transport = ASGITransport(app=app)
+    mock_client = MagicMock()
+    mock_match = {"id": "12345", "nomEquipe1": "Eq A", "nomEquipe2": "Eq B"}
+    mock_client.get_rencontre_async = AsyncMock(return_value=mock_match)
+
+    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/rencontre/12345")
+            assert r.status_code == 200
+            assert r.json().get("id") == "12345"
+
+            # Test alias /match
+            r_alias = await ac.get("/api/v1/match/12345")
+            assert r_alias.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_salle_and_competition_endpoints_caching():
+    transport = ASGITransport(app=app)
+    mock_client = MagicMock()
+    mock_client.get_salle_async = AsyncMock(
+        return_value={"id": "6543", "libelle": "Gymnase Fleury"}
+    )
+    mock_client.get_competition_async = AsyncMock(
+        return_value={"id": "999", "nom": "DMU13"}
+    )
+    mock_client.get_saisons_async = AsyncMock(
+        return_value=[{"id": "1037", "nom": "2026-2027"}]
+    )
+
+    with patch("ffbb_data_client.api.get_client", return_value=mock_client):
+        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 "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
+            assert r_comp.json().get("nom") == "DMU13"
+
+            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