البدء

المتطلبات

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

التثبيت

pip install bankstatementparser

لدعم DataFrame في Polars:

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

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

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

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

معالجة آمنة لملفات 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()

استخدام CLI

# Parse and display
python -m bankstatementparser.cli --type camt --input statement.xml

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

# Stream with PII visible
python -m bankstatementparser.cli --type camt --input statement.xml --streaming --show-pii

خيارات CLI:

• --type {camt,pain001} -- نوع المحلل
• --input <path> -- ملف الإدخال
• --output <csv_path> -- التصدير إلى CSV
• --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

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

pytest

مرجع API

فئات المحللات

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

الدالة	الغرض
detect_statement_format(path)	اكتشاف تنسيق الملف تلقائياً
create_parser(path, fmt)	إنشاء المحلل المناسب
parse_files_parallel(paths)	تحليل عدة ملفات بالتوازي
iter_secure_xml_entries(zip_path)	التكرار الآمن على عناصر ZIP

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

الفئة	الغرض
Deduplicator	كشف المعاملات المكررة
DeduplicationResult	النتيجة مع المعاملات الفريدة والمطابقة تماماً والمشتبه بها
InputValidator	التحقق من مسارات الملفات والتنسيقات
Transaction	سجل معاملة موحّد
FileResult	نتيجة التحليل المتوازي
ZipXMLSource	غلاف عضو ZIP

الاستثناءات

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