Pierwsze kroki

Wymagania

• Python 3.9 do 3.14
• Dostep do terminala (macOS, Linux lub WSL)

Instalacja

pip install bankstatementparser

Dla obslugi DataFrame Polars:

pip install bankstatementparser[polars]

Szybki start

Automatyczne wykrywanie i analiza dowolnego formatu

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

Dziala z plikami .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 i .sta.

Analiza CAMT.053

from bankstatementparser import CamtParser

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

Analiza PAIN.001

from bankstatementparser import Pain001Parser

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

Streaming dla duzych plikow

Dla plikow z tysiącami transakcji uzyj streamingu, aby utrzymac ograniczona pamiec:

parser = CamtParser("large_statement.xml")
for transaction in parser.parse_streaming(redact_pii=True):
    process(transaction)  # Pamiec pozostaje stala

Analiza w pamieci

Analizuj z bajtow bez operacji I/O na dysku -- przydatne dla przepływow SFTP lub API:

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

Rownolegle przetwarzanie plikow

Analizuj wiele plikow jednoczesnie:

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

Deduplikacja

Wykrywaj dokladne duplikaty i podejrzane dopasowania z wynikami zaufania:

from bankstatementparser import CamtParser, Deduplicator

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

print(f"Unikalne: {len(result.unique_transactions)}")
print(f"Dokladne duplikaty: {len(result.exact_duplicates)}")
print(f"Podejrzane dopasowania: {len(result.suspected_matches)}")

Bezpieczne przetwarzanie ZIP

Przetwarzaj zarchiwizowane pliki XML ze zintegrowanymi kontrolami bezpieczenstwa (ochrona przed bombami, odrzucanie zaszyfrowanych wpisow):

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

Eksport

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

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

Uzycie CLI

# Analizuj i wyswietl
python -m bankstatementparser.cli --type camt --input statement.xml

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

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

Opcje CLI:

• --type {camt,pain001} -- typ parsera
• --input <sciezka> -- plik wejsciowy
• --output <sciezka_csv> -- eksport do CSV
• --streaming -- streaming dla duzych plikow
• --show-pii -- pokaz wrazliwe pola (domyslnie maskowane)
• --max-size <MB> -- limit rozmiaru pliku

Lokalna konfiguracja deweloperska

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

Uruchom suite testow:

pytest

Referencja API

Klasy parsera

Funkcje pomocnicze

Funkcja	Cel
detect_statement_format(path)	Automatyczne wykrywanie formatu pliku
create_parser(path, fmt)	Tworzenie odpowiedniego parsera
parse_files_parallel(paths)	Jednoczesna analiza wielu plikow
iter_secure_xml_entries(zip_path)	Bezpieczna iteracja wpisow ZIP

Klasy danych

Klasa	Cel
Deduplicator	Wykrywanie zduplikowanych transakcji
DeduplicationResult	Wynik z unikalnymi, dokladnymi i podejrzanymi dopasowaniami
InputValidator	Walidacja sciezek i formatow plikow
Transaction	Znormalizowany rekord transakcji
FileResult	Wynik z rownolegles analizy
ZipXMLSource	Wrapper czlonka ZIP

Wyjatki

Wyjatek	Kiedy jest rzucany
ParserError	Bledy analizy
ExportError	Bledy eksportu (CSV/JSON/Excel)
ValidationError	Bledy walidacji danych wejsciowych
ZipSecurityError	Bledy kontroli bezpieczenstwa ZIP