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

Вимоги

• 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

Аналіз пам'яті

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