Iniziare

Requisiti

• Python da 3.10 a 3.14
• Accesso al terminale (macOS, Linux o WSL)

Installazione

# Core install (deterministic parsers only)
pip install bankstatementparser

Extra opzionali per funzionalità aggiuntive:

# 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]'

Avvio rapido

Rileva automaticamente e analizza qualsiasi formato strutturato

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

Funziona con file .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 e .sta.

Analisi CAMT.053

from bankstatementparser import CamtParser

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

Analisi PAIN.001

from bankstatementparser import Pain001Parser

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

Analisi di estratti conto PDF (pipeline ibrida)

La pipeline ibrida instrada i PDF in modo intelligente su tre percorsi di estrazione:

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

Ogni estrazione viene verificata con la Golden Rule: opening + credits − debits == closing.

Streaming di file di grandi dimensioni

Per file con migliaia di transazioni, lo streaming mantiene la memoria limitata:

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

Parsing in memoria

Analisi da byte senza I/O su disco — utile per flussi di lavoro SFTP o API:

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

Elaborazione file in parallelo

Analisi di più file in contemporanea:

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

Scansione in blocco di cartelle

Elabora intere cartelle con deduplicazione automatica:

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

Deduplicazione

Hash idempotenti delle transazioni per un'ingestione incrementale sicura:

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

Categorizzazione delle transazioni (arricchimento)

Categorizzazione automatica delle transazioni tramite classificazione LLM:

from bankstatementparser.enrichment import Categorizer

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

Esportazione contabile (hledger / beancount)

Esporta le transazioni in formato journal per la contabilità plaintext:

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

Verifica saldo multi-valuta

Verifica dei saldi in modo indipendente per ogni gruppo di valuta:

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

REST API

Deploy come microservizio FastAPI:

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

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

Endpoint:

• POST /ingest -- Analizza un file di estratto conto
• GET /health -- Controllo stato di salute

Elaborazione ZIP sicura

Elabora file XML compressi con controlli di sicurezza integrati (protezione anti-bomb, rifiuto di voci crittografate):

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

Esportazione

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

Utilizzo della CLI

# 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

Opzioni CLI:

• --type {camt,pain001,ingest,review} -- tipo di parser o modalità
• --input <path> -- file di input
• --output <path> -- file di esportazione (CSV o JSON)
• --streaming -- streaming per file di grandi dimensioni
• --show-pii -- mostra campi sensibili (oscurati di default)
• --max-size <MB> -- limite dimensione file

Configurazione per lo sviluppo locale

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

Esegui la suite di test:

pytest

Riferimento API

Classi parser

Funzioni di utilità

Funzione	Scopo
detect_statement_format(path)	Rilevamento automatico del formato file
create_parser(path, fmt)	Crea il parser appropriato
parse_files_parallel(paths)	Analizza più file in contemporanea
iter_secure_xml_entries(zip_path)	Itera le voci ZIP in modo sicuro
smart_ingest(path)	Estrazione PDF ibrida con verifica
scan_and_ingest(dir, pattern)	Scansione in blocco di cartelle
verify_balance_multi_currency(txns)	Verifica saldo per valuta
to_hledger(txns, account)	Esporta in formato journal hledger
to_beancount(txns, account)	Esporta in formato journal beancount

Classi dati

Classe	Scopo
Deduplicator	Rileva transazioni duplicate
DeduplicationResult	Risultato con corrispondenze univoche, esatte e sospette
InputValidator	Valida percorsi e formati di file
Transaction	Record di transazione normalizzato
FileResult	Risultato dell'analisi parallela
ZipXMLSource	Wrapper membro ZIP
IngestResult	Risultato della pipeline ibrida con verifica
VerificationResult	Esito della verifica del saldo
Categorizer	Categorizzazione transazioni tramite LLM
AccountMapper	Regole di mappatura conti basate su regex

Eccezioni

Eccezione	Quando sollevata
ParserError	Errori di parsing
ExportError	Errori di esportazione (CSV/JSON/Excel)
ValidationError	Errori di validazione dell'input
ZipSecurityError	Errori del controllo di sicurezza ZIP