ffbb-data-client 2.4.19__tar.gz → 2.4.20__tar.gz

ffbb_data_client-2.4.20/PKG-INFO

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: ffbb-data-client
+Version: 2.4.20
+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
+Author-email: nicolas.desimone@gmail.com
+License: Apache-2.0
+Project-URL: Homepage, https://nickdesi.github.io/ffbb-data-client/
+Project-URL: Documentation, https://nickdesi.github.io/ffbb-data-client/
+Project-URL: Source, https://github.com/nickdesi/ffbb-data-client
+Project-URL: Changelog, https://github.com/nickdesi/ffbb-data-client/blob/master/CHANGELOG.md
+Project-URL: Tracker, https://github.com/nickdesi/ffbb-data-client/issues
+Project-URL: Release Notes, https://github.com/nickdesi/ffbb-data-client/blob/master/RELEASE_NOTES.md
+Keywords: ffbb-api,api-ffbb,ffbb,api,basketball,basket-france,statistiques,python-sdk,pydantic,asynchrone,meilisearch,ffbb-api-client,ffbb-api-client-v2,open-data-basket,live-scores
+Platform: any
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: French
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8
+License-File: LICENSE.txt
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: hishel[async]>=1.3.0
+Requires-Dist: pydantic>=2.13.4
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115.0; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.34.0; extra == "server"
+Requires-Dist: starlette>=0.45.0; extra == "server"
+Provides-Extra: testing
+Requires-Dist: setuptools>=82.0.1; extra == "testing"
+Requires-Dist: coverage>=7.13.5; extra == "testing"
+Requires-Dist: pytest>=9.0.3; extra == "testing"
+Requires-Dist: pytest-xdist>=3.8.0; extra == "testing"
+Requires-Dist: pytest-cov>=7.1.0; extra == "testing"
+Requires-Dist: respx>=0.23.1; extra == "testing"
+Requires-Dist: pytest-asyncio>=1.3.0; extra == "testing"
+Requires-Dist: readme_renderer[md]>=44.0; extra == "testing"
+Provides-Extra: typing
+Requires-Dist: types-python-dateutil>=2.9.0.20260408; extra == "typing"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/nickdesi/ffbb-data-client/master/website/assets/logo.webp" alt="FFBB Data Client Logo" width="160" style="margin-bottom: 12px; border-radius: 20px; box-shadow: 0 8px 24px rgba(255, 107, 0, 0.25);" />
+
+# 🏀 FFBB Data Client
+### L'API Officielle du Basket Français en Python & Recherche Meilisearch
+
+**Le SDK Python moderne, ultra-rapide, asynchrone et typé pour exploiter l'API de la Fédération Française de BasketBall (FFBB) : clubs, compétitions nationales & régionales, scores en direct (lives), classements, calendriers, gymnases/salles et détection de niveau.**
+
+*Alternative officielle, haute performance et maintenue aux anciens packages obsolètes `ffbb-api-client` et `ffbb-api-client-v2`.*
+
+<p align="center">
+  <a href="https://pypi.org/project/ffbb-data-client/"><img src="https://img.shields.io/pypi/v/ffbb-data-client?color=ff6b00&label=PyPI%20Release&logo=python&logoColor=white&style=for-the-badge" alt="PyPI version" /></a>
+  <a href="https://pypi.org/project/ffbb-data-client/"><img src="https://img.shields.io/pypi/pyversions/ffbb-data-client?logo=python&logoColor=white&style=for-the-badge&color=238636" alt="Python versions" /></a>
+  <a href="https://github.com/nickdesi/ffbb-data-client/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/nickdesi/ffbb-data-client/ci.yml?branch=master&label=CI%20Build&logo=github&style=for-the-badge" alt="CI Status" /></a>
+  <a href="https://coveralls.io/github/nickdesi/ffbb-data-client?branch=master"><img src="https://img.shields.io/coveralls/github/nickdesi/ffbb-data-client/master?style=for-the-badge&logo=coveralls" alt="Coverage" /></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/nickdesi/FFBB-MCP-Server"><img src="https://img.shields.io/badge/MCP-Ready-0969da.svg?logo=modelcontextprotocol&logoColor=white&style=flat-square" alt="MCP Ready" /></a>
+  <a href="https://github.com/nickdesi/ffbb-data-client/blob/master/LICENSE.txt"><img src="https://img.shields.io/badge/License-Apache--2.0-blue.svg?style=flat-square" alt="License" /></a>
+  <a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/Code%20Style-Black-000000.svg?style=flat-square" alt="Code Style: Black" /></a>
+  <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/Fast%20Packaging-uv-de5fe9.svg?style=flat-square" alt="Packaged with uv" /></a>
+  <a href="https://github.com/nickdesi/ffbb-data-client/stargazers"><img src="https://img.shields.io/github/stars/nickdesi/ffbb-data-client?style=flat-square&color=gold" alt="GitHub Stars" /></a>
+  <a href="https://ffbb-api.desimone.fr/"><img src="https://img.shields.io/badge/Web-ffbb--api.desimone.fr-blue?style=flat-square&logo=googlechrome&logoColor=white" alt="API Website" /></a>
+</p>
+
+---
+
+[⚡ Démarrage Rapide](#-démarrage-rapide-30-secondes) •
+[📍 Recherche Géo & Clubs](#-recherche-géographique--clubs-de-france) •
+[🔥 Cas d'Usage](#-recettes--cas-dusage-concrets) •
+[🧵 Streaming Async](#-haute-performance--streaming-asynchrone) •
+[🤖 Intégration IA / MCP](#-ia-agents--mcp-server) •
+[🌐 API REST](#-serveur-rest-fastapi-embarqué) •
+[📖 Documentation](https://nickdesi.github.io/ffbb-data-client/)
+
+</div>
+
+<!-- DISCOVERY_METRICS:START -->
+> 🔄 **Cartographie API FFBB Synchronisée en Direct** : `162` collections Directus OpenAPI cartographiées, `13` index Meilisearch surveillés quotidiennement.
+<!-- DISCOVERY_METRICS:END -->
+
+---
+
+## 🏆 Pourquoi choisir `ffbb-data-client` ?
+
+| Fonctionnalité | Anciens clients (`ffbb-api-client`) | **`ffbb-data-client` (v2.4+)** |
+| :--- | :---: | :---: |
+| **Bypass WAF BunnyCDN** (anti-403) | ❌ Bloqué en 403 Forbidden | ✅ **Garanti (okhttp/4.12.0 emulated)** |
+| **Architecture Asynchrone Native** | ❌ 100% bloquant / synchrone | ✅ **Async native (`async/await` + `aiter`)** |
+| **Modèles de Données & Typage** | ❌ Dictionnaires bruts sans type | ✅ **Dataclasses & Pydantic v2 validés** |
+| **Recherche Meilisearch Instantanée** | ❌ Partielle ou absente | ✅ **Multi-index (Clubs, Salles, Poules, 3x3)** |
+| **Recherche Géographique par GPS** | ❌ Non disponible | ✅ **Rayon kilométrique autour de coordonnées** |
+| **Streaming de Masse (Pagination auto)** | ❌ Manuelle, risque d'OOM | ✅ **Générateurs streaming `aiter_all_*`** |
+| **Résolution d'Adresses de Salles** | ❌ Nom brut souvent vide | ✅ **Résolution physique complète (Gymnase, Rue, CP, Ville)** |
+| **Compatibilité IA & Agents MCP** | ❌ Incompatible | ✅ **Connecteur natif Model Context Protocol** |
+| **Couverture de Tests & Fiabilité** | ⚠️ < 30% | ✅ **680+ tests unitaires & 100% Zero-Red CI** |
+
+---
+
+## 📦 Installation
+
+Installez la dernière version stable via `pip` ou `uv` :
+
+```bash
+# Via pip standard
+pip install ffbb-data-client
+
+# Via uv (recommandé pour la rapidité)
+uv add ffbb-data-client
+```
+
+### Options supplémentaires
+
+```bash
+# Avec le serveur d'API REST FastAPI intégré
+pip install "ffbb-data-client[server]"
+
+# Pour le développement local et la suite de tests complète
+pip install "ffbb-data-client[testing]"
+```
+
+*Prérequis : Python `>=3.10`.*
+
+---
+
+## ⚡ Démarrage Rapide (30 secondes)
+
+Aucun compte développeur ni clé d'API compliquée : `FFBBDataClient.create()` résout et rafraîchit automatiquement les tokens publics nécessaires :
+
+```python
+from ffbb_data_client import FFBBDataClient
+
+# Initialisation en une seule ligne (zéro configuration requise)
+client = FFBBDataClient.create()
+
+# 1. Rechercher un club de basket en France
+clubs = client.search_organismes("Clermont", limit=3)
+for club in clubs.hits:
+    print(f"🏀 {club.nom} ({club.codePostal} {club.commune}) - ID: {club.id}")
+
+# 2. Consulter les scores et matchs en direct (Lives FFBB)
+lives = client.get_lives()
+print(f"Matchs suivis en direct : {len(lives)}")
+
+# 3. Explorer les rencontres d'une compétition (ex: Nationale 1 Masculine)
+rencontres = client.search_rencontres("NM1", limit=5)
+for m in rencontres.hits:
+    print(f"📅 {m.date_rencontre} : {m.equipe1} vs {m.equipe2}")
+```
+
+---
+
+## 📍 Recherche Géographique & Clubs de France
+
+Idéal pour concevoir des applications mobiles, des cartes interactives ou des annuaires de basketball :
+
+### 🌍 Trouver tous les clubs autour d'un point GPS
+
+```python
+# Exemple : Clubs dans un rayon de 20 km autour de Lyon / Clermont-Ferrand
+clubs = client.search_organismes_by_geo(
+    lat=45.7772,
+    lng=3.0870,
+    radius_km=20,
+    limit=15,
+)
+
+for club in clubs.hits:
+    print(f"📍 {club.nom} à {club.commune} [{club.geo}]")
+```
+
+### 🔍 Recherche ciblée par Code Postal, Ville ou Catégorie
+
+```python
+# Filtrer par département ou code postal
+organismes = client.search_organismes(
+    "Basket",
+    filter=['codePostal = "63000"'],
+    sort=["nom:asc"],
+    limit=10,
+)
+```
+
+---
+
+## 🔥 Recettes & Cas d'Usage Concrets
+
+<details>
+<summary><b>1. Suivre les classements et résultats d'une poule</b></summary>
+
+```python
+from ffbb_data_client import FFBBDataClient
+
+client = FFBBDataClient.create()
+
+# Récupération complète d'une poule de championnat
+poule = client.get_poule(11111)
+
+print(f"Championnat : {poule.nom}")
+for rk in poule.classement or []:
+    print(f"#{rk.position} {rk.organisme_nom} - {rk.points} pts ({rk.victoires}V - {rk.defaites}D)")
+```
+</details>
+
+<details>
+<summary><b>2. Résoudre l'adresse complète et exacte d'un gymnase</b></summary>
+
+```python
+# Fini les adresses partielles : résolution déterministe certifiée FFBB
+salles = client.search_salles("Maison des Sports", limit=3)
+for salle in salles.hits:
+    print(f"🏟️ {salle.nom} : {salle.adresse}, {salle.codePostal} {salle.ville}")
+```
+</details>
+
+<details>
+<summary><b>3. Détection automatique du niveau et de la catégorie (U13, R1, D2...)</b></summary>
+
+```python
+from ffbb_data_client import NiveauExtractor, NiveauType
+
+# Détection intelligente du niveau hiérarchique
+niveau = NiveauExtractor.extract_niveau("RÉGIONALE MASCULINE SENIORS - DIVISION 2")
+print(niveau.type)       # NiveauType.REGIONAL
+print(niveau.division)   # 2
+```
+</details>
+
+<details>
+<summary><b>4. Extraire les contacts d'un club (Président, Correspondant, Email)</b></summary>
+
+```python
+# Contacts administratifs officiels
+contacts = client.get_club_contacts(organisme_id=9326)
+if contacts:
+    print(f"Club : {contacts.club_contact.nom}")
+    print(f"Email : {contacts.club_contact.email}")
+    for membre in contacts.membres:
+        print(f" - {membre.role} : {membre.prenom} {membre.nom} ({membre.email})")
+```
+</details>
+
+---
+
+## 🧵 Haute Performance & Streaming Asynchrone
+
+Pour traiter de gros volumes de données sans saturer la mémoire vive ni bloquer la boucle d'événements :
+
+```python
+import asyncio
+from ffbb_data_client import FFBBDataClient
+
+async def main():
+    client = FFBBDataClient.create()
+
+    # Streaming asynchrone mémoire-constant (aiter)
+    count = 0
+    async for rencontre in client.aiter_all_rencontres(page_size=100, max_items=500):
+        count += 1
+        if count % 100 == 0:
+            print(f"Traitement du match #{count} : {rencontre.id}")
+
+    # Recherche asynchrone non-bloquante
+    results = await client.search_organismes_async("ASVEL")
+    print(f"Résultats trouvés : {results.estimated_total_hits}")
+
+asyncio.run(main())
+```
+
+---
+
+## 🤖 IA, Agents & MCP Server
+
+Le SDK `ffbb-data-client` est le moteur officiel du serveur **Model Context Protocol (MCP)** pour le basket français.
+
+Il permet aux LLMs (**Claude**, **ChatGPT**, **Cursor**, **Gemini**, **Antigravity**) d'interagir nativement avec les championnats de basket :
+
+* 💬 *"Quels sont les prochains matchs du SCBA ce week-end ?"*
+* 💬 *"Donne-moi le classement de la Poule Haute U13M2."*
+* 💬 *"Quelle est l'adresse exacte de la salle pour le match de samedi ?"*
+
+👉 Découvrez le projet dédié : **[FFBB-MCP-Server](https://github.com/nickdesi/FFBB-MCP-Server)**
+
+---
+
+## 🌐 Serveur REST FastAPI Embarqué
+
+Besoin d'une API web pour votre application React, Vue, Next.js ou mobile ? `ffbb-data-client` intègre une API FastAPI prête à l'emploi :
+
+```bash
+# Démarrer le serveur API local
+uvicorn ffbb_data_client.api:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Accédez ensuite à la documentation Swagger interactive sur `http://localhost:8000/docs` !
+
+*Endpoints phares :*
+- `GET /health` : Statut de santé et horodatage UTC.
+- `GET /api/v1/club/{id}/matches` : Calendrier optimisé du club avec adresses de salles résolues.
+- `GET /api/v1/lives` : Matchs en direct agrégés.
+
+---
+
+## 📚 Référence des Principales Méthodes
+
+| Domaine | Méthode Synchrone | Méthode Asynchrone | Description |
+| :--- | :--- | :--- | :--- |
+| **Multi-Search** | `client.multi_search()` | `client.multi_search_async()` | Recherche globale simultanée sur tous les index |
+| **Clubs / Organismes** | `client.search_organismes()` | `client.search_organismes_async()` | Recherche Meilisearch des clubs |
+| **Géo-Localisation** | `client.search_organismes_by_geo()` | `client.search_organismes_by_geo_async()` | Recherche de clubs par rayon GPS |
+| **Contacts Club** | `client.get_club_contacts()` | `client.get_club_contacts_async()` | Fiche contacts, président, emails officiels |
+| **Rencontres** | `client.search_rencontres()` | `client.search_rencontres_async()` | Recherche des matchs et résultats |
+| **Streaming Matchs** | — | `client.aiter_all_rencontres()` | Générateur asynchrone paginé |
+| **Salles / Gymnases** | `client.search_salles()` | `client.search_salles_async()` | Gymnases, adresses certifiées et coordonnées |
+| **Compétitions** | `client.search_competitions()` | `client.search_competitions_async()` | Championnats nationaux, régionaux, départementaux |
+| **Poules & Classements**| `client.get_poule()` | `client.get_poule_async()` | Classement complet et calendrier d'une poule |
+| **Tournois 3x3** | `client.search_tournois()` | `client.search_tournois_async()` | Tournois homologués 3x3 FFBB |
+| **Scores en Direct** | `client.get_lives()` | `client.get_lives_async()` | Flux des matchs live en cours |
+
+---
+
+## 🛠️ Robustesse, CI/CD & Découverte Quotidienne
+
+* **Protection BunnyCDN** : User-Agent garanti `okhttp/4.12.0` pour éviter tout blocage WAF 403.
+* **Découverte Quotidienne du Schéma** : Un cron GitHub Actions analyse chaque matin à 5h17 UTC l'OpenAPI spec officielle de la FFBB et détecte automatiquement tout nouveau champ ou collection Directus.
+* **Cache Intelligent Sécurisé** : Gestionnaire de cache HTTP `hishel` avec SQLite distinct pour les flux synchrones et asynchrones.
+* **CodeQL & Zéro Dette** : Conformité aux normes de sécurité, zéro alerte d'injection de log, 100% typé.
+
+---
+
+## 🤝 Contribuer
+
+Les contributions, signalements de bugs et suggestions sont les bienvenus !
+
+1. **Forkez** le projet.
+2. Créez une branche (`git checkout -b feat/ma-nouvelle-fonctionnalite`).
+3. Installez l'environnement de développement : `pip install -e ".[testing]"`.
+4. Vérifiez que tous les tests passent : `pytest tests/` et `pre-commit run --all-files`.
+5. Ouvrez une **Pull Request** claire et documentée.
+
+---
+
+## 📄 Licence
+
+Distribué sous la licence **Apache-2.0**. Voir [`LICENSE.txt`](LICENSE.txt) pour plus de détails.
+
+---
+
+<div align="center">
+
+**Développé avec passion pour la communauté du basketball français. 🇫🇷🏀**
+
+Si cette bibliothèque vous est utile, n'hésitez pas à **ajouter une étoile ⭐** sur GitHub pour encourager le projet !
+
+[![GitHub stars](https://img.shields.io/github/stars/nickdesi/ffbb-data-client?style=social)](https://github.com/nickdesi/ffbb-data-client/stargazers)
+
+</div>