pdf2csv

Convertisseur de fichiers PDF en CSV basé sur tabula-py et pandas, 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é)

# 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

# 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 :

# Placez vos PDFs dans un dossier (ex: ./mes_pdfs/)
docker run --rm -v $(pwd)/mes_pdfs:/data pdf2csv:latest

Mode verbeux :

docker run --rm -v $(pwd)/mes_pdfs:/data pdf2csv:latest --verbose

Avec variables d'environnement personnalisées :

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 :

# 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 :

docker run --rm -v $(pwd)/mes_pdfs:/data pdf2csv:latest --no-clean

Utilisation locale (Python)

# 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

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

# 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é

# 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

# 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 :

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

# 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