kadipy 1.0.0__tar.gz

kadipy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dels Marcel Dinla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kadipy-1.0.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: kadipy
+Version: 1.0.0
+Summary: Le "pandas" de l'agriculture africaine. Interface Python pour les données météo, de marché et de récoltes au Bénin.
+Author-email: Dels Dinla <delsdenla.dev@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Dels Marcel Dinla
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/delsDin/kadipy
+Project-URL: Documentation, https://delsDin.github.io/kadipy/
+Project-URL: Repository, https://github.com/delsDin/kadipy
+Project-URL: Bug Tracker, https://github.com/delsDin/kadipy/issues
+Project-URL: Changelog, https://github.com/delsDin/kadipy/releases
+Keywords: agriculture,benin,afrique-ouest,meteo,marche-agricole,prix,prevision,pandas,pipeline-donnees,analyse-donnees,donnees-collectes,agritech,decision-support
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Natural Language :: French
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Requires-Dist: pandas>=1.3
+Requires-Dist: numpy>=1.21
+Requires-Dist: openpyxl>=3.0
+Requires-Dist: geopy>=2.2
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: joblib>=1.1
+Requires-Dist: xarray>=2023.1
+Requires-Dist: netCDF4>=1.6
+Requires-Dist: chardet>=5.0
+Requires-Dist: scipy>=1.9
+Requires-Dist: shapely>=2.0
+Requires-Dist: Unidecode>=1.3
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.7; extra == "dev"
+Requires-Dist: responses>=0.21; extra == "dev"
+Requires-Dist: requests-mock>=1.9; extra == "dev"
+Requires-Dist: mkdocs>=1.3; extra == "dev"
+Requires-Dist: mkdocs-material>=8.0; extra == "dev"
+Requires-Dist: mkdocstrings[python]>=0.20; extra == "dev"
+Dynamic: license-file
+
+# KadiPy
+
+**Le "pandas" de l'agriculture africaine.**
+
+KadiPy est une bibliothèque Python conçue pour les agronomes, chercheurs
+et développeurs travaillant sur les données agricoles au Bénin et en
+Afrique de l'Ouest. Elle fournit une interface unifiée pour traiter les
+données météorologiques, les prix de marché et les données de récoltes,
+avec une approche hors ligne en premier (offline-first).
+
+---
+
+## Installation
+
+```bash
+pip install kadipy
+```
+
+Nécessite Python 3.9 ou supérieur.
+
+---
+
+## Modules disponibles
+
+**kadi.market** : analyse économique des marchés agricoles béninois.
+- Récupération des prix via l'API WFP DataBridges.
+- Prévisions de prix par régression linéaire saisonnière.
+- Calcul des coûts de transport avec données routières réelles (OSRM).
+- Aide à la décision : arbitrage spatial, stockage stratégique, score de confiance.
+- Backtesting des prévisions (MAE, RMSE, MAPE, précision directionnelle).
+
+**kadi.weather** : données météorologiques et indicateurs agronomiques.
+- Prévisions et historiques via Open-Meteo et CHIRPS.
+- Phénologie : détection de la saison des pluies (Sivakumar, Walter-Anyadike), GDD.
+- Hydrologie : évapotranspiration ET0 (Hargreaves-Samani), bilan hydrique FAO-56.
+- Risques climatiques : indice de sécheresse (SPI), probabilité de pluie.
+
+**kadi.kidas** : pipeline de traitement des données agricoles.
+- Nettoyage : valeurs manquantes, doublons, valeurs aberrantes.
+- Validation : types, plages de valeurs, rapport d'erreurs.
+- Normalisation : noms de cultures, marchés, unités et coordonnées GPS.
+
+---
+
+## Démarrage rapide
+
+```python
+from kadi.weather import WeatherSession
+from kadi.market import Market
+
+# Données météo pour Parakou
+session = WeatherSession(latitude=9.33, longitude=2.63, name="Parakou")
+previsions = session.forecast(days=3)
+print(previsions["data"])
+
+# Analyse de marché
+marche = Market(latitude=9.30, longitude=2.08, location="Parakou",
+                weather_session=session)
+
+# Recommandation d'arbitrage
+resultat = marche.decision_support.arbitrage_decision(
+    crop="maize",
+    origine="Parakou",
+    destination="Cotonou",
+    qty_tons=10.0,
+)
+print(resultat["recommandation"])
+print(f"Score de confiance : {resultat['confidence_score']:.0%}")
+```
+
+---
+
+## Documentation
+
+La documentation complète est disponible sur :
+**https://delsDin.github.io/kadipy/**
+
+---
+
+## Contribution et support
+
+- Dépôt GitHub : https://github.com/delsDin/kadipy
+- Licence : MIT
+- Python : >= 3.9

