Začínáme

Požadavky

• Python 3.9 až 3.14
• Přístup k terminálu (macOS, Linux nebo WSL)

Instalace

pip install bankstatementparser

Pro podporu Polars DataFrame:

pip install bankstatementparser[polars]

Rychlý start

Automatická detekce a analýza libovolného formátu

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

Funguje se soubory .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 a .sta.

Analýza CAMT.053

from bankstatementparser import CamtParser

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

Analýza PAIN.001

from bankstatementparser import Pain001Parser

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

Streaming velkých souborů

Pro soubory s tisíci transakcí použijte streaming pro omezení paměti:

parser = CamtParser("large_statement.xml")
for transaction in parser.parse_streaming(redact_pii=True):
    process(transaction)  # Paměť zůstává konstantní

Analýza v paměti

Analyzujte z bytů bez diskových I/O operací -- užitečné pro SFTP nebo API workflow:

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

Paralelní zpracování souborů

Analyzujte více souborů současně:

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

Deduplikace

Detekujte přesné duplicity a podezřelé shody s hodnocením spolehlivosti:

from bankstatementparser import CamtParser, Deduplicator

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

print(f"Unikátní: {len(result.unique_transactions)}")
print(f"Přesné duplicity: {len(result.exact_duplicates)}")
print(f"Podezřelé shody: {len(result.suspected_matches)}")

Zabezpečené zpracování ZIP

Zpracovávejte zazipované XML soubory s vestavěnými bezpečnostními kontrolami (ochrana před bombami, odmítnutí šifrovaných položek):

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())} transakcí")

Export

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

# Polars (vyžaduje bankstatementparser[polars])
polars_df = parser.to_polars()

Použití CLI

# Analýza a zobrazení
python -m bankstatementparser.cli --type camt --input statement.xml

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

# Streaming s viditelnými PII
python -m bankstatementparser.cli --type camt --input statement.xml --streaming --show-pii

Volby CLI:

• --type {camt,pain001} -- typ parseru
• --input <cesta> -- vstupní soubor
• --output <csv_cesta> -- export do CSV
• --streaming -- streaming velkých souborů
• --show-pii -- zobrazit citlivá pole (ve výchozím stavu maskováno)
• --max-size <MB> -- limit velikosti souboru

Lokální vývojové prostředí

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

Spuštění testů:

pytest

Reference API

Třídy parserů

Pomocné funkce

Funkce	Účel
detect_statement_format(path)	Automatická detekce formátu souboru
create_parser(path, fmt)	Vytvoření příslušného parseru
parse_files_parallel(paths)	Paralelní analýza více souborů
iter_secure_xml_entries(zip_path)	Bezpečná iterace položek ZIP

Datové třídy

Třída	Účel
Deduplicator	Detekce duplicitních transakcí
DeduplicationResult	Výsledek s unikátními, přesnými a podezřelými shodami
InputValidator	Validace cest k souborům a formátů
Transaction	Normalizovaný záznam transakce
FileResult	Výsledek z paralelní analýzy
ZipXMLSource	Wrapper položky ZIP

Výjimky

Výjimka	Kdy je vyvolána
ParserError	Chyby při analýze
ExportError	Chyby při exportu (CSV/JSON/Excel)
ValidationError	Chyby při validaci vstupů
ZipSecurityError	Chyby bezpečnostní kontroly ZIP