Commencer

Prérequis

• Python 3.10 à 3.14
• Accès au terminal (macOS, Linux ou WSL)

Installation

# Installation de base (analyseurs déterministes uniquement)
pip install bankstatementparser

Extras optionnels pour des fonctionnalités supplémentaires :

# Text-LLM path for digital PDFs (litellm + pypdf)
pip install 'bankstatementparser[hybrid]'

# Higher-fidelity table extraction (adds pdfplumber)
pip install 'bankstatementparser[hybrid-plus]'

# Vision-LLM path for scanned PDFs (adds pypdfium2)
pip install 'bankstatementparser[hybrid-vision]'

# LLM-powered transaction categorisation
pip install 'bankstatementparser[enrichment]'

# REST API microservice (FastAPI + uvicorn)
pip install 'bankstatementparser[api]'

# Optional Polars DataFrame support
pip install 'bankstatementparser[polars]'

Démarrage rapide

Détection automatique et analyse de tout format structuré

from bankstatementparser import create_parser, detect_statement_format

fmt = detect_statement_format("transactions.ofx")
parser = create_parser("transactions.ofx", fmt)
df = parser.parse()  # pandas DataFrame
print(df.head())

Fonctionne avec les fichiers .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 et .sta.

Analyser un fichier CAMT.053

from bankstatementparser import CamtParser

parser = CamtParser("statement.xml")
transactions = parser.parse()

Analyser un fichier PAIN.001

from bankstatementparser import Pain001Parser

parser = Pain001Parser("payment.xml")
payments = parser.parse()

Analyser des relevés bancaires PDF (pipeline hybride)

Le pipeline hybride achemine les PDF de manière intelligente via trois voies d'extraction :

from bankstatementparser.hybrid import smart_ingest

result = smart_ingest("statement.pdf")
print(result.source_method)         # "deterministic" | "llm" | "vision"
print(result.verification.status)   # VERIFIED | DISCREPANCY | FAILED
print(result.transactions)          # List of extracted transactions

Chaque extraction est vérifiée avec la Règle d'or : opening + credits − debits == closing.

Streaming de fichiers volumineux

Pour les fichiers contenant des milliers de transactions, utilisez le streaming pour limiter la mémoire :

parser = CamtParser("large_statement.xml")
for transaction in parser.parse_streaming(redact_pii=True):
    process(transaction)  # Memory stays constant

Analyse en mémoire

Analysez depuis des octets sans E/S disque — utile pour les flux SFTP ou API :

xml_bytes = download_from_sftp()
parser = CamtParser.from_bytes(xml_bytes, source_name="daily.xml")
transactions = parser.parse()

Traitement parallèle de fichiers

Analysez plusieurs fichiers simultanément :

from bankstatementparser import parse_files_parallel

results = parse_files_parallel([
    "statements/jan.xml",
    "statements/feb.xml",
    "statements/mar.xml",
])
for r in results:
    print(r.path, r.status, len(r.transactions), "rows")

Scan de répertoires en masse

Traitez des arborescences complètes avec déduplication automatique :

from bankstatementparser.hybrid import scan_and_ingest

batch = scan_and_ingest("statements/2026/", pattern="**/*.pdf")
print(f"Processed: {len(batch.results)} files")
print(f"Unique transactions: {batch.unique_count}")

Déduplication

Hash idempotent des transactions pour une ingestion incrémentale fiable :

from bankstatementparser import CamtParser, Deduplicator

parser = CamtParser("statement.xml")
dedup = Deduplicator()
result = dedup.deduplicate(dedup.from_dataframe(parser.parse()))

print(f"Unique: {len(result.unique_transactions)}")
print(f"Exact duplicates: {len(result.exact_duplicates)}")
print(f"Suspected matches: {len(result.suspected_matches)}")

Catégorisation des transactions (enrichissement)

Catégorisez automatiquement les transactions via une classification par LLM :

from bankstatementparser.enrichment import Categorizer

categorizer = Categorizer()
enriched = categorizer.categorize_batch(transactions)
for txn in enriched:
    print(f"{txn.description}: {txn.category}")

Export comptable (hledger / beancount)

Exportez les transactions au format journal de comptabilité en texte brut :

from bankstatementparser.export import to_hledger, to_beancount

