📌 À propos

ffbb_data_client simplifie l'accès aux API FFBB et à leurs index Meilisearch avec :

• une façade unique : FFBBDataClient ;
• des modèles Pydantic v2 typés ;
• une API utilisable en synchrone ou en async/await ;
• une gestion automatique des tokens via TokenManager ;
• du cache HTTP configurable via hishel ;
• des helpers prêts pour l'intégration MCP / agents IA.

🚀 Nouveautés

Les évolutions de chaque version sont documentées dans les GitHub Releases, ainsi que dans CHANGELOG.md et RELEASE_NOTES.md.

📦 Installation

pip install ffbb-data-client

Pour contribuer ou exécuter les tests :

git clone https://github.com/nickdesi/ffbb-data-client.git
cd ffbb-data-client
pip install -e ".[testing]"

Prérequis : Python >=3.10.

⚡ Démarrage rapide

from ffbb_data_client import FFBBDataClient

client = FFBBDataClient.create()

# Recherche globale sur les index FFBB
results = client.multi_search("Pau Orthez")

for result in results or []:
    print(result.index_uid, len(result.hits or []))

# Lives en cours
lives = client.get_lives()

FFBBDataClient.create() résout automatiquement les tokens si aucun token n'est passé explicitement.

✨ Fonctionnalités

🔍 Recherche Meilisearch

Recherche globale

results = client.multi_search("Clermont")

Recherche ciblée

organismes = client.search_organismes(
    "Clermont",
    filter=['codePostal = "63000"'],
    sort=["nom:asc"],
    limit=10,
)

rencontres = client.search_rencontres("N1M", limit=20)
salles = client.search_salles("Maison des Sports", limit=5)
engagements = client.search_engagements("U15M", limit=20)

Recherche géographique

clubs = client.search_organismes_by_geo(
    lat=45.7772,
    lng=3.0870,
    radius_km=20,
    limit=20,
)

Principales méthodes exposées

🧱 Accès REST typé

# Ressources principales
organisme = client.get_organisme(12345)
competition = client.get_competition(67890)
poule = client.get_poule(11111)

# Ressources ajoutées récemment
rencontre = client.get_rencontre(22222)
officiel = client.get_officiel(33333)
entraineur = client.get_entraineur(44444)

Les assets Directus et autres collections peuvent être exploités via les méthodes REST/listing dédiées exposées par le client lorsque disponibles.

Les réponses sont converties en modèles Pydantic lorsque le schéma est connu, ce qui apporte validation, autocomplétion et sérialisation propre.

🧵 Utilisation asynchrone

import asyncio
from ffbb_data_client import FFBBDataClient

async def main() -> None:
    client = FFBBDataClient.create()

    results = await client.search_organismes_async("ASVEL")
    lives = await client.get_lives_async()

    print(results.estimated_total_hits if results else 0)
    print(len(lives or []))

asyncio.run(main())

🔐 Tokens et configuration

Par défaut, le client utilise TokenManager.get_tokens() au moment de la création :

from ffbb_data_client import FFBBDataClient, TokenManager

tokens = TokenManager.get_tokens()

client = FFBBDataClient.create(
    api_bearer_token=tokens.api_token,
    meilisearch_bearer_token=tokens.meilisearch_token,
)

Il est donc possible de laisser le client résoudre les tokens automatiquement ou de les fournir explicitement selon le contexte d'exécution.

🏗 Architecture

src/ffbb_data_client/
├── clients/
│   ├── ffbb_data_client.py       # Façade publique (272 lignes, delegation)
│   ├── _rest_facade.py           # Façade REST API (Directus)
│   ├── _search_facade.py         # Façade recherche Meilisearch
│   ├── api_ffbb_app_client.py    # Client REST FFBB (async source of truth)
│   └── meilisearch_ffbb_client.py # Client recherche Meilisearch
├── helpers/                       # Requêtes HTTP, multi-search, conversions
├── models/                        # Modèles Pydantic v2
├── utils/                         # cache (sync/async séparés), tokens, logging sécurisé
└── data/                          # schémas et métadonnées embarqués

Architecture sync/async : Depuis v2.1.0, les méthodes asynchrones sont la source de vérité. Les méthodes synchrones délèguent via _run_async(), un helper qui gère les event loops imbriqués avec ThreadPoolExecutor.

Architecture facades : Depuis v2.2.0, FFBBDataClient est une fine coquille qui compose _RestFacade et _SearchFacade. L'API publique reste identique — client.get_organisme(123) fonctionne comme avant.

🧪 Développement local

pip install -e ".[testing]"
pytest tests/

Commandes utiles :

pytest tests/unit/
pytest tests/integration/
pytest tests/ --cov=src
tox -e type          # mypy + pyright

Hooks automatiques :

• pre-push : exécute mypy + pyright avant chaque push
• pre-commit : black, isort, flake8, trailing-whitespace

Documentation complémentaire :

• LOCAL_CI_GUIDE.md
• docs/testing_conventions.md
• docs/architecture.rst

🛠️ Découverte d'API et Détection de Drift (Schema Drift)

Le projet intègre un système robuste de surveillance quotidienne de l'API de production de la FFBB (Directus & Meilisearch) afin de détecter immédiatement l'apparition de nouvelles ressources, de nouveaux champs ou de changements de types.

1. Fonctionnement

• Script de découverte : scripts/discover_endpoints.py interroge dynamiquement l'OpenAPI spec Directus de la FFBB, extrait toutes les collections, sonde les index Meilisearch (via un échantillonnage agrégé sur 20 hits) et calcule les différences structurelles avec les fichiers locaux.
• Détection de dérive : Le script compare les structures internes de chaque modèle (propriétés ajoutées, supprimées ou types modifiés) ainsi que les attributs Meilisearch, et génère un rapport consolidé dans data/api_update_summary.md.

2. Automatisation CI/CD

Un workflow quotidien (update-ffbb-api-discovery.yml) s'exécute chaque matin à 5h17 UTC pour :

1. Télécharger l'OpenAPI spec et sonder Meilisearch en production.
2. Analyser les dérives structurelles.
3. Si un changement structurel est détecté (ajout de collection, de propriétés ou d'index), le workflow ouvre automatiquement une Pull Request sur GitHub contenant un résumé des modifications pour permettre aux développeurs de mettre à jour les modèles Pydantic.

3. Exécution locale

Pour lancer manuellement la découverte d'API et mettre à jour les fichiers de schémas locaux :

python scripts/discover_endpoints.py

🤖 Intégration IA / MCP

Le client sert de base au serveur MCP FFBB et expose une API stable pour construire des outils agent-friendly : recherche de clubs, récupération de poules, classements, lives, calendriers et détails de rencontres.

Projet associé : FFBB-MCP-Server

🤝 Contribuer

Les contributions sont bienvenues :

• ouvrez une issue pour un bug ;
• proposez une évolution via les discussions ;
• lancez les tests localement avant une pull request.

📄 Licence

Distribué sous licence Apache-2.0. Voir LICENSE.txt.