银行对账单解析器

＃＃ 要求

• 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 安全检查失败