ffbb-data-client 2.4.24__tar.gz → 2.4.25__tar.gz

{ffbb_data_client-2.4.24 → ffbb_data_client-2.4.25}/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.25] - 2026-09-17
+
+### Features & Parity
+- **SDK Search Async Parity**: Standardisation de toutes les méthodes de recherche asynchrones (`search_organismes_async`, `search_competitions_async`, `search_pratiques_async`, `search_salles_async`, `search_terrains_async`, `search_tournois_async`, `search_engagements_async`, `search_formations_async`) avec support complet de `filter`, `sort` et `limit` (pagination).
+- **FastAPI Prometheus Monitoring**: Ajout d'un middleware de métriques et de l'endpoint `/metrics` officiel Prometheus pour le monitoring de la latence (histogram), du débit de requêtes, des jauges de requêtes en cours et de l'état des caches mémoires.
+
 ## [2.4.6] - 2026-08-29
 
 ### Performance & Modern Standards (FastAPI Lifespan)

{ffbb_data_client-2.4.24 → ffbb_data_client-2.4.25}/PKG-INFO

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

@@ -7,9 +7,11 @@ Swagger UI at /swagger, ReDoc at /redoc, and hosts the official website at /.
 from __future__ import annotations
 
 import asyncio
+import bisect
 import logging
 import os
 import re
+import threading
 import time
 from collections import OrderedDict
 from contextlib import asynccontextmanager
@@ -95,7 +97,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.23",
+    version="2.4.25",
     openapi_tags=TAGS_METADATA,
     docs_url=None,
     redoc_url=None,
@@ -126,6 +128,48 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+# ---------------------------------------------------------------------------
+# Prometheus Metrics State & Middleware
+# ---------------------------------------------------------------------------
+_API_START_TIME = time.time()
+_LATENCY_BUCKETS = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0)
+_http_requests: dict[tuple[str, str, int], int] = {}
+_http_latency_bucket_counts: list[int] = [0] * (len(_LATENCY_BUCKETS) + 1)
+_http_latency_sum: float = 0.0
+_http_latency_count: int = 0
+_http_inflight: int = 0
+_metrics_lock = threading.Lock()
+
+
+@app.middleware("http")
+async def prometheus_metrics_middleware(request: Request, call_next):
+    global _http_inflight, _http_latency_sum, _http_latency_count
+    with _metrics_lock:
+        _http_inflight += 1
+    t0 = time.perf_counter()
+    status_code = 500
+    try:
+        response = await call_next(request)
+        status_code = response.status_code
+        return response
+    finally:
+        latency = time.perf_counter() - t0
+        path = request.url.path
+        # Normalize dynamic numeric IDs to prevent metric cardinality explosion
+        norm_path = re.sub(r"/\d+", "/{id}", path)
+        method = request.method
+        with _metrics_lock:
+            _http_inflight -= 1
+            key = (method, norm_path, status_code)
+            _http_requests[key] = _http_requests.get(key, 0) + 1
+            _http_latency_sum += latency
+            _http_latency_count += 1
+            idx = bisect.bisect_left(_LATENCY_BUCKETS, latency)
+            if idx < len(_LATENCY_BUCKETS):
+                _http_latency_bucket_counts[idx] += 1
+            _http_latency_bucket_counts[len(_LATENCY_BUCKETS)] += 1
+
+
 # Global Client Singleton
 _client: FFBBDataClient | None = None
 
@@ -550,6 +594,70 @@ async def health_head():
     return Response(status_code=200)
 
 
