ffbb-data-client 2.0.0

FFBB API Python Client (V3) — SDK asynchrone pour les Statistiques de Basket France. Type-safe Pydantic models, async/sync, Meilisearch.

🏀 FFBB API Python Client V3

SDK Python moderne, typé et asynchrone pour exploiter les données publiques FFBB : clubs, compétitions, rencontres, classements, salles, officiels et recherche Meilisearch.

Installation • Démarrage rapide • Fonctionnalités • Recherche • Async • Développement

---

📌 À 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.

La V3 remplace l’approche V2 basée sur des dictionnaires bruts et une configuration manuelle. Elle privilégie le typage, la robustesse réseau et les appels batchés.

---

🚀 Version v1.7.0 — 30 avril 2026

Principales évolutions récentes :

• ajout d'entités REST et Meilisearch : rencontres, officiels, entraîneurs, communes et assets ;
• réutilisation des clients httpx synchrones et asynchrones ;
• cache Meilisearch optimisé pour limiter les copies coûteuses ;
• retries de transport configurables via CacheConfig.transport_retries ;
• mise à jour des schémas OpenAPI, collections et index ;
• stabilisation CI, typage, tests et formatage.

Voir aussi : 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

Domaine	Capacités
API FFBB	clubs, compétitions, organismes, saisons, poules, classements, rencontres, lives
Recherche	organismes, compétitions, rencontres, salles, terrains, pratiques, tournois, engagements et formations
REST typé	récupération de ressources individuelles avec modèles Pydantic v2
Async	méthodes *_async() pour les appels réseau non bloquants
Cache	cache HTTP hishel, sessions httpx réutilisées, retries configurables
Sécurité	masquage des tokens dans les logs
IA / MCP	structure compatible avec des wrappers MCP et agents IA

---

🔍 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

Ressource	Méthode sync	Méthode async
Recherche globale	multi_search()	multi_search_async()
Clubs / organismes	search_organismes()	search_organismes_async()
Compétitions	search_competitions()	search_competitions_async()
Rencontres	search_rencontres()	search_rencontres_async()
Salles	search_salles()	search_salles_async()
Terrains	search_terrains()	search_terrains_async()
Pratiques	search_pratiques()	search_pratiques_async()
Tournois	search_tournois()	search_tournois_async()
Engagements	search_engagements()	search_engagements_async()
Formations	search_formations()	search_formations_async()

---

🧱 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
│   ├── api_ffbb_app_client.py      # Client REST FFBB
│   └── meilisearch_ffbb_client.py  # Client recherche Meilisearch
├── helpers/                        # Requêtes HTTP, multi-search, conversions
├── models/                         # Modèles Pydantic v2
├── utils/                          # cache, tokens, logging sécurisé
└── data/                           # schémas et métadonnées embarqués

---

🧪 Développement local

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

Commandes utiles :

pytest tests/unit/
pytest tests/integration/
pytest tests/ --cov=src

Documentation complémentaire :

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

---

🤖 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.

---

Si ce projet vous aide, une étoile est appréciée. ⭐