Metadata-Version: 2.4
Name: kadipy
Version: 1.2.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: beautifulsoup4>=4.11
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-cov>=4.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: pytest-timeout>=2.1; extra == "dev"
Requires-Dist: rioxarray>=0.14; extra == "dev"
Requires-Dist: rasterio>=1.3; extra == "dev"
Requires-Dist: mkdocs>=1.3; extra == "dev"
Requires-Dist: mkdocs-material>=8.0; extra == "dev"
Requires-Dist: mkdocs-static-i18n>=1.2; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.20; extra == "dev"
Provides-Extra: geospatial
Requires-Dist: rioxarray>=0.14; extra == "geospatial"
Requires-Dist: rasterio>=1.3; extra == "geospatial"
Provides-Extra: xls
Requires-Dist: xlrd<2.0; extra == "xls"
Dynamic: license-file

<p align="right">
  <strong>Français</strong> | <a href="docs/README.EN.md">English</a>
</p>

<div align="center" style="padding-bottom: 40px">
  <img src="img/kadipy-long.png" alt="KadiPy" width="100%" height="400px">
  <br>
  <p><strong>Traitement, analyse et modélisation des données agricoles et économiques</strong></p>
</div>

----

# KadiPy : le "pandas" de l'agriculture africaine

**KadiPy** est une bibliothèque Python open source conçue pour les agronomes,
chercheurs et développeurs travaillant sur l'agriculture au Bénin et en Afrique
de l'Ouest. Elle offre une interface unifiée pour ingérer, nettoyer, analyser
et modéliser des données météorologiques, des prix de marchés agricoles, des
coûts logistiques et des séries de récoltes, avec un fonctionnement conçu en
priorité pour le mode hors ligne (offline-first).

<br/>

## Fonctionnalités principales

- **Ingestion et E/S unifiées (`kadi.io`)** : fonctions expressives `read_csv`,
  `read_excel`, `read_json`, `read_netcdf`, `read_api` avec détection automatique
  du format, et leurs équivalents en écriture (`write_csv`, `write_excel`, etc.).
  Les fonctions `write`, `info` et `ping` fonctionnent avec n'importe quel format.

- **Météorologie agronomique (`kadi.weather`)** : façade `Weather` pour les
  données météo historiques et prévisionnelles (CHIRPS + Open-Meteo), détection
  des saisons des pluies (Sivakumar, Walter-Anyadike), bilan hydrique des sols
  (FAO-56), évapotranspiration (ET0 Hargreaves-Samani) et indices de sécheresse
  (SPI, Markov, Hurst).

- **Économie agricole et marchés (`kadi.market`)** : façade `Market` pour le
  suivi des prix réels (WFP/HAPI HumData), prévisions de prix (`Forecasting`),
  calculs de coûts logistiques routiers (`Logistics`) et aide à la décision
  (`Advisor`) pour l'arbitrage spatial et le stockage stratégique.

- **Pipeline et standardisation (`kadi.kidas`)** : nettoyage des données brutes
  (`Cleaner`), validation de schémas (`Validator`), normalisation des noms de
  cultures et coordonnées GPS (`Normalizer`), persistance SQLite locale (`Cache`)
  et chaîne de traitement complète (`Pipeline`).


<br/>

## Installation

### Via PyPI

```bash
pip install kadipy
```

### Depuis les sources

```bash
git clone https://github.com/delsDin/kadipy.git
cd kadipy
pip install -e ".[dev]"
```

### Dépendances optionnelles

```bash
# Support des anciens fichiers Excel (.xls, antérieurs à 2003)
pip install "kadipy[xls]"

# Traitements géospatiaux (découpage de rasters CHIRPS)
pip install "kadipy[geospatial]"
```

### Configuration de l'environnement

Créez un fichier `.env` à la racine du projet pour activer les sources de données
réelles :

```env
# Clé API WFP DataBridges (facultatif : des données publiques HAPI HumData
# sont utilisées sans elle)
WFP_API_Token=votre_cle_ici

# Prix du carburant manuel en XOF/litre (facultatif)
BENIN_FUEL_PRICE=680
```

<br/>

## Vue d'ensemble des modules

| Module | Façade / Composants | Description |
|--------|---------------------|-------------|
| `kadi.io` | `read_csv`, `read_excel`, `read_json`, `read_netcdf`, `read_api`, `write`, `info`, `ping` | Entrées et sorties avec détection automatique du format |
| `kadi.weather` | `Weather`, `Location`, `Phenology`, `Hydrology`, `Risk` | Météo, prévisions, historique et indicateurs agronomiques |
| `kadi.market` | `Market`, `Pricing`, `Forecasting`, `Logistics`, `Advisor` | Analyse économique, prix, logistique et aide à la décision |
| `kadi.kidas` | `Cleaner`, `Validator`, `Normalizer`, `Pipeline`, `Cache` | Traitement, contrôle qualité et persistance SQLite |

<br/>

## Structure du projet

```
kadipy/
├── kadi/
│   ├── io/              # Entrées et sorties unifiées
│   ├── market/          # Économie agricole et marchés
│   ├── weather/         # Météorologie agronomique
│   ├── kidas/           # Pipeline de traitement et standardisation
│   ├── _sources/        # Clients externes (WFP, CHIRPS, SoilGrids)
│   ├── cache.py         # Cache SQLite partagé
│   ├── config.py        # Configuration centralisée
│   └── exceptions.py    # Exceptions personnalisées
├── tests/               # Suite de tests (pytest)
├── docs/                # Documentation MkDocs
├── examples/            # Notebooks d'exemples Jupyter
├── config/              # Fichiers de configuration
└── pyproject.toml       # Dépendances et métadonnées du package
```

<br/>

## Lancer les tests

```bash
# Exécution simple
pytest tests/ -q

# Avec rapport de couverture de code
pytest tests/ --cov=kadi --cov-report=term-missing
```

Les tests couvrent l'ensemble des modules (`io`, `market`, `weather`, `kidas`),
y compris les connecteurs distants sans dépendance réseau et les composants
d'infrastructure (`kadi.cache`, `kadi.config`). Aucune clé API n'est nécessaire
pour les exécuter. La CI GitHub Actions contrôle que la couverture globale reste
supérieure à **70 %**.

<br/>

## Rétrocompatibilité

Les anciens noms de classes issus des versions antérieures à v1.2.0 émettent un `DeprecationWarning` et seront supprimés dans KadiPy v2.0 :

| Ancien nom (avant v1.2.0) | Nouveau nom |
|---------------------------|-------------|
| `WeatherSession` | `Weather` |
| `DataCleaner` | `Cleaner` |
| `DataValidator` | `Validator` |
| `DataNormalizer` | `Normalizer` |
| `DataCache` | `Cache` |
| `DataPipeline` | `Pipeline` |
| `CSVDataSource` | `CSVSource` |

<br/>

## Zone géographique (v1.x)

KadiPy v1.x est conçu **exclusivement pour le Bénin**. La validation des
coordonnées GPS, les algorithmes phénologiques, les facteurs logistiques et les
données de prix sont calibrés pour le contexte béninois.

Le support d'autres pays d'Afrique de l'Ouest est prévu dans les versions futures.

---

## Documentation

La documentation complète (guides d'API, exemples) est disponible sur :
**https://delsDin.github.io/kadipy/**

---

## Licence et contribution

- **Licence** : MIT
- **Dépôt GitHub** : https://github.com/delsDin/kadipy
- **Compatibilité Python** : >= 3.9
- **Version courante** : 1.2.0