+@app.get(
+    "/metrics",
+    tags=["Monitoring & Diagnostic"],
+    summary="Métriques Prometheus de l'API (/metrics)",
+    response_class=Response,
+)
+async def metrics():
+    """Expose les métriques temps réel du serveur au format officiel Prometheus."""
+    with _metrics_lock:
+        uptime = time.time() - _API_START_TIME
+        requests = dict(_http_requests)
+        lat_buckets = list(_http_latency_bucket_counts)
+        lat_sum = _http_latency_sum
+        lat_count = _http_latency_count
+        inflight = _http_inflight
+
+    lines: list[str] = [
+        "# HELP ffbb_api_uptime_seconds Uptime du serveur API en secondes",
+        "# TYPE ffbb_api_uptime_seconds gauge",
+        f"ffbb_api_uptime_seconds {uptime:.2f}",
+        "",
+        "# HELP ffbb_api_http_requests_total Total des requetes HTTP reçues par methode, route et statut",
+        "# TYPE ffbb_api_http_requests_total counter",
+    ]
+    for (method, path, status), count in sorted(requests.items()):
+        lines.append(
+            f'ffbb_api_http_requests_total{{method="{method}",path="{path}",status="{status}"}} {count}'
+        )
+
+    lines += [
+        "",
+        "# HELP ffbb_api_http_latency_seconds Latence des requetes HTTP en secondes",
+        "# TYPE ffbb_api_http_latency_seconds histogram",
+    ]
+    cumulative = 0
+    for i, bound in enumerate(_LATENCY_BUCKETS):
+        cumulative += lat_buckets[i]
+        lines.append(
+            f'ffbb_api_http_latency_seconds_bucket{{le="{bound}"}} {cumulative}'
+        )
+    lines.append(f'ffbb_api_http_latency_seconds_bucket{{le="+Inf"}} {lat_count}')
+    lines.append(f"ffbb_api_http_latency_seconds_sum {lat_sum:.4f}")
+    lines.append(f"ffbb_api_http_latency_seconds_count {lat_count}")
+
+    lines += [
+        "",
+        "# HELP ffbb_api_http_inflight_requests Requetes HTTP actuellement en cours d'execution",
+        "# TYPE ffbb_api_http_inflight_requests gauge",
+        f"ffbb_api_http_inflight_requests {inflight}",
+        "",
+        "# HELP ffbb_api_cache_entries Nombre d'elements dans les caches LRU en memoire",
+        "# TYPE ffbb_api_cache_entries gauge",
+        f'ffbb_api_cache_entries{{cache="organisme"}} {len(_org_cache._cache)}',
+        f'ffbb_api_cache_entries{{cache="logo"}} {len(_logo_cache._cache)}',
+        f'ffbb_api_cache_entries{{cache="salle"}} {len(_salle_cache._cache)}',
+        "",
+    ]
+
+    return Response(
+        content="\n".join(lines) + "\n",
+        media_type="text/plain; version=0.0.4; charset=utf-8",
+    )
+
+
 @app.get(
     "/api/v1/search",
     tags=["Recherche & Meilisearch"],

{ffbb_data_client-2.4.24 → ffbb_data_client-2.4.25}/src/ffbb_data_client/clients/_search_facade.py

@@ -137,18 +137,20 @@ class _SearchFacade:
         )
 
     async def search_competitions_async(
-        self, name: str | None = None
+        self,
+        name: str | None = None,
+        filter: list[str] | None = None,
+        sort: list[str] | None = None,
+        limit: int | None = 10,
     ) -> CompetitionsMultiSearchResult | None:
         """Search for competitions asynchronously."""
