銀行對帳單解析器

＃＃ 要求

• Python 3.9 至 3.14
• 終端存取（macOS、Linux 或 WSL）

＃＃ 安裝

pip install bankstatementparser

對於 Polars DataFrame 支援：

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

記憶體中解析

在沒有磁碟 I/O 的情況下從位元組進行解析——對於 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 安全檢查失敗