Primii pași

Cerințe

• Python 3.9 până la 3.14
• Acces la terminal (macOS, Linux sau WSL)

Instalare

pip install bankstatementparser

Pentru suport DataFrame Polars:

pip install bankstatementparser[polars]

Pornire rapidă

Detectare automată și analiză a oricărui format

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

Funcționează cu fișiere .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 și .sta.

Analiză CAMT.053

from bankstatementparser import CamtParser

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

Analiză PAIN.001

from bankstatementparser import Pain001Parser

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

Streaming pentru fișiere mari

Pentru fișiere cu mii de tranzacții, utilizați streaming pentru a menține memoria limitată:

parser = CamtParser("large_statement.xml")
for transaction in parser.parse_streaming(redact_pii=True):
    process(transaction)  # Memoria rămâne constantă

Analiză în memorie

Analizați din octeți fără operațiuni I/O pe disc -- util pentru fluxuri SFTP sau API:

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

Procesare paralelă a fișierelor

Analizați mai multe fișiere simultan:

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

Deduplicare

Detectați duplicate exacte și potriviri suspecte cu scoruri de încredere:

from bankstatementparser import CamtParser, Deduplicator

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

print(f"Unice: {len(result.unique_transactions)}")
print(f"Duplicate exacte: {len(result.exact_duplicates)}")
print(f"Potriviri suspecte: {len(result.suspected_matches)}")

Procesare securizată ZIP

Procesați fișiere XML arhivate cu verificări de securitate integrate (protecție împotriva bombelor, respingerea intrărilor criptate):

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())} tranzacții")

Export

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

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

Utilizare CLI

# Analizare și afișare
python -m bankstatementparser.cli --type camt --input statement.xml

# Export în CSV
python -m bankstatementparser.cli --type camt --input statement.xml --output transactions.csv

# Streaming cu PII vizibile
python -m bankstatementparser.cli --type camt --input statement.xml --streaming --show-pii

Opțiuni CLI:

• --type {camt,pain001} -- tipul parserului
• --input <cale> -- fișier de intrare
• --output <cale_csv> -- export în CSV
• --streaming -- streaming pentru fișiere mari
• --show-pii -- afișează câmpurile sensibile (mascate implicit)
• --max-size <MB> -- limita de dimensiune a fișierului

Configurare dezvoltare locală

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

Rulați suita de teste:

pytest

Referință API

Clase parser

Funcții utilitare

Funcție	Scop
detect_statement_format(path)	Detectare automată a formatului fișierului
create_parser(path, fmt)	Crearea parserului potrivit
parse_files_parallel(paths)	Analiză simultană a mai multor fișiere
iter_secure_xml_entries(zip_path)	Iterare securizată a intrărilor ZIP

Clase de date

Clasă	Scop
Deduplicator	Detectarea tranzacțiilor duplicate
DeduplicationResult	Rezultat cu tranzacții unice, exacte și potriviri suspecte
InputValidator	Validarea căilor și formatelor de fișiere
Transaction	Înregistrare tranzacție normalizată
FileResult	Rezultat din analiza paralelă
ZipXMLSource	Wrapper membru ZIP

Excepții

Excepție	Când este aruncată
ParserError	Erori de analiză
ExportError	Erori de export (CSV/JSON/Excel)
ValidationError	Erori de validare a datelor de intrare
ZipSecurityError	Erori de verificare a securității ZIP