-        if not name:
-            return None
-        queries = [CompetitionsMultiSearchQuery(name)]
-        results = await self._meilisearch.recursive_smart_multi_search_async(queries)
-        return (
-            cast(CompetitionsMultiSearchResult, results.results[0])
-            if results and results.results
-            else None
+        results = await self.search_multiple_competitions_async(
+            [name] if name is not None else None,
+            filter=filter,
+            sort=sort,
+            limit=limit,
         )
+        return results[0] if results else None
 
     async def search_multiple_competitions_async(
         self,
@@ -247,18 +249,20 @@ class _SearchFacade:
         )
 
     async def search_organismes_async(
-        self, name: str | None = None
+        self,
+        name: str | None = None,
+        filter: list[str] | None = None,
+        sort: list[str] | None = None,
+        limit: int | None = 10,
     ) -> OrganismesMultiSearchResult | None:
         """Search for organismes asynchronously."""
-        if not name:
-            return None
-        queries = [OrganismesMultiSearchQuery(name)]
-        results = await self._meilisearch.recursive_smart_multi_search_async(queries)
-        return (
-            cast(OrganismesMultiSearchResult, results.results[0])
-            if results and results.results
-            else None
+        results = await self.search_multiple_organismes_async(
+            [name] if name is not None else None,
+            filter=filter,
+            sort=sort,
+            limit=limit,
         )
+        return results[0] if results else None
 
     async def search_multiple_organismes_async(
         self,
@@ -324,18 +328,20 @@ class _SearchFacade:
         )
 
     async def search_pratiques_async(
-        self, name: str | None = None
+        self,
+        name: str | None = None,
+        filter: list[str] | None = None,
+        sort: list[str] | None = None,
+        limit: int | None = 10,
     ) -> PratiquesMultiSearchResult | None:
         """Search for pratiques asynchronously."""
-        if not name:
-            return None
-        queries = [PratiquesMultiSearchQuery(name)]
-        results = await self._meilisearch.recursive_smart_multi_search_async(queries)
-        return (
-            cast(PratiquesMultiSearchResult, results.results[0])
-            if results and results.results
-            else None
+        results = await self.search_multiple_pratiques_async(
+            [name] if name is not None else None,
+            filter=filter,
+            sort=sort,
+            limit=limit,
         )
+        return results[0] if results else None
 
     async def search_multiple_pratiques_async(
         self,
@@ -524,18 +530,20 @@ class _SearchFacade:
         return cast(list[SallesMultiSearchResult], results.results) if results else None
 
     async def search_salles_async(
-        self, name: str | None = None
+        self,
+        name: str | None = None,
+        filter: list[str] | None = None,
+        sort: list[str] | None = None,
+        limit: int | None = 10,
     ) -> SallesMultiSearchResult | None:
         """Search for salles asynchronously."""
-        if not name:
-            return None
-        queries = [SallesMultiSearchQuery(name)]
-        results = await self._meilisearch.recursive_smart_multi_search_async(queries)
-        return (
-            cast(SallesMultiSearchResult, results.results[0])
-            if results and results.results
-            else None
+        results = await self.search_multiple_salles_async(
+            [name] if name is not None else None,
+            filter=filter,
+            sort=sort,
+            limit=limit,
         )
+        return results[0] if results else None
 
     async def search_multiple_salles_async(
         self,
@@ -597,18 +605,20 @@ class _SearchFacade:
         )
 
     async def search_terrains_async(
-        self, name: str | None = None
+        self,
+        name: str | None = None,
+        filter: list[str] | None = None,
+        sort: list[str] | None = None,
+        limit: int | None = 10,
     ) -> TerrainsMultiSearchResult | None:
         """Search for terrains asynchronously."""
-        if not name:
-            return None
-        queries = [TerrainsMultiSearchQuery(name)]
-        results = await self._meilisearch.recursive_smart_multi_search_async(queries)
-        return (
-            cast(TerrainsMultiSearchResult, results.results[0])
-            if results and results.results
-            else None
+        results = await self.search_multiple_terrains_async(
+            [name] if name is not None else None,
+            filter=filter,
+            sort=sort,
+            limit=limit,
         )
+        return results[0] if results else None
 
     async def search_multiple_terrains_async(
         self,
@@ -672,18 +682,20 @@ class _SearchFacade:
         )
 
     async def search_tournois_async(
-        self, name: str | None = None
+        self,
+        name: str | None = None,
+        filter: list[str] | None = None,
+        sort: list[str] | None = None,
+        limit: int | None = 10,
     ) -> TournoisMultiSearchResult | None:
         """Search for tournois asynchronously."""
-        if not name:
-            return None
-        queries = [TournoisMultiSearchQuery(name)]
-        results = await self._meilisearch.recursive_smart_multi_search_async(queries)
-        return (
-            cast(TournoisMultiSearchResult, results.results[0])
-            if results and results.results
-            else None
+        results = await self.search_multiple_tournois_async(
+            [name] if name is not None else None,
+            filter=filter,
+            sort=sort,
+            limit=limit,
         )
+        return results[0] if results else None
 
     async def search_multiple_tournois_async(
         self,
@@ -791,18 +803,20 @@ class _SearchFacade:
         )
 
     async def search_engagements_async(
-        self, name: str | None = None
+        self,
+        name: str | None = None,
+        filter: list[str] | None = None,
+        sort: list[str] | None = None,
+        limit: int | None = 10,
     ) -> EngagementsMultiSearchResult | None:
         """Search for engagements asynchronously."""
-        if not name:
-            return None
-        queries = [EngagementsMultiSearchQuery(name)]
-        results = await self._meilisearch.recursive_smart_multi_search_async(queries)
-        return (
-            cast(EngagementsMultiSearchResult, results.results[0])
-            if results and results.results
-            else None
+        results = await self.search_multiple_engagements_async(
+            [name] if name is not None else None,
+            filter=filter,
+            sort=sort,
+            limit=limit,
         )
+        return results[0] if results else None
 
     async def search_multiple_engagements_async(
         self,
@@ -870,18 +884,20 @@ class _SearchFacade:
         )
 
     async def search_formations_async(
-        self, name: str | None = None
+        self,
+        name: str | None = None,
+        filter: list[str] | None = None,
+        sort: list[str] | None = None,
+        limit: int | None = 10,
     ) -> FormationsMultiSearchResult | None:
         """Search for formations asynchronously."""
-        if not name:
-            return None
-        queries = [FormationsMultiSearchQuery(name)]
-        results = await self._meilisearch.recursive_smart_multi_search_async(queries)
-        return (
-            cast(FormationsMultiSearchResult, results.results[0])
-            if results and results.results
-            else None
+        results = await self.search_multiple_formations_async(
+            [name] if name is not None else None,
+            filter=filter,
+            sort=sort,
+            limit=limit,
         )
+        return results[0] if results else None
 
     async def search_multiple_formations_async(
         self,

{ffbb_data_client-2.4.24 → ffbb_data_client-2.4.25}/src/ffbb_data_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffbb-data-client
-Version: 2.4.24
+Version: 2.4.25
 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.24 → ffbb_data_client-2.4.25}/src/ffbb_data_client.egg-info/SOURCES.txt

@@ -315,6 +315,7 @@ tests/unit/conftest.py
 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/clients/__init__.py
 tests/unit/clients/test_200_api_ffbb_app_client.py
 tests/unit/clients/test_201_unit_tests_core.py

{ffbb_data_client-2.4.24 → ffbb_data_client-2.4.25}/src/ffbb_data_client.egg-info/scm_file_list.json

@@ -361,6 +361,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/utils/__init__.py",
     "tests/unit/utils/test_300_secure_logging.py",
     "tests/unit/utils/test_301_input_validation.py",

ffbb_data_client-2.4.25/src/ffbb_data_client.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.4.25",
+  "distance": 0,
+  "node": "g26a270fad648b215937496d899f124d8eb80f2d4",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-17"
+}

{ffbb_data_client-2.4.24 → ffbb_data_client-2.4.25}/tests/unit/clients/test_v2_backport_search.py

@@ -122,3 +122,53 @@ class TestV2BackportSearch(unittest.TestCase):
         mock_rms.assert_called_once()
         queries = mock_rms.call_args[0][0]
         self.assertEqual(queries[0].limit, 3)
+
+
+class TestV2BackportSearchAsync(unittest.IsolatedAsyncioTestCase):
+    """Async tests for search_*_async filter/sort/limit parameters."""
+
+    async def asyncSetUp(self) -> None:
+        with patch("ffbb_data_client.clients.meilisearch_client.CacheManager"):
+            api_client = MagicMock(spec=ApiFFBBAppClient)
+            api_client.cached_session = None
+            api_client.async_cached_session = None
+            meilisearch_client = MeilisearchFFBBClient(bearer_token="test-token")
+            self.client = FFBBDataClient(api_client, meilisearch_client)
+
+    def _make_mock_results(self, result_mock: MagicMock) -> MultiSearchResults:
+        results = MagicMock(spec=MultiSearchResults)
+        results.results = [result_mock]
+        return results
+
+    @patch.object(MeilisearchFFBBClient, "recursive_smart_multi_search_async")
+    async def test_search_organismes_async_with_limit_and_filter(
+        self, mock_rms_async: MagicMock
+    ) -> None:
+        mock_result = MagicMock(spec=OrganismesMultiSearchResult)
+        mock_rms_async.return_value = self._make_mock_results(mock_result)
+
+        result = await self.client.search_organismes_async(
+            "Clermont",
+            filter=['codePostal = "63000"'],
+            sort=["nom:asc"],
+            limit=5,
+        )
+        self.assertIsNotNone(result)
+        mock_rms_async.assert_called_once()
+        queries = mock_rms_async.call_args[0][0]
+        self.assertEqual(queries[0].limit, 5)
+        self.assertEqual(queries[0].filter, ['codePostal = "63000"'])
+        self.assertEqual(queries[0].sort, ["nom:asc"])
+
+    @patch.object(MeilisearchFFBBClient, "recursive_smart_multi_search_async")
+    async def test_search_competitions_async_with_limit(
+        self, mock_rms_async: MagicMock
+    ) -> None:
+        mock_result = MagicMock(spec=CompetitionsMultiSearchResult)
+        mock_rms_async.return_value = self._make_mock_results(mock_result)
+
+        result = await self.client.search_competitions_async("U13", limit=7)
+        self.assertIsNotNone(result)
+        mock_rms_async.assert_called_once()
+        queries = mock_rms_async.call_args[0][0]
+        self.assertEqual(queries[0].limit, 7)

ffbb_data_client-2.4.25/tests/unit/test_313_api_metrics.py

@@ -0,0 +1,33 @@
+"""Unit tests for Prometheus /metrics endpoint on FastAPI API."""
+
+import httpx
+import pytest
+
+from ffbb_data_client.api import app
+
+
+@pytest.mark.asyncio
+async def test_metrics_endpoint_returns_valid_prometheus_format():
+    """Verify that /metrics endpoint returns 200 with standard Prometheus exposition format."""
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        # Trigger an endpoint to record metrics
+        health_resp = await client.get("/health")
+        assert health_resp.status_code == 200
+
+        # Now query /metrics
+        metrics_resp = await client.get("/metrics")
+        assert metrics_resp.status_code == 200
+        assert "text/plain" in metrics_resp.headers.get("content-type", "")
+
+        text = metrics_resp.text
+        assert "ffbb_api_uptime_seconds" in text
+        assert "ffbb_api_http_requests_total" in text
+        assert "ffbb_api_http_latency_seconds_bucket" in text
+        assert "ffbb_api_http_latency_seconds_sum" in text
+        assert "ffbb_api_http_latency_seconds_count" in text
+        assert "ffbb_api_http_inflight_requests" in text
+        assert "ffbb_api_cache_entries" in text
+        assert 'path="/health"' in text
+        assert 'status="200"' in text

ffbb_data_client-2.4.24/src/ffbb_data_client.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.4.24",
-  "distance": 0,
-  "node": "g48944fcb30cb345a1de2e8155012960a5bbace66",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-09-16"
-}