Başlarken

Gereksinimler

• Python 3.10 - 3.14
• Terminal erişimi (macOS, Linux veya WSL)

Kurulum

# Temel kurulum (yalnızca deterministik ayrıştırıcılar)
pip install bankstatementparser

Ek yetenekler için isteğe bağlı eklentiler:

# Dijital PDF'ler için metin-LLM yolu (litellm + pypdf)
pip install 'bankstatementparser[hybrid]'

# Daha yüksek doğrulukta tablo çıkarımı (pdfplumber ekler)
pip install 'bankstatementparser[hybrid-plus]'

# Taranmış PDF'ler için görüntü-LLM yolu (pypdfium2 ekler)
pip install 'bankstatementparser[hybrid-vision]'

# LLM destekli işlem sınıflandırması
pip install 'bankstatementparser[enrichment]'

# REST API mikro hizmeti (FastAPI + uvicorn)
pip install 'bankstatementparser[api]'

# İsteğe bağlı Polars DataFrame desteği
pip install 'bankstatementparser[polars]'

Hızlı Başlangıç

Yapılandırılmış Formatları Otomatik Algıla ve Ayrıştır

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

Bu .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 ve .sta dosyalarıyla çalışır.

CAMT.053 Ayrıştırma

from bankstatementparser import CamtParser

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

PAIN.001 Ayrıştırma

from bankstatementparser import Pain001Parser

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

PDF Banka Ekstrelerini Ayrıştırma (Hibrit Pipeline)

Hibrit pipeline, PDF'leri akıllıca üç çıkarım yolundan geçirir:

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

Her çıkarım Altın Kural ile doğrulanır: opening + credits − debits == closing.

Büyük Dosyalarda Streaming

Binlerce işlem içeren dosyalar için belleği sınırlı tutmak amacıyla streaming kullanın:

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

Bellekte Ayrıştırma

Disk G/Ç olmadan baytlardan ayrıştırma -- SFTP veya API iş akışları için kullanışlıdır:

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

Paralel Dosya İşleme

Birden fazla dosyayı eş zamanlı ayrıştırın:

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

Toplu Dizin Tarama

Klasör ağaçlarını otomatik tekilleştirmeyle işleyin:

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

Tekilleştirme

Güvenli artımlı veri alımı için idempotent işlem hash'leri:

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

İşlem Sınıflandırması (Zenginleştirme)

LLM destekli sınıflandırma ile işlemleri otomatik kategorize edin:

from bankstatementparser.enrichment import Categorizer

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

Defter Dışa Aktarımı (hledger / beancount)

İşlemleri düz metin muhasebe defter formatlarına aktarın:

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

Çoklu Para Birimi Bakiye Doğrulaması

Para birimi grubuna göre bakiyeleri bağımsız doğrulayın:

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

FastAPI mikro hizmeti olarak dağıtın:

# API sunucusunu başlatın
bankstatementparser-api --port 8000

# Konteyner dağıtımları için
bankstatementparser-api --host 0.0.0.0 --port 9000

Uç noktalar:

• POST /ingest -- Bir banka ekstresi dosyasını ayrıştır
• GET /health -- Sağlık kontrolü

Güvenli ZIP İşleme

Yerleşik güvenlik kontrolleriyle sıkıştırılmış XML dosyalarını işleyin (bomba koruması, şifreli giriş reddi):

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

Dışa Aktarım

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

CLI Kullanımı

# Yapılandırılmış formatları ayrıştır
bankstatementparser --type camt --input statement.xml
bankstatementparser --type pain001 --input payment.xml

# Hibrit PDF pipeline
bankstatementparser --type ingest --input statement.pdf
bankstatementparser --type ingest --input statement.pdf --output ledger.csv

# Etkileşimli inceleme modu
bankstatementparser --type review --input result.json
bankstatementparser --type review --input result.json --output reviewed.json

# Streaming ile CSV'ye aktar
bankstatementparser --type camt --input statement.xml --output transactions.csv
bankstatementparser --type camt --input statement.xml --streaming --show-pii

CLI seçenekleri:

• --type {camt,pain001,ingest,review} -- ayrıştırıcı türü veya modu
• --input <path> -- girdi dosyası
• --output <path> -- dışa aktarım dosyası (CSV veya JSON)
• --streaming -- büyük dosyaları akışla işle
• --show-pii -- hassas alanları göster (varsayılan olarak gizlidir)
• --max-size <MB> -- dosya boyutu sınırı

Yerel Geliştirme Ortamı

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

Test paketini çalıştırın:

pytest

API Referansı

Ayrıştırıcı Sınıfları

Yardımcı Fonksiyonlar

Fonksiyon	Amaç
detect_statement_format(path)	Dosya formatını otomatik algıla
create_parser(path, fmt)	Uygun ayrıştırıcıyı oluştur
parse_files_parallel(paths)	Birden fazla dosyayı eş zamanlı ayrıştır
iter_secure_xml_entries(zip_path)	ZIP girişlerini güvenli bir şekilde yinele
smart_ingest(path)	Doğrulamalı hibrit PDF çıkarımı
scan_and_ingest(dir, pattern)	Toplu dizin tarama
verify_balance_multi_currency(txns)	Para birimine göre bakiye doğrulama
to_hledger(txns, account)	hledger defter formatına aktar
to_beancount(txns, account)	beancount defter formatına aktar

Veri Sınıfları

Sınıf	Amaç
Deduplicator	Yinelenen işlemleri tespit etme
DeduplicationResult	Benzersiz, kesin ve şüpheli eşleşmelerle sonuç
InputValidator	Dosya yollarını ve formatlarını doğrulama
Transaction	Normalleştirilmiş işlem kaydı
FileResult	Paralel ayrıştırma sonucu
ZipXMLSource	ZIP üyesi sarmalayıcısı
IngestResult	Doğrulamalı hibrit pipeline sonucu
VerificationResult	Bakiye doğrulama sonucu
Categorizer	LLM destekli işlem sınıflandırması
AccountMapper	Regex tabanlı hesap eşleme kuralları

İstisnalar

İstisna	Ne Zaman Fırlatılır
ParserError	Ayrıştırma hataları
ExportError	Dışa aktarma hataları (CSV/JSON/Excel)
ValidationError	Girdi doğrulama hataları
ZipSecurityError	ZIP güvenlik kontrolü hataları