ابدء

المتطلبات

• Python 3.10 إلى 3.14
• وصول إلى الطرفية (macOS أو Linux أو WSL)

التثبيت

# Core install (deterministic parsers only)
pip install bankstatementparser

إضافات اختيارية لقدرات إضافية:

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

بداية سريعة

الاكتشاف التلقائي وتحليل أي تنسيق منظم

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

يعمل هذا مع ملفات .xml (CAMT/PAIN.001) و.csv و.ofx و.qfx و.mt940 و.sta.

تحليل CAMT.053

from bankstatementparser import CamtParser

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

تحليل PAIN.001

from bankstatementparser import Pain001Parser

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

تحليل كشوفات PDF البنكية (خط الأنابيب الهجين)

خط الأنابيب الهجين يوجّه ملفات PDF بذكاء عبر ثلاثة مسارات استخراج:

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

يُتحقق من كل استخراج بواسطة القاعدة الذهبية: opening + credits − debits == closing.

بث الملفات الكبيرة

للملفات التي تحتوي على آلاف المعاملات، استخدم streaming للحفاظ على ذاكرة محدودة:

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

التحليل في الذاكرة

التحليل من بايتات بدون إدخال/إخراج قرص — مفيد لسير عمل SFTP أو API:

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

معالجة الملفات بالتوازي

تحليل ملفات متعددة بالتوازي:

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

المسح المجمّع للمجلدات

معالجة أشجار مجلدات كاملة مع إزالة التكرار تلقائيًا:

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

إزالة التكرار

hash حتمي للمعاملات لاستيعاب تدريجي آمن:

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

تصنيف المعاملات (الإثراء)

تصنيف المعاملات تلقائيًا باستخدام تصنيف مدعوم بـ LLM:

from bankstatementparser.enrichment import Categorizer

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

تصدير دفتر الأستاذ (hledger / beancount)

تصدير المعاملات إلى تنسيقات يوميات المحاسبة النصية:

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

التحقق من الرصيد متعدد العملات

التحقق من الأرصدة بشكل مستقل لكل مجموعة عملات:

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:

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

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

نقاط النهاية:

• POST /ingest -- تحليل ملف كشف حساب بنكي
• GET /health -- فحص الحالة

معالجة ZIP الآمنة

معالجة ملفات XML المضغوطة مع فحوصات أمان مدمجة (حماية من القنابل، رفض مدخلات مشفرة):

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

التصدير

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

# 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

خيارات CLI:

• --type {camt,pain001,ingest,review} -- نوع المحلل أو الوضع
• --input <path> -- ملف الإدخال
• --output <path> -- ملف التصدير (CSV أو JSON)
• --streaming -- بث الملفات الكبيرة
• --show-pii -- إظهار الحقول الحساسة (مُنقّحة افتراضيًا)
• --max-size <MB> -- حد حجم الملف

إعداد التطوير المحلي

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

تشغيل مجموعة الاختبارات:

pytest

مرجع API

فئات المحلل

الدوال المساعدة

الدالة	الغرض
detect_statement_format(path)	اكتشاف تنسيق الملف تلقائيًا
create_parser(path, fmt)	إنشاء المحلل المناسب
parse_files_parallel(paths)	تحليل ملفات متعددة بالتوازي
iter_secure_xml_entries(zip_path)	تكرار مدخلات ZIP بأمان
smart_ingest(path)	استخراج PDF هجين مع تحقق
scan_and_ingest(dir, pattern)	مسح مجمّع للمجلدات
verify_balance_multi_currency(txns)	تحقق الرصيد لكل عملة
to_hledger(txns, account)	تصدير إلى تنسيق hledger
to_beancount(txns, account)	تصدير إلى تنسيق beancount

فئات البيانات

الفئة	الغرض
Deduplicator	كشف المعاملات المكررة
DeduplicationResult	النتيجة بمطابقات فريدة ودقيقة ومشتبه بها
InputValidator	التحقق من مسارات الملفات والتنسيقات
Transaction	سجل المعاملة الموحد
FileResult	نتيجة التحليل المتوازي
ZipXMLSource	غلاف عضو ZIP
IngestResult	نتيجة خط الأنابيب الهجين مع التحقق
VerificationResult	نتيجة التحقق من الرصيد
Categorizer	تصنيف معاملات مدعوم بـ LLM
AccountMapper	قواعد تعيين حسابات قائمة على regex

الاستثناءات

الاستثناء	متى يُرفع
ParserError	فشل التحليل
ExportError	فشل التصدير (CSV/JSON/Excel)
ValidationError	فشل التحقق من المدخلات
ZipSecurityError	فشل فحص أمان ZIP