kadipy-1.0.0/README.md

@@ -0,0 +1,84 @@
+# KadiPy
+
+**Le "pandas" de l'agriculture africaine.**
+
+KadiPy est une bibliothèque Python conçue pour les agronomes, chercheurs
+et développeurs travaillant sur les données agricoles au Bénin et en
+Afrique de l'Ouest. Elle fournit une interface unifiée pour traiter les
+données météorologiques, les prix de marché et les données de récoltes,
+avec une approche hors ligne en premier (offline-first).
+
+---
+
+## Installation
+
+```bash
+pip install kadipy
+```
+
+Nécessite Python 3.9 ou supérieur.
+
+---
+
+## Modules disponibles
+
+**kadi.market** : analyse économique des marchés agricoles béninois.
+- Récupération des prix via l'API WFP DataBridges.
+- Prévisions de prix par régression linéaire saisonnière.
+- Calcul des coûts de transport avec données routières réelles (OSRM).
+- Aide à la décision : arbitrage spatial, stockage stratégique, score de confiance.
+- Backtesting des prévisions (MAE, RMSE, MAPE, précision directionnelle).
+
+**kadi.weather** : données météorologiques et indicateurs agronomiques.
+- Prévisions et historiques via Open-Meteo et CHIRPS.
+- Phénologie : détection de la saison des pluies (Sivakumar, Walter-Anyadike), GDD.
+- Hydrologie : évapotranspiration ET0 (Hargreaves-Samani), bilan hydrique FAO-56.
+- Risques climatiques : indice de sécheresse (SPI), probabilité de pluie.
+
+**kadi.kidas** : pipeline de traitement des données agricoles.
+- Nettoyage : valeurs manquantes, doublons, valeurs aberrantes.
+- Validation : types, plages de valeurs, rapport d'erreurs.
+- Normalisation : noms de cultures, marchés, unités et coordonnées GPS.
+
+---
+
+## Démarrage rapide
+
+```python
+from kadi.weather import WeatherSession
+from kadi.market import Market
+
+# Données météo pour Parakou
+session = WeatherSession(latitude=9.33, longitude=2.63, name="Parakou")
+previsions = session.forecast(days=3)
+print(previsions["data"])
+
+# Analyse de marché
+marche = Market(latitude=9.30, longitude=2.08, location="Parakou",
+                weather_session=session)
+
+# Recommandation d'arbitrage
+resultat = marche.decision_support.arbitrage_decision(
+    crop="maize",
+    origine="Parakou",
+    destination="Cotonou",
+    qty_tons=10.0,
+)
+print(resultat["recommandation"])
+print(f"Score de confiance : {resultat['confidence_score']:.0%}")
+```
+
+---
+
+## Documentation
+
+La documentation complète est disponible sur :
+**https://delsDin.github.io/kadipy/**
+
+---
+
+## Contribution et support
+
+- Dépôt GitHub : https://github.com/delsDin/kadipy
+- Licence : MIT
+- Python : >= 3.9