journal = to_hledger(transactions, account="Assets:Bank:Checking")
beancount_journal = to_beancount(transactions, account="Assets:Bank:Checking")

Vérification du solde multi-devises

Vérifiez les soldes de manière indépendante par groupe de devises :

from bankstatementparser.hybrid import verify_balance_multi_currency

results = verify_balance_multi_currency(transactions)
for currency, verification in results.items():
    print(f"{currency}: {verification.status}")

API REST

Déployez comme microservice FastAPI :

# Start the API server
bankstatementparser-api --port 8000

# For container deployments
bankstatementparser-api --host 0.0.0.0 --port 9000

Endpoints :

• POST /ingest -- Analyser un fichier de relevé bancaire
• GET /health -- Vérification de l'état

Traitement ZIP sécurisé

Traitez des fichiers XML compressés avec des contrôles de sécurité intégrés (protection contre les bombes, rejet des entrées chiffrées) :

from bankstatementparser import iter_secure_xml_entries, CamtParser

for entry in iter_secure_xml_entries("statements.zip"):
    parser = CamtParser.from_bytes(entry.xml_bytes, source_name=entry.source_name)
    print(f"{entry.source_name}: {len(parser.parse())} transactions")

Export

parser = CamtParser("statement.xml")
parser.export_csv("output.csv")
parser.export_json("output.json")

# Polars (requires bankstatementparser[polars])
polars_df = parser.to_polars()

# Excel
parser.camt_to_excel("output.xlsx")

Utilisation en ligne de commande

# Parse structured formats
bankstatementparser --type camt --input statement.xml
bankstatementparser --type pain001 --input payment.xml

# Hybrid PDF pipeline
bankstatementparser --type ingest --input statement.pdf
bankstatementparser --type ingest --input statement.pdf --output ledger.csv

# Interactive review mode
bankstatementparser --type review --input result.json
bankstatementparser --type review --input result.json --output reviewed.json

# Export to CSV with streaming
bankstatementparser --type camt --input statement.xml --output transactions.csv
bankstatementparser --type camt --input statement.xml --streaming --show-pii

Options CLI :

• --type {camt,pain001,ingest,review} -- type d'analyseur ou mode
• --input <path> -- fichier d'entrée
• --output <path> -- fichier d'export (CSV ou JSON)
• --streaming -- streaming des fichiers volumineux
• --show-pii -- afficher les champs sensibles (masqués par défaut)
• --max-size <MB> -- limite de taille de fichier

Configuration de l'environnement de développement

git clone https://github.com/sebastienrousseau/bankstatementparser.git
cd bankstatementparser
python3 -m venv .venv && source .venv/bin/activate
pip install poetry && poetry install --with dev
make install-hooks   # pre-commit hook runs `make verify` before every commit

Exécutez la suite de tests :

pytest

Référence API

Classes d'analyseurs

Fonctions utilitaires

Fonction	Objectif
detect_statement_format(path)	Détection automatique du format
create_parser(path, fmt)	Créer l'analyseur approprié
parse_files_parallel(paths)	Analyser plusieurs fichiers simultanément
iter_secure_xml_entries(zip_path)	Itérer sur les entrées ZIP de manière sécurisée
smart_ingest(path)	Extraction PDF hybride avec vérification
scan_and_ingest(dir, pattern)	Scan de répertoires en masse
verify_balance_multi_currency(txns)	Vérification du solde par devise
to_hledger(txns, account)	Export au format journal hledger
to_beancount(txns, account)	Export au format journal beancount

Classes de données

Classe	Objectif
Deduplicator	Détecter les transactions en double
DeduplicationResult	Résultat avec correspondances uniques, exactes et suspectes
InputValidator	Valider les chemins et formats de fichiers
Transaction	Enregistrement de transaction normalisé
FileResult	Résultat de l'analyse parallèle
ZipXMLSource	Enveloppe de membre ZIP
IngestResult	Résultat du pipeline hybride avec vérification
VerificationResult	Résultat de la vérification du solde
Categorizer	Catégorisation des transactions par LLM
AccountMapper	Règles de mappage de comptes basées sur des regex

Exceptions

Exception	Déclenchée quand
ParserError	Échec de l'analyse
ExportError	Échec de l'export (CSV/JSON/Excel)
ValidationError	Échec de la validation des entrées
ZipSecurityError	Échec des contrôles de sécurité ZIP