ffbb-data-client 2.1.0

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

🏀 FFBB Data Client

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 v2.1.0 — Mai 2026

Principales évolutions récentes :

• unification sync/async : les méthodes synchrones délèguent désormais à leurs homologues asynchrones via _run_async(), éliminant ~604 lignes de duplication ;
• nouvelles entités : EDF (matches, joueurs, rosters, équipes), Genius Sport (matches, live logs), Rematch Videos ;
• cache SQLite concurrency-safe : fichiers séparés pour sync (http_cache.db) et async (http_cache_async.db) ;
• CI renforcée : mypy + pyright + CodeQL + Dependabot + hook pre-push ;
• nettoyage : suppression du shim ffbb_api_client_v3, scripts morts et code mort (invalidate_pattern).

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
Entités additionnelles	EDF (matches, joueurs, rosters, équipes), Genius Sport, Rematch Videos
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() — source de vérité ; sync délègue via _run_async()
Cache	cache HTTP hishel, sessions httpx réutilisées, retries configurables, SQLite séparés sync/async
Sécurité	masquage des tokens dans les logs, CodeQL scanning, Dependabot
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 (sync → async delegation)
│   ├── 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.

---

🧪 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

---

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