kadipy-1.0.0/kadi/__init__.py

@@ -0,0 +1,83 @@
+"""
+Package principal de KadiPy.
+
+KadiPy est le "pandas" de l'agriculture africaine, facilitant le traitement
+et l'analyse des données météorologiques, de marché et de récoltes locales
+avec une approche "offline-first".
+"""
+
+import logging
+
+# ------------------------------------------------------------------
+# Version du package
+# ------------------------------------------------------------------
+
+__version__ = "1.0.0"
+
+# ------------------------------------------------------------------
+# Configuration du logger racine de KadiPy
+#
+# Tous les sous-modules utilisent logging.getLogger(__name__), ce qui
+# crée des loggers de la forme "kadi.market.pricing", "kadi.weather.risk",
+# etc. Ces loggers héritent automatiquement du niveau défini ici sur
+# le logger racine "kadi". Il suffit donc de configurer ce seul logger
+# pour contrôler l'ensemble de la bibliothèque.
+# ------------------------------------------------------------------
+
+# Logger racine du package (silence par défaut : WARNING)
+_logger_kadi = logging.getLogger("kadi")
+_logger_kadi.setLevel(logging.WARNING)
+
+# Handler console minimal (affiché uniquement si aucun handler n'est
+# configuré en amont dans l'application de l'utilisateur)
+if not _logger_kadi.handlers:
+    _handler = logging.StreamHandler()
+    _handler.setFormatter(
+        logging.Formatter("%(levelname)s - %(name)s - %(message)s")
+    )
+    _logger_kadi.addHandler(_handler)
+
+
+def set_verbosity(level: str = "WARNING") -> None:
+    """Configure le niveau de log pour tous les sous-modules de KadiPy.
+
+    Cette fonction est le point d'entrée unique pour contrôler la
+    verbosité de la bibliothèque. Elle s'applique au logger racine
+    "kadi", dont héritent automatiquement tous les sous-loggers
+    (kadi.market, kadi.weather, kadi.kidas, etc.).
+
+    Args:
+        level (str): Niveau de log souhaité. Valeurs acceptées :
+            - "DEBUG"   : logs détaillés (requêtes API, calculs internes).
+            - "INFO"    : messages d'état du pipeline.
+            - "WARNING" : uniquement les avertissements (defaut).
+            - "ERROR"   : uniquement les erreurs critiques.
+
+    Raises:
+        ValueError: Si le niveau fourni n'est pas reconnu par le module
+            standard logging.
+
+    Exemple:
+        >>> import kadi
+        >>> kadi.set_verbosity("DEBUG")   # Active les logs détaillés
+        >>> kadi.set_verbosity("WARNING") # Remet en mode silencieux (défaut)
+    """
+    # Conversion du niveau texte en constante numérique logging
+    niveau_numerique = getattr(logging, level.upper(), None)
+
+    # Vérification que le niveau est valide
+    if not isinstance(niveau_numerique, int):
+        niveaux_valides = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        raise ValueError(
+            f"Niveau de log invalide : '{level}'. "
+            f"Valeurs acceptées : {niveaux_valides}"
+        )
+
+    # Application du niveau sur le logger racine du package
+    _logger_kadi.setLevel(niveau_numerique)
+
+    # Journalisation du changement (visible uniquement si le niveau
+    # sélectionné est DEBUG ou INFO)
+    _logger_kadi.info(
+        "kadi : niveau de verbosité défini à '%s'.", level.upper()
+    )

kadipy-1.0.0/kadi/_sources/chirps.py

