Trình phân tích sao kê ngân hàng

Yêu cầu

• Python 3,9 đến 3,14
• Truy cập thiết bị đầu cuối (macOS, Linux hoặc WSL)

Cài đặt

pip install bankstatementparser

Để được hỗ trợ Polars DataFrame:

pip install bankstatementparser[polars]

Bắt đầu nhanh

Tự động phát hiện và phân tích mọi định dạng

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

Điều này hoạt động với.xml(CAMT/PAIN.001),.csv, .ofx, .qfx, .mt940, Và.statập tin.

Phân tích CAMT.053

from bankstatementparser import CamtParser

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

Phân tích PAIN.001

from bankstatementparser import Pain001Parser

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

Truyền phát các tệp lớn

Đối với các tệp có hàng nghìn giao dịch, hãy sử dụng tính năng phát trực tuyến để giữ giới hạn bộ nhớ:

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

Phân tích cú pháp trong bộ nhớ

Phân tích cú pháp từ byte mà không cần I/O đĩa -- hữu ích cho quy trình làm việc SFTP hoặc API:

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

Xử lý tệp song song

Phân tích đồng thời nhiều tệp:

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

Chống trùng lặp

Phát hiện các bản sao chính xác và các kết quả trùng khớp đáng ngờ bằng điểm tin cậy:

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

Xử lý ZIP an toàn

Xử lý các tệp XML đã nén bằng tính năng kiểm tra bảo mật tích hợp (bảo vệ chống bom, từ chối mục nhập được mã hóa):

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

Xuất khẩu

parser = CamtParser("statement.xml")
parser.export_csv("output.csv")
parser.export_json("output.json")

# Polars (requires bankstatementparser[polars])
polars_df = parser.to_polars()

Cách sử dụng 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

Tùy chọn CLI:

• --type {camt,pain001}-- loại trình phân tích cú pháp ---input <path>-- tập tin đầu vào ---output <csv_path>-- xuất sang CSV ---streaming-- truyền phát các tập tin lớn ---show-pii-- hiển thị các trường nhạy cảm (được xử lý lại theo mặc định) ---max-size <MB>-- giới hạn kích thước tập tin

Thiết lập phát triển cục bộ

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

Chạy bộ thử nghiệm:

pytest

Tham khảo API

Lớp phân tích cú pháp

Chức năng tiện ích

Chức năng	Mục đích
detect_statement_format(path)	Tự động phát hiện định dạng tập tin
create_parser(path, fmt)	Tạo trình phân tích cú pháp thích hợp
parse_files_parallel(paths)	Phân tích đồng thời nhiều tệp
iter_secure_xml_entries(zip_path)	Lặp lại các mục ZIP một cách an toàn

Lớp dữ liệu

Lớp học	Mục đích
Deduplicator	Phát hiện giao dịch trùng lặp
DeduplicationResult	Kết quả có kết quả trùng khớp duy nhất, chính xác và đáng ngờ
InputValidator	Xác thực đường dẫn và định dạng tệp
Transaction	Hồ sơ giao dịch chuẩn hóa
FileResult	Kết quả phân tích song song
ZipXMLSource	Trình bao bọc thành viên ZIP

Ngoại lệ

Ngoại lệ	Khi nâng lên
ParserError	Lỗi phân tích cú pháp
ExportError	Lỗi xuất (CSV/JSON/Excel)
ValidationError	Lỗi xác thực đầu vào
ZipSecurityError	Lỗi kiểm tra bảo mật ZIP