382 lines
10 KiB
Markdown
382 lines
10 KiB
Markdown
# 📄 pdf2csv
|
|
|
|
Convertisseur de fichiers **PDF** en **CSV** basé sur [tabula-py](https://github.com/chezou/tabula-py) et [pandas](https://pandas.pydata.org/), empaqueté dans une image **Docker** légère.
|
|
|
|
Il est conçu pour traiter automatiquement les relevés bancaires PDF (ou autres tableaux PDF similaires) en appliquant des opérations de nettoyage et de fusion avant de produire un fichier CSV unique.
|
|
|
|
## ✨ Nouveautés v2.0
|
|
|
|
- ✅ **Gestion d'erreurs robuste** : Traitement gracieux des erreurs avec logs détaillés
|
|
- ✅ **Logging professionnel** : Logs structurés avec niveaux (INFO, DEBUG, ERROR)
|
|
- ✅ **Type hints** : Code entièrement typé pour une meilleure maintenabilité
|
|
- ✅ **Configuration flexible** : Variables d'environnement et arguments CLI
|
|
- ✅ **Validation des entrées** : Vérification de la validité des fichiers PDF
|
|
- ✅ **Nettoyage automatique** : Suppression des fichiers temporaires
|
|
- ✅ **Arguments CLI** : Paramétrage via ligne de commande
|
|
- ✅ **Requirements.txt** : Gestion des dépendances standardisée
|
|
|
|
---
|
|
|
|
## 🚀 Fonctionnalités
|
|
|
|
### Extraction
|
|
- Utilise `tabula-py` pour extraire les tableaux depuis tous les fichiers PDF
|
|
- Supporte les PDFs multi-pages
|
|
- Gestion d'erreurs pour chaque fichier (continue en cas d'échec)
|
|
|
|
### Nettoyage des données
|
|
- Supprime les **N premières lignes** (configurable, défaut: 3)
|
|
- Supprime jusqu'à la ligne contenant un mot-clé de début (défaut: `SOLDE`)
|
|
- Supprime toute ligne dont la première colonne contient un mot-clé (défaut: `date`)
|
|
- Supprime à partir d'un mot-clé de fin (défaut: `Total des mouvements`)
|
|
- Fusionne les lignes fragmentées
|
|
- Nettoie les séparateurs de milliers dans les montants
|
|
|
|
### Fusion et export
|
|
- Fusionne tous les CSV en un seul fichier final
|
|
- Ajoute l'en-tête automatiquement
|
|
- Produit un fichier CSV propre et standardisé
|
|
|
|
### Logging et monitoring
|
|
- Logs détaillés de chaque étape
|
|
- Mode verbeux disponible (`--verbose`)
|
|
- Résumé de traitement avec statistiques
|
|
|
|
---
|
|
|
|
## 📦 Installation
|
|
|
|
### Option 1 : Docker (Recommandé)
|
|
|
|
```bash
|
|
# Cloner le dépôt
|
|
git clone https://github.com/votre-user/pdf2csv.git
|
|
cd pdf2csv
|
|
|
|
# Construire l'image
|
|
docker build -t pdf2csv:latest .
|
|
```
|
|
|
|
### Option 2 : Installation locale
|
|
|
|
```bash
|
|
# Cloner le dépôt
|
|
git clone https://github.com/votre-user/pdf2csv.git
|
|
cd pdf2csv
|
|
|
|
# Installer les dépendances (Python 3.11+ recommandé)
|
|
pip install -r requirements.txt
|
|
|
|
# Java est requis pour tabula-py
|
|
# Sur Ubuntu/Debian :
|
|
sudo apt-get install openjdk-17-jre-headless
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Utilisation
|
|
|
|
### Utilisation avec Docker
|
|
|
|
**Utilisation basique :**
|
|
|
|
```bash
|
|
# Placez vos PDFs dans un dossier (ex: ./mes_pdfs/)
|
|
docker run --rm -v $(pwd)/mes_pdfs:/data pdf2csv:latest
|
|
```
|
|
|
|
**Mode verbeux :**
|
|
|
|
```bash
|
|
docker run --rm -v $(pwd)/mes_pdfs:/data pdf2csv:latest --verbose
|
|
```
|
|
|
|
**Avec variables d'environnement personnalisées :**
|
|
|
|
```bash
|
|
docker run --rm \
|
|
-v $(pwd)/mes_pdfs:/data \
|
|
-e MOT_DEBUT="BALANCE" \
|
|
-e MOT_FIN="Total général" \
|
|
pdf2csv:latest
|
|
```
|
|
|
|
**Avec fichier de configuration :**
|
|
|
|
```bash
|
|
# Copiez le fichier d'exemple
|
|
cp config.example.env .env
|
|
|
|
# Éditez .env selon vos besoins
|
|
nano .env
|
|
|
|
# Lancez avec le fichier de configuration
|
|
docker run --rm \
|
|
-v $(pwd)/mes_pdfs:/data \
|
|
--env-file .env \
|
|
pdf2csv:latest
|
|
```
|
|
|
|
**Conserver les fichiers temporaires :**
|
|
|
|
```bash
|
|
docker run --rm -v $(pwd)/mes_pdfs:/data pdf2csv:latest --no-clean
|
|
```
|
|
|
|
### Utilisation locale (Python)
|
|
|
|
```bash
|
|
# Utilisation basique
|
|
python convert.py /chemin/vers/pdfs
|
|
|
|
# Mode verbeux
|
|
python convert.py /chemin/vers/pdfs --verbose
|
|
|
|
# Personnaliser les mots-clés
|
|
python convert.py /chemin/vers/pdfs --mot-debut "BALANCE" --mot-fin "Total"
|
|
|
|
# Afficher l'aide
|
|
python convert.py --help
|
|
```
|
|
|
|
---
|
|
|
|
## ⚙️ Configuration
|
|
|
|
### Variables d'environnement
|
|
|
|
| Variable | Défaut | Description |
|
|
|----------|--------|-------------|
|
|
| `MOT_DEBUT` | `SOLDE` | Mot-clé marquant le début des données (supprime tout avant) |
|
|
| `MOT_FIN` | `Total des mouvements` | Mot-clé marquant la fin des données (supprime tout après) |
|
|
| `MOT_DATE` | `date` | Mot-clé dans les en-têtes à ignorer |
|
|
| `SKIP_LINES` | `3` | Nombre de lignes à sauter au début |
|
|
| `CLEAN_TEMP_FILES` | `true` | Supprime les fichiers temporaires (`true`/`false`) |
|
|
| `TABULA_LATTICE` | `true` | Mode lattice de Tabula (`true`/`false`) |
|
|
| `TABULA_PAGES` | `all` | Pages à extraire (`all`, `1`, `1-3`, etc.) |
|
|
|
|
### Arguments CLI
|
|
|
|
```bash
|
|
usage: convert.py [-h] [-v] [--mot-debut MOT_DEBUT] [--mot-fin MOT_FIN]
|
|
[--no-clean] [workdir]
|
|
|
|
Arguments positionnels:
|
|
workdir Répertoire contenant les PDFs (défaut: /data)
|
|
|
|
Options:
|
|
-h, --help Affiche l'aide
|
|
-v, --verbose Active le mode verbeux (DEBUG)
|
|
--mot-debut Surcharge le mot-clé de début
|
|
--mot-fin Surcharge le mot-clé de fin
|
|
--no-clean Conserve les fichiers temporaires
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 Exemples
|
|
|
|
### Exemple 1 : Relevés bancaires standards
|
|
|
|
```bash
|
|
# Structure :
|
|
mes_pdfs/
|
|
├── releve_janvier.pdf
|
|
├── releve_fevrier.pdf
|
|
└── releve_mars.pdf
|
|
|
|
# Commande :
|
|
docker run --rm -v $(pwd)/mes_pdfs:/data pdf2csv:latest
|
|
|
|
# Résultat :
|
|
mes_pdfs/
|
|
├── releve_janvier.pdf
|
|
├── releve_janvier_final.csv
|
|
├── releve_fevrier.pdf
|
|
├── releve_fevrier_final.csv
|
|
├── releve_mars.pdf
|
|
├── releve_mars_final.csv
|
|
└── fusion_total.csv ← Fichier final fusionné
|
|
```
|
|
|
|
### Exemple 2 : Format personnalisé
|
|
|
|
```bash
|
|
# Pour des relevés avec des mots-clés différents
|
|
docker run --rm \
|
|
-v $(pwd)/mes_pdfs:/data \
|
|
-e MOT_DEBUT="BALANCE" \
|
|
-e MOT_FIN="TOTAL OPERATIONS" \
|
|
-e SKIP_LINES="5" \
|
|
pdf2csv:latest --verbose
|
|
```
|
|
|
|
### Exemple 3 : Développement local
|
|
|
|
```bash
|
|
# Installation des dépendances
|
|
pip install -r requirements.txt
|
|
|
|
# Test sur un dossier local
|
|
python convert.py ./test_pdfs --verbose
|
|
|
|
# Avec personnalisation
|
|
python convert.py ./test_pdfs \
|
|
--mot-debut "SOLDE INITIAL" \
|
|
--mot-fin "SOLDE FINAL" \
|
|
--verbose
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 Logs et débogage
|
|
|
|
### Logs normaux
|
|
|
|
```
|
|
2025-10-11 14:23:15 - INFO - Trouvé 3 fichier(s) PDF à traiter
|
|
2025-10-11 14:23:15 - INFO - Configuration : Configuration(MOT_DEBUT=SOLDE, ...)
|
|
2025-10-11 14:23:16 - INFO - Conversion de releve_janvier.pdf...
|
|
2025-10-11 14:23:18 - INFO - ✓ Converti : releve_janvier.pdf
|
|
2025-10-11 14:23:18 - INFO - CSV nettoyé sauvegardé : releve_janvier_final.csv (45 lignes)
|
|
2025-10-11 14:23:18 - INFO - ✓ Nettoyé : releve_janvier_final.csv
|
|
...
|
|
2025-10-11 14:23:25 - INFO - ✓ Fichier fusionné créé : fusion_total.csv (132 lignes)
|
|
2025-10-11 14:23:25 - INFO - ============================================================
|
|
2025-10-11 14:23:25 - INFO - Traitement terminé :
|
|
2025-10-11 14:23:25 - INFO - - Fichiers traités avec succès : 3/3
|
|
2025-10-11 14:23:25 - INFO - - Erreurs : 0
|
|
2025-10-11 14:23:25 - INFO - ============================================================
|
|
```
|
|
|
|
### Mode verbeux
|
|
|
|
Utilisez `--verbose` pour des logs détaillés :
|
|
|
|
```bash
|
|
docker run --rm -v $(pwd)/mes_pdfs:/data pdf2csv:latest --verbose
|
|
```
|
|
|
|
Affiche des informations supplémentaires sur :
|
|
- Délimiteurs CSV détectés
|
|
- Nombre de lignes supprimées à chaque étape
|
|
- En-têtes détectées
|
|
- Fusion de lignes
|
|
- Fichiers temporaires
|
|
|
|
---
|
|
|
|
## 🐛 Résolution de problèmes
|
|
|
|
### Erreur : "Aucun PDF trouvé"
|
|
|
|
- Vérifiez que les fichiers ont bien l'extension `.pdf`
|
|
- Vérifiez le montage du volume Docker : `-v $(pwd)/mes_pdfs:/data`
|
|
|
|
### Erreur : "Erreur lors de la conversion"
|
|
|
|
- Vérifiez que le PDF contient bien des tableaux (pas juste du texte)
|
|
- Essayez avec `TABULA_LATTICE=false` pour les PDFs sans bordures
|
|
- Utilisez `--verbose` pour voir les détails de l'erreur
|
|
|
|
### Les données sont incorrectes
|
|
|
|
- Ajustez les mots-clés : `--mot-debut`, `--mot-fin`
|
|
- Modifiez `SKIP_LINES` si nécessaire
|
|
- Utilisez `--verbose` pour voir les étapes de nettoyage
|
|
|
|
### Encodage de caractères
|
|
|
|
- Le script utilise UTF-8 par défaut
|
|
- Java est configuré avec `JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8"`
|
|
|
|
---
|
|
|
|
## 🏗️ Architecture du code
|
|
|
|
```
|
|
convert.py
|
|
├── Configuration # Classe de configuration centralisée
|
|
├── temporary_file_tracker() # Gestionnaire de contexte pour fichiers temporaires
|
|
├── valider_fichier_pdf() # Validation des entrées
|
|
├── detect_delimiter() # Détection auto du séparateur CSV
|
|
├── supprimer_lignes_par_mot_cle() # Fonction utilitaire
|
|
├── nettoyer_csv_texte() # Logique de nettoyage principale
|
|
├── convertir_et_nettoyer() # Orchestration conversion + nettoyage
|
|
├── fusionner_csv() # Fusion des fichiers
|
|
├── traitement_batch() # Traitement complet batch
|
|
└── main() # Point d'entrée CLI
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 Tests
|
|
|
|
```bash
|
|
# Créer un dossier de test avec des PDFs échantillons
|
|
mkdir test_pdfs
|
|
cp vos_pdfs_test/*.pdf test_pdfs/
|
|
|
|
# Test local
|
|
python convert.py test_pdfs --verbose
|
|
|
|
# Test Docker
|
|
docker build -t pdf2csv:test .
|
|
docker run --rm -v $(pwd)/test_pdfs:/data pdf2csv:test --verbose
|
|
|
|
# Vérifier les résultats
|
|
ls -lh test_pdfs/
|
|
cat test_pdfs/fusion_total.csv
|
|
```
|
|
|
|
---
|
|
|
|
## 📄 Licence
|
|
|
|
Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.
|
|
|
|
---
|
|
|
|
## 🤝 Contribution
|
|
|
|
Les contributions sont les bienvenues ! N'hésitez pas à :
|
|
|
|
1. Fork le projet
|
|
2. Créer une branche (`git checkout -b feature/amelioration`)
|
|
3. Commit vos changements (`git commit -am 'Ajout nouvelle fonctionnalité'`)
|
|
4. Push vers la branche (`git push origin feature/amelioration`)
|
|
5. Créer une Pull Request
|
|
|
|
---
|
|
|
|
## 📞 Support
|
|
|
|
Pour toute question ou problème :
|
|
|
|
- Ouvrez une issue sur GitHub
|
|
- Consultez les logs avec `--verbose`
|
|
- Vérifiez la configuration des variables d'environnement
|
|
|
|
---
|
|
|
|
## 🔄 Changelog
|
|
|
|
### v2.0 (2025-10-11)
|
|
- ✨ Refactoring complet du code
|
|
- ✨ Ajout de la gestion d'erreurs robuste
|
|
- ✨ Logging professionnel avec niveaux
|
|
- ✨ Type hints pour tout le code
|
|
- ✨ Configuration via variables d'environnement
|
|
- ✨ Arguments CLI avec argparse
|
|
- ✨ Validation des entrées
|
|
- ✨ Nettoyage automatique des fichiers temporaires
|
|
- ✨ Documentation complète
|
|
- 📦 requirements.txt standardisé
|
|
- 🐛 Corrections de bugs divers
|
|
|
|
### v1.0
|
|
- 🎉 Version initiale
|
|
- Conversion PDF → CSV avec tabula
|
|
- Nettoyage basique
|
|
- Fusion de fichiers
|