@@ -0,0 +1,37 @@
+"""
+Connecteur pour CHIRPS (Climate Hazards Group InfraRed Precipitation with Station data).
+Permet de récupérer les données historiques de précipitation depuis un cache local.
+
+Statut V1 : désactivé.
+Le fichier CSV fourni (historical_rainfall_1981_2024.csv) est vide ou manquant.
+Un filtrage spatial approprié des données CHIRPS nécessitera la transition vers
+des fichiers NetCDF (.nc) dans la V2 du projet. En attendant, le système bascule
+exclusivement sur l'historique d'Open-Meteo.
+"""
+
+import pandas as pd
+from typing import Optional
+import logging
+
+# Journaliseur pour ce module
+logger = logging.getLogger(__name__)
+
+
+def fetch_historical_precipitation(lat: float, lon: float) -> Optional[pd.DataFrame]:
+    """
+    Récupère l'historique des précipitations pour un point donné depuis le cache CHIRPS.
+
+    Cette fonction est désactivée pour la V1. Le fichier CSV global fourni est vide.
+    Le filtrage spatial par coordonnées GPS nécessitera des fichiers NetCDF en V2.
+
+    :param lat: Latitude du lieu (non utilisée en V1).
+    :param lon: Longitude du lieu (non utilisée en V1).
+    :return: Toujours None en V1. Retournera un DataFrame en V2.
+    """
+    # Désactivé pour V1 : fichier CSV global vide, transition vers NetCDF prévue en V2.
+    logger.warning(
+        "Connecteur CHIRPS désactivé (V1) : fichier de données vide. "
+        "Le filtrage spatial des données NetCDF est prévu pour la V2. "
+        "Les données de précipitation proviennent exclusivement d'Open-Meteo."
+    )
+    return None

kadipy-1.0.0/kadi/_sources/open_meteo.py

