Premiers pas

Prérequis

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

Installation

pip install bankstatementparser

Pour le support des DataFrames Polars :

pip install bankstatementparser[polars]

Démarrage rapide

Détection automatique et analyse de tout format

from bankstatementparser import create_parser, detect_statement_format

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

Cela 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()

Streaming pour les gros fichiers

Pour les fichiers contenant des milliers de transactions, utilisez le streaming pour maintenir une mémoire constante :

parser = CamtParser("large_statement.xml")
for transaction in parser.parse_streaming(redact_pii=True):
    process(transaction)  # La memoire reste constante

Analyse en mémoire

Analysez des données 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")

Dédoublonnage

Détectez les doublons exacts et les correspondances suspectes avec des scores de confiance :

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)}")

Traitement ZIP sécurisé

Traitez des fichiers XML compressés avec des contrôles de sécurité intégrés (protection anti-bombe, 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 (necessite bankstatementparser[polars])
polars_df = parser.to_polars()

Utilisation en ligne de commande

# Analyser et afficher
python -m bankstatementparser.cli --type camt --input statement.xml

# Exporter en CSV
python -m bankstatementparser.cli --type camt --input statement.xml --output transactions.csv

# Streaming avec DCP visibles
python -m bankstatementparser.cli --type camt --input statement.xml --streaming --show-pii

Options CLI :

• --type {camt,pain001} -- type de parseur
• --input <path> -- fichier d'entrée
• --output <csv_path> -- exporter en CSV
• --streaming -- streaming pour les gros fichiers
• --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

Exécutez la suite de tests :

pytest

Référence API

Classes de parseurs

Fonctions utilitaires

Fonction	Objectif
detect_statement_format(path)	Détection automatique du format
create_parser(path, fmt)	Création du parseur adapté
parse_files_parallel(paths)	Analyse de plusieurs fichiers en parallèle
iter_secure_xml_entries(zip_path)	Itération sécurisée sur les entrées ZIP

Classes de données

Classe	Objectif
Deduplicator	Détection des transactions en double
DeduplicationResult	Résultat avec transactions uniques, doublons exacts et correspondances suspectes
InputValidator	Validation des chemins de fichiers et des formats
Transaction	Enregistrement de transaction normalisé
FileResult	Résultat de l'analyse parallèle
ZipXMLSource	Wrapper pour les membres ZIP

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