Начиная

Требования

• Python 3.10–3.14
• Доступ к терминалу (macOS, Linux или WSL)

Установка

# Базовая установка (только детерминированные парсеры)
pip install bankstatementparser

Дополнительные модули для расширенных возможностей:

# Text-LLM путь для цифровых PDF (litellm + pypdf)
pip install 'bankstatementparser[hybrid]'

# Более точное извлечение таблиц (добавляет pdfplumber)
pip install 'bankstatementparser[hybrid-plus]'

# Vision-LLM путь для сканированных PDF (добавляет pypdfium2)
pip install 'bankstatementparser[hybrid-vision]'

# Категоризация транзакций на основе LLM
pip install 'bankstatementparser[enrichment]'

# REST API микросервис (FastAPI + uvicorn)
pip install 'bankstatementparser[api]'

# Поддержка 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()

Разбор PDF-выписок (гибридный pipeline)

Гибридный pipeline автоматически направляет PDF по оптимальному пути извлечения:

from bankstatementparser.hybrid import smart_ingest

result = smart_ingest("statement.pdf")
print(result.source_method)         # "deterministic" | "llm" | "vision"
print(result.verification.status)   # VERIFIED | DISCREPANCY | FAILED
print(result.transactions)          # List of extracted transactions

Каждое извлечение проверяется Золотым правилом: opening + credits − debits == closing.

Потоковый разбор больших файлов

Для файлов с тысячами транзакций используйте streaming для ограничения памяти:

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.hybrid import scan_and_ingest

batch = scan_and_ingest("statements/2026/", pattern="**/*.pdf")
print(f"Processed: {len(batch.results)} files")
print(f"Unique transactions: {batch.unique_count}")

Дедупликация

Идемпотентные hash транзакций для безопасной инкрементальной загрузки:

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

Категоризация транзакций (обогащение)

Автоматическая категоризация транзакций с помощью LLM:

from bankstatementparser.enrichment import Categorizer

categorizer = Categorizer()
enriched = categorizer.categorize_batch(transactions)
for txn in enriched:
    print(f"{txn.description}: {txn.category}")

Экспорт в бухгалтерию (hledger / beancount)

Экспорт транзакций в форматы plaintext-accounting:

from bankstatementparser.export import to_hledger, to_beancount

journal = to_hledger(transactions, account="Assets:Bank:Checking")
beancount_journal = to_beancount(transactions, account="Assets:Bank:Checking")

Мультивалютная проверка баланса

Независимая проверка баланса по каждой группе валют:

from bankstatementparser.hybrid import verify_balance_multi_currency

results = verify_balance_multi_currency(transactions)
for currency, verification in results.items():
    print(f"{currency}: {verification.status}")

REST API

Развёртывание как микросервис FastAPI:

# Start the API server
bankstatementparser-api --port 8000

# For container deployments
bankstatementparser-api --host 0.0.0.0 --port 9000

Эндпоинты:

• POST /ingest -- Разбор файла банковской выписки
• GET /health -- Проверка состояния

Безопасная обработка ZIP

Обработка 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()

# Excel
parser.camt_to_excel("output.xlsx")

Использование CLI

# Разбор структурированных форматов
bankstatementparser --type camt --input statement.xml
bankstatementparser --type pain001 --input payment.xml

# Гибридный PDF-pipeline
bankstatementparser --type ingest --input statement.pdf
bankstatementparser --type ingest --input statement.pdf --output ledger.csv

# Интерактивный режим просмотра
bankstatementparser --type review --input result.json
bankstatementparser --type review --input result.json --output reviewed.json

# Экспорт в CSV с потоковым режимом
bankstatementparser --type camt --input statement.xml --output transactions.csv
bankstatementparser --type camt --input statement.xml --streaming --show-pii

Опции CLI:

• --type {camt,pain001,ingest,review} -- тип парсера или режим
• --input <path> -- входной файл
• --output <path> -- файл экспорта (CSV или JSON)
• --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
make install-hooks   # pre-commit hook runs `make verify` before every commit

Запуск тестов:

pytest

Справочник API

Классы парсеров

Вспомогательные функции

Функция	Назначение
detect_statement_format(path)	Автоопределение формата файла
create_parser(path, fmt)	Создание нужного парсера
parse_files_parallel(paths)	Параллельный разбор нескольких файлов
iter_secure_xml_entries(zip_path)	Безопасный перебор записей ZIP
smart_ingest(path)	Гибридное извлечение из PDF с проверкой
scan_and_ingest(dir, pattern)	Массовое сканирование каталогов
verify_balance_multi_currency(txns)	Проверка баланса по валютам
to_hledger(txns, account)	Экспорт в формат журнала hledger
to_beancount(txns, account)	Экспорт в формат журнала beancount

Классы данных

Класс	Назначение
Deduplicator	Обнаружение дублей транзакций
DeduplicationResult	Результат с уникальными, точными и предполагаемыми совпадениями
InputValidator	Валидация путей и форматов файлов
Transaction	Нормализованная запись транзакции
FileResult	Результат параллельного разбора
ZipXMLSource	Обёртка для записи ZIP
IngestResult	Результат гибридного pipeline с проверкой
VerificationResult	Результат проверки баланса
Categorizer	Категоризация транзакций на основе LLM
AccountMapper	Правила маппинга счетов на основе регулярных выражений

Исключения

Исключение	Когда возникает
ParserError	Ошибки разбора
ExportError	Ошибки экспорта (CSV/JSON/Excel)
ValidationError	Ошибки валидации ввода
ZipSecurityError	Ошибки проверки безопасности ZIP