@@ -0,0 +1,141 @@
+"""
+Connecteur pour l'API Open-Meteo.
+
+Permet de récupérer les prévisions et l'historique météo.
+Gère le formatage des paramètres et l'extraction de la réponse JSON.
+"""
+
+import requests
+import datetime
+from typing import Dict, Any, List
+
+from kadi.config import OPENMETEO_API_URL
+from kadi.exceptions import DataSourceError
+
+
+def fetch_forecast(lat: float, lon: float, days: int = 7) -> List[Dict[str, Any]]:
+    """
+    Récupère les prévisions météo journalières via Open-Meteo.
+    
+    Args:
+        lat (float): Latitude du lieu.
+        lon (float): Longitude du lieu.
+        days (int): Nombre de jours à récupérer.
+        
+    Returns:
+        List[Dict]: Une liste de dictionnaires représentant les données par jour.
+        
+    Raises:
+        DataSourceError: En cas d'erreur de requête HTTP.
+    """
+    url = f"{OPENMETEO_API_URL}/forecast"
+    params = {
+        "latitude": lat,
+        "longitude": lon,
+        "daily": "temperature_2m_max,temperature_2m_min,precipitation_sum",
+        "forecast_days": days,
+        "timezone": "auto"
+    }
+    
+    try:
+        response = requests.get(url, params=params, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+        
+        return _parse_daily_data(data, "forecast", "open-meteo", confidence=0.95)
+    except requests.RequestException as e:
+        raise DataSourceError(f"Erreur de connexion Open-Meteo (forecast): {e}")
+
+
+def fetch_historical(lat: float, lon: float, months_back: int = 12) -> List[Dict[str, Any]]:
+    """
+    Récupère l'historique météo (Archive) via Open-Meteo.
+    
+    Args:
+        lat (float): Latitude du lieu.
+        lon (float): Longitude du lieu.
+        months_back (int): Nombre de mois en arrière à récupérer.
+        
+    Returns:
+        List[Dict]: Une liste de dictionnaires représentant les données passées par jour.
+        
+    Raises:
+        DataSourceError: En cas d'erreur de requête HTTP.
+    """
+    url = "https://archive-api.open-meteo.com/v1/archive"
+    
+    # Calcul des dates de début et fin
+    end_date = datetime.date.today() - datetime.timedelta(days=2) # L'archive a environ 2 jours de délai
+    start_date = end_date - datetime.timedelta(days=30 * months_back)
+    
+    params = {
+        "latitude": lat,
+        "longitude": lon,
+        "start_date": start_date.strftime("%Y-%m-%d"),
+        "end_date": end_date.strftime("%Y-%m-%d"),
+        "daily": "temperature_2m_max,temperature_2m_min,precipitation_sum",
+        "timezone": "auto"
+    }
+    
+    try:
+        response = requests.get(url, params=params, timeout=15)
+        response.raise_for_status()
+        data = response.json()
+        
+        return _parse_daily_data(data, "historical", "open-meteo-archive", confidence=1.0)
+    except requests.RequestException as e:
+        raise DataSourceError(f"Erreur de connexion Open-Meteo (historical): {e}")
+
+
+def _parse_daily_data(
+    data: Dict[str, Any], 
+    data_type: str, 
+    source: str, 
+    confidence: float
+) -> List[Dict[str, Any]]:
+    """
+    Parse la structure JSON retournée par Open-Meteo (daily).
+    
+    Args:
+        data: Le dictionnaire JSON renvoyé par l'API.
+        data_type: Le type ('forecast' ou 'historical').
+        source: Le nom de la source.
+        confidence: L'indice de confiance.
+        
+    Returns:
+        Une liste de lignes prêtes à être insérées dans le cache ou traitées.
+    """
+    daily = data.get("daily", {})
+    if not daily:
+        return []
+        
+    dates = daily.get("time", [])
+    t_max = daily.get("temperature_2m_max", [])
+    t_min = daily.get("temperature_2m_min", [])
+    precip = daily.get("precipitation_sum", [])
+    
+    results = []
+    
+    for i, date_str in enumerate(dates):
+        # On calcule la température moyenne si min et max sont disponibles
+        max_val = t_max[i] if i < len(t_max) else None
+        min_val = t_min[i] if i < len(t_min) else None
+        
+        avg_val = None
+        if max_val is not None and min_val is not None:
+            avg_val = round((max_val + min_val) / 2.0, 2)
+            
+        row = {
+            "date": date_str,
+            "hour": None,
+            "temperature_min": min_val,
+            "temperature_max": max_val,
+            "temperature_avg": avg_val,
+            "precipitation": precip[i] if i < len(precip) else None,
+            "data_type": data_type,
+            "data_source": source,
+            "confidence": confidence
+        }
+        results.append(row)
+        
+    return results

kadipy-1.0.0/kadi/_sources/soilgrids.py

@@ -0,0 +1,53 @@
+"""
+Connecteur pour SoilGrids.
+Permet de récupérer les informations de sols (souvent via un cache local pour réduire la latence).
+"""
+
+import os
+import json
+import math
+import logging
+
+logger = logging.getLogger(__name__)
+
+def fetch_soil_type(lat: float, lon: float, default_soil: str = "ferrugineux") -> str:
+    """
+    Détermine le type de sol depuis le cache local pré-téléchargé SoilGrids.
+    
+    Args:
+        lat (float): Latitude.
+        lon (float): Longitude.
+        default_soil (str): Type de sol par défaut si introuvable.
+        
+    Returns:
+        str: Le type de sol trouvé, ou la valeur par défaut.
+    """
+    cache_file = os.path.expanduser("~/.kadipy_cache/soilgrids_cache.json")
+    
+    if not os.path.exists(cache_file):
+        logger.debug(f"Cache SoilGrids introuvable, utilisation du défaut: {default_soil}")
+        return default_soil
+        
+    try:
+        with open(cache_file, "r") as f:
+            data = json.load(f)
+            
+        if not data:
+            return default_soil
+            
+        closest_point = None
+        min_dist = float('inf')
+        
+        for pt in data:
+            dist = math.hypot(pt["lat"] - lat, pt["lon"] - lon)
+            if dist < min_dist:
+                min_dist = dist
+                closest_point = pt
+                
+        if closest_point and "soil_type" in closest_point:
+            return closest_point["soil_type"]
+            
+    except Exception as e:
+        logger.error(f"Erreur lors de la lecture du cache SoilGrids: {e}")
+        
+    return default_soil

kadipy-1.0.0/kadi/_utils/coordinates.py

@@ -0,0 +1,46 @@
+"""
+Utilitaires de gestion des coordonnées GPS pour KadiPy.
+
+Dans cette version V1, la résolution des villes se fait via un dictionnaire
+statique pour les principales villes du Bénin, afin de permettre les tests
+(mocking).
+"""
+
+from typing import Tuple
+from kadi.exceptions import LocationNotFound
+
+# Dictionnaire mocké pour la résolution des localisations (Villes du Bénin)
+BENIN_CITIES = {
+    "cotonou": (6.36536, 2.41833),
+    "porto-novo": (6.49722, 2.605),
+    "parakou": (9.33716, 2.63031),
+    "abomey": (7.18286, 1.99119),
+    "natitingou": (10.30416, 1.37962),
+    "djougou": (9.70853, 1.66598),
+    "bohicon": (7.17826, 2.0667),
+    "ouidah": (6.36408, 2.08383),
+}
+
+
+def normalize_location(location: str) -> Tuple[float, float]:
+    """
+    Transforme un nom de ville en un tuple de coordonnées (latitude, longitude).
+    
+    Args:
+        location: Le nom de la ville (ex: "Abomey", "Cotonou").
+        
+    Returns:
+        Tuple[float, float]: (latitude, longitude).
+        
+    Raises:
+        LocationNotFound: Si la ville n'est pas dans notre dictionnaire mocké.
+    """
+    # Nettoyage de la chaîne : passage en minuscules et suppression des espaces
+    loc_clean = location.strip().lower()
+    
+    if loc_clean in BENIN_CITIES:
+        return BENIN_CITIES[loc_clean]
+    
+    raise LocationNotFound(
+        f"La localisation '{location}' n'est pas reconnue dans la base du Bénin."
+    )

kadipy-1.0.0/kadi/_utils/network.py

@@ -0,0 +1,54 @@
+"""
+Utilitaires réseau pour KadiPy.
+
+Fournit des fonctions pour exécuter des requêtes réseau avec 
+mécanismes de retry (tentatives) et de fallback (repli).
+"""
+
+import time
+import logging
+from typing import Callable, Any
+
+from kadi.exceptions import DataSourceError
+
+logger = logging.getLogger(__name__)
+
+
+def fetch_with_retry(
+    fetch_func: Callable,
+    attempts: int = 3,
+    backoff_sec: int = 5,
+    *args,
+    **kwargs
+) -> Any:
+    """
+    Exécute une fonction de récupération réseau avec un mécanisme de tentatives multiples.
+    
+    Args:
+        fetch_func: La fonction à exécuter.
+        attempts: Nombre maximum de tentatives (défaut: 3).
+        backoff_sec: Temps d'attente (en secondes) entre deux tentatives (défaut: 5).
+        *args, **kwargs: Arguments passés à fetch_func.
+        
+    Returns:
+        Any: Les données retournées par fetch_func.
+        
+    Raises:
+        DataSourceError: Si toutes les tentatives échouent.
+    """
+    last_exception = None
+    
+    for attempt in range(1, attempts + 1):
+        try:
+            return fetch_func(*args, **kwargs)
+        except Exception as e:
+            last_exception = e
+            logger.warning(
+                f"Échec de la récupération (Tentative {attempt}/{attempts}) : {e}"
+            )
+            if attempt < attempts:
+                time.sleep(backoff_sec)
+                
+    # Si on sort de la boucle, c'est que toutes les tentatives ont échoué
+    logger.error(f"Toutes les tentatives ({attempts}) ont échoué.")
+    raise DataSourceError(f"Échec définitif de récupération : {last_exception}")