Парсер банковских выписок

Требования

• Питон 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

Парсинг в памяти

Анализ байтов без дискового ввода-вывода — полезно для рабочих процессов 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